文档(#99): 补充上传链路自检 runbook

Co-authored-by: multica-agent <github@multica.ai>

.codex-tmp/inspect_device_cache_roundtrip.go

@@ -0,0 +1,25 @@
+package main
+
+import (
+  "fmt"
+
+  "github.com/perfect-panel/server/internal/config"
+  "github.com/perfect-panel/server/internal/svc"
+  "github.com/perfect-panel/server/pkg/conf"
+)
+
+func main() {
+  var c config.Config
+  conf.MustLoad("/private/tmp/ppanel-local-upload.yaml", &c)
+  ctx := svc.NewServiceContext(c)
+  const key = "cache:auth:method:device"
+  before, _ := ctx.Redis.Get(ctx.DB.Statement.Context, key).Result()
+  fmt.Printf("cache before=%q\n", before)
+  m, err := ctx.AuthModel.FindOneByMethod(ctx.DB.Statement.Context, "device")
+  fmt.Printf("model err=%v enabled_nil=%v", err, m == nil || m.Enabled == nil)
+  if m != nil && m.Enabled != nil { fmt.Printf(" enabled=%v", *m.Enabled) }
+  if m != nil { fmt.Printf(" config=%s", m.Config) }
+  fmt.Println()
+  after, _ := ctx.Redis.Get(ctx.DB.Statement.Context, key).Result()
+  fmt.Printf("cache after=%q\n", after)
+}

.codex-tmp/inspect_device_config.go

@@ -0,0 +1,23 @@
+package main
+
+import (
+  "fmt"
+
+  initpkg "github.com/perfect-panel/server/initialize"
+  "github.com/perfect-panel/server/internal/config"
+  "github.com/perfect-panel/server/internal/svc"
+  "github.com/perfect-panel/server/pkg/conf"
+)
+
+func main() {
+  var c config.Config
+  conf.MustLoad("/private/tmp/ppanel-local-upload.yaml", &c)
+  ctx := svc.NewServiceContext(c)
+  method, err := ctx.AuthModel.FindOneByMethod(ctx.DB.Statement.Context, "device")
+  if err != nil {
+    panic(err)
+  }
+  fmt.Printf("db auth_method.enabled=%v config=%s\n", *method.Enabled, method.Config)
+  initpkg.Device(ctx)
+  fmt.Printf("ctx.Config.Device.Enable=%v SecuritySecret=%q EnableSecurity=%v\n", ctx.Config.Device.Enable, ctx.Config.Device.SecuritySecret, ctx.Config.Device.EnableSecurity)
+}

.codex-tmp/inspect_device_db_vs_model.go

@@ -0,0 +1,36 @@
+package main
+
+import (
+  "fmt"
+
+  "github.com/perfect-panel/server/internal/config"
+  "github.com/perfect-panel/server/internal/svc"
+  "github.com/perfect-panel/server/pkg/conf"
+)
+
+type row struct {
+  ID int64
+  Method string
+  Enabled int
+  Config string
+}
+
+func main() {
+  var c config.Config
+  conf.MustLoad("/private/tmp/ppanel-local-upload.yaml", &c)
+  ctx := svc.NewServiceContext(c)
+
+  var rows []row
+  if err := ctx.DB.Raw("SELECT id, method, enabled, config FROM auth_method WHERE method = ?", "device").Scan(&rows).Error; err != nil {
+    panic(err)
+  }
+  fmt.Printf("raw rows: %+v\n", rows)
+
+  m, err := ctx.AuthModel.FindOneByMethod(ctx.DB.Statement.Context, "device")
+  fmt.Printf("model err=%v\n", err)
+  if err == nil && m != nil && m.Enabled != nil {
+    fmt.Printf("model row: id=%d method=%s enabled=%v config=%s\n", m.Id, m.Method, *m.Enabled, m.Config)
+  } else {
+    fmt.Printf("model row nil or no enabled ptr: %#v\n", m)
+  }
+}

.codex-tmp/inspect_device_gorm.go

@@ -0,0 +1,28 @@
+package main
+
+import (
+  "fmt"
+
+  "github.com/perfect-panel/server/internal/config"
+  authmodel "github.com/perfect-panel/server/internal/model/auth"
+  "github.com/perfect-panel/server/internal/svc"
+  "github.com/perfect-panel/server/pkg/conf"
+)
+
+func main() {
+  var c config.Config
+  conf.MustLoad("/private/tmp/ppanel-local-upload.yaml", &c)
+  ctx := svc.NewServiceContext(c)
+
+  var a1 authmodel.Auth
+  err1 := ctx.DB.Model(&authmodel.Auth{}).Where("method = ?", "device").First(&a1).Error
+  fmt.Printf("gorm direct err=%v enabled_nil=%v", err1, a1.Enabled == nil)
+  if a1.Enabled != nil { fmt.Printf(" enabled=%v", *a1.Enabled) }
+  fmt.Printf(" config=%s\n", a1.Config)
+
+  var a2 authmodel.Auth
+  err2 := ctx.DB.Table("auth_method").Where("method = ?", "device").First(&a2).Error
+  fmt.Printf("gorm table err=%v enabled_nil=%v", err2, a2.Enabled == nil)
+  if a2.Enabled != nil { fmt.Printf(" enabled=%v", *a2.Enabled) }
+  fmt.Printf(" config=%s\n", a2.Config)
+}

.env.example

@@ -7,8 +7,8 @@ MYSQL_ROOT_PASSWORD=CHANGE_ME_TO_STRONG_PASSWORD
 # Grafana 管理员密码
 GRAFANA_PASSWORD=CHANGE_ME_TO_STRONG_PASSWORD
 
-# PPanel Server 镜像标签（留空使用 latest）
+# PPanel Server 镜像标签（由 CI/CD 传入不可变 tag，如 git SHA）
-PPANEL_SERVER_TAG=latest
+PPANEL_SERVER_TAG=CHANGE_ME_TO_GIT_SHA
 
 # AWS 区域（香港）
 AWS_REGION=ap-east-1

.gitea/workflows/docker.yml

@@ -14,14 +14,15 @@ on:
 env:
   # Docker镜像仓库
   REPO: ${{ vars.REPO || 'registry.kxsw.us/vpn-server' }}
-  # SSH连接信息 (根据分支自动选择)
+  # SSH连接信息 (根据分支自动选择服务器和用户)
   SSH_HOST: ${{ github.ref_name == 'main' && vars.SSH_HOST || vars.DEV_SSH_HOST }}
   SSH_PORT: ${{ vars.SSH_PORT }}
-  SSH_USER: ${{ vars.SSH_USER }}
+  SSH_USER: ${{ github.ref_name == 'main' && 'ubuntu' || 'root' }}
-  SSH_PASSWORD: ${{ github.ref_name == 'main' && vars.SSH_PASSWORD || vars.DEV_SSH_PASSWORD }}
+  # SSH私钥（Gitea Secret 名称：AWS）
+  SSH_KEY: ${{ secrets.AWS }}
   # TG通知
-  TG_BOT_TOKEN: 8114337882:AAHkEx03HSu7RxN4IHBJJEnsK9aPPzNLIk0
+  TG_BOT_TOKEN: ${{ secrets.TG_BOT_TOKEN }}
-  TG_CHAT_ID: "-4940243803"
+  TG_CHAT_ID: ${{ secrets.TG_CHAT_ID }}
   # Go构建变量
   SERVICE: vpn
   SERVICE_STYLE: vpn
@@ -42,27 +43,30 @@ jobs:
       # 步骤1: 下载代码
       - name: 📥 下载代码
         uses: actions/checkout@v4
-        
+
       # 步骤2: 设置动态环境变量
       - name: ⚙️ 设置动态环境变量
         run: |
           if [ "${{ github.ref_name }}" = "main" ]; then
             echo "DOCKER_TAG_SUFFIX=latest" >> $GITHUB_ENV
             echo "CONTAINER_NAME=ppanel-server" >> $GITHUB_ENV
-            echo "DEPLOY_PATH=/root/hifast" >> $GITHUB_ENV
+            echo "DEPLOY_PATH=/opt/ppanel" >> $GITHUB_ENV
+            echo "DEPLOY_ENV_LABEL=🚀 服务已成功部署到生产环境" >> $GITHUB_ENV
             echo "为 main 分支设置生产环境变量"
           elif [ "${{ github.ref_name }}" = "internal" ]; then
             echo "DOCKER_TAG_SUFFIX=internal" >> $GITHUB_ENV
             echo "CONTAINER_NAME=ppanel-server-internal" >> $GITHUB_ENV
-            echo "DEPLOY_PATH=/root/hifast" >> $GITHUB_ENV
+            echo "DEPLOY_PATH=/root/bindbox" >> $GITHUB_ENV
+            echo "DEPLOY_ENV_LABEL=🧪 服务已成功部署到测试环境" >> $GITHUB_ENV
             echo "为 internal 分支设置开发环境变量"
           else
             echo "DOCKER_TAG_SUFFIX=${{ github.ref_name }}" >> $GITHUB_ENV
             echo "CONTAINER_NAME=ppanel-server-${{ github.ref_name }}" >> $GITHUB_ENV
             echo "DEPLOY_PATH=/root/vpn_server_other" >> $GITHUB_ENV
+            echo "DEPLOY_ENV_LABEL=🔧 服务已成功部署到其他环境" >> $GITHUB_ENV
             echo "为其他分支 (${{ github.ref_name }}) 设置环境变量"
           fi
-        
+
       # 步骤3: 安装系统工具 (curl, jq) 并升级 Docker CLI 到 1.44+
       - name: 🔧 安装系统工具并升级 Docker CLI
         run: |
@@ -110,127 +114,224 @@ jobs:
           docker --version || true
           docker version || true
           echo "客户端 API 版本:" $(docker version --format '{{.Client.APIVersion}}')
-        
+
-      # 步骤4: 构建并发布到镜像仓库
+      # 步骤4: 构建镜像
-      - name: 📤 构建并发布到镜像仓库
+      - name: 🏗️ 构建镜像
         run: |
-          echo "开始构建并推送镜像..."
+          echo "开始构建镜像..."
           echo "仓库: ${{ env.REPO }}"
           echo "版本标签: ${{ env.VERSION }}"
           echo "分支标签: ${{ env.DOCKER_TAG_SUFFIX }}"
 
-          # 构建镜像，同时打上版本和分支两个标签
+          BUILD_TAG_ARGS="-t ${{ env.REPO }}:${{ env.VERSION }}"
+          if [ "${{ github.event_name }}" = "push" ]; then
+            BUILD_TAG_ARGS="$BUILD_TAG_ARGS -t ${{ env.REPO }}:${{ env.DOCKER_TAG_SUFFIX }}"
+          else
+            echo "PR事件仅构建版本标签，不推送镜像、不部署"
+          fi
+
           docker build -f Dockerfile \
             --platform linux/amd64 \
             --build-arg TARGETARCH=amd64 \
             --build-arg VERSION=${{ env.VERSION }} \
             --build-arg BUILDTIME=${{ env.BUILDTIME }} \
-            -t ${{ env.REPO }}:${{ env.VERSION }} \
+            $BUILD_TAG_ARGS \
-            -t ${{ env.REPO }}:${{ env.DOCKER_TAG_SUFFIX }} \
             .
-          
+
+          echo "镜像构建完成"
+
+      # 步骤5: 发布到镜像仓库
+      - name: 📤 发布到镜像仓库
+        if: github.event_name == 'push'
+        run: |
+          echo "开始推送镜像..."
+
           echo "推送版本标签镜像: ${{ env.REPO }}:${{ env.VERSION }}"
           docker push ${{ env.REPO }}:${{ env.VERSION }}
-          
+
           echo "推送分支标签镜像: ${{ env.REPO }}:${{ env.DOCKER_TAG_SUFFIX }}"
           docker push ${{ env.REPO }}:${{ env.DOCKER_TAG_SUFFIX }}
-          
+
           echo "镜像推送完成"
-          
+
-      # 调试: 打印 SSH 连接信息
+      # 步骤6: 调试 - 打印部署目标（不输出敏感信息）
-      - name: 🔍 调试 - 打印 SSH 连接信息
+      - name: 🔍 调试 - 打印部署目标
+        if: github.event_name == 'push'
         run: |
-          echo "========== SSH 连接信息调试 =========="
+          echo "========== 部署目标调试 =========="
           echo "当前分支: ${{ github.ref_name }}"
           echo "SSH_HOST: ${{ env.SSH_HOST }}"
           echo "SSH_PORT: ${{ env.SSH_PORT }}"
           echo "SSH_USER: ${{ env.SSH_USER }}"
-          echo "SSH_PASSWORD 长度: ${#SSH_PASSWORD}"
+          echo "SSH认证方式: 私钥 (AWS)"
-          echo "SSH_PASSWORD 前3位: $(echo "$SSH_PASSWORD" | cut -c1-3)***"
-          echo "SSH_PASSWORD 完整值: ${{ env.SSH_PASSWORD }}"
           echo "DEPLOY_PATH: ${{ env.DEPLOY_PATH }}"
           echo "====================================="
 
-      # 步骤5: 传输配置文件
+      # 步骤7: 传输配置文件
       - name: 📂 传输配置文件
+        if: github.event_name == 'push'
         uses: appleboy/scp-action@v0.1.7
         with:
           host: ${{ env.SSH_HOST }}
           username: ${{ env.SSH_USER }}
-          password: ${{ env.SSH_PASSWORD }}
+          key: ${{ env.SSH_KEY }}
           port: ${{ env.SSH_PORT }}
           source: "docker-compose.cloud.yml"
-          target: "${{ env.DEPLOY_PATH }}/"
+          target: "/tmp/ppanel-deploy/"
 
-      # 步骤6: 连接服务器更新并启动
+      # 步骤8: 连接服务器更新、健康检查并按需回滚
       - name: 🚀 连接服务器更新并启动
+        if: github.event_name == 'push'
         uses: appleboy/ssh-action@v1.0.3
         with:
           host: ${{ env.SSH_HOST }}
           username: ${{ env.SSH_USER }}
-          password: ${{ env.SSH_PASSWORD }}
+          key: ${{ env.SSH_KEY }}
           port: ${{ env.SSH_PORT }}
           timeout: 300s
           command_timeout: 600s
           script: |
+            set -e
+
             echo "连接服务器成功，开始部署..."
             echo "部署目录: ${{ env.DEPLOY_PATH }}"
             echo "部署标签: ${{ env.DOCKER_TAG_SUFFIX }}"
+            echo "登录用户: ${{ env.SSH_USER }}"
+
+            HEALTHCHECK_URL="http://127.0.0.1:8080/v1/common/heartbeat"
+            NEW_TAG="${{ env.DOCKER_TAG_SUFFIX }}"
+            ROLLBACK_TAG="rollback-${{ env.VERSION }}"
+            SUDO=""
+            if [ "${{ github.ref_name }}" = "main" ]; then
+              SUDO="sudo"
+            fi
+
+            docker_cmd() {
+              if [ -n "$SUDO" ]; then
+                sudo docker "$@"
+              else
+                docker "$@"
+              fi
+            }
+
+            compose_with_tag() {
+              tag="$1"
+              shift
+              if [ -n "$SUDO" ]; then
+                sudo env PPANEL_SERVER_TAG="$tag" docker-compose -f docker-compose.cloud.yml "$@"
+              else
+                PPANEL_SERVER_TAG="$tag" docker-compose -f docker-compose.cloud.yml "$@"
+              fi
+            }
+
+            write_previous_tag() {
+              if [ -n "$SUDO" ]; then
+                printf '%s\n' "${PREVIOUS_IMAGE_TAG:-}" | sudo tee .previous-ppanel-image-tag >/dev/null
+              else
+                printf '%s\n' "${PREVIOUS_IMAGE_TAG:-}" > .previous-ppanel-image-tag
+              fi
+            }
+
+            health_check() {
+              attempt=1
+              while [ "$attempt" -le 3 ]; do
+                if curl -sf "$HEALTHCHECK_URL"; then
+                  echo
+                  return 0
+                fi
+
+                echo "健康检查第 ${attempt}/3 次失败，10s 后重试..."
+                attempt=$((attempt + 1))
+                sleep 10
+              done
+
+              return 1
+            }
+
+            if [ "${{ github.ref_name }}" = "main" ]; then
+              sudo mkdir -p ${{ env.DEPLOY_PATH }}
+              sudo cp /tmp/ppanel-deploy/docker-compose.cloud.yml ${{ env.DEPLOY_PATH }}/docker-compose.cloud.yml
+            else
+              mkdir -p ${{ env.DEPLOY_PATH }}
+              cp /tmp/ppanel-deploy/docker-compose.cloud.yml ${{ env.DEPLOY_PATH }}/docker-compose.cloud.yml
+            fi
 
-            # 进入部署目录
             cd ${{ env.DEPLOY_PATH }}
-            
+
-            # 创建/更新环境变量文件
+            PREVIOUS_IMAGE_TAG="$(docker_cmd inspect --format '{{.Config.Image}}' ppanel-server 2>/dev/null || true)"
-            # echo "PPANEL_SERVER_TAG=${{ env.DOCKER_TAG_SUFFIX }}" > .env
+            PREVIOUS_IMAGE_ID="$(docker_cmd inspect --format '{{.Image}}' ppanel-server 2>/dev/null || true)"
-            
+            echo "上一版本镜像tag: ${PREVIOUS_IMAGE_TAG:-未发现}"
-            # 拉取最新镜像
+            echo "上一版本镜像ID: ${PREVIOUS_IMAGE_ID:-未发现}"
-            echo "📥 拉取镜像..."
+            write_previous_tag
-            docker-compose -f docker-compose.cloud.yml pull ppanel-server
+
-            
+            echo "📥 拉取镜像: ${{ env.REPO }}:${NEW_TAG}"
-            # 启动服务
+            compose_with_tag "$NEW_TAG" pull ppanel-server
             echo "🚀 启动服务..."
-            docker-compose -f docker-compose.cloud.yml up -d ppanel-server
+            compose_with_tag "$NEW_TAG" up -d ppanel-server
-            
+
-            # 清理未使用的镜像
+            echo "🩺 部署后健康检查: ${HEALTHCHECK_URL}"
-            docker image prune -f || true
+            if health_check; then
-            
+              docker_cmd image prune -f || true
-            echo "✅ 部署命令执行完成"
+              echo "✅ 部署后健康检查通过"
-            
+              echo "✅ 部署命令执行完成"
-      # 步骤6: TG通知 (成功)
+              exit 0
+            fi
+
+            echo "❌ 部署后健康检查连续 3 次失败，开始回滚..."
+            if [ -n "$PREVIOUS_IMAGE_ID" ]; then
+              docker_cmd tag "$PREVIOUS_IMAGE_ID" "${{ env.REPO }}:${ROLLBACK_TAG}"
+              echo "回滚镜像tag: ${{ env.REPO }}:${ROLLBACK_TAG}"
+              compose_with_tag "$ROLLBACK_TAG" up -d ppanel-server
+
+              echo "🩺 回滚后健康检查: ${HEALTHCHECK_URL}"
+              if health_check; then
+                echo "✅ 回滚后健康检查通过"
+              else
+                echo "❌ 回滚后健康检查仍失败"
+              fi
+            else
+              echo "未找到上一版本镜像ID，无法自动回滚"
+            fi
+
+            docker_cmd image prune -f || true
+            exit 1
+
+      # 步骤9: TG通知 (成功)
       - name: 📱 发送成功通知到Telegram
-        if: success()
+        if: success() && github.event_name == 'push'
         uses: appleboy/telegram-action@master
         with:
           token: ${{ env.TG_BOT_TOKEN }}
           to: ${{ env.TG_CHAT_ID }}
           message: |
             ✅ 部署成功！
-            
+
             📦 项目: ${{ github.repository }}
             🌿 分支: ${{ github.ref_name }}
             📝 提交: ${{ github.sha }}
             👤 提交者: ${{ github.actor }}
             🕐 时间: ${{ github.event.head_commit.timestamp }}
-            
+
-            🚀 服务已成功部署到生产环境
+            ${{ env.DEPLOY_ENV_LABEL }}
+            🩺 健康检查: 通过 (http://127.0.0.1:8080/v1/common/heartbeat)
           parse_mode: Markdown
-          
+
-      # 步骤5: TG通知 (失败)
+      # 步骤10: TG通知 (失败)
       - name: 📱 发送失败通知到Telegram
-        if: failure()
+        if: failure() && github.event_name == 'push'
         uses: appleboy/telegram-action@master
         with:
           token: ${{ env.TG_BOT_TOKEN }}
           to: ${{ env.TG_CHAT_ID }}
           message: |
             ❌ 部署失败！
-            
+
             📦 项目: ${{ github.repository }}
             🌿 分支: ${{ github.ref_name }}
             📝 提交: ${{ github.sha }}
             👤 提交者: ${{ github.actor }}
             🕐 时间: ${{ github.event.head_commit.timestamp }}
-            
+
+            🩺 健康检查: 失败或未完成；若新版本健康检查连续 3 次失败，已自动尝试回滚并重新检查
             ⚠️ 请检查构建日志获取详细信息
           parse_mode: Markdown
-          

apis/admin/log.api

@@ -149,6 +149,35 @@ type (
 		Total int64           `json:"total"`
 		List  []CommissionLog `json:"list"`
 	}
+	OrderRefundLog {
+		OrderId                int64  `json:"order_id"`
+		OrderNo                string `json:"order_no"`
+		OperatorUserId         int64  `json:"operator_user_id"`
+		OperatorAuthIdentifier string `json:"operator_auth_identifier,omitempty"`
+		TargetUserId           int64  `json:"target_user_id"`
+		UserSubscribeId        int64  `json:"user_subscribe_id"`
+		RefererUserId          int64  `json:"referer_user_id,omitempty"`
+		CommissionAmount       int64  `json:"commission_amount"`
+		Reason                 string `json:"reason,omitempty"`
+		OrderStatusBefore      uint8  `json:"order_status_before"`
+		OrderStatusAfter       uint8  `json:"order_status_after"`
+		SubscribeStatusBefore  uint8  `json:"subscribe_status_before"`
+		SubscribeStatusAfter   uint8  `json:"subscribe_status_after"`
+		SubscribeExpireBefore  int64  `json:"subscribe_expire_before"`
+		SubscribeExpireAfter   int64  `json:"subscribe_expire_after"`
+		CommissionBefore       int64  `json:"commission_before"`
+		CommissionAfter        int64  `json:"commission_after"`
+		Timestamp              int64  `json:"timestamp"`
+	}
+	FilterOrderRefundLogRequest {
+		FilterLogParams
+		OrderId int64 `form:"order_id,optional"`
+		UserId  int64 `form:"user_id,optional"`
+	}
+	FilterOrderRefundLogResponse {
+		Total int64            `json:"total"`
+		List  []OrderRefundLog `json:"list"`
+	}
 	GiftLog {
 		Type        uint16 `json:"type"`
 		userId      int64  `json:"user_id"`
@@ -239,6 +268,30 @@ type (
 		OccurredAt int64  `json:"occurred_at"`
 		CreatedAt  int64  `json:"created_at"`
 	}
+	GetLogMessageRawRequest {
+		Id int64 `form:"id" validate:"required"`
+	}
+	GetLogMessageRawResponse {
+		Id         int64       `json:"id"`
+		Platform   string      `json:"platform"`
+		AppVersion string      `json:"app_version"`
+		OsName     string      `json:"os_name"`
+		OsVersion  string      `json:"os_version"`
+		DeviceId   string      `json:"device_id"`
+		UserId     *int64      `json:"user_id"`
+		SessionId  string      `json:"session_id"`
+		Level      uint8       `json:"level"`
+		ErrorCode  string      `json:"error_code"`
+		Message    string      `json:"message"`
+		Stack      string      `json:"stack"`
+		Context    interface{} `json:"context"`
+		ClientIP   string      `json:"client_ip"`
+		UserAgent  string      `json:"user_agent"`
+		Locale     string      `json:"locale"`
+		Digest     string      `json:"digest"`
+		OccurredAt int64       `json:"occurred_at"`
+		CreatedAt  int64       `json:"created_at"`
+	}
 )
 
 @server (
@@ -291,6 +344,10 @@ service ppanel {
 	@handler FilterCommissionLog
 	get /commission/list (FilterCommissionLogRequest) returns (FilterCommissionLogResponse)
 
+	@doc "Filter order refund log"
+	@handler FilterOrderRefundLog
+	get /order/refund/list (FilterOrderRefundLogRequest) returns (FilterOrderRefundLogResponse)
+
 	@doc "Filter gift log"
 	@handler FilterGiftLog
 	get /gift/list (FilterGiftLogRequest) returns (FilterGiftLogResponse)
@@ -314,5 +371,9 @@ service ppanel {
 	@doc "Get error log message detail"
 	@handler GetErrorLogMessageDetail
 	get /error_message/detail returns (GetErrorLogMessageDetailResponse)
+
+	@doc "Get log message raw detail (temporary)"
+	@handler GetLogMessageRaw
+	get /message/detail (GetLogMessageRawRequest) returns (GetLogMessageRawResponse)
 }
 

apis/admin/order.api

@@ -33,6 +33,10 @@ type (
 		PaymentId int64  `json:"payment_id,omitempty"`
 		TradeNo   string `json:"trade_no,omitempty"`
 	}
+	RefundOrderRequest {
+		Id     int64  `json:"id" validate:"required"`
+		Reason string `json:"reason,omitempty" validate:"omitempty,max=500"`
+	}
 	ActivateOrderRequest {
 		OrderNo string `json:"order_no" validate:"required"`
 	}
@@ -68,6 +72,10 @@ service ppanel {
 	@handler UpdateOrderStatus
 	put /status (UpdateOrderStatusRequest)
 
+	@doc "Refund order"
+	@handler RefundOrder
+	post /refund (RefundOrderRequest)
+
 	@doc "Manually activate order"
 	@handler ActivateOrder
 	post /activate (ActivateOrderRequest)

apis/admin/user.api

@@ -38,20 +38,20 @@ type (
 		Id int64 `form:"id" validate:"required"`
 	}
 	UpdateUserBasiceInfoRequest {
-		UserId             int64  `json:"user_id" validate:"required"`
+		UserId             int64   `json:"user_id" validate:"required"`
-		Password           string `json:"password"`
+		Password           string  `json:"password"`
-		Avatar             string `json:"avatar"`
+		Avatar             string  `json:"avatar"`
-		Balance            int64  `json:"balance"`
+		Balance            *int64  `json:"balance"`
-		Commission         int64  `json:"commission"`
+		Commission         *int64  `json:"commission"`
-		ReferralPercentage uint8  `json:"referral_percentage"`
+		ReferralPercentage uint8   `json:"referral_percentage"`
-		OnlyFirstPurchase  *bool  `json:"only_first_purchase"`
+		OnlyFirstPurchase  *bool   `json:"only_first_purchase"`
-		GiftAmount         int64  `json:"gift_amount"`
+		GiftAmount         *int64  `json:"gift_amount"`
-		Telegram           int64  `json:"telegram"`
+		Telegram           int64   `json:"telegram"`
-		ReferCode          string `json:"refer_code"`
+		ReferCode          string  `json:"refer_code"`
-		RefererId          int64  `json:"referer_id"`
+		RefererId          *int64  `json:"referer_id"`
-		Enable             *bool  `json:"enable"`
+		Enable             *bool   `json:"enable"`
-		IsAdmin            *bool  `json:"is_admin"`
+		IsAdmin            *bool   `json:"is_admin"`
-		Remark             string `json:"remark"`
+		Remark             *string `json:"remark"`
 	}
 	UpdateUserNotifySettingRequest {
 		UserId                int64 `json:"user_id" validate:"required"`
@@ -230,6 +230,24 @@ type (
 		FamilyId int64  `json:"family_id" validate:"required,gt=0"`
 		Reason   string `json:"reason,omitempty"`
 	}
+	GetWithdrawalListRequest {
+		Page   int    `form:"page"`
+		Size   int    `form:"size"`
+		UserId *int64 `form:"user_id,omitempty"`
+		Status *uint8 `form:"status,omitempty"`
+		Method *uint8 `form:"method,omitempty"`
+	}
+	GetWithdrawalListResponse {
+		List  []WithdrawalLog `json:"list"`
+		Total int64           `json:"total"`
+	}
+	ApproveWithdrawalRequest {
+		WithdrawalId int64 `json:"withdrawal_id" validate:"required,gt=0"`
+	}
+	RejectWithdrawalRequest {
+		WithdrawalId int64  `json:"withdrawal_id" validate:"required,gt=0"`
+		Reason       string `json:"reason" validate:"required,max=500"`
+	}
 )
 
 @server (
@@ -370,5 +388,16 @@ service ppanel {
 	@doc "Dissolve family"
 	@handler DissolveFamily
 	put /family/dissolve (DissolveFamilyRequest)
-}
 
+	@doc "Get withdrawal list"
+	@handler GetWithdrawalList
+	get /withdrawal/list (GetWithdrawalListRequest) returns (GetWithdrawalListResponse)
+
+	@doc "Approve withdrawal"
+	@handler ApproveWithdrawal
+	post /withdrawal/approve (ApproveWithdrawalRequest)
+
+	@doc "Reject withdrawal"
+	@handler RejectWithdrawal
+	post /withdrawal/reject (RejectWithdrawalRequest)
+}

apis/public/file.api

@@ -11,6 +11,20 @@ info (
 import "../types.api"
 
 type (
+	FileUploadRequest {
+		BizType string `form:"biz_type" validate:"required"`
+	}
+
+	FileUploadResponse {
+		FileId      string `json:"file_id"`
+		FileName    string `json:"file_name"`
+		ObjectKey   string `json:"object_key"`
+		Size        int64  `json:"size"`
+		ContentType string `json:"content_type"`
+		Etag        string `json:"etag"`
+		Status      string `json:"status"`
+	}
+
 	FileUploadInitRequest {
 		BizType     string `json:"biz_type" validate:"required"`
 		FileName    string `json:"file_name" validate:"required"`
@@ -48,6 +62,10 @@ type (
 	middleware: AuthMiddleware,DeviceMiddleware
 )
 service ppanel {
+	@doc "Upload file to RustFS"
+	@handler FileUpload
+	post /upload (FileUploadRequest) returns (FileUploadResponse)
+
 	@doc "Init file upload"
 	@handler FileUploadInit
 	post /upload/init (FileUploadInitRequest) returns (FileUploadInitResponse)

apis/public/user.api

@@ -109,8 +109,11 @@ type (
 		Rules []string `json:"rules" validate:"required"`
 	}
 	CommissionWithdrawRequest {
-		Amount  int64  `json:"amount"`
+		Amount    int64  `json:"amount"`
-		Content string `json:"content"`
+		Content   string `json:"content"`
+		Method    uint8  `json:"method" validate:"oneof=0 1 2 3"`
+		Account   string `json:"account,omitempty"`
+		QrCodeUrl string `json:"qr_code_url,omitempty"`
 	}
 	WithdrawalLog {
 		Id        int64  `json:"id"`
@@ -119,9 +122,15 @@ type (
 		Content   string `json:"content"`
 		Status    uint8  `json:"status"`
 		Reason    string `json:"reason,omitempty"`
+		Method    uint8  `json:"method"`
+		Account   string `json:"account"`
+		QrCodeUrl string `json:"qr_code_url"`
 		CreatedAt int64  `json:"created_at"`
 		UpdatedAt int64  `json:"updated_at"`
 	}
+	CancelWithdrawalRequest {
+		WithdrawalId int64 `json:"withdrawal_id" validate:"required,gt=0"`
+	}
 	QueryWithdrawalLogListRequest {
 		Page int `form:"page"`
 		Size int `form:"size"`
@@ -352,6 +361,10 @@ service ppanel {
 	@handler CommissionWithdraw
 	post /commission_withdraw (CommissionWithdrawRequest) returns (WithdrawalLog)
 
+	@doc "Cancel pending withdrawal"
+	@handler CancelWithdrawal
+	post /withdrawal_cancel (CancelWithdrawalRequest) returns (WithdrawalLog)
+
 	@doc "Query Withdrawal Log"
 	@handler QueryWithdrawalLog
 	get /withdrawal_log (QueryWithdrawalLogListRequest) returns (QueryWithdrawalLogListResponse)

apis/types.api

@@ -27,6 +27,7 @@ type (
 		EnableLoginNotify     bool             `json:"enable_login_notify"`
 		EnableSubscribeNotify bool             `json:"enable_subscribe_notify"`
 		EnableTradeNotify     bool             `json:"enable_trade_notify"`
+		UseStatus             bool             `json:"use_status"` // Whether to show the "bind email to get free trial" prompt
 		AuthMethods           []UserAuthMethod `json:"auth_methods"`
 		UserDevices           []UserDevice     `json:"user_devices"`
 		Rules                 []string         `json:"rules"`
@@ -426,6 +427,7 @@ type (
 		FeeAmount      int64         `json:"fee_amount"`
 		TradeNo        string        `json:"trade_no"`
 		Status         uint8         `json:"status"`
+		StatusName     string        `json:"status_name,omitempty"`
 		SubscribeId    int64         `json:"subscribe_id"`
 		CreatedAt      int64         `json:"created_at"`
 		UpdatedAt      int64         `json:"updated_at"`
@@ -448,6 +450,7 @@ type (
 		FeeAmount      int64         `json:"fee_amount"`
 		TradeNo        string        `json:"trade_no"`
 		Status         uint8         `json:"status"`
+		StatusName     string        `json:"status_name,omitempty"`
 		SubscribeId    int64         `json:"subscribe_id"`
 		Subscribe      Subscribe     `json:"subscribe"`
 		CreatedAt      int64         `json:"created_at"`
@@ -1004,4 +1007,3 @@ type (
 		ConfigSnapshot map[string]interface{} `json:"config_snapshot,omitempty"`
 	}
 )
-

deploy/aws/ap-east-1/configs/replica-ops.env.example

@@ -17,7 +17,7 @@ REDIS_HOST=127.0.0.1
 REDIS_PORT=6379
 REDIS_PASSWORD=CHANGE_ME
 
-REDIS_SOURCE_HOST=43.198.248.161
+REDIS_SOURCE_HOST=18.163.33.75
 REDIS_SOURCE_PORT=6379
 REDIS_SOURCE_USER=
 REDIS_SOURCE_PASSWORD=CHANGE_ME

deploy/aws/ap-northeast-1/README.md

@@ -0,0 +1,358 @@
+# PPanel 日本东京区 AWS 部署说明
+
+本目录用于在 **AWS 日本东京区 `ap-northeast-1`** 重建一套全新生产环境，并承接当前香港区 `ap-east-1` 的正式迁移。
+
+如果你要看“当前已经真实跑起来的东京架构”，优先看：
+
+- [`ops/hifast-current-architecture-zh.md`](/Users/Apple/code_vpn/vpn/ppanel-server/ops/hifast-current-architecture-zh.md)
+- [`configs/resource-inventory.current.md`](./configs/resource-inventory.current.md)
+
+这份 README 更偏向：
+
+- 目标架构
+- 资源规划
+- 部署方法
+- 后续待完成项
+
+目标架构：
+
+`DNS -> ALB -> WAF -> EC2(Nginx + ppanel-server + Redis + observability) -> RDS MySQL`
+
+灾备链路：
+
+`RDS MySQL / EC2 Redis -> 104.238.220.230 外部灾备`
+
+当前仓库内已补充：
+
+- 东京基础设施参数模板：[`configs/aws-jp-infra.env.example`](./configs/aws-jp-infra.env.example)
+- 东京真实实施状态登记：[`configs/resource-inventory.current.md`](./configs/resource-inventory.current.md)
+- 东京底座资源创建脚本：[`../../scripts/aws_jp_create_base_infra.sh`](../../scripts/aws_jp_create_base_infra.sh)
+- 东京资源状态检查脚本：[`../../scripts/aws_jp_describe_state.sh`](../../scripts/aws_jp_describe_state.sh)
+- MySQL 备份脚本：[`../../scripts/mysql_backup_to_s3.sh`](../../scripts/mysql_backup_to_s3.sh)
+- 10 分钟 MySQL 备份定时器安装脚本：[`../../scripts/install_mysql_backup_timer.sh`](../../scripts/install_mysql_backup_timer.sh)
+
+## 1. 资源清单
+
+按下面顺序创建资源：
+
+1. VPC
+2. 2 个公有子网 + 2 个私有子网
+3. Internet Gateway
+4. 公有 / 私有路由表
+5. 安全组
+6. RDS MySQL
+7. EC2 本机 Redis Docker
+8. EC2
+9. ACM 证书
+10. ALB + Target Group
+11. WAF Web ACL
+12. 东京平行环境域名
+13. 东京 S3 备份桶
+
+建议命名：
+
+- VPC: `ppanel-jp-prod`
+- EC2: `ppanel-app-jp-01`
+- RDS: `ppanel-mysql-jp`
+- Redis container: `hifast-redis`
+- ALB: `ppanel-alb-jp`
+- WAF: `ppanel-waf-jp`
+- S3: `hifast-prod-backups-200810848252-ap-northeast-1`
+
+## 2. 默认规格
+
+### EC2
+
+- Region: `ap-northeast-1`
+- OS: Ubuntu 24.04 LTS
+- Instance type: `t4g.large`
+- Disk: `gp3 80GB`
+- Public subnet: 是
+- IAM Role:
+  - 允许读取 CloudWatch / SSM（如使用）
+  - 如果要在东京 EC2 上执行 S3 备份：额外允许写入东京备份桶
+
+### RDS MySQL
+
+- Engine: `MySQL 8.4`
+- Class: `db.r7g.xlarge`
+- Storage: `gp3 100GB`
+- DB name: `hifast`
+- Username: `admin`
+- Public access: `Yes`
+- Charset: `utf8mb4`
+- Backup retention: `7-14 days`
+- Deletion protection: `On`
+- Multi-AZ: `Yes`（当前按 2 实例 Multi-AZ 创建）
+
+说明：
+
+- 当前东京 RDS 需要允许 `104.238.220.230` 从公网直连 `3306`，用于外部 MySQL 从库复制
+- 因此本阶段 RDS 使用 `public subnet group + Publicly accessible = Yes`
+- 访问面只通过 `sg-rds` 严格限制到业务 EC2 安全组和 `104.238.220.230/32`
+
+### Redis
+
+- 部署位置：业务 EC2 本机
+- 部署方式：Docker
+- 版本：`redis:8.2.1`
+- 监听：`0.0.0.0:6379`
+- 应用连接：`127.0.0.1:6379`
+- 安全组：仅对白名单备用节点 `104.238.220.230/32` 或同机应用开放
+
+## 3. 网络与安全组
+
+### 子网布局
+
+- `public-a`, `public-c`: ALB / EC2
+- `private-a`, `private-c`: RDS
+
+说明：
+
+- 东京优先使用 `ap-northeast-1a` 和 `ap-northeast-1c`
+- 如果账户映射不同，也可以用任意 2 个可用区，但公私网必须各 2 个子网
+
+### 安全组建议
+
+#### `sg-alb`
+
+- Inbound
+  - `80/tcp` from `0.0.0.0/0`
+  - `443/tcp` from `0.0.0.0/0`
+- Outbound
+  - `80/tcp` to `sg-ec2`
+
+#### `sg-ec2`
+
+- Inbound
+  - `80/tcp` from `sg-alb`
+  - `22/tcp` from `你的固定运维 IP`
+  - `6379/tcp` from `104.238.220.230/32`
+- Outbound
+  - all
+
+说明：
+
+- 应用容器监听 `127.0.0.1:8080`
+- EC2 对外只让 Nginx 监听 `80`
+- Grafana / Prometheus / Tempo 仅监听 `127.0.0.1`
+
+#### `sg-rds`
+
+- Inbound
+  - `3306/tcp` from `sg-ec2`
+  - `3306/tcp` from `104.238.220.230/32`
+
+## 4. ALB / Target Group / 健康检查
+
+### Target Group
+
+- Type: `Instance`
+- Protocol: `HTTP`
+- Port: `80`
+- Health check path: `/v1/common/heartbeat`
+- Success code: `200`
+
+### ALB 监听器
+
+- `80` -> redirect to `443`
+- `443` -> forward 到 target group
+
+### ACM
+
+- 在 `ap-northeast-1` 重新申请证书
+- 先给平行环境域名，例如：
+  - `api-jp.hifast.biz`
+  - `logs-jp.hifast.biz`
+
+## 5. WAF 规则
+
+首版至少启用：
+
+1. `AWSManagedRulesCommonRuleSet`
+2. `AWSManagedRulesKnownBadInputsRuleSet`
+3. `AWSManagedRulesAmazonIpReputationList`
+4. 全站 rate-based rule
+5. 针对高风险路径的 rate-based rule
+
+建议的第一版限流：
+
+- 全站：每 IP `2000 / 5 分钟`
+- `/v1/public/user/subscribe`：每 IP `300 / 5 分钟`
+- 登录 / 注册 / 验证码接口：每 IP `100 / 5 分钟`
+
+节点上报接口建议后续补：
+
+- `/v1/server/status`
+- `/v1/server/online`
+- `/v1/server/traffic`
+
+## 6. EC2 文件落地
+
+在 EC2 上建议使用：
+
+- 应用目录：`/opt/ppanel`
+- Nginx 配置：`/etc/nginx/sites-available/ppanel-api.conf`
+
+需要上传这些文件 / 目录：
+
+- `docker-compose.cloud.yml`
+- `deploy/aws/ap-northeast-1/configs/ppanel.yaml.example` -> 重命名为 `configs/ppanel.yaml`
+- `deploy/aws/ap-northeast-1/nginx/ppanel-api.conf`
+- `grafana/`
+- `loki/`
+- `prometheus/`
+- `tempo/`
+- `.env.example` -> 重命名为 `.env`
+
+目标目录示例：
+
+```text
+/opt/ppanel/
+  docker-compose.cloud.yml
+  .env
+  configs/ppanel.yaml
+  grafana/
+  loki/
+  prometheus/
+  tempo/
+  logs/
+  cache/
+  tempo_data/
+```
+
+## 7. 应用配置
+
+基线模板见：
+
+- [`configs/ppanel.yaml.example`](./configs/ppanel.yaml.example)
+- [`nginx/ppanel-api.conf`](./nginx/ppanel-api.conf)
+
+关键值必须替换：
+
+- `MySQL.Addr`
+- `MySQL.Password`
+- `Redis.Host`
+- `Redis.Pass`
+- `JwtAuth.AccessSecret`
+- `Administrator.Email`
+- `Administrator.Password`
+- `AppSignature.AppSecrets.*`
+- `device.security_secret`
+- `Site.Host`
+- `Site.SiteName`
+
+Redis 约定保持不变：
+
+- 业务缓存：DB `0`
+- Asynq：DB `5`
+
+## 8. 部署步骤
+
+### 8.0 创建东京基础设施
+
+如果本机或跳板机已经配置好 AWS CLI 凭据，可以先直接执行：
+
+```bash
+cp deploy/aws/ap-northeast-1/configs/aws-jp-infra.env.example /root/aws-jp-infra.env
+chmod 600 /root/aws-jp-infra.env
+vim /root/aws-jp-infra.env
+
+chmod +x deploy/scripts/aws_jp_create_base_infra.sh
+bash deploy/scripts/aws_jp_create_base_infra.sh /root/aws-jp-infra.env
+```
+
+执行后可用下面命令随时核对东京底座状态：
+
+```bash
+chmod +x deploy/scripts/aws_jp_describe_state.sh
+bash deploy/scripts/aws_jp_describe_state.sh /root/aws-jp-infra.env
+```
+
+### 8.1 初始化 EC2
+
+把脚本上传到东京 EC2 后执行：
+
+```bash
+chmod +x deploy/scripts/bootstrap_aws_ec2.sh
+sudo APP_DIR=/opt/ppanel APP_USER=ubuntu deploy/scripts/bootstrap_aws_ec2.sh
+```
+
+### 8.2 安装 Nginx 配置
+
+```bash
+sudo cp deploy/aws/ap-northeast-1/nginx/ppanel-api.conf /etc/nginx/sites-available/ppanel-api.conf
+sudo ln -sf /etc/nginx/sites-available/ppanel-api.conf /etc/nginx/sites-enabled/ppanel-api.conf
+sudo nginx -t
+sudo systemctl reload nginx
+```
+
+### 8.3 启动容器
+
+```bash
+cd /opt/ppanel
+docker compose -f docker-compose.cloud.yml up -d
+```
+
+### 8.4 预检
+
+```bash
+chmod +x deploy/scripts/preflight_aws_jp.sh
+APP_DIR=/opt/ppanel \
+RDS_HOST=<TOKYO_RDS_ENDPOINT> \
+REDIS_HOST=127.0.0.1 \
+deploy/scripts/preflight_aws_jp.sh
+```
+
+## 9. 数据迁移与切换
+
+正式迁移请按：
+
+- [`ops/hifast-aws-jp-migration-runbook-zh.md`](/Users/Apple/code_vpn/vpn/ppanel-server/ops/hifast-aws-jp-migration-runbook-zh.md)
+
+执行。
+
+核心原则：
+
+- 先搭平行环境
+- 停机后再导出香港主数据
+- 东京验收通过后再切正式域名
+- 切换后再重挂 `104` 灾备
+
+## 10. 104 灾备节点常用模板
+
+如果迁移完成后要把 `104.238.220.230` 重挂为东京主站从库，可复用：
+
+- [`deploy/scripts/hifast_mysql_seed_primary_and_replica.sh`](/Users/Apple/code_vpn/vpn/ppanel-server/deploy/scripts/hifast_mysql_seed_primary_and_replica.sh)
+- [`deploy/scripts/hifast_mysql_attach_replica.sh`](/Users/Apple/code_vpn/vpn/ppanel-server/deploy/scripts/hifast_mysql_attach_replica.sh)
+- [`deploy/scripts/hifast_redis_attach_replica.sh`](/Users/Apple/code_vpn/vpn/ppanel-server/deploy/scripts/hifast_redis_attach_replica.sh)
+- [`deploy/scripts/hifast_data_sync_tool.sh`](/Users/Apple/code_vpn/vpn/ppanel-server/deploy/scripts/hifast_data_sync_tool.sh)
+- [`configs/replica-ops.env.example`](./configs/replica-ops.env.example)
+
+## 11. 东京资源创建前置检查
+
+在 AWS 控制台里至少先确认：
+
+- 东京区已启用
+- `ap-northeast-1` 可创建 `t4g.large`
+- `ap-northeast-1` RDS 可创建 `db.r7g.xlarge`
+- ACM / ALB / WAF / S3 服务在东京区可正常使用
+- Tokyo 对应配额满足：
+  - On-Demand Standard vCPU
+  - ALB 数量
+  - Elastic IP（如需）
+  - RDS 实例数
+
+## 12. 当前已知真实进度
+
+截至 `2026-05-20`，已知状态如下：
+
+- 东京 VPC `ppanel-jp-prod` 已创建
+- VPC ID: `vpc-0846b23b4a7d64eac`
+- VPC CIDR: `10.20.0.0/16`
+- 4 个子网在 AWS 控制台里曾填写完成，但提交时控制台 session 失效
+- 因此：
+  - 子网是否真正创建成功，需要重新核实
+  - IGW / 路由表 / 安全组 / RDS / EC2 / ALB / WAF 都应按“未完成”处理，重新复核
+
+实时状态请以后续更新的 [`configs/resource-inventory.current.md`](./configs/resource-inventory.current.md) 为准。

deploy/aws/ap-northeast-1/configs/aws-jp-infra.env.example

@@ -0,0 +1,55 @@
+AWS_REGION=ap-northeast-1
+AWS_ACCOUNT_ID=200810848252
+
+VPC_NAME=ppanel-jp-prod
+VPC_ID=
+VPC_CIDR=10.20.0.0/16
+
+PUBLIC_SUBNET_A_NAME=ppanel-jp-public-a
+PUBLIC_SUBNET_A_AZ=ap-northeast-1a
+PUBLIC_SUBNET_A_CIDR=10.20.0.0/24
+
+PUBLIC_SUBNET_C_NAME=ppanel-jp-public-c
+PUBLIC_SUBNET_C_AZ=ap-northeast-1c
+PUBLIC_SUBNET_C_CIDR=10.20.1.0/24
+
+PRIVATE_SUBNET_A_NAME=ppanel-jp-private-a
+PRIVATE_SUBNET_A_AZ=ap-northeast-1a
+PRIVATE_SUBNET_A_CIDR=10.20.10.0/24
+
+PRIVATE_SUBNET_C_NAME=ppanel-jp-private-c
+PRIVATE_SUBNET_C_AZ=ap-northeast-1c
+PRIVATE_SUBNET_C_CIDR=10.20.11.0/24
+
+IGW_NAME=ppanel-jp-igw
+PUBLIC_ROUTE_TABLE_NAME=ppanel-jp-public-rt
+PRIVATE_ROUTE_TABLE_NAME=ppanel-jp-private-rt
+
+SG_ALB_NAME=ppanel-jp-sg-alb
+SG_EC2_NAME=ppanel-jp-sg-ec2
+SG_RDS_NAME=ppanel-jp-sg-rds
+
+OPS_SSH_CIDR=CHANGE_ME_TO_YOUR_FIXED_PUBLIC_IP_OR_CIDR
+DR_REPLICA_IP=104.238.220.230/32
+
+EC2_NAME=ppanel-app-jp-01
+EC2_AMI_FAMILY=ubuntu-24.04
+EC2_INSTANCE_TYPE=t4g.large
+EC2_DISK_GB=80
+EC2_KEY_PAIR=CHANGE_ME
+
+RDS_IDENTIFIER=ppanel-mysql-jp
+RDS_DB_NAME=hifast
+RDS_ADMIN_USER=admin
+RDS_INSTANCE_CLASS=db.r7g.xlarge
+RDS_STORAGE_GB=100
+
+ALB_NAME=ppanel-alb-jp
+TARGET_GROUP_NAME=ppanel-tg-jp
+WAF_NAME=ppanel-waf-jp
+
+PARALLEL_API_DOMAIN=api-jp.hifast.biz
+PARALLEL_LOGS_DOMAIN=logs-jp.hifast.biz
+PRODUCTION_API_DOMAIN=CHANGE_ME
+
+S3_BACKUP_BUCKET=hifast-prod-backups-200810848252-ap-northeast-1

deploy/aws/ap-northeast-1/configs/backup-to-s3.env.example

@@ -0,0 +1,19 @@
+AWS_REGION=ap-northeast-1
+S3_BUCKET=hifast-prod-backups-200810848252-ap-northeast-1
+S3_PREFIX=mysql
+BACKUP_DIR=/var/backups/hifast
+HOST_TAG=104-standby-for-jp
+KEEP_LOCAL_DAYS=3
+CHECK_REPLICA=1
+
+MYSQL_HOST=127.0.0.1
+MYSQL_PORT=3306
+MYSQL_USER=backup_reader
+MYSQL_PASSWORD=CHANGE_ME
+MYSQL_SOCKET=
+MYSQL_DATABASE=hifast
+
+REDIS_HOST=127.0.0.1
+REDIS_PORT=6379
+REDIS_PASSWORD=CHANGE_ME
+

deploy/aws/ap-northeast-1/configs/mysql-seed-primary-and-replica.env.example

@@ -0,0 +1,21 @@
+PRIMARY_HOST=ppanel-mysql-jp.<CHANGE_ME>.ap-northeast-1.rds.amazonaws.com
+PRIMARY_PORT=3306
+PRIMARY_USER=admin
+PRIMARY_PASSWORD=CHANGE_ME
+PRIMARY_DB=hifast
+
+PRIMARY_REPL_USER=repl
+PRIMARY_REPL_PASSWORD=CHANGE_ME
+PRIMARY_REPL_HOST=104.238.220.230
+PRIMARY_BINLOG_RETENTION_HOURS=24
+
+REPLICA_HOST=127.0.0.1
+REPLICA_PORT=3306
+REPLICA_USER=root
+REPLICA_PASSWORD=
+REPLICA_SOCKET=/var/run/mysqld/mysqld.sock
+REPLICA_DB=hifast
+REPLICA_SOURCE_SSL=1
+
+DUMP_FILE=
+

deploy/aws/ap-northeast-1/configs/ppanel.yaml.example

@@ -0,0 +1,112 @@
+Host: 0.0.0.0
+Port: 8080
+Debug: false
+
+JwtAuth:
+  AccessSecret: CHANGE_ME_TO_A_LONG_RANDOM_SECRET
+  AccessExpire: 604800
+
+Logger:
+  ServiceName: PPanel
+  Mode: console
+  Encoding: plain
+  TimeFormat: "2006-01-02 15:04:05.000"
+  Path: logs
+  Level: info
+  MaxContentLength: 0
+  Compress: false
+  Stat: true
+  KeepDays: 7
+  StackCooldownMillis: 100
+  MaxBackups: 7
+  MaxSize: 100
+  Rotation: daily
+  FileTimeFormat: "2006-01-02T15:04:05.000Z07:00"
+
+MySQL:
+  Addr: YOUR_TOKYO_RDS_ENDPOINT:3306
+  Dbname: hifast
+  Username: admin
+  Password: CHANGE_ME_TO_TOKYO_RDS_PASSWORD
+  Config: charset=utf8mb4&parseTime=true&loc=Asia%2FTokyo
+  MaxIdleConns: 10
+  MaxOpenConns: 100
+  SlowThreshold: 1000
+
+Redis:
+  Host: 127.0.0.1:6379
+  Pass: CHANGE_ME_TO_TOKYO_REDIS_PASSWORD
+  DB: 0
+  PoolSize: 100
+  MinIdleConns: 10
+  MaxRetries: 3
+  PoolTimeout: 4
+  IdleTimeout: 300
+  MaxConnAge: 0
+  DialTimeout: 5
+  ReadTimeout: 3
+  WriteTimeout: 3
+
+Trace:
+  Name: ppanel-server
+  Endpoint: 127.0.0.1:4317
+  Sampler: 0.1
+  Batcher: otlpgrpc
+
+Site:
+  Host: api-jp.hifast.biz
+  SiteName: HiFastVPN
+
+Administrator:
+  Email: admin@example.com
+  Password: CHANGE_ME_TO_STRONG_ADMIN_PASSWORD
+
+Telegram:
+  Enable: false
+  BotID: 0
+  BotName: ""
+  BotToken: ""
+  GroupChatID: ""
+  EnableNotify: false
+  WebHookDomain: ""
+
+Kutt:
+  Enable: false
+  ApiURL: ""
+  ApiKey: ""
+  TargetURL: ""
+  Domain: ""
+
+OpenInstall:
+  Enable: false
+  AppKey: ""
+  ApiKey: ""
+
+Loki:
+  Enable: true
+  URL: "http://localhost:3100"
+
+AppSignature:
+  AppSecrets:
+    android-client: CHANGE_ME_ANDROID_SIGNATURE_SECRET
+    ios-client: CHANGE_ME_IOS_SIGNATURE_SECRET
+    web-client: CHANGE_ME_WEB_SIGNATURE_SECRET
+  ValidWindowSeconds: 300
+  SkipPrefixes:
+    - /v1/notify/
+    - /v1/iap/notifications
+    - /v1/telegram/webhook
+    - /v1/subscribe/config
+
+Signature:
+  EnableSignature: false
+
+device:
+  enable: true
+  security_secret: CHANGE_ME_DEVICE_SECURITY_SECRET
+
+Register:
+  EnableTrial: true
+  EnableTrialEmailWhitelist: true
+  TrialEmailDomainWhitelist: "gmail.com,outlook.com,icloud.com,qq.com,163.com"
+

deploy/aws/ap-northeast-1/configs/replica-ops.env.example

@@ -0,0 +1,23 @@
+MYSQL_HOST=127.0.0.1
+MYSQL_PORT=3306
+MYSQL_USER=root
+MYSQL_PASSWORD=CHANGE_ME
+MYSQL_SOCKET=
+
+REPL_SOURCE_HOST=ppanel-mysql-jp.cpo0keikgh80.ap-northeast-1.rds.amazonaws.com
+REPL_SOURCE_PORT=3306
+REPL_SOURCE_USER=repl
+REPL_SOURCE_PASSWORD=XwWrQGVWtxmXJ3etHmkFvnRSD54MKYer
+REPL_SOURCE_SSL=1
+REPL_SOURCE_LOG_FILE=mysql-bin-changelog.000189
+REPL_SOURCE_LOG_POS=185053
+REPL_SOURCE_AUTO_POSITION=1
+
+REDIS_HOST=127.0.0.1
+REDIS_PORT=6379
+REDIS_PASSWORD=CHANGE_ME
+
+REDIS_SOURCE_HOST=3.114.29.208
+REDIS_SOURCE_PORT=6379
+REDIS_SOURCE_USER=
+REDIS_SOURCE_PASSWORD=hifast67yj

deploy/aws/ap-northeast-1/configs/resource-inventory.current.md

@@ -0,0 +1,187 @@
+# Tokyo Resource Inventory
+
+最后更新：`2026-05-21`
+
+这个文件记录当前东京迁移的真实实施状态，不是示例。
+
+## Region
+
+- AWS account: `hifastvpn (200810848252)`
+- Region: `ap-northeast-1`
+
+## Current Status
+
+- 东京迁移方案已在仓库内落地为执行资产
+- 东京 VPC 已创建
+- 东京子网、IGW、路由表已在 AWS 控制台创建并复核
+- 东京三层安全组已在 AWS 控制台创建并复核
+- 东京 VPC DNS 开关已开启，可支持公网可访问 RDS
+- 东京 S3 备份桶已在 AWS 控制台创建并复核
+- 东京 ACM 证书请求已创建，等待 DNS 验证
+- 东京 RDS MySQL 已创建完成并可用
+- 东京业务 EC2 已创建完成并绑定固定 EIP
+- 因当前本机没有可用 AWS CLI 凭据，云上资源状态仍需在 AWS 控制台或已登录环境中复查
+
+## Networking
+
+- VPC
+  - Name: `ppanel-jp-prod`
+  - VPC ID: `vpc-0846b23b4a7d64eac`
+  - CIDR: `10.20.0.0/16`
+  - Status: `created`
+- Public subnet A
+  - Name: `ppanel-jp-public-a`
+  - AZ: `ap-northeast-1a`
+  - CIDR: `10.20.0.0/24`
+  - Subnet ID: `subnet-091232bdb53e71490`
+  - Status: `created`
+- Public subnet C
+  - Name: `ppanel-jp-public-c`
+  - AZ: `ap-northeast-1c`
+  - CIDR: `10.20.1.0/24`
+  - Subnet ID: `subnet-01ba0975c525ce8cf`
+  - Status: `created`
+- Private subnet A
+  - Name: `ppanel-jp-private-a`
+  - AZ: `ap-northeast-1a`
+  - CIDR: `10.20.10.0/24`
+  - Subnet ID: `subnet-0bd13111c02f0edbe`
+  - Status: `created`
+- Private subnet C
+  - Name: `ppanel-jp-private-c`
+  - AZ: `ap-northeast-1c`
+  - CIDR: `10.20.11.0/24`
+  - Subnet ID: `subnet-0d86c5c756dbc84b2`
+  - Status: `created`
+- Internet Gateway
+  - Name: `ppanel-jp-igw`
+  - IGW ID: `igw-028041bcbf63b672c`
+  - Status: `created`
+- Public route table
+  - Name: `ppanel-jp-public-rt`
+  - Route Table ID: `rtb-061b101080e4800e5`
+  - Default route: `0.0.0.0/0 -> igw-028041bcbf63b672c`
+  - Status: `created`
+- Private route table
+  - Name: `ppanel-jp-private-rt`
+  - Route Table ID: `rtb-0d7a191a515031c45`
+  - Status: `created`
+
+## Security
+
+- `sg-alb`
+  - Name: `ppanel-jp-sg-alb`
+  - Security Group ID: `sg-0b3a23c31041a5a5a`
+  - Inbound:
+    - `80/tcp <- 0.0.0.0/0`
+    - `443/tcp <- 0.0.0.0/0`
+  - Status: `created`
+- `sg-ec2`
+  - Name: `ppanel-jp-sg-ec2`
+  - Security Group ID: `sg-01f2a5a81e7505c91`
+  - Inbound:
+    - `80/tcp <- sg-0b3a23c31041a5a5a`
+    - `22/tcp <- 64.118.144.142/32`
+    - `6379/tcp <- 104.238.220.230/32`
+  - Status: `created`
+- `sg-rds`
+  - Name: `ppanel-jp-sg-rds`
+  - Security Group ID: `sg-0b71db1e2c18b57c0`
+  - Inbound:
+    - `3306/tcp <- sg-01f2a5a81e7505c91`
+    - `3306/tcp <- 104.238.220.230/32`
+  - Status: `created`
+
+## Compute / Database / Edge
+
+- EC2 `ppanel-app-jp-01`:
+  - Instance ID: `i-07839130074cd7ed9`
+  - Type: `c7i.xlarge`
+  - Platform: `Ubuntu 26.04 / Linux`
+  - AZ: `ap-northeast-1c`
+  - VPC: `ppanel-jp-prod (vpc-0846b23b4a7d64eac)`
+  - Subnet: `ppanel-jp-public-c (subnet-01ba0975c525ce8cf)`
+  - Private IP: `10.20.1.168`
+  - Public IP / Elastic IP: `3.114.29.208`
+  - Public DNS: `ec2-3-114-29-208.ap-northeast-1.compute.amazonaws.com`
+  - Security group: `ppanel-jp-sg-ec2 (sg-01f2a5a81e7505c91)`
+  - Key pair: `ppanel-jp-key-20260521`
+  - Root volume: `gp3 100GiB`
+  - ENI: `eni-08accb427a470c9f7`
+  - EIP allocation ID: `eipalloc-038b32d5c0119accf`
+  - EIP association ID: `eipassoc-09184aa9161b6a4d9`
+  - Status: `running`
+  - SSH recovery private key: `deploy/aws/ap-northeast-1/keys/ppanel-jp-recovery`
+  - SSH recovery public key: `deploy/aws/ap-northeast-1/keys/ppanel-jp-recovery.pub`
+- RDS subnet group:
+  - Name: `ppanel-jp-rds-subnet-group`
+  - VPC: `vpc-0846b23b4a7d64eac`
+  - Subnets:
+    - `subnet-0bd13111c02f0edbe` / `ppanel-jp-private-a`
+    - `subnet-0d86c5c756dbc84b2` / `ppanel-jp-private-c`
+  - Status: `created`
+- RDS public subnet group:
+  - Name: `ppanel-jp-rds-public-subnet-group`
+  - VPC: `vpc-0846b23b4a7d64eac`
+  - Subnets:
+    - `subnet-091232bdb53e71490` / `ppanel-jp-public-a`
+    - `subnet-01ba0975c525ce8cf` / `ppanel-jp-public-c`
+  - Status: `created`
+- RDS `ppanel-mysql-jp`:
+  - Engine: `MySQL Community 8.4.8`
+  - Class: `db.r7g.xlarge`
+  - Storage: `gp3 100GiB`
+  - Deployment: `Single instance (current actual state)`
+  - VPC: `ppanel-jp-prod (vpc-0846b23b4a7d64eac)`
+  - Subnet group: `ppanel-jp-rds-public-subnet-group`
+  - Security group: `ppanel-jp-sg-rds (sg-0b71db1e2c18b57c0)`
+  - Master username: `admin`
+  - Credential management: `self-managed`
+  - Secrets Manager managed password: `disabled`
+  - Current master password visibility: `not retrievable from AWS console; reset only`
+  - Public access: `enabled (set at creation time for external replication)`
+  - Status: `available`
+  - Endpoint: `ppanel-mysql-jp.cpo0keikgh80.ap-northeast-1.rds.amazonaws.com`
+  - Public IP (resolved via public DNS): `52.196.204.186`
+  - Connection test from Tokyo EC2:
+    - `mysql -h ppanel-mysql-jp.cpo0keikgh80.ap-northeast-1.rds.amazonaws.com -u admin -e "select 1"`
+    - Result: `ERROR 1045 (28000): Access denied for user 'admin'@'ip-10-20-1-168.ap-northeast-1.compute.internal' (using password: NO)`
+    - Meaning: `network path and security group are working; only the password is missing`
+  - Current admin password: `TkyRds20260521!N9mQ8sKe2vLp7Xa`
+  - External replica prep for `104.238.220.230`:
+    - binlog retention hours: `24`
+    - replication user: `repl@104.238.220.230`
+    - replication password: `XwWrQGVWtxmXJ3etHmkFvnRSD54MKYer`
+    - current binlog file: `mysql-bin-changelog.000189`
+    - current binlog position: `185053`
+- ALB `ppanel-alb-jp`: `not created`
+- WAF `ppanel-waf-jp`: `not created`
+- ACM certificate in `ap-northeast-1`:
+  - Certificate ID: `29d0b9b6-ab37-44d9-ad9e-18fa7e9aae3a`
+  - Domains:
+    - `api-jp.hifast.biz`
+    - `logs-jp.hifast.biz`
+  - Status: `pending_validation`
+  - Route 53 hosted zone in current AWS account: `not found`
+- S3 backup bucket `hifast-prod-backups-200810848252-ap-northeast-1`: `created`
+
+## Domains
+
+- Parallel API domain: `api-jp.hifast.biz`
+- Parallel logs domain: `logs-jp.hifast.biz`
+- Production API domain: `pending user final confirmation`
+- ACM DNS validation records pending external DNS add:
+  - `api-jp.hifast.biz`
+    - Name: `_0de5970dfbadaf46759447b2ea627a10.api-jp.hifast.biz.`
+    - Type: `CNAME`
+    - Value: `_6a632a5b85c5b3f304cc492090b741b3.jkddzztszm.acm-validations.aws.`
+  - `logs-jp.hifast.biz`
+    - Name: `_349a2b2bc4678d76c3ab341ccf73db61.logs-jp.hifast.biz.`
+    - Type: `CNAME`
+    - Value: `_74ced20dc96aa39070188605cf0ced18.jkddzztszm.acm-validations.aws.`
+
+## DR
+
+- DR host: `104.238.220.230`
+- Planned MySQL upstream after cutover: `Tokyo RDS`
+- Planned Redis upstream after cutover: `Tokyo EC2 public IP`

deploy/aws/ap-northeast-1/configs/resource-inventory.example.md

@@ -0,0 +1,69 @@
+# Tokyo Resource Inventory Example
+
+Use this file as the single source of truth while building the Tokyo environment.
+
+## Region
+
+- AWS account: `hifastvpn (200810848252)`
+- Region: `ap-northeast-1`
+
+## DNS
+
+- Production API domain: `CHANGE_ME`
+- Parallel API domain: `api-jp.hifast.biz`
+- Parallel logs domain: `logs-jp.hifast.biz`
+
+## Networking
+
+- VPC name: `ppanel-jp-prod`
+- VPC CIDR: `10.20.0.0/16`
+- Public subnet A: `10.20.0.0/24`
+- Public subnet C: `10.20.1.0/24`
+- Private subnet A: `10.20.10.0/24`
+- Private subnet C: `10.20.11.0/24`
+- Ops CIDR for SSH: `CHANGE_ME`
+
+## Compute
+
+- EC2 name: `ppanel-app-jp-01`
+- EC2 type: `t4g.large`
+- EC2 disk: `gp3 80GB`
+- SSH key pair: `CHANGE_ME`
+
+## Database
+
+- RDS identifier: `ppanel-mysql-jp`
+- RDS engine: `MySQL 8.4`
+- RDS class: `db.r7g.xlarge`
+- RDS storage: `gp3 100GB`
+- DB name: `hifast`
+- DB admin user: `admin`
+
+## Cache
+
+- Redis container: `hifast-redis`
+- Redis port: `6379`
+- Redis password: `CHANGE_ME`
+
+## Security / Secrets
+
+- JWT secret: `CHANGE_ME`
+- Admin email: `CHANGE_ME`
+- Admin password: `CHANGE_ME`
+- Android app signature secret: `CHANGE_ME`
+- iOS app signature secret: `CHANGE_ME`
+- Web app signature secret: `CHANGE_ME`
+- Device security secret: `CHANGE_ME`
+
+## Backup
+
+- S3 backup bucket: `hifast-prod-backups-200810848252-ap-northeast-1`
+- Versioning: `Enabled`
+
+## DR
+
+- DR host: `104.238.220.230`
+- MySQL repl user: `repl`
+- MySQL repl password: `CHANGE_ME`
+- Redis source password: `CHANGE_ME`
+

deploy/aws/ap-northeast-1/keys/ppanel-jp-recovery

@@ -0,0 +1,7 @@
+-----BEGIN OPENSSH PRIVATE KEY-----
+b3BlbnNzaC1rZXktdjEAAAAABG5vbmUAAAAEbm9uZQAAAAAAAAABAAAAMwAAAAtzc2gtZW
+QyNTUxOQAAACBsJxZDjKvaIdVjer3QMHRYw43wkVnzHurA2TQqHlr1YwAAAKBaQXT3WkF0
+9wAAAAtzc2gtZWQyNTUxOQAAACBsJxZDjKvaIdVjer3QMHRYw43wkVnzHurA2TQqHlr1Yw
+AAAEArWQWWwPoJp+za5JhSnrE0Pw1/TtqWRrdY5e8hULqYDGwnFkOMq9oh1WN6vdAwdFjD
+jfCRWfMe6sDZNCoeWvVjAAAAF0FwcGxlQE1hY0Jvb2stUHJvLmxvY2FsAQIDBAUG
+-----END OPENSSH PRIVATE KEY-----

deploy/aws/ap-northeast-1/keys/ppanel-jp-recovery.pub

@@ -0,0 +1 @@
+ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGwnFkOMq9oh1WN6vdAwdFjDjfCRWfMe6sDZNCoeWvVj Apple@MacBook-Pro.local

deploy/aws/ap-northeast-1/nginx/ppanel-api.conf

@@ -0,0 +1,34 @@
+server {
+    listen 80 default_server;
+    listen [::]:80 default_server;
+    server_name _;
+
+    client_max_body_size 20m;
+
+    access_log /var/log/nginx/ppanel-access.log;
+    error_log /var/log/nginx/ppanel-error.log warn;
+
+    location / {
+        proxy_http_version 1.1;
+        proxy_pass http://127.0.0.1:8080;
+
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header X-Forwarded-Host $host;
+        proxy_set_header X-Forwarded-Port $server_port;
+
+        proxy_connect_timeout 10s;
+        proxy_send_timeout 60s;
+        proxy_read_timeout 60s;
+    }
+
+    location = /nginx_status {
+        stub_status;
+        access_log off;
+        allow 127.0.0.1;
+        deny all;
+    }
+}
+

deploy/systemd/hifast-mysql-backup.service

@@ -0,0 +1,17 @@
+[Unit]
+Description=Hifast MySQL backup to S3
+Wants=network-online.target
+After=network-online.target
+
+[Service]
+Type=oneshot
+User=root
+Group=root
+EnvironmentFile=/root/backup-to-s3.env
+ExecStart=/usr/bin/env bash -lc 'exec /opt/ppanel/deploy/scripts/mysql_backup_to_s3.sh'
+Nice=10
+IOSchedulingClass=best-effort
+IOSchedulingPriority=7
+
+[Install]
+WantedBy=multi-user.target

deploy/systemd/hifast-mysql-backup.timer

@@ -0,0 +1,11 @@
+[Unit]
+Description=Run Hifast MySQL backup to S3 every 10 minutes
+
+[Timer]
+OnCalendar=*:0/10
+Persistent=true
+RandomizedDelaySec=30
+Unit=hifast-mysql-backup.service
+
+[Install]
+WantedBy=timers.target

doc/tapi-file-upload-zh.md

@@ -0,0 +1,184 @@
+# TAPI 文件上传接入说明
+
+本文档说明 `https://tapi.hifast.biz/v1/public/file/upload` 相关上传接口的推荐接入方式、签名规则与常见排查方式。
+
+## 总览
+
+上传能力包含两类接入方式：
+
+- 推荐方式：`init -> S3 PUT -> complete`
+- 兼容方式：`/upload` multipart 直传
+
+推荐优先使用预签名三段式，因为：
+
+- 现有签名串包含 `BODY_SHA256`
+- `/upload` 是 `multipart/form-data`
+- multipart 原始 body 的签名和调试成本更高
+- `init` 和 `complete` 是 JSON，更适合客户端和 Apifox 调试
+
+## 签名生效逻辑
+
+项目保持现有旧逻辑，不做强制签名改造：
+
+- `Signature.EnableSignature = false` 时：不校验签名
+- `Signature.EnableSignature = true` 且未携带 `X-App-Id` 时：不校验签名，兼容老客户端
+- `Signature.EnableSignature = true` 且携带 `X-App-Id` 时：必须同时携带并校验
+  - `X-Timestamp`
+  - `X-Nonce`
+  - `X-Signature`
+
+这意味着：
+
+- 新客户端建议始终带完整签名头
+- 老客户端如果没有 `X-App-Id`，仍可按旧逻辑访问
+
+## 签名头定义
+
+- `X-App-Id`: 客户端标识，例如 `ios-client`
+- `X-Timestamp`: Unix 秒级时间戳
+- `X-Nonce`: 每次请求唯一随机串
+- `X-Signature`: `HMAC-SHA256` 结果的十六进制小写字符串
+
+## StringToSign 规则
+
+StringToSign 由下面 7 段按换行符 `\n` 拼接：
+
+```text
+METHOD
+PATH
+CANONICAL_QUERY
+BODY_SHA256
+X-App-Id
+X-Timestamp
+X-Nonce
+```
+
+说明：
+
+- `METHOD`：HTTP 方法大写，例如 `POST`
+- `PATH`：请求路径，例如 `/v1/public/file/upload/init`
+- `CANONICAL_QUERY`：按 key 排序后的 query string，没有 query 则为空字符串
+- `BODY_SHA256`：请求体原始字节的 SHA-256 十六进制小写
+- 其余三项直接使用请求头值
+
+签名计算方式：
+
+```text
+signature = hex_lower(HMAC_SHA256(app_secret, string_to_sign))
+```
+
+时间窗与防重放：
+
+- `X-Timestamp` 默认有效时间窗是 300 秒
+- `X-Nonce` 在有效时间窗内不能重复使用
+
+## 推荐接入：预签名三段式
+
+### 1. 初始化上传
+
+请求：
+
+```bash
+curl -X POST 'https://tapi.hifast.biz/v1/public/file/upload/init' \
+  -H 'Accept: application/json, text/plain, */*' \
+  -H 'Content-Type: application/json' \
+  -H 'authorization: your-token' \
+  -H 'X-App-Id: ios-client' \
+  -H 'X-Timestamp: 1778776400' \
+  -H 'X-Nonce: nonce-001' \
+  -H 'X-Signature: your-signature' \
+  -d '{
+    "biz_type": "app-package",
+    "file_name": "demo.zip",
+    "content_type": "application/zip",
+    "size": 123456,
+    "sha256": ""
+  }'
+```
+
+典型返回：
+
+```json
+{
+  "code": 200,
+  "msg": "success",
+  "data": {
+    "file_id": "c29274ee26ab5aa211e0396e",
+    "object_key": "app-upload/app-package/519/2026/05/c29274ee26ab5aa211e0396e_demo.zip",
+    "upload_url": "https://bucket.s3.ap-east-1.amazonaws.com/...",
+    "method": "PUT",
+    "headers": {
+      "Content-Type": "application/zip"
+    },
+    "expired_at": 1778776715
+  }
+}
+```
+
+### 2. 直传 S3
+
+这一步是直接上传二进制文件到 S3，不走业务签名中间件。
+
+```bash
+curl -X PUT 'https://bucket.s3.ap-east-1.amazonaws.com/...' \
+  -H 'Content-Type: application/zip' \
+  --upload-file '/tmp/demo.zip'
+```
+
+说明：
+
+- `Content-Type` 需和 `init` 返回的 `headers.Content-Type` 一致
+- `upload_url` 有过期时间，通常 300 秒
+- 成功时 S3 常见返回 `200` 或 `204`
+
+### 3. 完成上传
+
+```bash
+curl -X POST 'https://tapi.hifast.biz/v1/public/file/upload/complete' \
+  -H 'Accept: application/json, text/plain, */*' \
+  -H 'Content-Type: application/json' \
+  -H 'authorization: your-token' \
+  -H 'X-App-Id: ios-client' \
+  -H 'X-Timestamp: 1778776405' \
+  -H 'X-Nonce: nonce-002' \
+  -H 'X-Signature: your-signature' \
+  -d '{
+    "file_id": "c29274ee26ab5aa211e0396e"
+  }'
+```
+
+## 兼容接入：单接口 multipart 直传
+
+接口：
+
+- `POST /v1/public/file/upload`
+
+表单字段：
+
+- `biz_type`
+- `file`
+
+说明：
+
+- 该接口继续保留，兼容旧客户端
+- 如果请求带了 `X-App-Id`，就按现有逻辑验签
+- 如果没有 `X-App-Id`，仍按旧逻辑放行
+- 如果要给该接口加签，签名时必须对原始 multipart body 计算 `BODY_SHA256`
+
+## 常见错误码
+
+- `200`: 成功
+- `400`: 参数错误
+- `40008`: 缺少签名头
+- `40009`: 签名已过期
+- `40010`: 签名无效
+- `40011`: nonce 重放
+- `10001`: 上传元数据不存在或对象不存在
+
+## 排查建议
+
+- `40008`：确认带了 `X-App-Id` 后，也同时带上 `X-Timestamp / X-Nonce / X-Signature`
+- `40009`：检查客户端时间是否偏差过大
+- `40010`：确认 `PATH`、query 排序、body 原始字节、secret 是否完全一致
+- `40011`：确保每次请求都生成新的 `X-Nonce`
+- `complete` 失败：确认 S3 `PUT` 已成功，且上传大小与 `init.size` 一致

doc/withdrawal-api-zh.md

@@ -0,0 +1,144 @@
+# 提现接口文档
+
+## 基础信息
+
+| 项目 | 值 |
+|------|-----|
+| Base URL | `/v1/public/user` |
+| 认证方式 | JWT Token（`AuthMiddleware` + `DeviceMiddleware`） |
+| 数据表 | `user_withdrawal` |
+
+## 数据模型
+
+### user_withdrawal 表
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `id` | int64 | 主键 |
+| `user_id` | int64 | 用户 ID |
+| `amount` | int64 | 提现金额（单位：分） |
+| `content` | text | 收款信息（账号、姓名等） |
+| `status` | tinyint | 0=待审核, 1=已通过, 2=已拒绝 |
+| `reason` | varchar(500) | 拒绝原因（通过时为空） |
+| `created_at` | datetime | 创建时间 |
+| `updated_at` | datetime | 更新时间 |
+
+### status 枚举
+
+| 值 | 含义 | 说明 |
+|----|------|------|
+| 0 | Pending（待审核） | 用户提交申请后的初始状态 |
+| 1 | Approved（已通过） | 管理员审核通过，佣金已扣减 |
+| 2 | Rejected（已拒绝） | 管理员拒绝，无需退款（申请时未扣款） |
+
+---
+
+## 用户端接口
+
+### 1. 申请提现
+
+申请佣金提现，创建一条待审核记录。申请时**不扣余额**，管理员审核通过后才扣。
+
+```
+POST /v1/public/user/commission_withdraw
+```
+
+#### 请求体
+
+```json
+{
+  "amount": 1000,
+  "content": "支付宝：138xxxx1234 / 张三"
+}
+```
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `amount` | int64 | 是 | 提现金额（单位：分） |
+| `content` | string | 是 | 收款信息（支付宝/银行卡等） |
+
+#### 成功响应
+
+```json
+{
+  "data": {
+    "id": 1,
+    "user_id": 10001,
+    "amount": 1000,
+    "content": "支付宝：138xxxx1234 / 张三",
+    "status": 0,
+    "reason": "",
+    "created_at": 1716624000000,
+    "updated_at": 1716624000000
+  }
+}
+```
+
+> **注意**：此接口的 `created_at` / `updated_at` 返回**毫秒级**时间戳（`.UnixMilli()`），与项目其他接口的秒级时间戳不一致。
+
+#### 业务逻辑
+
+1. 查询该用户所有 status=0（待审核）的提现记录，求和得 `pendingTotal`
+2. 校验可用余额：`commission >= amount + pendingTotal`
+3. 创建 `user_withdrawal` 记录，status=0
+4. **不扣减** `user.commission`，等审核通过才扣
+
+#### 错误码
+
+| 错误码 | 常量 | 说明 |
+|--------|------|------|
+| 20010 | `UserCommissionNotEnough` | 可用余额不足（余额 = commission - 所有 pending 提现总额） |
+| 40005 | `InvalidAccess` | 未登录 / Token 无效 |
+
+#### 源码位置
+
+- Handler: `internal/handler/public/user/commissionWithdrawHandler.go`
+- Logic: `internal/logic/public/user/commissionWithdrawLogic.go`
+
+---
+
+### 2. 查询提现记录
+
+分页查询当前用户的提现记录。
+
+```
+GET /v1/public/user/withdrawal_log
+```
+
+#### 请求参数（Query）
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `page` | int | 否 | 页码 |
+| `size` | int | 否 | 每页数量 |
+
+#### 成功响应
+
+```json
+{
+  "data": {
+    "list": [
+      {
+        "id": 1,
+        "user_id": 10001,
+        "amount": 1000,
+        "content": "支付宝：138xxxx1234",
+        "status": 0,
+        "reason": "",
+        "created_at": 1716624000,
+        "updated_at": 1716624000
+      }
+    ],
+    "total": 1
+  }
+}
+```
+
+#### 源码位置
+
+- Handler: `internal/handler/public/user/queryWithdrawalLogHandler.go`
+- Logic: `internal/logic/public/user/queryWithdrawalLogLogic.go`
+
+> **Warning**: Logic 层尚未实现（仍为 TODO），调用会返回空响应。
+
+---

docker-compose.cloud.yml

@@ -19,9 +19,10 @@ services:
   # ----------------------------------------------------
   # 1. 业务后端 (PPanel Server)
   #    host 网络：可出外网，直接访问 AWS RDS/Redis；通过 127.0.0.1 访问 Tempo
+  #    PPANEL_SERVER_TAG 由 CI/CD 传入不可变镜像标签（如 git SHA）
   # ----------------------------------------------------
   ppanel-server:
-    image: registry.kxsw.us/vpn-server:${PPANEL_SERVER_TAG:-latest}
+    image: registry.kxsw.us/vpn-server:${PPANEL_SERVER_TAG:?please set PPANEL_SERVER_TAG to an immutable image tag}
     container_name: ppanel-server
     restart: always
     volumes:
@@ -119,7 +120,7 @@ services:
   # 或配置 Nginx 反代（建议加认证）
   # ----------------------------------------------------
   grafana:
-    image: grafana/grafana:latest
+    image: grafana/grafana:13.0.1
     container_name: ppanel-grafana
     restart: always
     ports:
@@ -154,7 +155,7 @@ services:
   # 6. Prometheus (指标采集)
   # ----------------------------------------------------
   prometheus:
-    image: prom/prometheus:latest
+    image: prom/prometheus:v3.11.3
     container_name: ppanel-prometheus
     restart: always
     ports:
@@ -179,7 +180,7 @@ services:
   # 7. Nginx Exporter (监控宿主机 Nginx)
   # ----------------------------------------------------
   nginx-exporter:
-    image: nginx/nginx-prometheus-exporter:latest
+    image: nginx/nginx-prometheus-exporter:1.5.0
     container_name: ppanel-nginx-exporter
     restart: always
     command:
@@ -198,7 +199,7 @@ services:
   # 8. Node Exporter (宿主机监控)
   # ----------------------------------------------------
   node-exporter:
-    image: prom/node-exporter:latest
+    image: prom/node-exporter:v1.11.1
     container_name: ppanel-node-exporter
     restart: always
     volumes:
@@ -221,7 +222,7 @@ services:
   # 9. cAdvisor (容器监控)
   # ----------------------------------------------------
   cadvisor:
-    image: gcr.io/cadvisor/cadvisor:latest
+    image: gcr.io/cadvisor/cadvisor:v0.55.1
     container_name: ppanel-cadvisor
     restart: always
     volumes:

grafana/provisioning/dashboards/json/aws-rds-redis-overview.json

@@ -34,7 +34,7 @@
       },
       "id": 1,
       "options": {
-        "content": "<b>AWS CloudWatch overview</b><br/>Region: ap-east-1 (Hong Kong)<br/>RDS DBInstanceIdentifier: database-1<br/>Redis ReplicationGroupId: hifastapp-redis<br/><br/>Note: Redis panels are configured using <code>ReplicationGroupId</code>. If a panel shows no data in your account, switch that dimension to the concrete <code>CacheClusterId</code> in Grafana query editor.",
+        "content": "<b>AWS CloudWatch overview</b><br/>Region: ap-east-1 (Hong Kong)<br/>RDS DBInstanceIdentifier: hifast-mysql-prod-v2<br/>Redis: current production uses a local Docker Redis container (<code>hifast-redis</code>) on EC2 rather than AWS ElastiCache.<br/><br/>This dashboard keeps the RDS CloudWatch panels. Redis should be observed from the local ops dashboard via Prometheus/cAdvisor instead of ElastiCache metrics.",
         "mode": "html"
       },
       "pluginVersion": "11.0.0",
@@ -75,7 +75,7 @@
             "uid": "cloudwatch"
           },
           "dimensions": {
-            "DBInstanceIdentifier": "database-1"
+            "DBInstanceIdentifier": "hifast-mysql-prod-v2"
           },
           "metricName": "CPUUtilization",
           "namespace": "AWS/RDS",
@@ -122,7 +122,7 @@
             "uid": "cloudwatch"
           },
           "dimensions": {
-            "DBInstanceIdentifier": "database-1"
+            "DBInstanceIdentifier": "hifast-mysql-prod-v2"
           },
           "metricName": "DatabaseConnections",
           "namespace": "AWS/RDS",
@@ -169,7 +169,7 @@
             "uid": "cloudwatch"
           },
           "dimensions": {
-            "DBInstanceIdentifier": "database-1"
+            "DBInstanceIdentifier": "hifast-mysql-prod-v2"
           },
           "metricName": "FreeStorageSpace",
           "namespace": "AWS/RDS",
@@ -216,7 +216,7 @@
             "uid": "cloudwatch"
           },
           "dimensions": {
-            "DBInstanceIdentifier": "database-1"
+            "DBInstanceIdentifier": "hifast-mysql-prod-v2"
           },
           "metricName": "ReadLatency",
           "namespace": "AWS/RDS",
@@ -231,7 +231,7 @@
             "uid": "cloudwatch"
           },
           "dimensions": {
-            "DBInstanceIdentifier": "database-1"
+            "DBInstanceIdentifier": "hifast-mysql-prod-v2"
           },
           "metricName": "WriteLatency",
           "namespace": "AWS/RDS",
@@ -278,7 +278,7 @@
             "uid": "cloudwatch"
           },
           "dimensions": {
-            "DBInstanceIdentifier": "database-1"
+            "DBInstanceIdentifier": "hifast-mysql-prod-v2"
           },
           "metricName": "ReadIOPS",
           "namespace": "AWS/RDS",
@@ -293,7 +293,7 @@
             "uid": "cloudwatch"
           },
           "dimensions": {
-            "DBInstanceIdentifier": "database-1"
+            "DBInstanceIdentifier": "hifast-mysql-prod-v2"
           },
           "metricName": "WriteIOPS",
           "namespace": "AWS/RDS",
@@ -350,7 +350,7 @@
           "statistic": "Average"
         }
       ],
-      "title": "Redis Host CPU",
+      "title": "Redis Host CPU (Legacy ElastiCache)",
       "type": "timeseries"
     },
     {
@@ -397,7 +397,7 @@
           "statistic": "Average"
         }
       ],
-      "title": "Redis Engine CPU",
+      "title": "Redis Engine CPU (Legacy ElastiCache)",
       "type": "timeseries"
     },
     {
@@ -444,7 +444,7 @@
           "statistic": "Average"
         }
       ],
-      "title": "Redis Connections",
+      "title": "Redis Connections (Legacy ElastiCache)",
       "type": "timeseries"
     },
     {
@@ -491,7 +491,7 @@
           "statistic": "Average"
         }
       ],
-      "title": "Redis Memory Usage %",
+      "title": "Redis Memory Usage % (Legacy ElastiCache)",
       "type": "timeseries"
     }
   ],

grafana/provisioning/dashboards/json/ppanel-server-logs.json

@@ -58,7 +58,7 @@
             "uid": "P8E80F9AEF21F6940"
           },
           "editorMode": "code",
-          "expr": "sum(count_over_time({container=\"ppanel-server\"} |~ \"${user_id:raw}\" |~ \"${email:raw}\" |~ \"${order:raw}\" |~ \"${keyword:raw}\" |~ \"${level:raw}\" [5m]))",
+          "expr": "sum(count_over_time({compose_service=\"ppanel-server\"}[5m]))",
           "queryType": "range",
           "refId": "A"
         }
@@ -103,7 +103,7 @@
             "uid": "P8E80F9AEF21F6940"
           },
           "editorMode": "code",
-          "expr": "sum(count_over_time({container=\"ppanel-server\"} |~ \"${user_id:raw}\" |~ \"${email:raw}\" |~ \"${order:raw}\" |~ \"${keyword:raw}\" |~ \"(?i)(error|panic|fatal)\" [5m]))",
+          "expr": "sum(count_over_time({compose_service=\"ppanel-server\"} |~ \"(?i)(error|panic|fatal)\" [5m]))",
           "queryType": "range",
           "refId": "A"
         }
@@ -140,7 +140,7 @@
             "uid": "P8E80F9AEF21F6940"
           },
           "editorMode": "code",
-          "expr": "{container=\"ppanel-server\"} |~ \"${user_id:raw}\" |~ \"${email:raw}\" |~ \"${order:raw}\" |~ \"${keyword:raw}\" |~ \"${level:raw}\"",
+          "expr": "{compose_service=\"ppanel-server\"}",
           "queryType": "range",
           "refId": "A"
         }
@@ -177,7 +177,7 @@
             "uid": "P8E80F9AEF21F6940"
           },
           "editorMode": "code",
-          "expr": "{container=\"ppanel-server\"} |~ \"${user_id:raw}\" |~ \"${email:raw}\" |~ \"${order:raw}\" |~ \"${keyword:raw}\" |~ \"(?i)(error|panic|fatal)\"",
+          "expr": "{compose_service=\"ppanel-server\"} |~ \"(?i)(error|panic|fatal)\"",
           "queryType": "range",
           "refId": "A"
         }
@@ -318,7 +318,7 @@
     ]
   },
   "time": {
-    "from": "now-7d",
+    "from": "now-1h",
     "to": "now"
   },
   "timepicker": {},

initialize/migrate/database/00001_init_schema.up.sql

@@ -449,7 +449,7 @@ CREATE TABLE IF NOT EXISTS `user_device`
     `subscribe_id` bigint                                                        DEFAULT NULL COMMENT 'Subscribe ID',
     `ip`           varchar(191) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci DEFAULT NULL COMMENT 'Device Ip.',
     `Identifier`   varchar(191) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci DEFAULT NULL COMMENT 'Device Identifier.',
-    `user_agent`   varchar(64) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci  DEFAULT NULL COMMENT 'Device User Agent.',
+    `user_agent`   varchar(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci DEFAULT NULL COMMENT 'Device User Agent.',
     `online`       tinyint(1) NOT NULL                                           DEFAULT '0' COMMENT 'Online',
     `enabled`      tinyint(1) NOT NULL                                           DEFAULT '1' COMMENT 'EnableDeviceNumber',
     `created_at`   datetime(3)                                                   DEFAULT NULL COMMENT 'Creation Time',

initialize/migrate/database/02141_order_iap_token.down.sql

@@ -0,0 +1,13 @@
+-- Remove app_account_token column from order table if it exists
+SET @col_exists = (SELECT COUNT(*) FROM INFORMATION_SCHEMA.COLUMNS WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'order' AND COLUMN_NAME = 'app_account_token');
+SET @sql = IF(@col_exists = 1, 'ALTER TABLE `order` DROP COLUMN `app_account_token`', 'SELECT 1');
+PREPARE stmt FROM @sql;
+EXECUTE stmt;
+DEALLOCATE PREPARE stmt;
+
+-- Remove subscription_user_id column from order table if it exists
+SET @col_exists2 = (SELECT COUNT(*) FROM INFORMATION_SCHEMA.COLUMNS WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'order' AND COLUMN_NAME = 'subscription_user_id');
+SET @sql2 = IF(@col_exists2 = 1, 'ALTER TABLE `order` DROP COLUMN `subscription_user_id`', 'SELECT 1');
+PREPARE stmt2 FROM @sql2;
+EXECUTE stmt2;
+DEALLOCATE PREPARE stmt2;

initialize/migrate/database/02148_log_message_column_sizes.down.sql

@@ -0,0 +1,7 @@
+ALTER TABLE `log_message`
+  MODIFY COLUMN `app_version` VARCHAR(32) NULL,
+  MODIFY COLUMN `os_name` VARCHAR(32) NULL,
+  MODIFY COLUMN `os_version` VARCHAR(32) NULL,
+  MODIFY COLUMN `device_id` VARCHAR(64) NULL,
+  MODIFY COLUMN `session_id` VARCHAR(64) NULL,
+  MODIFY COLUMN `error_code` VARCHAR(64) NULL;

initialize/migrate/database/02148_log_message_column_sizes.up.sql

@@ -0,0 +1,7 @@
+ALTER TABLE `log_message`
+  MODIFY COLUMN `app_version` VARCHAR(64) NULL,
+  MODIFY COLUMN `os_name` VARCHAR(64) NULL,
+  MODIFY COLUMN `os_version` VARCHAR(64) NULL,
+  MODIFY COLUMN `device_id` VARCHAR(255) NULL,
+  MODIFY COLUMN `session_id` VARCHAR(255) NULL,
+  MODIFY COLUMN `error_code` VARCHAR(128) NULL;

initialize/migrate/database/02149_user_device_user_agent_length.down.sql

@@ -0,0 +1,2 @@
+ALTER TABLE `user_device`
+  MODIFY COLUMN `user_agent` VARCHAR(64) NULL COMMENT 'Device User Agent.';

initialize/migrate/database/02149_user_device_user_agent_length.up.sql

@@ -0,0 +1,2 @@
+ALTER TABLE `user_device`
+  MODIFY COLUMN `user_agent` VARCHAR(255) NULL COMMENT 'Device User Agent.';

initialize/migrate/database/02150_refund_pending_withdrawals.down.sql

@@ -0,0 +1,19 @@
+-- Rollback: re-deduct commission for users with pending (status=0) withdrawals.
+-- This re-applies the OLD behaviour where commission is deducted on application.
+-- Only run this if you are rolling back to the old code; do NOT run against
+-- the new code or commission will be double-deducted on approval.
+
+UPDATE `user` u
+JOIN (
+    SELECT user_id, COALESCE(SUM(amount), 0) AS pending_total
+    FROM withdrawals
+    WHERE status = 0
+    GROUP BY user_id
+) p ON u.id = p.user_id
+SET u.commission = u.commission - p.pending_total
+WHERE p.pending_total > 0;
+
+-- Remove the migration log entries written by the up migration.
+DELETE FROM system_logs
+WHERE type = 33
+  AND content LIKE '%migration: refund pending withdrawal commission (HIF-22)%';

initialize/migrate/database/02150_refund_pending_withdrawals.up.sql

@@ -0,0 +1,65 @@
+-- Migration: refund commission for existing pending (status=0) withdrawals
+--
+-- Under the old logic, commission was deducted when a withdrawal was submitted.
+-- Under the new logic, commission is only deducted on approval.
+-- This migration refunds the deducted amounts back to each user so that
+-- the system is in a consistent state before the new code is deployed.
+--
+-- Idempotency: the UPDATE only touches rows whose commission would need
+-- to increase, and each execution produces the same result because
+-- COALESCE(SUM(amount),0) is deterministic given the same pending set.
+-- Running this script multiple times is safe only if no new pending
+-- withdrawals are created between runs; deploy new code immediately after.
+
+-- Compatibility: some historical databases missed migration 02122, so the
+-- withdrawals table may not exist yet. Create it idempotently before the
+-- refund logic so this migration can self-heal older installations.
+CREATE TABLE IF NOT EXISTS `withdrawals` (
+    `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT 'Primary Key',
+    `user_id` BIGINT NOT NULL COMMENT 'User ID',
+    `amount` BIGINT NOT NULL COMMENT 'Withdrawal Amount',
+    `content` TEXT COMMENT 'Withdrawal Content',
+    `status` TINYINT(1) NOT NULL DEFAULT 0 COMMENT 'Withdrawal Status',
+    `reason` VARCHAR(500) NOT NULL DEFAULT '' COMMENT 'Rejection Reason',
+    `created_at` DATETIME NOT NULL COMMENT 'Creation Time',
+    `updated_at` DATETIME NOT NULL COMMENT 'Update Time',
+    PRIMARY KEY (`id`),
+    KEY `idx_user_id` (`user_id`)
+    ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+
+INSERT IGNORE INTO `system` (`category`, `key`, `value`, `type`, `desc`, `created_at`, `updated_at`)
+VALUES
+    ('invite', 'WithdrawalMethod', '', 'string', 'withdrawal method', '2025-04-22 14:25:16.637', '2025-04-22 14:25:16.637');
+
+-- Step 1: refund commission for all users with pending withdrawals.
+UPDATE `user` u
+JOIN (
+    SELECT user_id, COALESCE(SUM(amount), 0) AS pending_total
+    FROM withdrawals
+    WHERE status = 0
+    GROUP BY user_id
+) p ON u.id = p.user_id
+SET u.commission = u.commission + p.pending_total
+WHERE p.pending_total > 0;
+
+-- Step 2: write a migration log entry for each refunded user.
+INSERT INTO system_logs (type, date, object_id, content, created_at)
+SELECT
+    33 AS type,
+    DATE(NOW()) AS date,
+    p.user_id AS object_id,
+    JSON_OBJECT(
+        'type', 99,
+        'amount', p.pending_total,
+        'order_no', '',
+        'timestamp', UNIX_TIMESTAMP(NOW()) * 1000,
+        'note', 'migration: refund pending withdrawal commission (HIF-22)'
+    ) AS content,
+    NOW() AS created_at
+FROM (
+    SELECT user_id, COALESCE(SUM(amount), 0) AS pending_total
+    FROM withdrawals
+    WHERE status = 0
+    GROUP BY user_id
+    HAVING pending_total > 0
+) p;

initialize/migrate/database/02151_order_activation_context.down.sql

@@ -0,0 +1,2 @@
+-- Remove activation_context column from order table
+ALTER TABLE `order` DROP COLUMN IF EXISTS `activation_context`;

initialize/migrate/database/02151_order_activation_context.up.sql

@@ -0,0 +1,6 @@
+-- Add activation_context column to order table for Redis fallback persistence (idempotent)
+SET @col_exists = (SELECT COUNT(*) FROM INFORMATION_SCHEMA.COLUMNS WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'order' AND COLUMN_NAME = 'activation_context');
+SET @sql = IF(@col_exists = 0, 'ALTER TABLE `order` ADD COLUMN `activation_context` TEXT DEFAULT NULL COMMENT ''Activation context JSON (guest/redemption info for DB fallback)'' AFTER `app_account_token`', 'SELECT 1');
+PREPARE stmt FROM @sql;
+EXECUTE stmt;
+DEALLOCATE PREPARE stmt;

initialize/migrate/database/02152_withdrawal_method.down.sql

@@ -0,0 +1,4 @@
+ALTER TABLE `withdrawals`
+  DROP COLUMN `qr_code_url`,
+  DROP COLUMN `account`,
+  DROP COLUMN `method`;

initialize/migrate/database/02152_withdrawal_method.up.sql

@@ -0,0 +1,4 @@
+ALTER TABLE `withdrawals`
+  ADD COLUMN `method`      TINYINT(1)   NOT NULL DEFAULT 0 COMMENT '收款方式 0:其他 1:支付宝 2:微信 3:银行卡' AFTER `content`,
+  ADD COLUMN `account`     VARCHAR(255) NOT NULL DEFAULT '' COMMENT '收款账号' AFTER `method`,
+  ADD COLUMN `qr_code_url` VARCHAR(500) NOT NULL DEFAULT '' COMMENT '收款码图片URL' AFTER `account`;

initialize/schema_compat.go

@@ -20,6 +20,14 @@ type schemaColumnPatch struct {
 	ddl    string
 }
 
+type schemaColumnDefinitionPatch struct {
+	table           string
+	column          string
+	dataType        string
+	characterMaxLen *int64
+	ddl             string
+}
+
 func EnsureSchemaCompatibility(ctx *svc.ServiceContext) error {
 	tablePatches := []schemaTablePatch{
 		{
@@ -142,6 +150,17 @@ func EnsureSchemaCompatibility(ctx *svc.ServiceContext) error {
 		},
 	}
 
+	varchar255 := int64(255)
+	columnDefinitionPatches := []schemaColumnDefinitionPatch{
+		{
+			table:           "user_device",
+			column:          "user_agent",
+			dataType:        "varchar",
+			characterMaxLen: &varchar255,
+			ddl:             "ALTER TABLE `user_device` MODIFY COLUMN `user_agent` VARCHAR(255) NULL COMMENT 'Device User Agent.';",
+		},
+	}
+
 	for _, patch := range tablePatches {
 		exists, err := tableExists(ctx.DB, patch.table)
 		if err != nil {
@@ -199,6 +218,27 @@ func EnsureSchemaCompatibility(ctx *svc.ServiceContext) error {
 		logger.Infof("[SchemaCompat] created missing index: %s.%s", patch.table, patch.index)
 	}
 
+	for _, patch := range columnDefinitionPatches {
+		tblExists, err := tableExists(ctx.DB, patch.table)
+		if err != nil {
+			return errors.Wrapf(err, "check table %s failed", patch.table)
+		}
+		if !tblExists {
+			continue
+		}
+		matches, err := columnDefinitionMatches(ctx.DB, patch.table, patch.column, patch.dataType, patch.characterMaxLen)
+		if err != nil {
+			return errors.Wrapf(err, "check column definition %s.%s failed", patch.table, patch.column)
+		}
+		if matches {
+			continue
+		}
+		if err = ctx.DB.Exec(patch.ddl).Error; err != nil {
+			return errors.Wrapf(err, "modify column %s.%s failed", patch.table, patch.column)
+		}
+		logger.Infof("[SchemaCompat] repaired column definition: %s.%s", patch.table, patch.column)
+	}
+
 	return nil
 }
 
@@ -237,6 +277,38 @@ func indexExists(db *gorm.DB, table, index string) (bool, error) {
 	return count > 0, nil
 }
 
+func columnDefinitionMatches(db *gorm.DB, table, column, dataType string, characterMaxLen *int64) (bool, error) {
+	type columnMeta struct {
+		DataType            string
+		CharacterMaximumLen *int64
+	}
+
+	var meta columnMeta
+	err := db.Raw(
+		`SELECT DATA_TYPE AS data_type, CHARACTER_MAXIMUM_LENGTH AS character_maximum_len
+FROM information_schema.COLUMNS
+WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = ? AND COLUMN_NAME = ?`,
+		table,
+		column,
+	).Scan(&meta).Error
+	if err != nil {
+		return false, err
+	}
+	if meta.DataType == "" {
+		return false, nil
+	}
+	if meta.DataType != dataType {
+		return false, nil
+	}
+	if characterMaxLen == nil {
+		return true, nil
+	}
+	if meta.CharacterMaximumLen == nil {
+		return false, nil
+	}
+	return *meta.CharacterMaximumLen == *characterMaxLen, nil
+}
+
 func _schemaCompatDebug(table, column string) string {
 	if column == "" {
 		return table

internal/handler/admin/log/filterOrderRefundLogHandler.go

@@ -0,0 +1,25 @@
+package log
+
+import (
+	"github.com/gin-gonic/gin"
+	"github.com/perfect-panel/server/internal/logic/admin/log"
+	"github.com/perfect-panel/server/internal/svc"
+	"github.com/perfect-panel/server/internal/types"
+	"github.com/perfect-panel/server/pkg/result"
+)
+
+func FilterOrderRefundLogHandler(svcCtx *svc.ServiceContext) func(c *gin.Context) {
+	return func(c *gin.Context) {
+		var req types.FilterOrderRefundLogRequest
+		_ = c.ShouldBind(&req)
+		validateErr := svcCtx.Validate(&req)
+		if validateErr != nil {
+			result.ParamErrorResult(c, validateErr)
+			return
+		}
+
+		l := log.NewFilterOrderRefundLogLogic(c.Request.Context(), svcCtx)
+		resp, err := l.FilterOrderRefundLog(&req)
+		result.HttpResult(c, resp, err)
+	}
+}

internal/handler/admin/log/getLogMessageRawHandler.go

@@ -0,0 +1,23 @@
+package log
+
+import (
+	"github.com/gin-gonic/gin"
+	"github.com/perfect-panel/server/internal/logic/admin/log"
+	"github.com/perfect-panel/server/internal/svc"
+	"github.com/perfect-panel/server/internal/types"
+	"github.com/perfect-panel/server/pkg/result"
+)
+
+func GetLogMessageRawHandler(svcCtx *svc.ServiceContext) func(c *gin.Context) {
+	return func(c *gin.Context) {
+		var req types.GetLogMessageRawRequest
+		_ = c.ShouldBind(&req)
+		if err := svcCtx.Validate(&req); err != nil {
+			result.ParamErrorResult(c, err)
+			return
+		}
+		l := log.NewGetLogMessageRawLogic(c.Request.Context(), svcCtx)
+		resp, err := l.GetLogMessageRaw(&req)
+		result.HttpResult(c, resp, err)
+	}
+}

internal/handler/admin/order/refundOrderHandler.go

@@ -0,0 +1,25 @@
+package order
+
+import (
+	"github.com/gin-gonic/gin"
+	"github.com/perfect-panel/server/internal/logic/admin/order"
+	"github.com/perfect-panel/server/internal/svc"
+	"github.com/perfect-panel/server/internal/types"
+	"github.com/perfect-panel/server/pkg/result"
+)
+
+func RefundOrderHandler(svcCtx *svc.ServiceContext) func(c *gin.Context) {
+	return func(c *gin.Context) {
+		var req types.RefundOrderRequest
+		_ = c.ShouldBind(&req)
+		validateErr := svcCtx.Validate(&req)
+		if validateErr != nil {
+			result.ParamErrorResult(c, validateErr)
+			return
+		}
+
+		l := order.NewRefundOrderLogic(c.Request.Context(), svcCtx)
+		err := l.RefundOrder(&req)
+		result.HttpResult(c, nil, err)
+	}
+}

internal/handler/admin/user/approveWithdrawalHandler.go

@@ -0,0 +1,26 @@
+package user
+
+import (
+	"github.com/gin-gonic/gin"
+	"github.com/perfect-panel/server/internal/logic/admin/user"
+	"github.com/perfect-panel/server/internal/svc"
+	"github.com/perfect-panel/server/internal/types"
+	"github.com/perfect-panel/server/pkg/result"
+)
+
+// Approve withdrawal
+func ApproveWithdrawalHandler(svcCtx *svc.ServiceContext) func(c *gin.Context) {
+	return func(c *gin.Context) {
+		var req types.ApproveWithdrawalRequest
+		_ = c.ShouldBind(&req)
+		validateErr := svcCtx.Validate(&req)
+		if validateErr != nil {
+			result.ParamErrorResult(c, validateErr)
+			return
+		}
+
+		l := user.NewApproveWithdrawalLogic(c.Request.Context(), svcCtx)
+		err := l.ApproveWithdrawal(&req)
+		result.HttpResult(c, nil, err)
+	}
+}

internal/handler/admin/user/getWithdrawalListHandler.go

@@ -0,0 +1,26 @@
+package user
+
+import (
+	"github.com/gin-gonic/gin"
+	"github.com/perfect-panel/server/internal/logic/admin/user"
+	"github.com/perfect-panel/server/internal/svc"
+	"github.com/perfect-panel/server/internal/types"
+	"github.com/perfect-panel/server/pkg/result"
+)
+
+// Get withdrawal list
+func GetWithdrawalListHandler(svcCtx *svc.ServiceContext) func(c *gin.Context) {
+	return func(c *gin.Context) {
+		var req types.GetWithdrawalListRequest
+		_ = c.ShouldBind(&req)
+		validateErr := svcCtx.Validate(&req)
+		if validateErr != nil {
+			result.ParamErrorResult(c, validateErr)
+			return
+		}
+
+		l := user.NewGetWithdrawalListLogic(c.Request.Context(), svcCtx)
+		resp, err := l.GetWithdrawalList(&req)
+		result.HttpResult(c, resp, err)
+	}
+}

internal/handler/admin/user/rejectWithdrawalHandler.go

@@ -0,0 +1,26 @@
+package user
+
+import (
+	"github.com/gin-gonic/gin"
+	"github.com/perfect-panel/server/internal/logic/admin/user"
+	"github.com/perfect-panel/server/internal/svc"
+	"github.com/perfect-panel/server/internal/types"
+	"github.com/perfect-panel/server/pkg/result"
+)
+
+// Reject withdrawal
+func RejectWithdrawalHandler(svcCtx *svc.ServiceContext) func(c *gin.Context) {
+	return func(c *gin.Context) {
+		var req types.RejectWithdrawalRequest
+		_ = c.ShouldBind(&req)
+		validateErr := svcCtx.Validate(&req)
+		if validateErr != nil {
+			result.ParamErrorResult(c, validateErr)
+			return
+		}
+
+		l := user.NewRejectWithdrawalLogic(c.Request.Context(), svcCtx)
+		err := l.RejectWithdrawal(&req)
+		result.HttpResult(c, nil, err)
+	}
+}

internal/handler/public/file/fileUploadHandler.go

@@ -0,0 +1,43 @@
+package file
+
+import (
+	"mime/multipart"
+
+	"github.com/gin-gonic/gin"
+	"github.com/perfect-panel/server/internal/logic/public/file"
+	"github.com/perfect-panel/server/internal/svc"
+	"github.com/perfect-panel/server/internal/types"
+	"github.com/perfect-panel/server/pkg/result"
+)
+
+// Upload file to RustFS
+func FileUploadHandler(svcCtx *svc.ServiceContext) func(c *gin.Context) {
+	return func(c *gin.Context) {
+		var req types.FileUploadRequest
+		_ = c.ShouldBind(&req)
+		validateErr := svcCtx.Validate(&req)
+		if validateErr != nil {
+			result.ParamErrorResult(c, validateErr)
+			return
+		}
+
+		fileHeader, err := c.FormFile("file")
+		if err != nil {
+			result.ParamErrorResult(c, err)
+			return
+		}
+
+		fileReader, err := fileHeader.Open()
+		if err != nil {
+			result.HttpResult(c, nil, err)
+			return
+		}
+		defer func(file multipart.File) {
+			_ = file.Close()
+		}(fileReader)
+
+		l := file.NewFileUploadLogic(c.Request.Context(), svcCtx)
+		resp, err := l.FileUpload(&req, fileHeader, fileReader)
+		result.HttpResult(c, resp, err)
+	}
+}

internal/handler/public/user/cancelWithdrawalHandler.go

@@ -0,0 +1,26 @@
+package user
+
+import (
+	"github.com/gin-gonic/gin"
+	"github.com/perfect-panel/server/internal/logic/public/user"
+	"github.com/perfect-panel/server/internal/svc"
+	"github.com/perfect-panel/server/internal/types"
+	"github.com/perfect-panel/server/pkg/result"
+)
+
+// Cancel Withdrawal
+func CancelWithdrawalHandler(svcCtx *svc.ServiceContext) func(c *gin.Context) {
+	return func(c *gin.Context) {
+		var req types.CancelWithdrawalRequest
+		_ = c.ShouldBind(&req)
+		validateErr := svcCtx.Validate(&req)
+		if validateErr != nil {
+			result.ParamErrorResult(c, validateErr)
+			return
+		}
+
+		l := user.NewCancelWithdrawalLogic(c.Request.Context(), svcCtx)
+		resp, err := l.CancelWithdrawal(&req)
+		result.HttpResult(c, resp, err)
+	}
+}

internal/handler/routes.go

@@ -250,12 +250,18 @@ func RegisterHandlers(router *gin.Engine, serverCtx *svc.ServiceContext) {
 		// Filter commission log
 		adminLogGroupRouter.GET("/commission/list", adminLog.FilterCommissionLogHandler(serverCtx))
 
+		// Filter order refund log
+		adminLogGroupRouter.GET("/order/refund/list", adminLog.FilterOrderRefundLogHandler(serverCtx))
+
 		// Filter email log
 		adminLogGroupRouter.GET("/email/list", adminLog.FilterEmailLogHandler(serverCtx))
 
 		// Get error log message detail
 		adminLogGroupRouter.GET("/error_message/detail", adminLog.GetErrorLogMessageDetailHandler(serverCtx))
 
+		// Get log message raw detail (temporary)
+		adminLogGroupRouter.GET("/message/detail", adminLog.GetLogMessageRawHandler(serverCtx))
+
 		// Get error log message list
 		adminLogGroupRouter.GET("/error_message/list", adminLog.GetErrorLogMessageListHandler(serverCtx))
 
@@ -341,6 +347,9 @@ func RegisterHandlers(router *gin.Engine, serverCtx *svc.ServiceContext) {
 		// Update order status
 		adminOrderGroupRouter.PUT("/status", adminOrder.UpdateOrderStatusHandler(serverCtx))
 
+		// Refund order
+		adminOrderGroupRouter.POST("/refund", adminOrder.RefundOrderHandler(serverCtx))
+
 		// Manually activate order
 		adminOrderGroupRouter.POST("/activate", adminOrder.ActivateOrderHandler(serverCtx))
 	}
@@ -707,6 +716,15 @@ func RegisterHandlers(router *gin.Engine, serverCtx *svc.ServiceContext) {
 
 		// Get admin user invite list
 		adminUserGroupRouter.GET("/invite/list", adminUser.GetAdminUserInviteListHandler(serverCtx))
+
+		// Get withdrawal list
+		adminUserGroupRouter.GET("/withdrawal/list", adminUser.GetWithdrawalListHandler(serverCtx))
+
+		// Approve withdrawal
+		adminUserGroupRouter.POST("/withdrawal/approve", adminUser.ApproveWithdrawalHandler(serverCtx))
+
+		// Reject withdrawal
+		adminUserGroupRouter.POST("/withdrawal/reject", adminUser.RejectWithdrawalHandler(serverCtx))
 	}
 
 	authGroupRouter := router.Group("/v1/auth")
@@ -870,6 +888,9 @@ func RegisterHandlers(router *gin.Engine, serverCtx *svc.ServiceContext) {
 	publicFileGroupRouter.Use(middleware.AuthMiddleware(serverCtx), middleware.DeviceMiddleware(serverCtx))
 
 	{
+		// Upload file to RustFS
+		publicFileGroupRouter.POST("/upload", publicFile.FileUploadHandler(serverCtx))
+
 		// Init file upload
 		publicFileGroupRouter.POST("/upload/init", publicFile.FileUploadInitHandler(serverCtx))
 
@@ -1038,6 +1059,9 @@ func RegisterHandlers(router *gin.Engine, serverCtx *svc.ServiceContext) {
 		// Commission Withdraw
 		publicUserGroupRouter.POST("/commission_withdraw", publicUser.CommissionWithdrawHandler(serverCtx))
 
+		// Cancel Withdrawal
+		publicUserGroupRouter.POST("/withdrawal_cancel", publicUser.CancelWithdrawalHandler(serverCtx))
+
 		// Delete Current User Account
 		publicUserGroupRouter.DELETE("/current_user_account", publicUser.DeleteCurrentUserAccountHandler(serverCtx))
 

internal/logic/admin/log/filterOrderRefundLogLogic.go

@@ -0,0 +1,77 @@
+package log
+
+import (
+	"context"
+
+	modellog "github.com/perfect-panel/server/internal/model/log"
+	"github.com/perfect-panel/server/internal/svc"
+	"github.com/perfect-panel/server/internal/types"
+	"github.com/perfect-panel/server/pkg/logger"
+	"github.com/perfect-panel/server/pkg/xerr"
+	"github.com/pkg/errors"
+)
+
+type FilterOrderRefundLogLogic struct {
+	logger.Logger
+	ctx    context.Context
+	svcCtx *svc.ServiceContext
+}
+
+func NewFilterOrderRefundLogLogic(ctx context.Context, svcCtx *svc.ServiceContext) *FilterOrderRefundLogLogic {
+	return &FilterOrderRefundLogLogic{
+		Logger: logger.WithContext(ctx),
+		ctx:    ctx,
+		svcCtx: svcCtx,
+	}
+}
+
+func (l *FilterOrderRefundLogLogic) FilterOrderRefundLog(req *types.FilterOrderRefundLogRequest) (resp *types.FilterOrderRefundLogResponse, err error) {
+	data, total, err := l.svcCtx.LogModel.FilterSystemLog(l.ctx, &modellog.FilterParams{
+		Page:     req.Page,
+		Size:     req.Size,
+		Data:     req.Date,
+		Search:   req.Search,
+		Type:     modellog.TypeOrderRefund.Uint8(),
+		ObjectID: req.OrderId,
+	})
+	if err != nil {
+		l.Errorw("Query order refund log failed", logger.Field("error", err.Error()))
+		return nil, errors.Wrapf(xerr.NewErrCode(xerr.DatabaseQueryError), "Query order refund log failed")
+	}
+
+	var list []types.OrderRefundLog
+	for _, item := range data {
+		var content modellog.OrderRefund
+		if err := content.Unmarshal([]byte(item.Content)); err != nil {
+			l.Errorf("unmarshal order refund log content failed: %v", err.Error())
+			continue
+		}
+		if req.UserId > 0 && content.TargetUserId != req.UserId && content.RefererUserId != req.UserId && content.OperatorUserId != req.UserId {
+			continue
+		}
+		list = append(list, types.OrderRefundLog{
+			OrderId:                content.OrderId,
+			OrderNo:                content.OrderNo,
+			OperatorUserId:         content.OperatorUserId,
+			OperatorAuthIdentifier: content.OperatorAuthIdentifier,
+			TargetUserId:           content.TargetUserId,
+			UserSubscribeId:        content.UserSubscribeId,
+			RefererUserId:          content.RefererUserId,
+			CommissionAmount:       content.CommissionAmount,
+			Reason:                 content.Reason,
+			OrderStatusBefore:      content.OrderStatusBefore,
+			OrderStatusAfter:       content.OrderStatusAfter,
+			SubscribeStatusBefore:  content.SubscribeStatusBefore,
+			SubscribeStatusAfter:   content.SubscribeStatusAfter,
+			SubscribeExpireBefore:  content.SubscribeExpireBefore,
+			SubscribeExpireAfter:   content.SubscribeExpireAfter,
+			CommissionBefore:       content.CommissionBefore,
+			CommissionAfter:        content.CommissionAfter,
+			Timestamp:              content.Timestamp,
+		})
+	}
+	return &types.FilterOrderRefundLogResponse{
+		Total: total,
+		List:  list,
+	}, nil
+}

internal/logic/admin/log/getLogMessageRawLogic.go

@@ -0,0 +1,66 @@
+package log
+
+import (
+	"context"
+	"encoding/json"
+
+	"github.com/perfect-panel/server/internal/svc"
+	"github.com/perfect-panel/server/internal/types"
+	"github.com/perfect-panel/server/pkg/logger"
+	"github.com/perfect-panel/server/pkg/xerr"
+	"github.com/pkg/errors"
+)
+
+type GetLogMessageRawLogic struct {
+	logger.Logger
+	ctx    context.Context
+	svcCtx *svc.ServiceContext
+}
+
+func NewGetLogMessageRawLogic(ctx context.Context, svcCtx *svc.ServiceContext) *GetLogMessageRawLogic {
+	return &GetLogMessageRawLogic{Logger: logger.WithContext(ctx), ctx: ctx, svcCtx: svcCtx}
+}
+
+func (l *GetLogMessageRawLogic) GetLogMessageRaw(req *types.GetLogMessageRawRequest) (resp *types.GetLogMessageRawResponse, err error) {
+	row, err := l.svcCtx.LogMessageModel.FindOne(l.ctx, req.Id)
+	if err != nil {
+		return nil, errors.Wrapf(xerr.NewErrCode(xerr.DatabaseQueryError), "FindOne log_message id=%d: %v", req.Id, err)
+	}
+
+	var contextJSON json.RawMessage
+	if row.Context != "" {
+		if json.Valid([]byte(row.Context)) {
+			contextJSON = json.RawMessage(row.Context)
+		} else {
+			b, _ := json.Marshal(row.Context)
+			contextJSON = b
+		}
+	}
+
+	var occurredAt int64
+	if row.OccurredAt != nil {
+		occurredAt = row.OccurredAt.UnixMilli()
+	}
+
+	return &types.GetLogMessageRawResponse{
+		Id:         row.Id,
+		Platform:   row.Platform,
+		AppVersion: row.AppVersion,
+		OsName:     row.OsName,
+		OsVersion:  row.OsVersion,
+		DeviceId:   row.DeviceId,
+		UserId:     row.UserId,
+		SessionId:  row.SessionId,
+		Level:      row.Level,
+		ErrorCode:  row.ErrorCode,
+		Message:    row.Message,
+		Stack:      row.Stack,
+		Context:    contextJSON,
+		ClientIP:   row.ClientIP,
+		UserAgent:  row.UserAgent,
+		Locale:     row.Locale,
+		Digest:     row.Digest,
+		OccurredAt: occurredAt,
+		CreatedAt:  row.CreatedAt.UnixMilli(),
+	}, nil
+}

internal/logic/admin/order/getOrderListLogic.go

@@ -35,6 +35,28 @@ func (l *GetOrderListLogic) GetOrderList(req *types.GetOrderListRequest) (resp *
 	resp = &types.GetOrderListResponse{}
 	resp.List = make([]types.Order, 0)
 	tool.DeepCopy(&resp.List, list)
+	for i := range resp.List {
+		resp.List[i].StatusName = orderStatusName(resp.List[i].Status)
+	}
 	resp.Total = total
 	return
 }
+
+func orderStatusName(status uint8) string {
+	switch status {
+	case 1:
+		return "pending"
+	case 2:
+		return "paid"
+	case 3:
+		return "closed"
+	case 4:
+		return "failed"
+	case 5:
+		return "finished"
+	case 6:
+		return "refunded"
+	default:
+		return "unknown"
+	}
+}

internal/logic/admin/order/refundOrderLogic.go

@@ -0,0 +1,298 @@
+package order
+
+import (
+	"context"
+	"fmt"
+	"strings"
+	"time"
+
+	"github.com/perfect-panel/server/internal/model/log"
+	modelorder "github.com/perfect-panel/server/internal/model/order"
+	modeluser "github.com/perfect-panel/server/internal/model/user"
+	"github.com/perfect-panel/server/internal/svc"
+	"github.com/perfect-panel/server/internal/types"
+	"github.com/perfect-panel/server/pkg/constant"
+	"github.com/perfect-panel/server/pkg/logger"
+	"github.com/perfect-panel/server/pkg/xerr"
+	"github.com/pkg/errors"
+	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
+)
+
+const (
+	orderStatusRefunded = 6
+)
+
+type RefundOrderLogic struct {
+	logger.Logger
+	ctx    context.Context
+	svcCtx *svc.ServiceContext
+}
+
+func NewRefundOrderLogic(ctx context.Context, svcCtx *svc.ServiceContext) *RefundOrderLogic {
+	return &RefundOrderLogic{
+		Logger: logger.WithContext(ctx),
+		ctx:    ctx,
+		svcCtx: svcCtx,
+	}
+}
+
+func (l *RefundOrderLogic) RefundOrder(req *types.RefundOrderRequest) error {
+	operator, ok := l.ctx.Value(constant.CtxKeyUser).(*modeluser.User)
+	if !ok {
+		return errors.Wrapf(xerr.NewErrCode(xerr.InvalidAccess), "Invalid Access")
+	}
+
+	reason := strings.TrimSpace(req.Reason)
+	var cachesToClear []*modeluser.Subscribe
+	var planCacheIDs []int64
+	var userCacheTargets []*modeluser.User
+
+	err := l.svcCtx.DB.WithContext(l.ctx).Transaction(func(tx *gorm.DB) error {
+		var orderInfo modelorder.Order
+		if err := tx.Clauses(clause.Locking{Strength: "UPDATE"}).
+			Model(&modelorder.Order{}).
+			Where("id = ?", req.Id).
+			First(&orderInfo).Error; err != nil {
+			if errors.Is(err, gorm.ErrRecordNotFound) {
+				return errors.Wrapf(xerr.NewErrCode(xerr.OrderNotExist), "order %d not found", req.Id)
+			}
+			return errors.Wrapf(xerr.NewErrCode(xerr.DatabaseQueryError), "query order failed: %v", err)
+		}
+
+		if orderInfo.Status == orderStatusRefunded {
+			return errors.Wrapf(xerr.NewErrCode(xerr.OrderAlreadyRefunded), "order %d already refunded", orderInfo.Id)
+		}
+		if orderInfo.Status != 2 && orderInfo.Status != 5 {
+			return errors.Wrapf(xerr.NewErrCode(xerr.OrderStatusError), "order %d status %d is not refundable", orderInfo.Id, orderInfo.Status)
+		}
+
+		userSub, err := l.lockRefundTargetSubscription(tx, &orderInfo)
+		if err != nil {
+			return err
+		}
+
+		orderStatusBefore := orderInfo.Status
+		subStatusBefore := userSub.Status
+		subExpireBefore := userSub.ExpireTime
+		now := time.Now()
+
+		referer, commissionAmount, err := l.lockCommissionSource(tx, orderInfo.OrderNo, orderInfo.Commission)
+		if err != nil {
+			return err
+		}
+
+		var commissionBefore int64
+		var commissionAfter int64
+		if referer != nil {
+			commissionBefore = referer.Commission
+			commissionAfter = referer.Commission - commissionAmount
+			if err := tx.Model(&modeluser.User{}).
+				Where("id = ?", referer.Id).
+				UpdateColumn("commission", gorm.Expr("commission - ?", commissionAmount)).Error; err != nil {
+				return errors.Wrapf(xerr.NewErrCode(xerr.DatabaseUpdateError), "refund commission failed: %v", err)
+			}
+
+			commissionLog := log.Commission{
+				Type:      log.CommissionTypeRefund,
+				Amount:    -commissionAmount,
+				OrderNo:   orderInfo.OrderNo,
+				Timestamp: now.UnixMilli(),
+			}
+			content, marshalErr := commissionLog.Marshal()
+			if marshalErr != nil {
+				return errors.Wrapf(xerr.NewErrCode(xerr.ERROR), "marshal commission refund log failed: %v", marshalErr)
+			}
+			if err := tx.Model(&log.SystemLog{}).Create(&log.SystemLog{
+				Type:      log.TypeCommission.Uint8(),
+				Date:      now.Format(time.DateOnly),
+				ObjectID:  referer.Id,
+				Content:   string(content),
+				CreatedAt: now,
+			}).Error; err != nil {
+				return errors.Wrapf(xerr.NewErrCode(xerr.DatabaseInsertError), "insert commission refund log failed: %v", err)
+			}
+			referer.Commission = commissionAfter
+			userCacheTargets = append(userCacheTargets, referer)
+		}
+
+		if err := tx.Model(&modelorder.Order{}).
+			Where("id = ? AND status IN ?", orderInfo.Id, []int{2, 5}).
+			Update("status", orderStatusRefunded).Error; err != nil {
+			return errors.Wrapf(xerr.NewErrCode(xerr.DatabaseUpdateError), "refund order status update failed: %v", err)
+		}
+		orderInfo.Status = orderStatusRefunded
+
+		userSub.Status = 3
+		userSub.ExpireTime = now.Add(-time.Second)
+		userSub.FinishedAt = &now
+		if err := tx.Model(&modeluser.Subscribe{}).
+			Where("id = ?", userSub.Id).
+			Updates(map[string]interface{}{
+				"status":      userSub.Status,
+				"expire_time": userSub.ExpireTime,
+				"finished_at": userSub.FinishedAt,
+			}).Error; err != nil {
+			return errors.Wrapf(xerr.NewErrCode(xerr.DatabaseUpdateError), "update subscription failed: %v", err)
+		}
+
+		refundLog, err := l.buildRefundAuditLog(operator, &orderInfo, userSub, referer, commissionAmount, reason, orderStatusBefore, subStatusBefore, subExpireBefore, commissionBefore, commissionAfter, now)
+		if err != nil {
+			return err
+		}
+		logContent, err := refundLog.Marshal()
+		if err != nil {
+			return errors.Wrapf(xerr.NewErrCode(xerr.ERROR), "marshal refund audit log failed: %v", err)
+		}
+		if err := tx.Model(&log.SystemLog{}).Create(&log.SystemLog{
+			Type:      log.TypeOrderRefund.Uint8(),
+			Date:      now.Format(time.DateOnly),
+			ObjectID:  orderInfo.Id,
+			Content:   string(logContent),
+			CreatedAt: now,
+		}).Error; err != nil {
+			return errors.Wrapf(xerr.NewErrCode(xerr.DatabaseInsertError), "insert refund audit log failed: %v", err)
+		}
+
+		cachesToClear = append(cachesToClear, userSub)
+		if userSub.SubscribeId > 0 {
+			planCacheIDs = append(planCacheIDs, userSub.SubscribeId)
+		}
+		if orderInfo.UserId > 0 {
+			orderUser := &modeluser.User{Id: orderInfo.UserId}
+			userCacheTargets = append(userCacheTargets, orderUser)
+		}
+		return nil
+	})
+	if err != nil {
+		l.Errorw("[RefundOrder] refund failed", logger.Field("error", err.Error()), logger.Field("order_id", req.Id))
+		return err
+	}
+
+	if len(cachesToClear) > 0 {
+		if clearErr := l.svcCtx.UserModel.ClearSubscribeCache(l.ctx, cachesToClear...); clearErr != nil {
+			l.Errorw("[RefundOrder] clear subscribe cache failed", logger.Field("error", clearErr.Error()), logger.Field("order_id", req.Id))
+		}
+	}
+	for _, subscribeID := range planCacheIDs {
+		if clearErr := l.svcCtx.SubscribeModel.ClearCache(l.ctx, subscribeID); clearErr != nil {
+			l.Errorw("[RefundOrder] clear subscribe cache failed", logger.Field("error", clearErr.Error()), logger.Field("subscribe_id", subscribeID))
+		}
+	}
+	if len(userCacheTargets) > 0 {
+		if clearErr := l.svcCtx.UserModel.ClearUserCache(l.ctx, userCacheTargets...); clearErr != nil {
+			l.Errorw("[RefundOrder] clear user cache failed", logger.Field("error", clearErr.Error()))
+		}
+	}
+	return nil
+}
+
+func (l *RefundOrderLogic) lockRefundTargetSubscription(tx *gorm.DB, orderInfo *modelorder.Order) (*modeluser.Subscribe, error) {
+	var userSub modeluser.Subscribe
+	err := tx.Clauses(clause.Locking{Strength: "UPDATE"}).
+		Model(&modeluser.Subscribe{}).
+		Where("order_id = ?", orderInfo.Id).
+		First(&userSub).Error
+	if err == nil {
+		return &userSub, nil
+	}
+	if !errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, errors.Wrapf(xerr.NewErrCode(xerr.DatabaseQueryError), "query refund subscription failed: %v", err)
+	}
+
+	if orderInfo.Type != 2 {
+		return nil, errors.Wrapf(xerr.NewErrCode(xerr.OrderRefundNoSubscription), "order %d has no linked subscription", orderInfo.Id)
+	}
+
+	if orderInfo.ParentId == 0 {
+		return nil, errors.Wrapf(xerr.NewErrCode(xerr.OrderRefundNoSubscription), "renewal order %d has no parent order", orderInfo.Id)
+	}
+
+	err = tx.Clauses(clause.Locking{Strength: "UPDATE"}).
+		Model(&modeluser.Subscribe{}).
+		Where("order_id = ?", orderInfo.ParentId).
+		First(&userSub).Error
+	if err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			return nil, errors.Wrapf(xerr.NewErrCode(xerr.OrderRefundNoSubscription), "renewal order %d parent subscription not found", orderInfo.Id)
+		}
+		return nil, errors.Wrapf(xerr.NewErrCode(xerr.DatabaseQueryError), "query renewal subscription failed: %v", err)
+	}
+	return &userSub, nil
+}
+
+func (l *RefundOrderLogic) lockCommissionSource(tx *gorm.DB, orderNo string, orderCommission int64) (*modeluser.User, int64, error) {
+	var commissionLogs []log.SystemLog
+	if err := tx.Clauses(clause.Locking{Strength: "UPDATE"}).
+		Model(&log.SystemLog{}).
+		Where("type = ? AND content LIKE ?", log.TypeCommission.Uint8(), fmt.Sprintf("%%\"order_no\":\"%s\"%%", orderNo)).
+		Order("id DESC").
+		Find(&commissionLogs).Error; err != nil {
+		return nil, 0, errors.Wrapf(xerr.NewErrCode(xerr.DatabaseQueryError), "query commission log failed: %v", err)
+	}
+
+	for _, item := range commissionLogs {
+		var content log.Commission
+		if err := content.Unmarshal([]byte(item.Content)); err != nil {
+			continue
+		}
+		if content.Type != log.CommissionTypePurchase && content.Type != log.CommissionTypeRenewal {
+			continue
+		}
+
+		var referer modeluser.User
+		if err := tx.Clauses(clause.Locking{Strength: "UPDATE"}).
+			Model(&modeluser.User{}).
+			Where("id = ?", item.ObjectID).
+			First(&referer).Error; err != nil {
+			return nil, 0, errors.Wrapf(xerr.NewErrCode(xerr.DatabaseQueryError), "query commission owner failed: %v", err)
+		}
+		return &referer, content.Amount, nil
+	}
+
+	if orderCommission > 0 {
+		return nil, 0, errors.Wrapf(xerr.NewErrCode(xerr.OrderRefundCommissionMismatch), "order %s commission owner not found", orderNo)
+	}
+	return nil, 0, nil
+}
+
+func (l *RefundOrderLogic) buildRefundAuditLog(
+	operator *modeluser.User,
+	orderInfo *modelorder.Order,
+	userSub *modeluser.Subscribe,
+	referer *modeluser.User,
+	commissionAmount int64,
+	reason string,
+	orderStatusBefore uint8,
+	subStatusBefore uint8,
+	subExpireBefore time.Time,
+	commissionBefore int64,
+	commissionAfter int64,
+	now time.Time,
+) (*log.OrderRefund, error) {
+	refundLog := &log.OrderRefund{
+		OrderId:               orderInfo.Id,
+		OrderNo:               orderInfo.OrderNo,
+		OperatorUserId:        operator.Id,
+		TargetUserId:          userSub.UserId,
+		UserSubscribeId:       userSub.Id,
+		CommissionAmount:      commissionAmount,
+		Reason:                reason,
+		OrderStatusBefore:     orderStatusBefore,
+		OrderStatusAfter:      orderInfo.Status,
+		SubscribeStatusBefore: subStatusBefore,
+		SubscribeStatusAfter:  userSub.Status,
+		SubscribeExpireBefore: subExpireBefore.UnixMilli(),
+		SubscribeExpireAfter:  userSub.ExpireTime.UnixMilli(),
+		CommissionBefore:      commissionBefore,
+		CommissionAfter:       commissionAfter,
+		Timestamp:             now.UnixMilli(),
+	}
+	if referer != nil {
+		refundLog.RefererUserId = referer.Id
+	}
+	if len(operator.AuthMethods) > 0 {
+		refundLog.OperatorAuthIdentifier = operator.AuthMethods[0].AuthIdentifier
+	}
+	return refundLog, nil
+}

internal/logic/admin/order/refundOrderLogic_test.go

@@ -0,0 +1,85 @@
+package order
+
+import (
+	"testing"
+	"time"
+
+	modelorder "github.com/perfect-panel/server/internal/model/order"
+	modeluser "github.com/perfect-panel/server/internal/model/user"
+)
+
+func TestOrderStatusName(t *testing.T) {
+	tests := map[uint8]string{
+		1: "pending",
+		2: "paid",
+		3: "closed",
+		4: "failed",
+		5: "finished",
+		6: "refunded",
+		7: "unknown",
+	}
+
+	for input, want := range tests {
+		if got := orderStatusName(input); got != want {
+			t.Fatalf("status %d: got %q want %q", input, got, want)
+		}
+	}
+}
+
+func TestBuildRefundAuditLog(t *testing.T) {
+	logic := &RefundOrderLogic{}
+	now := time.Unix(1710000000, 0)
+	expireBefore := now.Add(24 * time.Hour)
+	expireAfter := now.Add(-time.Second)
+	operator := &modeluser.User{
+		Id: 100,
+		AuthMethods: []modeluser.AuthMethods{
+			{AuthIdentifier: "admin@example.com"},
+		},
+	}
+	orderInfo := &modelorder.Order{Id: 10, OrderNo: "ORD-1", Status: orderStatusRefunded}
+	userSub := &modeluser.Subscribe{Id: 20, UserId: 30, Status: 3, ExpireTime: expireAfter}
+	referer := &modeluser.User{Id: 40}
+
+	got, err := logic.buildRefundAuditLog(
+		operator,
+		orderInfo,
+		userSub,
+		referer,
+		500,
+		"manual refund",
+		5,
+		1,
+		expireBefore,
+		900,
+		400,
+		now,
+	)
+	if err != nil {
+		t.Fatalf("buildRefundAuditLog error: %v", err)
+	}
+	if got.OrderId != 10 || got.OrderNo != "ORD-1" {
+		t.Fatalf("unexpected order info: %+v", got)
+	}
+	if got.OperatorUserId != 100 || got.OperatorAuthIdentifier != "admin@example.com" {
+		t.Fatalf("unexpected operator info: %+v", got)
+	}
+	if got.TargetUserId != 30 || got.UserSubscribeId != 20 {
+		t.Fatalf("unexpected subscription info: %+v", got)
+	}
+	if got.RefererUserId != 40 || got.CommissionAmount != 500 {
+		t.Fatalf("unexpected commission info: %+v", got)
+	}
+	if got.OrderStatusBefore != 5 || got.OrderStatusAfter != orderStatusRefunded {
+		t.Fatalf("unexpected order status: %+v", got)
+	}
+	if got.SubscribeStatusBefore != 1 || got.SubscribeStatusAfter != 3 {
+		t.Fatalf("unexpected subscribe status: %+v", got)
+	}
+	if got.SubscribeExpireBefore != expireBefore.UnixMilli() || got.SubscribeExpireAfter != expireAfter.UnixMilli() {
+		t.Fatalf("unexpected expire transition: %+v", got)
+	}
+	if got.CommissionBefore != 900 || got.CommissionAfter != 400 {
+		t.Fatalf("unexpected commission transition: %+v", got)
+	}
+}

internal/logic/admin/user/approveWithdrawalLogic.go

@@ -0,0 +1,27 @@
+package user
+
+import (
+	"context"
+
+	"github.com/perfect-panel/server/internal/svc"
+	"github.com/perfect-panel/server/internal/types"
+	"github.com/perfect-panel/server/pkg/logger"
+)
+
+type ApproveWithdrawalLogic struct {
+	logger.Logger
+	ctx    context.Context
+	svcCtx *svc.ServiceContext
+}
+
+func NewApproveWithdrawalLogic(ctx context.Context, svcCtx *svc.ServiceContext) *ApproveWithdrawalLogic {
+	return &ApproveWithdrawalLogic{
+		Logger: logger.WithContext(ctx),
+		ctx:    ctx,
+		svcCtx: svcCtx,
+	}
+}
+
+func (l *ApproveWithdrawalLogic) ApproveWithdrawal(req *types.ApproveWithdrawalRequest) error {
+	return approveWithdrawal(l.ctx, l.svcCtx, req.WithdrawalId)
+}

internal/logic/admin/user/getWithdrawalListLogic.go

@@ -0,0 +1,80 @@
+package user
+
+import (
+	"context"
+
+	usermodel "github.com/perfect-panel/server/internal/model/user"
+	"github.com/perfect-panel/server/internal/svc"
+	"github.com/perfect-panel/server/internal/types"
+	"github.com/perfect-panel/server/pkg/logger"
+	"github.com/perfect-panel/server/pkg/xerr"
+	"github.com/pkg/errors"
+)
+
+type GetWithdrawalListLogic struct {
+	logger.Logger
+	ctx    context.Context
+	svcCtx *svc.ServiceContext
+}
+
+func NewGetWithdrawalListLogic(ctx context.Context, svcCtx *svc.ServiceContext) *GetWithdrawalListLogic {
+	return &GetWithdrawalListLogic{
+		Logger: logger.WithContext(ctx),
+		ctx:    ctx,
+		svcCtx: svcCtx,
+	}
+}
+
+func (l *GetWithdrawalListLogic) GetWithdrawalList(req *types.GetWithdrawalListRequest) (*types.GetWithdrawalListResponse, error) {
+	page := req.Page
+	size := req.Size
+	if page <= 0 {
+		page = 1
+	}
+	if size <= 0 {
+		size = 10
+	}
+
+	query := l.svcCtx.DB.WithContext(l.ctx).Model(&usermodel.Withdrawal{})
+	if req.UserId != nil {
+		query = query.Where("user_id = ?", *req.UserId)
+	}
+	if req.Status != nil {
+		query = query.Where("status = ?", *req.Status)
+	}
+	if req.Method != nil {
+		query = query.Where("method = ?", *req.Method)
+	}
+
+	var total int64
+	if err := query.Count(&total).Error; err != nil {
+		return nil, errors.Wrapf(xerr.NewErrCode(xerr.DatabaseQueryError), "count withdrawals failed: %v", err)
+	}
+
+	var rows []usermodel.Withdrawal
+	if err := query.Order("id DESC").Limit(size).Offset((page - 1) * size).Find(&rows).Error; err != nil {
+		return nil, errors.Wrapf(xerr.NewErrCode(xerr.DatabaseQueryError), "query withdrawals failed: %v", err)
+	}
+
+	list := make([]types.WithdrawalLog, 0, len(rows))
+	for _, row := range rows {
+		list = append(list, types.WithdrawalLog{
+			Id:        row.Id,
+			UserId:    row.UserId,
+			Amount:    row.Amount,
+			Content:   row.Content,
+			Status:    row.Status,
+			Reason:    row.Reason,
+			Method:    row.Method,
+			Account:   row.Account,
+			QrCodeUrl: row.QrCodeUrl,
+			CreatedAt: row.CreatedAt.UnixMilli(),
+			UpdatedAt: row.UpdatedAt.UnixMilli(),
+		})
+	}
+
+	return &types.GetWithdrawalListResponse{
+		List:  list,
+		Total: total,
+	}, nil
+}

internal/logic/admin/user/rejectWithdrawalLogic.go

@@ -0,0 +1,27 @@
+package user
+
+import (
+	"context"
+
+	"github.com/perfect-panel/server/internal/svc"
+	"github.com/perfect-panel/server/internal/types"
+	"github.com/perfect-panel/server/pkg/logger"
+)
+
+type RejectWithdrawalLogic struct {
+	logger.Logger
+	ctx    context.Context
+	svcCtx *svc.ServiceContext
+}
+
+func NewRejectWithdrawalLogic(ctx context.Context, svcCtx *svc.ServiceContext) *RejectWithdrawalLogic {
+	return &RejectWithdrawalLogic{
+		Logger: logger.WithContext(ctx),
+		ctx:    ctx,
+		svcCtx: svcCtx,
+	}
+}
+
+func (l *RejectWithdrawalLogic) RejectWithdrawal(req *types.RejectWithdrawalRequest) error {
+	return rejectWithdrawal(l.ctx, l.svcCtx, req.WithdrawalId, req.Reason)
+}

internal/logic/admin/user/updateUserBasicInfoLogic.go

@@ -6,6 +6,7 @@ import (
 	"strings"
 	"time"
 
+	logicCommon "github.com/perfect-panel/server/internal/logic/common"
 	"github.com/perfect-panel/server/internal/model/log"
 	"github.com/perfect-panel/server/internal/svc"
 	"github.com/perfect-panel/server/internal/types"
@@ -45,13 +46,13 @@ func (l *UpdateUserBasicInfoLogic) UpdateUserBasicInfo(req *types.UpdateUserBasi
 	}
 
 	err = l.svcCtx.UserModel.Transaction(l.ctx, func(tx *gorm.DB) error {
-		if userInfo.Balance != req.Balance {
+		if req.Balance != nil && userInfo.Balance != *req.Balance {
-			change := req.Balance - userInfo.Balance
+			change := *req.Balance - userInfo.Balance
 			balanceLog := log.Balance{
 				Type:      log.BalanceTypeAdjust,
 				Amount:    change,
 				OrderNo:   "",
-				Balance:   req.Balance,
+				Balance:   *req.Balance,
 				Timestamp: time.Now().UnixMilli(),
 			}
 			content, _ := balanceLog.Marshal()
@@ -65,14 +66,14 @@ func (l *UpdateUserBasicInfoLogic) UpdateUserBasicInfo(req *types.UpdateUserBasi
 			if err != nil {
 				return err
 			}
-			userInfo.Balance = req.Balance
+			userInfo.Balance = *req.Balance
 		}
 
-		if userInfo.GiftAmount != req.GiftAmount {
+		if req.GiftAmount != nil && userInfo.GiftAmount != *req.GiftAmount {
-			change := req.GiftAmount - userInfo.GiftAmount
+			change := *req.GiftAmount - userInfo.GiftAmount
 			if change != 0 {
 				var changeType uint16
-				if userInfo.GiftAmount < req.GiftAmount {
+				if userInfo.GiftAmount < *req.GiftAmount {
 					changeType = log.GiftTypeIncrease
 				} else {
 					changeType = log.GiftTypeReduce
@@ -80,7 +81,7 @@ func (l *UpdateUserBasicInfoLogic) UpdateUserBasicInfo(req *types.UpdateUserBasi
 				giftLog := log.Gift{
 					Type:      changeType,
 					Amount:    change,
-					Balance:   req.GiftAmount,
+					Balance:   *req.GiftAmount,
 					Remark:    "Admin adjustment",
 					Timestamp: time.Now().UnixMilli(),
 				}
@@ -95,29 +96,27 @@ func (l *UpdateUserBasicInfoLogic) UpdateUserBasicInfo(req *types.UpdateUserBasi
 				if err != nil {
 					return err
 				}
-				userInfo.GiftAmount = req.GiftAmount
+				userInfo.GiftAmount = *req.GiftAmount
 			}
 		}
 
-		if req.Commission != userInfo.Commission {
+		if req.Commission != nil && *req.Commission != userInfo.Commission {
-
+			remark := ""
-			commentLog := log.Commission{
+			if req.Remark != nil {
-				Type:      log.CommissionTypeAdjust,
+				remark = *req.Remark
-				Amount:    req.Commission - userInfo.Commission,
-				Timestamp: time.Now().UnixMilli(),
 			}
-
+			if isWithdrawalScene(remark) {
-			content, _ := commentLog.Marshal()
+				logWithdrawalGuard(l.Logger, userInfo.Id)
-			err = tx.Create(&log.SystemLog{
+				return errors.Wrapf(xerr.NewErrCode(xerr.InvalidAccess), "commission overwrite is blocked in withdrawal scene")
-				Type:     log.TypeCommission.Uint8(),
+			}
-				Date:     time.Now().Format(time.DateOnly),
+			change := *req.Commission - userInfo.Commission
-				ObjectID: userInfo.Id,
+			if err = l.svcCtx.UserModel.UpdateCommission(l.ctx, userInfo.Id, change, tx); err != nil {
-				Content:  string(content),
-			}).Error
-			if err != nil {
 				return err
 			}
-			userInfo.Commission = req.Commission
+			if err = logicCommon.WriteCommissionLog(tx, userInfo.Id, log.CommissionTypeAdjust, change, ""); err != nil {
+				return err
+			}
+			userInfo.Commission = *req.Commission
 		}
 		if req.Avatar != "" {
 			userInfo.Avatar = req.Avatar
@@ -125,15 +124,17 @@ func (l *UpdateUserBasicInfoLogic) UpdateUserBasicInfo(req *types.UpdateUserBasi
 		if req.ReferCode != "" {
 			userInfo.ReferCode = req.ReferCode
 		}
-		userInfo.RefererId = req.RefererId
+		if req.RefererId != nil {
+			userInfo.RefererId = *req.RefererId
+		}
 		if req.Enable != nil {
 			userInfo.Enable = req.Enable
 		}
 		if req.IsAdmin != nil {
 			userInfo.IsAdmin = req.IsAdmin
 		}
-		if req.Remark != "" {
+		if req.Remark != nil {
-			userInfo.Remark = req.Remark
+			userInfo.Remark = *req.Remark
 		}
 		if req.OnlyFirstPurchase != nil {
 			userInfo.OnlyFirstPurchase = req.OnlyFirstPurchase

internal/logic/admin/user/withdrawalCommon.go

@@ -0,0 +1,98 @@
+package user
+
+import (
+	"context"
+	"strings"
+
+	logicCommon "github.com/perfect-panel/server/internal/logic/common"
+	"github.com/perfect-panel/server/internal/model/log"
+	usermodel "github.com/perfect-panel/server/internal/model/user"
+	"github.com/perfect-panel/server/internal/svc"
+	"github.com/perfect-panel/server/pkg/logger"
+	"github.com/perfect-panel/server/pkg/xerr"
+	"github.com/pkg/errors"
+	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
+)
+
+func approveWithdrawal(ctx context.Context, svcCtx *svc.ServiceContext, withdrawalID int64) error {
+	var approvedUserID int64
+	err := svcCtx.DB.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		withdrawal, err := logicCommon.LoadPendingWithdrawalForUpdate(ctx, tx, withdrawalID)
+		if err != nil {
+			if err.Error() == "withdrawal status invalid" {
+				return errors.Wrapf(xerr.NewErrCode(xerr.WithdrawalStatusInvalid), "withdrawal %d already processed", withdrawalID)
+			}
+			return errors.Wrapf(xerr.NewErrCode(xerr.DatabaseQueryError), "load withdrawal failed: %v", err)
+		}
+
+		// Lock user row and verify sufficient balance before deducting.
+		var u usermodel.User
+		if err := tx.Clauses(clause.Locking{Strength: "UPDATE"}).
+			Where("id = ?", withdrawal.UserId).First(&u).Error; err != nil {
+			return errors.Wrapf(xerr.NewErrCode(xerr.DatabaseQueryError), "load user failed: %v", err)
+		}
+		if u.Commission < withdrawal.Amount {
+			return errors.Wrapf(xerr.NewErrCode(xerr.UserCommissionNotEnough), "user %d has insufficient commission balance", withdrawal.UserId)
+		}
+
+		if err := tx.Model(&usermodel.Withdrawal{}).
+			Where("id = ? AND status = ?", withdrawalID, usermodel.WithdrawalStatusPending).
+			Updates(map[string]interface{}{
+				"status": usermodel.WithdrawalStatusApproved,
+				"reason": "",
+			}).Error; err != nil {
+			return errors.Wrapf(xerr.NewErrCode(xerr.DatabaseUpdateError), "approve withdrawal failed: %v", err)
+		}
+
+		// Deduct commission atomically inside the transaction.
+		if err := tx.Model(&usermodel.User{}).
+			Where("id = ?", withdrawal.UserId).
+			UpdateColumn("commission", gorm.Expr("commission - ?", withdrawal.Amount)).Error; err != nil {
+			return errors.Wrapf(xerr.NewErrCode(xerr.DatabaseUpdateError), "deduct commission failed: %v", err)
+		}
+
+		if err := logicCommon.WriteCommissionLog(tx, withdrawal.UserId, log.CommissionTypeWithdraw, withdrawal.Amount, ""); err != nil {
+			return errors.Wrapf(xerr.NewErrCode(xerr.DatabaseInsertError), "write commission log failed: %v", err)
+		}
+
+		approvedUserID = withdrawal.UserId
+		return nil
+	})
+
+	if err == nil && approvedUserID > 0 {
+		_ = svcCtx.UserModel.ClearUserCache(ctx, &usermodel.User{Id: approvedUserID})
+	}
+	return err
+}
+
+func rejectWithdrawal(ctx context.Context, svcCtx *svc.ServiceContext, withdrawalID int64, reason string) error {
+	reason = strings.TrimSpace(reason)
+	return svcCtx.DB.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		_, err := logicCommon.LoadPendingWithdrawalForUpdate(ctx, tx, withdrawalID)
+		if err != nil {
+			if err.Error() == "withdrawal status invalid" {
+				return errors.Wrapf(xerr.NewErrCode(xerr.WithdrawalStatusInvalid), "withdrawal %d already processed", withdrawalID)
+			}
+			return errors.Wrapf(xerr.NewErrCode(xerr.DatabaseQueryError), "load withdrawal failed: %v", err)
+		}
+
+		// Commission was NOT deducted at application time under the new logic,
+		// so rejection requires no refund — only a status update.
+		return tx.Model(&usermodel.Withdrawal{}).
+			Where("id = ? AND status = ?", withdrawalID, usermodel.WithdrawalStatusPending).
+			Updates(map[string]interface{}{
+				"status": usermodel.WithdrawalStatusRejected,
+				"reason": reason,
+			}).Error
+	})
+}
+
+func isWithdrawalScene(remark string) bool {
+	normalized := strings.ToLower(strings.TrimSpace(remark))
+	return strings.Contains(normalized, "withdraw") || strings.Contains(normalized, "提现")
+}
+
+func logWithdrawalGuard(l logger.Logger, userID int64) {
+	l.Errorw("blocked commission overwrite in withdrawal scene", logger.Field("user_id", userID))
+}

internal/logic/common/logMessageReportLogic.go

@@ -1,108 +1,120 @@
 package common
 
 import (
-    "context"
+	"context"
-    "crypto/sha256"
+	"crypto/sha256"
-    "encoding/hex"
+	"encoding/hex"
-    "encoding/json"
+	"encoding/json"
-    "net"
+	"net"
-    "strings"
+	"strings"
-    "time"
+	"time"
 
-    "github.com/gin-gonic/gin"
+	"github.com/gin-gonic/gin"
-    logmessage "github.com/perfect-panel/server/internal/model/logmessage"
+	logmessage "github.com/perfect-panel/server/internal/model/logmessage"
-    "github.com/perfect-panel/server/internal/svc"
+	"github.com/perfect-panel/server/internal/svc"
-    "github.com/perfect-panel/server/internal/types"
+	"github.com/perfect-panel/server/internal/types"
-    "github.com/perfect-panel/server/pkg/logger"
+	"github.com/perfect-panel/server/pkg/logger"
-    "github.com/perfect-panel/server/pkg/xerr"
+	"github.com/perfect-panel/server/pkg/xerr"
-    "github.com/pkg/errors"
+	"github.com/pkg/errors"
 )
 
 type ReportLogMessageLogic struct {
-    logger.Logger
+	logger.Logger
-    ctx    context.Context
+	ctx    context.Context
-    svcCtx *svc.ServiceContext
+	svcCtx *svc.ServiceContext
 }
 
 func NewReportLogMessageLogic(ctx context.Context, svcCtx *svc.ServiceContext) *ReportLogMessageLogic {
-    return &ReportLogMessageLogic{ Logger: logger.WithContext(ctx), ctx: ctx, svcCtx: svcCtx }
+	return &ReportLogMessageLogic{Logger: logger.WithContext(ctx), ctx: ctx, svcCtx: svcCtx}
 }
 
 func (l *ReportLogMessageLogic) ReportLogMessage(req *types.ReportLogMessageRequest, c *gin.Context) (resp *types.ReportLogMessageResponse, err error) {
-    ip := clientIP(c)
+	ip := clientIP(c)
-    ua := c.GetHeader("User-Agent")
+	ua := c.GetHeader("User-Agent")
-    locale := c.GetHeader("Accept-Language")
+	locale := c.GetHeader("Accept-Language")
 
-    // 简单限流：设备ID优先，其次IP
+	// 简单限流：设备ID优先，其次IP
-    limitKey := "logmsg:" + strings.TrimSpace(req.DeviceId)
+	limitKey := "logmsg:" + strings.TrimSpace(req.DeviceId)
-    if limitKey == "logmsg:" { limitKey = "logmsg:" + ip }
+	if limitKey == "logmsg:" {
-    count, _ := l.svcCtx.Redis.Incr(l.ctx, limitKey).Result()
+		limitKey = "logmsg:" + ip
-    if count == 1 { _ = l.svcCtx.Redis.Expire(l.ctx, limitKey, 60*time.Second).Err() }
+	}
-    if count > 120 { // 每分钟最多120条
+	count, _ := l.svcCtx.Redis.Incr(l.ctx, limitKey).Result()
-        return nil, errors.Wrapf(xerr.NewErrCode(xerr.TooManyRequests), "too many reports")
+	if count == 1 {
-    }
+		_ = l.svcCtx.Redis.Expire(l.ctx, limitKey, 60*time.Second).Err()
+	}
+	if count > 120 { // 每分钟最多120条
+		return nil, errors.Wrapf(xerr.NewErrCode(xerr.TooManyRequests), "too many reports")
+	}
 
-    // 指纹生成
+	// 指纹生成
-    h := sha256.New()
+	h := sha256.New()
-    h.Write([]byte(strings.Join([]string{req.Message, req.Stack, req.ErrorCode, req.AppVersion, req.Platform}, "|")))
+	h.Write([]byte(strings.Join([]string{req.Message, req.Stack, req.ErrorCode, req.AppVersion, req.Platform}, "|")))
-    digest := hex.EncodeToString(h.Sum(nil))
+	digest := hex.EncodeToString(h.Sum(nil))
 
-    var ctxStr string
+	var ctxStr string
-    if req.Context != nil {
+	if req.Context != nil {
-        if b, e := json.Marshal(req.Context); e == nil {
+		if b, e := json.Marshal(req.Context); e == nil {
-            ctxStr = string(b)
+			ctxStr = string(b)
-        }
+		}
-    }
+	}
-    var occurredAt *time.Time
+	var occurredAt *time.Time
-    if req.OccurredAt > 0 {
+	if req.OccurredAt > 0 {
-        t := time.UnixMilli(req.OccurredAt)
+		t := time.UnixMilli(req.OccurredAt)
-        occurredAt = &t
+		occurredAt = &t
-    }
+	}
 
-    var userIdPtr *int64
+	var userIdPtr *int64
-    if req.UserId > 0 { userIdPtr = &req.UserId }
+	if req.UserId > 0 {
+		userIdPtr = &req.UserId
+	}
 
-    row := &logmessage.LogMessage{
+	row := &logmessage.LogMessage{
-        Platform:   req.Platform,
+		Platform:   safeTruncate(req.Platform, 32),
-        AppVersion: req.AppVersion,
+		AppVersion: safeTruncate(req.AppVersion, 64),
-        OsName:     req.OsName,
+		OsName:     safeTruncate(req.OsName, 64),
-        OsVersion:  req.OsVersion,
+		OsVersion:  safeTruncate(req.OsVersion, 64),
-        DeviceId:   req.DeviceId,
+		DeviceId:   safeTruncate(req.DeviceId, 255),
-        UserId:     userIdPtr,
+		UserId:     userIdPtr,
-        SessionId:  req.SessionId,
+		SessionId:  safeTruncate(req.SessionId, 255),
-        Level:      req.Level,
+		Level:      req.Level,
-        ErrorCode:  req.ErrorCode,
+		ErrorCode:  safeTruncate(req.ErrorCode, 128),
-        Message:    safeTruncate(req.Message, 1024*64),
+		Message:    safeTruncate(req.Message, 1024*64),
-        Stack:      safeTruncate(req.Stack, 1024*1024),
+		Stack:      safeTruncate(req.Stack, 1024*1024),
-        Context:    ctxStr,
+		Context:    ctxStr,
-        ClientIP:   ip,
+		ClientIP:   ip,
-        UserAgent:  safeTruncate(ua, 255),
+		UserAgent:  safeTruncate(ua, 255),
-        Locale:     safeTruncate(locale, 16),
+		Locale:     safeTruncate(locale, 16),
-        Digest:     digest,
+		Digest:     digest,
-        OccurredAt: occurredAt,
+		OccurredAt: occurredAt,
-    }
+	}
 
-    if err = l.svcCtx.LogMessageModel.Insert(l.ctx, row); err != nil {
+	if err = l.svcCtx.LogMessageModel.Insert(l.ctx, row); err != nil {
-        // 唯一指纹冲突时尝试查询已有记录返回ID
+		// 唯一指纹冲突时尝试查询已有记录返回ID
-        ex, _, findErr := l.svcCtx.LogMessageModel.Filter(l.ctx, &logmessage.FilterParams{ Keyword: req.Message, Page: 1, Size: 1 })
+		ex, _, findErr := l.svcCtx.LogMessageModel.Filter(l.ctx, &logmessage.FilterParams{Keyword: req.Message, Page: 1, Size: 1})
-        if findErr == nil && len(ex) > 0 {
+		if findErr == nil && len(ex) > 0 {
-            return &types.ReportLogMessageResponse{ Id: ex[0].Id }, nil
+			return &types.ReportLogMessageResponse{Id: ex[0].Id}, nil
-        }
+		}
-        l.Errorf("[ReportLogMessage] insert error: %v", err)
+		l.Errorf("[ReportLogMessage] insert error: %v", err)
-        return nil, errors.Wrapf(xerr.NewErrCode(xerr.DatabaseQueryError), "insert log_message failed: %v", err)
+		return nil, errors.Wrapf(xerr.NewErrCode(xerr.DatabaseQueryError), "insert log_message failed: %v", err)
-    }
+	}
-    return &types.ReportLogMessageResponse{ Id: row.Id }, nil
+	return &types.ReportLogMessageResponse{Id: row.Id}, nil
 }
 
 func safeTruncate(s string, n int) string {
-    if len(s) <= n { return s }
+	if len(s) <= n {
-    return s[:n]
+		return s
+	}
+	return s[:n]
 }
 
 func clientIP(c *gin.Context) string {
-    ip := c.ClientIP()
+	ip := c.ClientIP()
-    if ip != "" { return ip }
+	if ip != "" {
-    host, _, err := net.SplitHostPort(strings.TrimSpace(c.Request.RemoteAddr))
+		return ip
-    if err == nil && host != "" { return host }
+	}
-    return ""
+	host, _, err := net.SplitHostPort(strings.TrimSpace(c.Request.RemoteAddr))
+	if err == nil && host != "" {
+		return host
+	}
+	return ""
 }

internal/logic/common/withdrawal.go

@@ -0,0 +1,48 @@
+package common
+
+import (
+	"context"
+	"time"
+
+	"github.com/perfect-panel/server/internal/model/log"
+	usermodel "github.com/perfect-panel/server/internal/model/user"
+	"github.com/pkg/errors"
+	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
+)
+
+func WriteCommissionLog(tx *gorm.DB, objectID int64, logType uint16, amount int64, orderNo string) error {
+	logInfo := log.Commission{
+		Type:      logType,
+		Amount:    amount,
+		OrderNo:   orderNo,
+		Timestamp: time.Now().UnixMilli(),
+	}
+
+	content, err := logInfo.Marshal()
+	if err != nil {
+		return err
+	}
+
+	return tx.Model(log.SystemLog{}).Create(&log.SystemLog{
+		Type:      log.TypeCommission.Uint8(),
+		Date:      time.Now().Format(time.DateOnly),
+		ObjectID:  objectID,
+		Content:   string(content),
+		CreatedAt: time.Now(),
+	}).Error
+}
+
+func LoadPendingWithdrawalForUpdate(ctx context.Context, tx *gorm.DB, withdrawalID int64) (*usermodel.Withdrawal, error) {
+	var withdrawal usermodel.Withdrawal
+	if err := tx.WithContext(ctx).
+		Clauses(clause.Locking{Strength: "UPDATE"}).
+		Where("id = ?", withdrawalID).
+		First(&withdrawal).Error; err != nil {
+		return nil, err
+	}
+	if withdrawal.Status != usermodel.WithdrawalStatusPending {
+		return nil, errors.New("withdrawal status invalid")
+	}
+	return &withdrawal, nil
+}

internal/logic/notify/appleIAPNotifyLogic.go

@@ -3,17 +3,20 @@ package notify
 import (
 	"context"
 	"encoding/json"
+	"fmt"
 	"strconv"
 	"strings"
 
 	commonLogic "github.com/perfect-panel/server/internal/logic/common"
 	iapmodel "github.com/perfect-panel/server/internal/model/iap/apple"
+	"github.com/perfect-panel/server/internal/model/order"
 	"github.com/perfect-panel/server/internal/model/subscribe"
 	"github.com/perfect-panel/server/internal/model/user"
 	"github.com/perfect-panel/server/internal/svc"
 	"github.com/perfect-panel/server/internal/types"
 	iapapple "github.com/perfect-panel/server/pkg/iap/apple"
 	"github.com/perfect-panel/server/pkg/logger"
+	"github.com/perfect-panel/server/pkg/tool"
 	"gorm.io/gorm"
 )
 
@@ -84,6 +87,7 @@ func (l *AppleIAPNotifyLogic) Handle(signedPayload string) error {
 				l.Errorw("iap notify insert transaction error", logger.Field("error", e.Error()), logger.Field("productId", txPayload.ProductId), logger.Field("originalTransactionId", txPayload.OriginalTransactionId))
 				return e
 			}
+			existing = rec
 		} else {
 			if txPayload.RevocationDate != nil {
 				// 撤销场景：更新 revocation_at
@@ -96,6 +100,32 @@ func (l *AppleIAPNotifyLogic) Handle(signedPayload string) error {
 				}
 			}
 		}
+
+		// Fix Bug 7: resolve userId when the IAP transaction record has no associated user.
+		// This can happen if the first notification for a subscription arrived before the
+		// in-app purchase flow created the order (race) or the order was made in a previous
+		// build that did not write user_id to the IAP transaction table.
+		if existing != nil && existing.UserId == 0 {
+			var origOrder order.Order
+			if lookupErr := db.Model(&order.Order{}).
+				Where("trade_no = ? AND method = ?", txPayload.OriginalTransactionId, "apple_iap").
+				Order("id ASC").
+				First(&origOrder).Error; lookupErr == nil && origOrder.UserId > 0 {
+				existing.UserId = origOrder.UserId
+				_ = db.Model(&iapmodel.Transaction{}).
+					Where("id = ?", existing.Id).
+					Update("user_id", origOrder.UserId).Error
+				l.Infow("iap notify resolved zero userId from original purchase order",
+					logger.Field("userId", origOrder.UserId),
+					logger.Field("originalTransactionId", txPayload.OriginalTransactionId),
+				)
+			} else {
+				l.Errorw("CRITICAL: iap notify UserId=0 and cannot resolve from order, notification dropped",
+					logger.Field("originalTransactionId", txPayload.OriginalTransactionId))
+				return fmt.Errorf("iap notify: UserId=0 and cannot resolve from order for original_transaction_id=%s", txPayload.OriginalTransactionId)
+			}
+		}
+
 		var days int64
 		{
 			pid := strings.ToLower(txPayload.ProductId)
@@ -169,7 +199,12 @@ func (l *AppleIAPNotifyLogic) Handle(signedPayload string) error {
 			}
 		}
 		if days == 0 {
-			l.Errorw("iap notify product mapping missing", logger.Field("productId", txPayload.ProductId))
+			// Both string-parse and DB fallback failed to map the product to days.
+			// Return an error so Apple retries the notification; silently ignoring
+			// this would cause the subscriber's renewal to be lost.
+			l.Errorw("CRITICAL: iap notify product mapping missing, returning error to trigger retry",
+				logger.Field("productId", txPayload.ProductId))
+			return fmt.Errorf("iap product id %s could not be mapped to subscription days", txPayload.ProductId)
 		}
 		token := "iap:" + txPayload.OriginalTransactionId
 		sub, e := l.svcCtx.UserModel.FindOneSubscribeByToken(l.ctx, token)
@@ -216,6 +251,11 @@ func (l *AppleIAPNotifyLogic) Handle(signedPayload string) error {
 							logger.Field("product_id", txPayload.ProductId),
 						)...,
 					)
+					// Create audit order record for renewal notifications (Bug 7)
+					if err := l.createIAPRenewalAuditOrder(db, ntype, txPayload.TransactionId, candidate.UserId, candidate.SubscribeId, candidate.Token); err != nil {
+						l.Errorw("iap notify fallback create renewal order error", logger.Field("error", err.Error()))
+						// Non-fatal: subscription already updated; order creation failure is logged only
+					}
 					break
 				}
 			}
@@ -248,7 +288,52 @@ func (l *AppleIAPNotifyLogic) Handle(signedPayload string) error {
 					logger.Field("product_id", txPayload.ProductId),
 				)...,
 			)
+			// Create audit order record for renewal notifications (Bug 7)
+			if err := l.createIAPRenewalAuditOrder(db, ntype, txPayload.TransactionId, sub.UserId, sub.SubscribeId, sub.Token); err != nil {
+				l.Errorw("iap notify create renewal order error", logger.Field("error", err.Error()))
+				// Non-fatal: subscription already updated; order creation failure is logged only
+			}
 		}
 		return nil
 	})
 }
+
+// createIAPRenewalAuditOrder creates a finished renewal order record for DID_RENEW and SUBSCRIBED
+// Apple SSNS notifications so that the order table has a complete financial audit trail.
+// The operation is idempotent: if an order with the same trade_no already exists it is skipped.
+func (l *AppleIAPNotifyLogic) createIAPRenewalAuditOrder(db *gorm.DB, ntype, transactionId string, userId, subscribeId int64, subscribeToken string) error {
+	if ntype != "DID_RENEW" && ntype != "SUBSCRIBED" {
+		return nil
+	}
+	// Idempotency check
+	var count int64
+	if err := db.Model(&order.Order{}).
+		Where("trade_no = ? AND method = ?", transactionId, "apple_iap").
+		Count(&count).Error; err != nil {
+		return fmt.Errorf("check existing iap renewal order: %w", err)
+	}
+	if count > 0 {
+		return nil
+	}
+	rec := &order.Order{
+		UserId:         userId,
+		OrderNo:        tool.GenerateTradeNo(),
+		Type:           2, // OrderTypeRenewal
+		Status:         5, // OrderStatusFinished
+		Method:         "apple_iap",
+		TradeNo:        transactionId,
+		SubscribeId:    subscribeId,
+		SubscribeToken: subscribeToken,
+		Quantity:       1,
+		IsNew:          false,
+	}
+	if err := db.Model(&order.Order{}).Create(rec).Error; err != nil {
+		return fmt.Errorf("create iap renewal audit order: %w", err)
+	}
+	l.Infow("iap notify created renewal audit order",
+		logger.Field("orderNo", rec.OrderNo),
+		logger.Field("transactionId", transactionId),
+		logger.Field("userId", userId),
+	)
+	return nil
+}

internal/logic/public/file/common.go

@@ -109,14 +109,14 @@ func buildObjectKey(prefix string, userID int64, bizType, fileID, fileName strin
 	if prefix == "" {
 		prefix = "app-upload"
 	}
-	return fmt.Sprintf("%s/%s/%d/%04d/%02d/%s_%s",
+	return fmt.Sprintf("%s/%04d/%02d/%02d/%d/%s__%s",
 		prefix,
-		strings.Trim(safeFileNameRegexp.ReplaceAllString(strings.ToLower(strings.TrimSpace(bizType)), "-"), "-"),
-		userID,
 		now.Year(),
 		int(now.Month()),
-		fileID,
+		now.Day(),
+		userID,
 		safeFileName(fileName),
+		fileID,
 	)
 }
 

internal/logic/public/file/fileuploadlogic.go

@@ -0,0 +1,88 @@
+package file
+
+import (
+	"bytes"
+	"context"
+	"io"
+	"mime/multipart"
+	"net/http"
+	"time"
+
+	"github.com/perfect-panel/server/internal/svc"
+	"github.com/perfect-panel/server/internal/types"
+	"github.com/perfect-panel/server/pkg/logger"
+	"github.com/perfect-panel/server/pkg/xerr"
+	"github.com/pkg/errors"
+)
+
+type FileUploadLogic struct {
+	logger.Logger
+	ctx    context.Context
+	svcCtx *svc.ServiceContext
+}
+
+// Upload file to RustFS
+func NewFileUploadLogic(ctx context.Context, svcCtx *svc.ServiceContext) *FileUploadLogic {
+	return &FileUploadLogic{
+		Logger: logger.WithContext(ctx),
+		ctx:    ctx,
+		svcCtx: svcCtx,
+	}
+}
+
+func (l *FileUploadLogic) FileUpload(req *types.FileUploadRequest, fileHeader *multipart.FileHeader, file multipart.File) (resp *types.FileUploadResponse, err error) {
+	u, err := currentUserFromContext(l.ctx)
+	if err != nil {
+		return nil, err
+	}
+
+	if fileHeader == nil {
+		return nil, errors.Wrapf(xerr.NewErrCode(xerr.InvalidParams), "file is required")
+	}
+
+	contentType, err := sniffContentType(fileHeader, file)
+	if err != nil {
+		return nil, err
+	}
+	if err := validateInitRequest(l.svcCtx, req.BizType, fileHeader.Filename, contentType, fileHeader.Size); err != nil {
+		return nil, err
+	}
+
+	now := time.Now()
+	fileID := buildFileID(u.Id, req.BizType, fileHeader.Filename)
+	objectKey := buildObjectKey(l.svcCtx.Config.S3.Prefix, u.Id, req.BizType, fileID, fileHeader.Filename, now)
+
+	putResult, err := l.svcCtx.S3Store.PutObject(l.ctx, objectKey, file, fileHeader.Size, contentType)
+	if err != nil {
+		l.Errorw("put object failed", logger.Field("error", err.Error()), logger.Field("user_id", u.Id), logger.Field("file_id", fileID))
+		return nil, err
+	}
+
+	return &types.FileUploadResponse{
+		FileId:      fileID,
+		FileName:    fileHeader.Filename,
+		ObjectKey:   objectKey,
+		Size:        fileHeader.Size,
+		ContentType: contentType,
+		Etag:        putResult.ETag,
+		Status:      fileUploadCompleteStatus,
+	}, nil
+}
+
+func sniffContentType(fileHeader *multipart.FileHeader, file multipart.File) (string, error) {
+	if headerType := fileHeader.Header.Get("Content-Type"); headerType != "" {
+		return headerType, nil
+	}
+	if seeker, ok := file.(io.ReadSeeker); ok {
+		buf := make([]byte, 512)
+		n, readErr := seeker.Read(buf)
+		if readErr != nil && readErr != io.EOF {
+			return "", readErr
+		}
+		if _, err := seeker.Seek(0, io.SeekStart); err != nil {
+			return "", err
+		}
+		return http.DetectContentType(bytes.TrimRight(buf[:n], "\x00")), nil
+	}
+	return "application/octet-stream", nil
+}

internal/logic/public/portal/purchaseLogic.go

@@ -154,9 +154,12 @@ func (l *PurchaseLogic) Purchase(req *types.PortalPurchaseRequest) (resp *types.
 		}
 		content, _ := tempOrder.Marshal()
 
-		if _, err = l.svcCtx.Redis.Set(l.ctx, fmt.Sprintf(constant.TempOrderCacheKey, orderInfo.OrderNo), string(content), CloseOrderTimeMinutes*time.Minute).Result(); err != nil {
+		// Persist activation context to DB so the worker can recover if Redis TTL expires.
-			l.Errorw("[Purchase] Redis set error", logger.Field("error", err.Error()), logger.Field("order_no", orderInfo.OrderNo))
+		orderInfo.ActivationContext = string(content)
-			return err
+
+		// Write to Redis as a hot cache (best-effort; non-fatal on failure).
+		if _, redisErr := l.svcCtx.Redis.Set(l.ctx, fmt.Sprintf(constant.TempOrderCacheKey, orderInfo.OrderNo), string(content), CloseOrderTimeMinutes*time.Minute).Result(); redisErr != nil {
+			l.Infow("[Purchase] Redis set error (non-fatal, DB fallback available)", logger.Field("error", redisErr.Error()), logger.Field("order_no", orderInfo.OrderNo))
 		}
 		l.Infow("[Purchase] Guest order", logger.Field("order_no", orderInfo.OrderNo), logger.Field("identifier", req.Identifier))
 
@@ -169,7 +172,7 @@ func (l *PurchaseLogic) Purchase(req *types.PortalPurchaseRequest) (resp *types.
 			}
 		}
 
-		// save guest order
+		// save guest order (activation_context is included)
 		if err = l.svcCtx.OrderModel.Insert(l.ctx, orderInfo, tx); err != nil {
 			return err
 		}

internal/logic/public/redemption/redeemCodeLogic.go

@@ -151,34 +151,48 @@ func (l *RedeemCodeLogic) RedeemCode(req *types.RedeemCodeRequest) (resp *types.
 	}
 
 	// 创建Order记录
+	redemptionContext := struct {
+		Type             string `json:"type"`
+		RedemptionCodeId int64  `json:"redemption_code_id"`
+		UnitTime         string `json:"unit_time"`
+		Quantity         int64  `json:"quantity"`
+	}{
+		Type:             "redemption",
+		RedemptionCodeId: redemptionCode.Id,
+		UnitTime:         redemptionCode.UnitTime,
+		Quantity:         redemptionCode.Quantity,
+	}
+	activationContextJSON, _ := json.Marshal(redemptionContext)
+
 	orderInfo := &order.Order{
-		UserId:         u.Id,
+		UserId:            u.Id,
-		OrderNo:        tool.GenerateTradeNo(),
+		OrderNo:           tool.GenerateTradeNo(),
-		Type:           5, // 兑换类型
+		Type:              5, // 兑换类型
-		Quantity:       redemptionCode.Quantity,
+		Quantity:          redemptionCode.Quantity,
-		Price:          0, // 兑换无价格
+		Price:             0, // 兑换无价格
-		Amount:         0, // 兑换无金额
+		Amount:            0, // 兑换无金额
-		Discount:       0,
+		Discount:          0,
-		GiftAmount:     0,
+		GiftAmount:        0,
-		Coupon:         "",
+		Coupon:            "",
-		CouponDiscount: 0,
+		CouponDiscount:    0,
-		PaymentId:      0,
+		PaymentId:         0,
-		Method:         "redemption",
+		Method:            "redemption",
-		FeeAmount:      0,
+		FeeAmount:         0,
-		Commission:     0,
+		Commission:        0,
-		Status:         2, // 直接设置为已支付
+		Status:            2, // 直接设置为已支付
-		SubscribeId:    redemptionCode.SubscribePlan,
+		SubscribeId:       redemptionCode.SubscribePlan,
-		IsNew:          isNew,
+		IsNew:             isNew,
+		ActivationContext: string(activationContextJSON),
 	}
 
-	// 保存Order到数据库
+	// 保存Order到数据库（activation_context 同步写入，作为 Redis 的持久化兜底）
 	err = l.svcCtx.OrderModel.Insert(l.ctx, orderInfo)
 	if err != nil {
 		l.Errorw("[RedeemCode] Create order failed", logger.Field("error", err.Error()))
 		return nil, errors.Wrapf(xerr.NewErrCode(xerr.DatabaseInsertError), "create order failed")
 	}
 
-	// 缓存兑换码信息到Redis（供队列任务使用）
+	// 缓存兑换码信息到Redis（热缓存，供队列任务快速读取，非关键路径）
 	cacheKey := fmt.Sprintf("redemption_order:%s", orderInfo.OrderNo)
 	cacheData := map[string]interface{}{
 		"redemption_code_id": redemptionCode.Id,
@@ -186,16 +200,8 @@ func (l *RedeemCodeLogic) RedeemCode(req *types.RedeemCodeRequest) (resp *types.
 		"quantity":           redemptionCode.Quantity,
 	}
 	jsonData, _ := json.Marshal(cacheData)
-	err = l.svcCtx.Redis.Set(l.ctx, cacheKey, jsonData, 2*time.Hour).Err()
+	if redisErr := l.svcCtx.Redis.Set(l.ctx, cacheKey, jsonData, 2*time.Hour).Err(); redisErr != nil {
-	if err != nil {
+		l.Infow("[RedeemCode] Cache redemption data failed (non-fatal, DB fallback available)", logger.Field("error", redisErr.Error()))
-		l.Errorw("[RedeemCode] Cache redemption data failed", logger.Field("error", err.Error()))
-		// 缓存失败，删除已创建的Order避免孤儿记录
-		if delErr := l.svcCtx.OrderModel.Delete(l.ctx, orderInfo.Id); delErr != nil {
-			l.Errorw("[RedeemCode] Delete order failed after cache error",
-				logger.Field("order_id", orderInfo.Id),
-				logger.Field("error", delErr.Error()))
-		}
-		return nil, errors.Wrapf(xerr.NewErrCode(xerr.ERROR), "cache redemption data failed")
 	}
 
 	// 触发队列任务

internal/logic/public/user/cancelWithdrawalLogic.go

@@ -0,0 +1,89 @@
+package user
+
+import (
+	"context"
+
+	logicCommon "github.com/perfect-panel/server/internal/logic/common"
+	"github.com/perfect-panel/server/internal/model/log"
+	"github.com/perfect-panel/server/internal/model/user"
+	"github.com/perfect-panel/server/internal/svc"
+	"github.com/perfect-panel/server/internal/types"
+	"github.com/perfect-panel/server/pkg/constant"
+	"github.com/perfect-panel/server/pkg/logger"
+	"github.com/perfect-panel/server/pkg/xerr"
+	"github.com/pkg/errors"
+	"gorm.io/gorm"
+)
+
+type CancelWithdrawalLogic struct {
+	logger.Logger
+	ctx    context.Context
+	svcCtx *svc.ServiceContext
+}
+
+func NewCancelWithdrawalLogic(ctx context.Context, svcCtx *svc.ServiceContext) *CancelWithdrawalLogic {
+	return &CancelWithdrawalLogic{
+		Logger: logger.WithContext(ctx),
+		ctx:    ctx,
+		svcCtx: svcCtx,
+	}
+}
+
+func (l *CancelWithdrawalLogic) CancelWithdrawal(req *types.CancelWithdrawalRequest) (resp *types.WithdrawalLog, err error) {
+	u, ok := l.ctx.Value(constant.CtxKeyUser).(*user.User)
+	if !ok {
+		l.Error("current user is not found in context")
+		return nil, errors.Wrapf(xerr.NewErrCode(xerr.InvalidAccess), "Invalid Access")
+	}
+
+	var withdrawal *user.Withdrawal
+	err = l.svcCtx.DB.WithContext(l.ctx).Transaction(func(tx *gorm.DB) error {
+		var txErr error
+		withdrawal, txErr = logicCommon.LoadPendingWithdrawalForUpdate(l.ctx, tx, req.WithdrawalId)
+		if txErr != nil {
+			if txErr.Error() == "withdrawal status invalid" {
+				return errors.Wrapf(xerr.NewErrCode(xerr.WithdrawalStatusInvalid), "withdrawal %d is not in pending state", req.WithdrawalId)
+			}
+			return errors.Wrapf(xerr.NewErrCode(xerr.DatabaseQueryError), "load withdrawal failed: %v", txErr)
+		}
+
+		if withdrawal.UserId != u.Id {
+			return errors.Wrapf(xerr.NewErrCode(xerr.PermissionDenied), "user %d cannot cancel withdrawal belonging to user %d", u.Id, withdrawal.UserId)
+		}
+
+		if txErr = tx.Model(&user.Withdrawal{}).
+			Where("id = ? AND status = ?", req.WithdrawalId, user.WithdrawalStatusPending).
+			Update("status", user.WithdrawalStatusCancelled).Error; txErr != nil {
+			return errors.Wrapf(xerr.NewErrCode(xerr.DatabaseUpdateError), "cancel withdrawal failed: %v", txErr)
+		}
+
+		if txErr = l.svcCtx.UserModel.UpdateCommission(l.ctx, withdrawal.UserId, withdrawal.Amount, tx); txErr != nil {
+			return errors.Wrapf(xerr.NewErrCode(xerr.DatabaseUpdateError), "refund commission failed: %v", txErr)
+		}
+
+		if txErr = logicCommon.WriteCommissionLog(tx, withdrawal.UserId, log.CommissionTypeWithdrawCancel, withdrawal.Amount, ""); txErr != nil {
+			return errors.Wrapf(xerr.NewErrCode(xerr.DatabaseInsertError), "write commission log failed: %v", txErr)
+		}
+
+		return nil
+	})
+	if err != nil {
+		return nil, err
+	}
+
+	_ = l.svcCtx.UserModel.ClearUserCache(l.ctx, u)
+
+	return &types.WithdrawalLog{
+		Id:        withdrawal.Id,
+		UserId:    withdrawal.UserId,
+		Amount:    withdrawal.Amount,
+		Content:   withdrawal.Content,
+		Status:    user.WithdrawalStatusCancelled,
+		Reason:    "",
+		Method:    withdrawal.Method,
+		Account:   withdrawal.Account,
+		QrCodeUrl: withdrawal.QrCodeUrl,
+		CreatedAt: withdrawal.CreatedAt.UnixMilli(),
+		UpdatedAt: withdrawal.UpdatedAt.UnixMilli(),
+	}, nil
+}

internal/logic/public/user/commissionWithdrawLogic.go

@@ -2,9 +2,7 @@ package user
 
 import (
 	"context"
-	"time"
 
-	"github.com/perfect-panel/server/internal/model/log"
 	"github.com/perfect-panel/server/internal/model/user"
 	"github.com/perfect-panel/server/internal/svc"
 	"github.com/perfect-panel/server/internal/types"
@@ -12,6 +10,7 @@ import (
 	"github.com/perfect-panel/server/pkg/logger"
 	"github.com/perfect-panel/server/pkg/xerr"
 	"github.com/pkg/errors"
+	"gorm.io/gorm"
 )
 
 type CommissionWithdrawLogic struct {
@@ -36,73 +35,70 @@ func (l *CommissionWithdrawLogic) CommissionWithdraw(req *types.CommissionWithdr
 		return nil, errors.Wrapf(xerr.NewErrCode(xerr.InvalidAccess), "Invalid Access")
 	}
 
-	if u.Commission < req.Amount {
+	// Validate payment method fields
-		logger.Errorf("User %d has insufficient commission balance: %.2f, requested: %.2f", u.Id, float64(u.Commission)/100, float64(req.Amount)/100)
+	switch req.Method {
+	case user.WithdrawalMethodAlipay, user.WithdrawalMethodWechat:
+		if req.QrCodeUrl == "" {
+			return nil, errors.Wrapf(xerr.NewErrCode(xerr.InvalidParams), "qr_code_url is required for method %d", req.Method)
+		}
+	case user.WithdrawalMethodBank:
+		if req.Account == "" {
+			return nil, errors.Wrapf(xerr.NewErrCode(xerr.InvalidParams), "account is required for bank transfer")
+		}
+	default: // WithdrawalMethodOther
+		if req.Account == "" && req.Content == "" {
+			return nil, errors.Wrapf(xerr.NewErrCode(xerr.InvalidParams), "account or content is required for other methods")
+		}
+	}
+
+	// Sum all pending (status=0) withdrawals to compute available balance.
+	// Available = commission - pendingTotal; commission is only deducted on approval.
+	var pendingTotal int64
+	if err = l.svcCtx.DB.WithContext(l.ctx).
+		Model(&user.Withdrawal{}).
+		Where("user_id = ? AND status = ?", u.Id, user.WithdrawalStatusPending).
+		Select("COALESCE(SUM(amount), 0)").
+		Scan(&pendingTotal).Error; err != nil {
+		l.Errorf("Failed to query pending withdrawals for user %d: %v", u.Id, err)
+		return nil, errors.Wrapf(xerr.NewErrCode(xerr.DatabaseQueryError), "Failed to query pending withdrawals for user %d", u.Id)
+	}
+
+	if u.Commission < req.Amount+pendingTotal {
+		logger.Errorf("User %d insufficient available commission: total=%d pending=%d requested=%d",
+			u.Id, u.Commission, pendingTotal, req.Amount)
 		return nil, errors.Wrapf(xerr.NewErrCode(xerr.UserCommissionNotEnough), "User %d has insufficient commission balance", u.Id)
 	}
 
-	tx := l.svcCtx.DB.WithContext(l.ctx).Begin()
+	var w user.Withdrawal
-
+	err = l.svcCtx.DB.WithContext(l.ctx).Transaction(func(tx *gorm.DB) error {
-	// update user commission balance
+		w = user.Withdrawal{
-	u.Commission -= req.Amount
+			UserId:    u.Id,
-	if err = l.svcCtx.UserModel.Update(l.ctx, u, tx); err != nil {
+			Amount:    req.Amount,
-		tx.Rollback()
+			Content:   req.Content,
-		l.Errorf("Failed to update user %d commission balance: %v", u.Id, err)
+			Status:    user.WithdrawalStatusPending,
-		return nil, errors.Wrapf(xerr.NewErrCode(xerr.DatabaseUpdateError), "Failed to update user %d commission balance: %v", u.Id, err)
+			Reason:    "",
-	}
+			Method:    req.Method,
-
+			Account:   req.Account,
-	// create withdrawal log
+			QrCodeUrl: req.QrCodeUrl,
-	logInfo := log.Commission{
+		}
-		Type:      log.CommissionTypeConvertBalance,
+		return tx.Create(&w).Error
-		Amount:    req.Amount,
+	})
-		Timestamp: time.Now().UnixMilli(),
-	}
-	b, err := logInfo.Marshal()
-
 	if err != nil {
-		tx.Rollback()
+		l.Errorf("Failed to create withdrawal for user %d: %v", u.Id, err)
-		l.Errorf("Failed to marshal commission log for user %d: %v", u.Id, err)
+		return nil, errors.Wrapf(xerr.NewErrCode(xerr.DatabaseInsertError), "Failed to create withdrawal for user %d: %v", u.Id, err)
-		return nil, errors.Wrapf(xerr.NewErrCode(xerr.ERROR), "Failed to marshal commission log for user %d: %v", u.Id, err)
-	}
-
-	err = tx.Model(log.SystemLog{}).Create(&log.SystemLog{
-		Type:      log.TypeCommission.Uint8(),
-		Date:      time.Now().Format("2006-01-02"),
-		ObjectID:  u.Id,
-		Content:   string(b),
-		CreatedAt: time.Now(),
-	}).Error
-
-	if err != nil {
-		tx.Rollback()
-		l.Errorf("Failed to create commission log for user %d: %v", u.Id, err)
-		return nil, errors.Wrapf(xerr.NewErrCode(xerr.DatabaseInsertError), "Failed to create commission log for user %d: %v", u.Id, err)
-	}
-
-	err = tx.Model(&user.Withdrawal{}).Create(&user.Withdrawal{
-		UserId:  u.Id,
-		Amount:  req.Amount,
-		Content: req.Content,
-		Status:  0,
-		Reason:  "",
-	}).Error
-
-	if err != nil {
-		tx.Rollback()
-		l.Errorf("Failed to create withdrawal log for user %d: %v", u.Id, err)
-		return nil, errors.Wrapf(xerr.NewErrCode(xerr.DatabaseInsertError), "Failed to create withdrawal log for user %d: %v", u.Id, err)
-	}
-	if err = tx.Commit().Error; err != nil {
-		l.Errorf("Transaction commit failed for user %d withdrawal: %v", u.Id, err)
-		return nil, errors.Wrapf(xerr.NewErrCode(xerr.ERROR), "Transaction commit failed for user %d withdrawal: %v", u.Id, err)
 	}
 
 	return &types.WithdrawalLog{
+		Id:        w.Id,
 		UserId:    u.Id,
 		Amount:    req.Amount,
 		Content:   req.Content,
-		Status:    0,
+		Status:    user.WithdrawalStatusPending,
 		Reason:    "",
-		CreatedAt: time.Now().UnixMilli(),
+		Method:    req.Method,
+		Account:   req.Account,
+		QrCodeUrl: req.QrCodeUrl,
+		CreatedAt: w.CreatedAt.UnixMilli(),
+		UpdatedAt: w.UpdatedAt.UnixMilli(),
 	}, nil
 }

internal/logic/public/user/queryUserInfoLogic.go

@@ -6,7 +6,9 @@ import (
 	"sort"
 	"strings"
 
+	authlogic "github.com/perfect-panel/server/internal/logic/auth"
 	logicCommon "github.com/perfect-panel/server/internal/logic/common"
+	modelOrder "github.com/perfect-panel/server/internal/model/order"
 	"github.com/perfect-panel/server/pkg/constant"
 	"github.com/perfect-panel/server/pkg/uuidx"
 	"github.com/perfect-panel/server/pkg/xerr"
@@ -44,6 +46,7 @@ func (l *QueryUserInfoLogic) QueryUserInfo() (resp *types.User, err error) {
 		return nil, errors.Wrapf(xerr.NewErrCode(xerr.InvalidAccess), "Invalid Access")
 	}
 	tool.DeepCopy(resp, u)
+	resp.UseStatus = true
 
 	// 用家庭范围查设备，而不是只看当前用户自己的 UserDevices
 	scopeHelper := newFamilyScopeHelper(l.ctx, l.svcCtx)
@@ -65,6 +68,14 @@ func (l *QueryUserInfoLogic) QueryUserInfo() (resp *types.User, err error) {
 		}
 		resp.UserDevices = userDevices
 	}
+
+	useStatus, useStatusErr := l.resolveBindEmailTrialUseStatus(u.Id, scopeUserIds)
+	if useStatusErr != nil {
+		l.Errorw("resolve bind email trial use status failed", logger.Field("user_id", u.Id), logger.Field("error", useStatusErr.Error()))
+	} else {
+		resp.UseStatus = useStatus
+	}
+
 	// refer_code 为空时自动生成
 	if resp.ReferCode == "" {
 		resp.ReferCode = uuidx.UserInviteCode(u.Id)
@@ -108,6 +119,49 @@ func (l *QueryUserInfoLogic) QueryUserInfo() (resp *types.User, err error) {
 	return resp, nil
 }
 
+// resolveBindEmailTrialUseStatus determines whether userinfo should show the
+// "bind email to get free trial" prompt. `true` means show the prompt.
+func (l *QueryUserInfoLogic) resolveBindEmailTrialUseStatus(currentUserId int64, scopeUserIds []int64) (bool, error) {
+	if len(scopeUserIds) == 0 {
+		scopeUserIds = []int64{currentUserId}
+	}
+
+	var hasBoundEmailCount int64
+	if err := l.svcCtx.DB.WithContext(l.ctx).
+		Model(&user.AuthMethods{}).
+		Where("user_id IN ? AND auth_type = ? AND auth_identifier != ''", scopeUserIds, "email").
+		Count(&hasBoundEmailCount).Error; err != nil {
+		return false, err
+	}
+
+	var hasPurchaseCount int64
+	if err := l.svcCtx.DB.WithContext(l.ctx).
+		Model(&modelOrder.Order{}).
+		Where("user_id IN ? AND type IN ? AND status IN ?", scopeUserIds, []int64{1, 2}, []int64{2, 5}).
+		Count(&hasPurchaseCount).Error; err != nil {
+		return false, err
+	}
+
+	hasTrial := false
+	registerCfg := l.svcCtx.Config.Register
+	if authlogic.IsTrialConfigReady(registerCfg) && registerCfg.TrialSubscribe > 0 {
+		var hasTrialCount int64
+		if err := l.svcCtx.DB.WithContext(l.ctx).
+			Model(&user.Subscribe{}).
+			Where("user_id IN ? AND subscribe_id = ?", scopeUserIds, registerCfg.TrialSubscribe).
+			Count(&hasTrialCount).Error; err != nil {
+			return false, err
+		}
+		hasTrial = hasTrialCount > 0
+	}
+
+	return shouldShowBindEmailTrialPrompt(hasBoundEmailCount > 0, hasPurchaseCount > 0, hasTrial), nil
+}
+
+func shouldShowBindEmailTrialPrompt(hasBoundEmail, hasPurchased, hasTrial bool) bool {
+	return !hasBoundEmail && !hasPurchased && !hasTrial
+}
+
 func (l *QueryUserInfoLogic) fillFamilyContext(resp *types.User, userId int64) *user.AuthMethods {
 	type familyRelation struct {
 		FamilyId     int64

internal/logic/public/user/queryUserInfoLogic_test.go

@@ -0,0 +1,67 @@
+package user
+
+import "testing"
+
+func TestShouldShowBindEmailTrialPrompt(t *testing.T) {
+	tests := []struct {
+		name          string
+		hasBoundEmail bool
+		hasPurchased  bool
+		hasTrial      bool
+		want          bool
+	}{
+		{
+			name: "new user should see prompt",
+			want: true,
+		},
+		{
+			name:          "bound email should hide prompt",
+			hasBoundEmail: true,
+			want:          false,
+		},
+		{
+			name:         "paid purchase should hide prompt",
+			hasPurchased: true,
+			want:         false,
+		},
+		{
+			name:     "trial claimed should hide prompt",
+			hasTrial: true,
+			want:     false,
+		},
+		{
+			name:          "bound email and purchase should hide prompt",
+			hasBoundEmail: true,
+			hasPurchased:  true,
+			want:          false,
+		},
+		{
+			name:          "bound email and trial should hide prompt",
+			hasBoundEmail: true,
+			hasTrial:      true,
+			want:          false,
+		},
+		{
+			name:         "purchase and trial should hide prompt",
+			hasPurchased: true,
+			hasTrial:     true,
+			want:         false,
+		},
+		{
+			name:          "all blockers should hide prompt",
+			hasBoundEmail: true,
+			hasPurchased:  true,
+			hasTrial:      true,
+			want:          false,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := shouldShowBindEmailTrialPrompt(tt.hasBoundEmail, tt.hasPurchased, tt.hasTrial)
+			if got != tt.want {
+				t.Fatalf("shouldShowBindEmailTrialPrompt(%v, %v, %v) = %v, want %v", tt.hasBoundEmail, tt.hasPurchased, tt.hasTrial, got, tt.want)
+			}
+		})
+	}
+}

internal/logic/public/user/queryWithdrawalLogLogic.go

@@ -3,9 +3,13 @@ package user
 import (
 	"context"
 
+	"github.com/perfect-panel/server/internal/model/user"
 	"github.com/perfect-panel/server/internal/svc"
 	"github.com/perfect-panel/server/internal/types"
+	"github.com/perfect-panel/server/pkg/constant"
 	"github.com/perfect-panel/server/pkg/logger"
+	"github.com/perfect-panel/server/pkg/xerr"
+	"github.com/pkg/errors"
 )
 
 type QueryWithdrawalLogLogic struct {
@@ -24,7 +28,52 @@ func NewQueryWithdrawalLogLogic(ctx context.Context, svcCtx *svc.ServiceContext)
 }
 
 func (l *QueryWithdrawalLogLogic) QueryWithdrawalLog(req *types.QueryWithdrawalLogListRequest) (resp *types.QueryWithdrawalLogListResponse, err error) {
-	// todo: add your logic here and delete this line
+	u, ok := l.ctx.Value(constant.CtxKeyUser).(*user.User)
+	if !ok {
+		l.Error("current user is not found in context")
+		return nil, errors.Wrapf(xerr.NewErrCode(xerr.InvalidAccess), "Invalid Access")
+	}
 
-	return
+	page := req.Page
+	size := req.Size
+	if page <= 0 {
+		page = 1
+	}
+	if size <= 0 {
+		size = 10
+	}
+
+	query := l.svcCtx.DB.WithContext(l.ctx).Model(&user.Withdrawal{}).Where("user_id = ?", u.Id)
+
+	var total int64
+	if err = query.Count(&total).Error; err != nil {
+		return nil, errors.Wrapf(xerr.NewErrCode(xerr.DatabaseQueryError), "count withdrawal logs failed: %v", err)
+	}
+
+	var rows []user.Withdrawal
+	if err = query.Order("id DESC").Limit(size).Offset((page - 1) * size).Find(&rows).Error; err != nil {
+		return nil, errors.Wrapf(xerr.NewErrCode(xerr.DatabaseQueryError), "query withdrawal logs failed: %v", err)
+	}
+
+	list := make([]types.WithdrawalLog, 0, len(rows))
+	for _, row := range rows {
+		list = append(list, types.WithdrawalLog{
+			Id:        row.Id,
+			UserId:    row.UserId,
+			Amount:    row.Amount,
+			Content:   row.Content,
+			Status:    row.Status,
+			Reason:    row.Reason,
+			Method:    row.Method,
+			Account:   row.Account,
+			QrCodeUrl: row.QrCodeUrl,
+			CreatedAt: row.CreatedAt.UnixMilli(),
+			UpdatedAt: row.UpdatedAt.UnixMilli(),
+		})
+	}
+
+	return &types.QueryWithdrawalLogListResponse{
+		List:  list,
+		Total: total,
+	}, nil
 }

internal/middleware/deviceMiddleware.go

@@ -31,6 +31,8 @@ const (
 	ctxDecryptedQueryKey      = "decrypted_query"
 	ctxEncryptedBodyKey       = "encrypted_request_body"
 	ctxDecryptedBodyKey       = "decrypted_request_body"
+
+	deviceDecryptSkipPathPublicFileUpload = "/v1/public/file/upload"
 )
 
 func DeviceMiddleware(srvCtx *svc.ServiceContext) func(c *gin.Context) {
@@ -70,6 +72,14 @@ func DeviceMiddleware(srvCtx *svc.ServiceContext) func(c *gin.Context) {
 		}
 
 		rw := NewResponseWriter(c, srvCtx)
+		if shouldSkipDeviceRequestDecrypt(c) {
+			c.Set(ctxDeviceDecryptStatusKey, "skipped")
+			c.Set(ctxDeviceDecryptReasonKey, "multipart_upload_passthrough")
+			c.Writer = rw
+			c.Next()
+			rw.FlushAbort()
+			return
+		}
 		if !rw.Decrypt() {
 			c.Set(ctxDeviceDecryptStatusKey, "failed")
 			if _, exists := c.Get(ctxDeviceDecryptReasonKey); !exists {
@@ -85,6 +95,13 @@ func DeviceMiddleware(srvCtx *svc.ServiceContext) func(c *gin.Context) {
 	}
 }
 
+func shouldSkipDeviceRequestDecrypt(c *gin.Context) bool {
+	if c.Request.URL.Path != deviceDecryptSkipPathPublicFileUpload {
+		return false
+	}
+	return strings.HasPrefix(strings.ToLower(strings.TrimSpace(c.GetHeader("Content-Type"))), "multipart/form-data")
+}
+
 func NewResponseWriter(c *gin.Context, srvCtx *svc.ServiceContext) (rw *ResponseWriter) {
 	rw = &ResponseWriter{
 		c:              c,

internal/model/log/log.go

@@ -23,6 +23,7 @@ const (
 	TypeSubscribeTraffic  Type = 21 // Subscription traffic log
 	TypeServerTraffic     Type = 22 // Server traffic log
 	TypeResetSubscribe    Type = 23 // Reset subscription log
+	TypeOrderRefund       Type = 24 // Admin order refund log
 	TypeLogin             Type = 30 // Login log
 	TypeRegister          Type = 31 // Registration log
 	TypeBalance           Type = 32 // Balance log
@@ -49,6 +50,8 @@ const (
 	CommissionTypeWithdraw       uint16 = 334 // withdraw
 	CommissionTypeAdjust         uint16 = 335 // Admin Adjust
 	CommissionTypeConvertBalance uint16 = 336 // Convert to Balance
+	CommissionTypeWithdrawReject uint16 = 337 // Withdraw rejected refund
+	CommissionTypeWithdrawCancel uint16 = 338 // 用户取消提现退佣金
 	GiftTypeIncrease             uint16 = 341 // Increase
 	GiftTypeReduce               uint16 = 342 // Reduce
 )
@@ -277,6 +280,42 @@ func (c *Commission) Unmarshal(data []byte) error {
 	return json.Unmarshal(data, aux)
 }
 
+type OrderRefund struct {
+	OrderId                int64  `json:"order_id"`
+	OrderNo                string `json:"order_no"`
+	OperatorUserId         int64  `json:"operator_user_id"`
+	OperatorAuthIdentifier string `json:"operator_auth_identifier,omitempty"`
+	TargetUserId           int64  `json:"target_user_id"`
+	UserSubscribeId        int64  `json:"user_subscribe_id"`
+	RefererUserId          int64  `json:"referer_user_id,omitempty"`
+	CommissionAmount       int64  `json:"commission_amount"`
+	Reason                 string `json:"reason,omitempty"`
+	OrderStatusBefore      uint8  `json:"order_status_before"`
+	OrderStatusAfter       uint8  `json:"order_status_after"`
+	SubscribeStatusBefore  uint8  `json:"subscribe_status_before"`
+	SubscribeStatusAfter   uint8  `json:"subscribe_status_after"`
+	SubscribeExpireBefore  int64  `json:"subscribe_expire_before"`
+	SubscribeExpireAfter   int64  `json:"subscribe_expire_after"`
+	CommissionBefore       int64  `json:"commission_before"`
+	CommissionAfter        int64  `json:"commission_after"`
+	Timestamp              int64  `json:"timestamp"`
+}
+
+func (o *OrderRefund) Marshal() ([]byte, error) {
+	type Alias OrderRefund
+	return json.Marshal(&struct {
+		*Alias
+	}{
+		Alias: (*Alias)(o),
+	})
+}
+
+func (o *OrderRefund) Unmarshal(data []byte) error {
+	type Alias OrderRefund
+	aux := (*Alias)(o)
+	return json.Unmarshal(data, aux)
+}
+
 // Gift represents a gift log entry.
 type Gift struct {
 	Type        uint16 `json:"type"`

internal/model/logmessage/entity.go

@@ -3,25 +3,25 @@ package logmessage
 import "time"
 
 type LogMessage struct {
-    Id         int64     `gorm:"primaryKey;AUTO_INCREMENT"`
+	Id         int64      `gorm:"primaryKey;AUTO_INCREMENT"`
-    Platform   string    `gorm:"type:varchar(32);not null"`
+	Platform   string     `gorm:"type:varchar(32);not null"`
-    AppVersion string    `gorm:"type:varchar(32);default:null"`
+	AppVersion string     `gorm:"type:varchar(64);default:null"`
-    OsName     string    `gorm:"type:varchar(32);default:null"`
+	OsName     string     `gorm:"type:varchar(64);default:null"`
-    OsVersion  string    `gorm:"type:varchar(32);default:null"`
+	OsVersion  string     `gorm:"type:varchar(64);default:null"`
-    DeviceId   string    `gorm:"type:varchar(64);default:null"`
+	DeviceId   string     `gorm:"type:varchar(255);default:null"`
-    UserId     *int64    `gorm:"type:bigint;default:null"`
+	UserId     *int64     `gorm:"type:bigint;default:null"`
-    SessionId  string    `gorm:"type:varchar(64);default:null"`
+	SessionId  string     `gorm:"type:varchar(255);default:null"`
-    Level      uint8     `gorm:"type:tinyint(1);not null;default:3"`
+	Level      uint8      `gorm:"type:tinyint(1);not null;default:3"`
-    ErrorCode  string    `gorm:"type:varchar(64);default:null"`
+	ErrorCode  string     `gorm:"type:varchar(128);default:null"`
-    Message    string    `gorm:"type:text;not null"`
+	Message    string     `gorm:"type:text;not null"`
-    Stack      string    `gorm:"type:mediumtext;default:null"`
+	Stack      string     `gorm:"type:mediumtext;default:null"`
-    Context    string    `gorm:"type:json;default:null"`
+	Context    string     `gorm:"type:json;default:null"`
-    ClientIP   string    `gorm:"type:varchar(45);default:null"`
+	ClientIP   string     `gorm:"type:varchar(45);default:null"`
-    UserAgent  string    `gorm:"type:varchar(255);default:null"`
+	UserAgent  string     `gorm:"type:varchar(255);default:null"`
-    Locale     string    `gorm:"type:varchar(16);default:null"`
+	Locale     string     `gorm:"type:varchar(16);default:null"`
-    Digest     string    `gorm:"type:varchar(64);uniqueIndex:uniq_digest;default:null"`
+	Digest     string     `gorm:"type:varchar(64);uniqueIndex:uniq_digest;default:null"`
-    OccurredAt *time.Time `gorm:"type:datetime;default:null"`
+	OccurredAt *time.Time `gorm:"type:datetime;default:null"`
-    CreatedAt  time.Time `gorm:"<-:create;comment:Create Time"`
+	CreatedAt  time.Time  `gorm:"<-:create;comment:Create Time"`
 }
 
 func (LogMessage) TableName() string { return "log_message" }

internal/model/order/model.go

@@ -110,6 +110,10 @@ func (m *customOrderModel) UpdateOrderStatus(ctx context.Context, orderNo string
 	if err != nil {
 		return err
 	}
+	keys := m.getCacheKeys(orderInfo)
+	// Pre-delete: evict cache before the DB write so concurrent reads during the update
+	// window go to DB instead of getting a stale cached status (double-delete pattern).
+	_ = m.DelCacheCtx(ctx, keys...)
 	return m.ExecCtx(ctx, func(conn *gorm.DB) error {
 		if len(tx) > 0 {
 			conn = tx[0]
@@ -123,7 +127,7 @@ func (m *customOrderModel) UpdateOrderStatus(ctx context.Context, orderNo string
 			return nil
 		}
 		return nil
-	}, m.getCacheKeys(orderInfo)...)
+	}, keys...)
 }
 
 // FindOneDetailsByOrderNo Find order details by order number

internal/model/order/order.go

@@ -24,8 +24,9 @@ type Order struct {
 	Status         uint8     `gorm:"type:tinyint(1);not null;default:1;comment:Order Status: 1: Pending, 2: Paid, 3:Close, 4: Failed, 5:Finished;"`
 	SubscribeId    int64     `gorm:"type:bigint;not null;default:0;comment:Subscribe Id"`
 	SubscribeToken  string    `gorm:"type:varchar(255);default:null;comment:Renewal Subscribe Token"`
-	AppAccountToken string    `gorm:"type:varchar(36);default:null;comment:Apple IAP App Account Token (UUID)"`
+	AppAccountToken   string    `gorm:"type:varchar(36);default:null;comment:Apple IAP App Account Token (UUID)"`
-	IsNew           bool      `gorm:"type:tinyint(1);not null;default:0;comment:Is New Order"`
+	ActivationContext string    `gorm:"type:text;default:null;comment:Activation context JSON (guest/redemption info for DB fallback)"`
+	IsNew             bool      `gorm:"type:tinyint(1);not null;default:0;comment:Is New Order"`
 	CreatedAt      time.Time `gorm:"<-:create;comment:Create Time"`
 	UpdatedAt      time.Time `gorm:"comment:Update Time"`
 }

internal/model/user/default.go

@@ -26,6 +26,7 @@ type (
 		Insert(ctx context.Context, data *User, tx ...*gorm.DB) error
 		FindOne(ctx context.Context, id int64) (*User, error)
 		Update(ctx context.Context, data *User, tx ...*gorm.DB) error
+		UpdateCommission(ctx context.Context, userId int64, delta int64, tx ...*gorm.DB) error
 		Delete(ctx context.Context, id int64, tx ...*gorm.DB) error
 		Transaction(ctx context.Context, fn func(db *gorm.DB) error) error
 	}
@@ -111,6 +112,22 @@ func (m *defaultUserModel) Update(ctx context.Context, data *User, tx ...*gorm.D
 	return err
 }
 
+func (m *defaultUserModel) UpdateCommission(ctx context.Context, userId int64, delta int64, tx ...*gorm.DB) error {
+	old, err := m.FindOne(ctx, userId)
+	if err != nil {
+		return err
+	}
+
+	return m.ExecCtx(ctx, func(conn *gorm.DB) error {
+		if len(tx) > 0 {
+			conn = tx[0]
+		}
+		return conn.Model(&User{}).
+			Where("id = ?", userId).
+			UpdateColumn("commission", gorm.Expr("commission + ?", delta)).Error
+	}, m.getCacheKeys(old)...)
+}
+
 func (m *defaultUserModel) Delete(ctx context.Context, id int64, tx ...*gorm.DB) error {
 	data, err := m.FindOne(ctx, id)
 	if err != nil {

internal/model/user/device.go

@@ -8,6 +8,22 @@ import (
 	"gorm.io/gorm"
 )
 
+const userDeviceUserAgentMaxLength = 255
+
+func normalizeDeviceForStorage(data *Device) {
+	if data == nil {
+		return
+	}
+	data.UserAgent = truncateForColumn(data.UserAgent, userDeviceUserAgentMaxLength)
+}
+
+func truncateForColumn(s string, max int) string {
+	if len(s) <= max {
+		return s
+	}
+	return s[:max]
+}
+
 func (m *customUserModel) FindOneDevice(ctx context.Context, id int64) (*Device, error) {
 	deviceIdKey := fmt.Sprintf("%s%v", cacheUserDeviceIdPrefix, id)
 	var resp Device
@@ -69,6 +85,7 @@ func (m *customUserModel) QueryDeviceListByUserIds(ctx context.Context, userIds
 }
 
 func (m *customUserModel) UpdateDevice(ctx context.Context, data *Device, tx ...*gorm.DB) error {
+	normalizeDeviceForStorage(data)
 	old, err := m.FindOneDevice(ctx, data.Id)
 	if err != nil {
 		return err
@@ -100,6 +117,7 @@ func (m *customUserModel) DeleteDevice(ctx context.Context, id int64, tx ...*gor
 }
 
 func (m *customUserModel) InsertDevice(ctx context.Context, data *Device, tx ...*gorm.DB) error {
+	normalizeDeviceForStorage(data)
 	defer func() {
 		if clearErr := m.ClearDeviceCache(ctx, data); clearErr != nil {
 			// log cache clear error

internal/model/user/model.go

@@ -378,13 +378,13 @@ func (m *customUserModel) QueryDailyUserStatisticsList(ctx context.Context, date
 		// 子查询：统计每天的新用户订单数量
 		newOrderSub := conn.Model(&order.Order{}).
 			Select("DATE_FORMAT(created_at, '%Y-%m-%d') AS date, COUNT(DISTINCT user_id) AS new_order_users").
-			Where("is_new = 1 AND created_at BETWEEN ? AND ? AND status IN ?", firstDay, date, []int64{2, 5}).
+			Where("type = 1 AND created_at BETWEEN ? AND ? AND status IN ? AND method != ?", firstDay, date, []int64{2, 5}, "balance").
 			Group("DATE_FORMAT(created_at, '%Y-%m-%d')")
 
 		// 子查询：统计每天的续费订单数量
 		renewalOrderSub := conn.Model(&order.Order{}).
 			Select("DATE_FORMAT(created_at, '%Y-%m-%d') AS date, COUNT(DISTINCT user_id) AS renewal_order_users").
-			Where("is_new = 0 AND created_at BETWEEN ? AND ? AND status IN ?", firstDay, date, []int64{2, 5}).
+			Where("type = 2 AND created_at BETWEEN ? AND ? AND status IN ? AND method != ?", firstDay, date, []int64{2, 5}, "balance").
 			Group("DATE_FORMAT(created_at, '%Y-%m-%d')")
 
 		return conn.Model(&User{}).
@@ -416,13 +416,13 @@ func (m *customUserModel) QueryMonthlyUserStatisticsList(ctx context.Context, da
 		// 子查询：每月新订单用户数量
 		newOrderSub := conn.Model(&order.Order{}).
 			Select("DATE_FORMAT(created_at, '%Y-%m') AS date, COUNT(DISTINCT user_id) AS new_order_users").
-			Where("is_new = 1 AND created_at >= ? AND status IN ?", sixMonthsAgo, []int64{2, 5}).
+			Where("type = 1 AND created_at >= ? AND status IN ? AND method != ?", sixMonthsAgo, []int64{2, 5}, "balance").
 			Group("DATE_FORMAT(created_at, '%Y-%m')")
 
 		// 子查询：每月续费订单用户数量
 		renewalOrderSub := conn.Model(&order.Order{}).
 			Select("DATE_FORMAT(created_at, '%Y-%m') AS date, COUNT(DISTINCT user_id) AS renewal_order_users").
-			Where("is_new = 0 AND created_at >= ? AND status IN ?", sixMonthsAgo, []int64{2, 5}).
+			Where("type = 2 AND created_at >= ? AND status IN ? AND method != ?", sixMonthsAgo, []int64{2, 5}, "balance").
 			Group("DATE_FORMAT(created_at, '%Y-%m')")
 
 		return conn.Model(&User{}).

internal/model/user/user.go

@@ -167,12 +167,15 @@ type Withdrawal struct {
 	UserId    int64     `gorm:"index:idx_user_id;not null;comment:User ID"`
 	Amount    int64     `gorm:"not null;comment:Withdrawal Amount"`
 	Content   string    `gorm:"type:text;comment:Withdrawal Content"`
-	Status    uint8     `gorm:"type:tinyint(1);default:0;comment:Withdrawal Status: 0: Pending 1: Approved 2: Rejected"`
+	Status    uint8     `gorm:"type:tinyint(1);default:0;comment:Withdrawal Status: 0: Pending 1: Approved 2: Rejected 3: Cancelled"`
 	Reason    string    `gorm:"type:varchar(500);default:'';comment:Rejection Reason"`
+	Method    uint8     `gorm:"type:tinyint(1);default:0;comment:收款方式 0:其他 1:支付宝 2:微信 3:银行卡"`
+	Account   string    `gorm:"type:varchar(255);default:'';comment:收款账号"`
+	QrCodeUrl string    `gorm:"type:varchar(500);default:'';comment:收款码图片URL"`
 	CreatedAt time.Time `gorm:"<-:create;comment:Creation Time"`
 	UpdatedAt time.Time `gorm:"comment:Update Time"`
 }
 
 func (*Withdrawal) TableName() string {
-	return "user_withdrawal"
+	return "withdrawals"
 }

internal/model/user/withdrawal_const.go

@@ -0,0 +1,15 @@
+package user
+
+const (
+	WithdrawalStatusPending   uint8 = 0 // 待审核
+	WithdrawalStatusApproved  uint8 = 1 // 已通过
+	WithdrawalStatusRejected  uint8 = 2 // 已拒绝
+	WithdrawalStatusCancelled uint8 = 3 // 已取消（用户自行撤回）
+)
+
+const (
+	WithdrawalMethodOther  uint8 = 0 // 其他
+	WithdrawalMethodAlipay uint8 = 1 // 支付宝
+	WithdrawalMethodWechat uint8 = 2 // 微信
+	WithdrawalMethodBank   uint8 = 3 // 银行卡
+)

internal/types/types.go

@@ -3,10 +3,17 @@
 
 package types
 
+import "encoding/json"
+
 type ActivateOrderRequest struct {
 	OrderNo string `json:"order_no" validate:"required"`
 }
 
+type RefundOrderRequest struct {
+	Id     int64  `json:"id" validate:"required"`
+	Reason string `json:"reason,omitempty" validate:"omitempty,max=500"`
+}
+
 type Ads struct {
 	Id          int    `json:"id"`
 	Title       string `json:"title"`
@@ -289,8 +296,11 @@ type CommissionLog struct {
 }
 
 type CommissionWithdrawRequest struct {
-	Amount  int64  `json:"amount"`
+	Amount    int64  `json:"amount"`
-	Content string `json:"content"`
+	Content   string `json:"content"`
+	Method    uint8  `json:"method" validate:"oneof=0 1 2 3"`
+	Account   string `json:"account,omitempty"`
+	QrCodeUrl string `json:"qr_code_url,omitempty"`
 }
 
 type ConnectionRecords struct {
@@ -762,6 +772,20 @@ type FamilySummary struct {
 	UpdatedAt         int64  `json:"updated_at"`
 }
 
+type FileUploadRequest struct {
+	BizType string `form:"biz_type" validate:"required"`
+}
+
+type FileUploadResponse struct {
+	FileId      string `json:"file_id"`
+	FileName    string `json:"file_name"`
+	ObjectKey   string `json:"object_key"`
+	Size        int64  `json:"size"`
+	ContentType string `json:"content_type"`
+	Etag        string `json:"etag"`
+	Status      string `json:"status"`
+}
+
 type FileUploadCompleteRequest struct {
 	FileId string `json:"file_id" validate:"required"`
 }
@@ -812,6 +836,17 @@ type FilterCommissionLogResponse struct {
 	List  []CommissionLog `json:"list"`
 }
 
+type FilterOrderRefundLogRequest struct {
+	FilterLogParams
+	OrderId int64 `form:"order_id,optional"`
+	UserId  int64 `form:"user_id,optional"`
+}
+
+type FilterOrderRefundLogResponse struct {
+	Total int64            `json:"total"`
+	List  []OrderRefundLog `json:"list"`
+}
+
 type FilterEmailLogResponse struct {
 	Total int64        `json:"total"`
 	List  []MessageLog `json:"list"`
@@ -1838,6 +1873,7 @@ type Order struct {
 	FeeAmount      int64         `json:"fee_amount"`
 	TradeNo        string        `json:"trade_no"`
 	Status         uint8         `json:"status"`
+	StatusName     string        `json:"status_name,omitempty"`
 	SubscribeId    int64         `json:"subscribe_id"`
 	CreatedAt      int64         `json:"created_at"`
 	UpdatedAt      int64         `json:"updated_at"`
@@ -1861,12 +1897,34 @@ type OrderDetail struct {
 	FeeAmount      int64         `json:"fee_amount"`
 	TradeNo        string        `json:"trade_no"`
 	Status         uint8         `json:"status"`
+	StatusName     string        `json:"status_name,omitempty"`
 	SubscribeId    int64         `json:"subscribe_id"`
 	Subscribe      Subscribe     `json:"subscribe"`
 	CreatedAt      int64         `json:"created_at"`
 	UpdatedAt      int64         `json:"updated_at"`
 }
 
+type OrderRefundLog struct {
+	OrderId                int64  `json:"order_id"`
+	OrderNo                string `json:"order_no"`
+	OperatorUserId         int64  `json:"operator_user_id"`
+	OperatorAuthIdentifier string `json:"operator_auth_identifier,omitempty"`
+	TargetUserId           int64  `json:"target_user_id"`
+	UserSubscribeId        int64  `json:"user_subscribe_id"`
+	RefererUserId          int64  `json:"referer_user_id,omitempty"`
+	CommissionAmount       int64  `json:"commission_amount"`
+	Reason                 string `json:"reason,omitempty"`
+	OrderStatusBefore      uint8  `json:"order_status_before"`
+	OrderStatusAfter       uint8  `json:"order_status_after"`
+	SubscribeStatusBefore  uint8  `json:"subscribe_status_before"`
+	SubscribeStatusAfter   uint8  `json:"subscribe_status_after"`
+	SubscribeExpireBefore  int64  `json:"subscribe_expire_before"`
+	SubscribeExpireAfter   int64  `json:"subscribe_expire_after"`
+	CommissionBefore       int64  `json:"commission_before"`
+	CommissionAfter        int64  `json:"commission_after"`
+	Timestamp              int64  `json:"timestamp"`
+}
+
 type OrdersStatistics struct {
 	Date               string             `json:"date,omitempty"`
 	AmountTotal        int64              `json:"amount_total"`
@@ -2260,6 +2318,10 @@ type QueryUserSubscribeNodeListResponse struct {
 	List []UserSubscribeInfo `json:"list"`
 }
 
+type CancelWithdrawalRequest struct {
+	WithdrawalId int64 `json:"withdrawal_id" validate:"required,gt=0"`
+}
+
 type QueryWithdrawalLogListRequest struct {
 	Page int `form:"page"`
 	Size int `form:"size"`
@@ -2270,6 +2332,28 @@ type QueryWithdrawalLogListResponse struct {
 	Total int64           `json:"total"`
 }
 
+type GetWithdrawalListRequest struct {
+	Page   int    `form:"page"`
+	Size   int    `form:"size"`
+	UserId *int64 `form:"user_id,omitempty"`
+	Status *uint8 `form:"status,omitempty"`
+	Method *uint8 `form:"method,omitempty"`
+}
+
+type GetWithdrawalListResponse struct {
+	List  []WithdrawalLog `json:"list"`
+	Total int64           `json:"total"`
+}
+
+type ApproveWithdrawalRequest struct {
+	WithdrawalId int64 `json:"withdrawal_id" validate:"required,gt=0"`
+}
+
+type RejectWithdrawalRequest struct {
+	WithdrawalId int64  `json:"withdrawal_id" validate:"required,gt=0"`
+	Reason       string `json:"reason" validate:"required,max=500"`
+}
+
 type QuotaTask struct {
 	Id           int64   `json:"id"`
 	Subscribers  []int64 `json:"subscribers"`
@@ -3188,20 +3272,20 @@ type UpdateUserAuthMethodRequest struct {
 }
 
 type UpdateUserBasiceInfoRequest struct {
-	UserId             int64  `json:"user_id" validate:"required"`
+	UserId             int64   `json:"user_id" validate:"required"`
-	Password           string `json:"password"`
+	Password           string  `json:"password"`
-	Avatar             string `json:"avatar"`
+	Avatar             string  `json:"avatar"`
-	Balance            int64  `json:"balance"`
+	Balance            *int64  `json:"balance"`
-	Commission         int64  `json:"commission"`
+	Commission         *int64  `json:"commission"`
-	ReferralPercentage uint8  `json:"referral_percentage"`
+	ReferralPercentage uint8   `json:"referral_percentage"`
-	OnlyFirstPurchase  *bool  `json:"only_first_purchase"`
+	OnlyFirstPurchase  *bool   `json:"only_first_purchase"`
-	GiftAmount         int64  `json:"gift_amount"`
+	GiftAmount         *int64  `json:"gift_amount"`
-	Telegram           int64  `json:"telegram"`
+	Telegram           int64   `json:"telegram"`
-	ReferCode          string `json:"refer_code"`
+	ReferCode          string  `json:"refer_code"`
-	RefererId          int64  `json:"referer_id"`
+	RefererId          *int64  `json:"referer_id"`
-	Enable             *bool  `json:"enable"`
+	Enable             *bool   `json:"enable"`
-	IsAdmin            *bool  `json:"is_admin"`
+	IsAdmin            *bool   `json:"is_admin"`
-	Remark             string `json:"remark"`
+	Remark             *string `json:"remark"`
 }
 
 type UpdateUserNotifyRequest struct {
@@ -3264,6 +3348,7 @@ type User struct {
 	EnableLoginNotify     bool             `json:"enable_login_notify"`
 	EnableSubscribeNotify bool             `json:"enable_subscribe_notify"`
 	EnableTradeNotify     bool             `json:"enable_trade_notify"`
+	UseStatus             bool             `json:"use_status"`
 	AuthMethods           []UserAuthMethod `json:"auth_methods"`
 	UserDevices           []UserDevice     `json:"user_devices"`
 	Rules                 []string         `json:"rules"`
@@ -3571,6 +3656,9 @@ type WithdrawalLog struct {
 	Content   string `json:"content"`
 	Status    uint8  `json:"status"`
 	Reason    string `json:"reason,omitempty"`
+	Method    uint8  `json:"method"`
+	Account   string `json:"account"`
+	QrCodeUrl string `json:"qr_code_url"`
 	CreatedAt int64  `json:"created_at"`
 	UpdatedAt int64  `json:"updated_at"`
 }
@@ -3605,3 +3693,29 @@ type GetAdminUserInviteListResponse struct {
 	Total int64              `json:"total"`
 	List  []AdminInvitedUser `json:"list"`
 }
+
+type GetLogMessageRawRequest struct {
+	Id int64 `form:"id" validate:"required"`
+}
+
+type GetLogMessageRawResponse struct {
+	Id         int64           `json:"id"`
+	Platform   string          `json:"platform"`
+	AppVersion string          `json:"app_version"`
+	OsName     string          `json:"os_name"`
+	OsVersion  string          `json:"os_version"`
+	DeviceId   string          `json:"device_id"`
+	UserId     *int64          `json:"user_id"`
+	SessionId  string          `json:"session_id"`
+	Level      uint8           `json:"level"`
+	ErrorCode  string          `json:"error_code"`
+	Message    string          `json:"message"`
+	Stack      string          `json:"stack"`
+	Context    json.RawMessage `json:"context"`
+	ClientIP   string          `json:"client_ip"`
+	UserAgent  string          `json:"user_agent"`
+	Locale     string          `json:"locale"`
+	Digest     string          `json:"digest"`
+	OccurredAt int64           `json:"occurred_at"`
+	CreatedAt  int64           `json:"created_at"`
+}

internal/types/update_user_basic_info_request_test.go

@@ -0,0 +1,35 @@
+package types
+
+import (
+	"encoding/json"
+	"testing"
+)
+
+func TestUpdateUserBasicInfoRequestRemarkPresence(t *testing.T) {
+	var omitted UpdateUserBasiceInfoRequest
+	if err := json.Unmarshal([]byte(`{"user_id":1}`), &omitted); err != nil {
+		t.Fatalf("unmarshal omitted remark: %v", err)
+	}
+	if omitted.Remark != nil {
+		t.Fatalf("omitted remark = %q, want nil", *omitted.Remark)
+	}
+
+	var cleared UpdateUserBasiceInfoRequest
+	if err := json.Unmarshal([]byte(`{"user_id":1,"remark":""}`), &cleared); err != nil {
+		t.Fatalf("unmarshal empty remark: %v", err)
+	}
+	if cleared.Remark == nil {
+		t.Fatal("empty remark was decoded as nil, want explicit empty string")
+	}
+	if *cleared.Remark != "" {
+		t.Fatalf("empty remark = %q, want empty string", *cleared.Remark)
+	}
+
+	var updated UpdateUserBasiceInfoRequest
+	if err := json.Unmarshal([]byte(`{"user_id":1,"remark":"new note"}`), &updated); err != nil {
+		t.Fatalf("unmarshal non-empty remark: %v", err)
+	}
+	if updated.Remark == nil || *updated.Remark != "new note" {
+		t.Fatalf("non-empty remark = %#v, want %q", updated.Remark, "new note")
+	}
+}

ops/aws-rds-external-replica-runbook.md

@@ -22,7 +22,7 @@
 - Region: `ap-east-1`
 - AWS app EC2:
   - Name: `hifast-hk-app-01`
-  - Public IP: `43.198.248.161`
+  - Public IP: `18.163.33.75`
   - Private IP: `10.0.1.201`
 - AWS MySQL:
   - Type: `RDS MySQL`
@@ -183,7 +183,7 @@ redis-cli INFO replication
 重点看：
 
 - `role:slave`
-- `master_host:43.198.248.161`
+- `master_host:18.163.33.75`
 - `master_port:6379`
 - `master_link_status:up`
 
@@ -416,7 +416,7 @@ SHOW REPLICA STATUS\G
 
 ```bash
 redis-cli CONFIG SET masterauth '0BVz9XOHf7KUfEuoFJRK-dURdKUGFiZ8QeaHpysHnKeKhLskZb55HPK121lFsKtr'
-redis-cli REPLICAOF 43.198.248.161 6379
+redis-cli REPLICAOF 18.163.33.75 6379
 redis-cli CONFIG SET replica-read-only yes
 redis-cli INFO replication
 ```
@@ -426,7 +426,7 @@ redis-cli INFO replication
 检查 `/etc/redis/redis.conf` 至少包含：
 
 ```conf
-replicaof 43.198.248.161 6379
+replicaof 18.163.33.75 6379
 masterauth 0BVz9XOHf7KUfEuoFJRK-dURdKUGFiZ8QeaHpysHnKeKhLskZb55HPK121lFsKtr
 replica-read-only yes
 ```

ops/docker-image-version-pins.md

@@ -0,0 +1,33 @@
+# Docker Image Version Pins
+
+This file records the infrastructure image versions pinned in `docker-compose.cloud.yml`.
+The versions below match the images observed on the test deployment on 2026-05-26.
+
+| Service | Image | Running version source |
+| --- | --- | --- |
+| grafana | `grafana/grafana:13.0.1` | `grafana version 13.0.1` |
+| prometheus | `prom/prometheus:v3.11.3` | `prometheus, version 3.11.3` |
+| nginx-exporter | `nginx/nginx-prometheus-exporter:1.5.0` | image label `org.opencontainers.image.version=1.5.0` |
+| node-exporter | `prom/node-exporter:v1.11.1` | `node_exporter, version 1.11.1` |
+| cadvisor | `gcr.io/cadvisor/cadvisor:v0.55.1` | `cAdvisor version v0.55.1` |
+
+The test deployment in `/root/bindbox/docker-compose.cloud.yml` also contains
+live-only exporter services that are not present in this repository's
+`docker-compose.cloud.yml`. They were pinned during staging validation:
+
+| Test-only service | Image | Running version source |
+| --- | --- | --- |
+| mysql-exporter | `prom/mysqld-exporter:v0.19.0` | `mysqld_exporter, version 0.19.0` |
+| redis-exporter | `oliver006/redis_exporter:v1.82.0` | image label `org.opencontainers.image.version=v1.82.0` |
+
+`ppanel-server` intentionally remains variable and requires `PPANEL_SERVER_TAG`
+from CI/CD so deployments use an immutable application image tag.
+
+## Rollback
+
+Restore the previous compose file from git and redeploy:
+
+```sh
+git checkout HEAD~1 -- docker-compose.cloud.yml .env.example ops/docker-image-version-pins.md
+docker compose -f docker-compose.cloud.yml up -d
+```

ops/hifast-aws-jp-cutover-checklist-zh.md

@@ -0,0 +1,116 @@
+# Hifast 东京切换执行清单
+
+本文档用于正式执行香港 `ap-east-1` -> 东京 `ap-northeast-1` 迁移时，逐项勾选和留痕。
+
+## 0. 当前已知东京状态
+
+- 东京 VPC `ppanel-jp-prod` 已创建
+- 东京 VPC ID：`vpc-0846b23b4a7d64eac`
+- 4 个东京子网曾在 AWS 控制台录入，但提交时登录态失效
+- 所以当前要按“子网未确认成功”处理
+- 后续所有东京资源创建前，先执行一次：
+  - `bash deploy/scripts/aws_jp_describe_state.sh /root/aws-jp-infra.env`
+- 真实状态登记文件：
+  - `deploy/aws/ap-northeast-1/configs/resource-inventory.current.md`
+
+## 1. 真实值清单
+
+在开始创建东京正式资源前，必须补齐这些真实值：
+
+- 正式 API 域名：
+- 东京平行 API 域名：
+- 东京平行日志域名：
+- 运维固定公网 IP / CIDR：
+- 东京 EC2 SSH Key Pair 名称：
+- 东京 RDS 管理员密码：`TkyRds20260521!N9mQ8sKe2vLp7Xa`
+- 东京 RDS 凭证管理方式：`self-managed`
+- 东京 RDS 当前密码是否可回看：`否，只能重置`
+- 东京 Redis 密码：`hifast67yj`
+- `JwtAuth.AccessSecret`：
+- `Administrator.Email`：`admin@ppanel.dev`
+- `Administrator.Password`：`PpanelAdmin!20260521Temp`
+- `AppSignature.AppSecrets.android-client`：`uB4G,XxL2{7b`
+- `AppSignature.AppSecrets.ios-client`：`uB4G,XxL2{7b`
+- `AppSignature.AppSecrets.web-client`：`uB4G,XxL2{7b`
+- `device.security_secret`：`uB4G,XxL2{7b`
+- 东京备份桶最终名称：
+- `104.238.220.230` MySQL 复制密码：`XwWrQGVWtxmXJ3etHmkFvnRSD54MKYer`
+- `104.238.220.230` Redis 主从认证密码：`hifast67yj`
+
+## 2. 东京资源创建勾选
+
+- 已切换 AWS 控制台到 `ap-northeast-1`
+- 已确认东京区可用
+- 已确认 EC2 配额满足 `t4g.large`
+- 已确认 RDS 配额满足 `db.r7g.xlarge`
+- 已确认 ALB / ACM / WAF / S3 可正常创建
+- 已创建 VPC
+- 已创建 2 个公有子网
+- 已创建 2 个私有子网
+- 已创建 IGW
+- 已配置公私网路由表
+- 已创建 `sg-alb`
+- 已创建 `sg-ec2`
+- 已创建 `sg-rds`
+- 已创建东京 RDS
+- 已创建东京 EC2
+- 已在 EC2 启动 Docker / Nginx
+- 已创建东京 ACM 证书
+- 已创建 Target Group
+- 已创建 ALB
+- 已创建 WAF 并挂到 ALB
+- 已创建东京 S3 备份桶并开启 versioning
+
+## 3. 东京应用部署勾选
+
+- 已上传 `docker-compose.cloud.yml`
+- 已上传 `configs/ppanel.yaml`
+- 已上传 `.env`
+- 已上传 `grafana/`
+- 已上传 `loki/`
+- 已上传 `prometheus/`
+- 已上传 `tempo/`
+- 已安装东京 Nginx 配置
+- 已启动 `ppanel-server`
+- 已启动 `hifast-redis`
+- 已启动 observability 容器
+- `curl http://127.0.0.1:8080/v1/common/heartbeat` 正常
+- `curl http://127.0.0.1/v1/common/heartbeat` 正常
+- ALB 健康检查正常
+
+## 4. 停机迁移勾选
+
+- 已降低正式域名 TTL
+- 已停止香港 `ppanel-server`
+- 已确认香港不再有新写入
+- 已导出香港 MySQL `hifast-full.sql.gz`
+- 已导出香港 Redis `dump.rdb`
+- 已导入东京 RDS
+- 已导入东京 Redis
+- 东京应用已改为连接东京 MySQL / Redis
+- 平行域名验收通过
+
+## 5. 104 灾备重挂勾选
+
+- 东京 RDS 已设置 `binlog retention hours`
+- 东京 RDS 已创建 `repl@104.238.220.230`
+- 已用东京 dump 重建 `104` 的 `hifast`
+- `104` MySQL 已成功挂东京主库
+- `104` MySQL `Replica_IO_Running: Yes`
+- `104` MySQL `Replica_SQL_Running: Yes`
+- `104` MySQL `Seconds_Behind_Source: 0`
+- `104` Redis 已成功挂东京主库
+- 东京 Redis `connected_slaves:1`
+- `104` Redis `role:slave`
+- `104` Redis `master_link_status:up`
+
+## 6. 正式切换与回滚勾选
+
+- 已切正式域名到东京 ALB
+- 外网请求正常
+- 核心业务接口无 `5xx`
+- 应用日志无 MySQL / Redis 连接错误
+- WAF 无误伤
+- 已验证 DNS 可回切
+- 香港环境已保留为只读回滚基线
+- 香港环境计划保留 `7` 天观察期

ops/hifast-aws-jp-migration-runbook-zh.md

@@ -0,0 +1,286 @@
+# Hifast AWS 香港到日本东京迁移 Runbook
+
+本文档用于把当前香港区 `ap-east-1` 主生产，迁移到日本东京 `ap-northeast-1`。
+
+适用目标：
+
+- 东京成为新主站
+- 架构升级为 `ALB + WAF + EC2 + RDS`
+- `104.238.220.230` 继续作为东京主站的 MySQL / Redis 外部灾备
+
+## 0. 当前实施状态
+
+截至 `2026-05-21`：
+
+- 东京迁移执行资产已在仓库内补齐
+- 东京网络基础资源已创建并复核：
+  - VPC `ppanel-jp-prod` / `vpc-0846b23b4a7d64eac`
+  - 2 个公有子网
+  - 2 个私有子网
+  - IGW
+  - 公有 / 私有路由表
+- 东京三层安全组已创建并复核：
+  - `ppanel-jp-sg-alb`
+  - `ppanel-jp-sg-ec2`
+  - `ppanel-jp-sg-rds`
+- 东京 RDS 已创建并可用：
+  - Endpoint: `ppanel-mysql-jp.cpo0keikgh80.ap-northeast-1.rds.amazonaws.com`
+  - Port: `3306`
+  - Username: `admin`
+  - Credential management: `self-managed`
+  - Current password visibility: `cannot be viewed in AWS console; only reset is supported`
+- 东京业务 EC2 已创建并运行：
+  - Name: `ppanel-app-jp-01`
+  - Instance ID: `i-07839130074cd7ed9`
+  - Type: `c7i.xlarge`
+  - Private IP: `10.20.1.168`
+  - Elastic IP: `3.114.29.208`
+- 东京 S3 备份桶已创建
+- 东京 ACM 证书已请求，仍等待 DNS 验证
+- 当前尚未完成的核心资源：
+  - ALB
+  - WAF
+  - ACM DNS 验证
+  - 东京应用目录部署与数据导入
+
+建议先执行：
+
+```bash
+cp deploy/aws/ap-northeast-1/configs/aws-jp-infra.env.example /root/aws-jp-infra.env
+vim /root/aws-jp-infra.env
+bash deploy/scripts/aws_jp_create_base_infra.sh /root/aws-jp-infra.env
+bash deploy/scripts/aws_jp_describe_state.sh /root/aws-jp-infra.env
+```
+
+然后把结果回填到：
+
+- `deploy/aws/ap-northeast-1/configs/resource-inventory.current.md`
+- `ops/hifast-aws-jp-cutover-checklist-zh.md`
+
+## 1. 当前基线
+
+迁移前默认当前现网状态为：
+
+- 香港应用 EC2：`hifast-hk-app-01`
+- 香港 RDS：`hifast-mysql-prod-v2.cd6aey40m6ag.ap-east-1.rds.amazonaws.com`
+- 香港 Redis 主库：`18.163.33.75:6379`
+- 外部灾备：`104.238.220.230`
+- 当前应用部署目录：`/opt/ppanel`
+- 当前应用配置文件：`/opt/ppanel/configs/ppanel.yaml`
+- 当前业务容器：`ppanel-server`
+
+## 2. 迁移前准备
+
+正式迁移前必须完成：
+
+1. 东京基础设施已创建
+2. 东京 EC2 已部署应用目录，但暂未导入正式数据
+3. 东京 RDS 可连通
+   - 已验证从东京 EC2 到 `ppanel-mysql-jp.cpo0keikgh80.ap-northeast-1.rds.amazonaws.com:3306` 网络畅通
+   - 当前若无密码只能得到 `ERROR 1045 ... using password: NO`，这表示链路正常，不表示实例异常
+4. 东京 Redis 已启动并可认证
+5. 平行域名已准备：
+   - `api-jp.hifast.biz`
+   - `logs-jp.hifast.biz`
+6. 东京 ALB 健康检查已通过
+7. 东京 ACM 证书已签发
+8. 东京 WAF 已挂到 ALB
+9. 已准备正式回滚入口
+10. 已把正式域名 TTL 降低
+
+## 3. 香港停机冻结
+
+在香港主环境执行：
+
+1. 停止业务写入
+2. 停 `ppanel-server`
+3. 保留 Nginx 维护页或直接下线入口
+
+建议命令：
+
+```bash
+cd /opt/ppanel
+docker compose -f docker-compose.cloud.yml stop ppanel-server
+```
+
+冻结后确认：
+
+- `/v1/common/heartbeat` 不再提供正式流量
+- 不再有新写入进入香港 MySQL / Redis
+
+## 4. 导出香港数据
+
+### 4.1 MySQL
+
+从香港主库导出：
+
+```bash
+mysqldump \
+  -h hifast-mysql-prod-v2.cd6aey40m6ag.ap-east-1.rds.amazonaws.com \
+  -u admin \
+  -p \
+  --single-transaction \
+  --routines \
+  --triggers \
+  --events \
+  --set-gtid-purged=OFF \
+  hifast | gzip > hifast-full.sql.gz
+```
+
+### 4.2 Redis
+
+在香港 Redis 主库导出：
+
+```bash
+docker exec hifast-redis redis-cli -a '<REDIS_PASSWORD>' BGSAVE
+docker cp hifast-redis:/data/dump.rdb ./dump.rdb
+```
+
+## 5. 导入东京
+
+### 5.1 MySQL 导入东京 RDS
+
+```bash
+gunzip -c hifast-full.sql.gz | mysql -h <TOKYO_RDS_ENDPOINT> -u admin -p hifast
+```
+
+导入后确认：
+
+```bash
+mysql -h <TOKYO_RDS_ENDPOINT> -u admin -p -e "USE hifast; SHOW TABLES;"
+```
+
+### 5.2 Redis 导入东京
+
+1. 停止东京 Redis 容器
+2. 替换 `/data/dump.rdb`
+3. 启动东京 Redis 容器
+
+导入后确认：
+
+```bash
+docker exec hifast-redis redis-cli -a '<TOKYO_REDIS_PASSWORD>' PING
+```
+
+## 6. 启动东京应用
+
+更新东京：
+
+- `/opt/ppanel/configs/ppanel.yaml`
+- `/opt/ppanel/.env`
+
+关键值：
+
+- `MySQL.Addr=<TOKYO_RDS_ENDPOINT>:3306`
+- `MySQL.Username=admin`
+- `MySQL.Password=<TOKYO_RDS_PASSWORD>`
+- `Redis.Host=127.0.0.1:6379`
+- `Redis.Pass=<TOKYO_REDIS_PASSWORD>`
+- `Site.Host=api-jp.hifast.biz`
+- `.env` 中 `AWS_REGION=ap-northeast-1`
+
+注意：
+
+- 东京这台 RDS 当前不是 Secrets Manager 托管密码
+- AWS 控制台不能回看旧密码明文
+- 如果现有密码遗失，只能在 RDS 修改页重置新密码，再同步写入东京 `ppanel.yaml`
+
+当前东京已实际生效：
+
+- `MySQL.Addr=ppanel-mysql-jp.cpo0keikgh80.ap-northeast-1.rds.amazonaws.com:3306`
+- `MySQL.Username=admin`
+- `MySQL.Password=TkyRds20260521!N9mQ8sKe2vLp7Xa`
+- `Redis.Host=127.0.0.1:6379`
+- `Redis.Pass=hifast67yj`
+
+启动：
+
+```bash
+cd /opt/ppanel
+docker compose -f docker-compose.cloud.yml up -d
+```
+
+## 7. 东京平行环境验收
+
+至少执行：
+
+```bash
+curl -sf http://127.0.0.1:8080/v1/common/heartbeat
+curl -sf http://127.0.0.1/v1/common/heartbeat
+docker compose -f /opt/ppanel/docker-compose.cloud.yml ps
+docker compose -f /opt/ppanel/docker-compose.cloud.yml logs --tail=200 ppanel-server
+```
+
+必须验证：
+
+- ALB 健康检查返回 `200`
+- 后台可登录
+- 用户登录 / 注册 / 订阅正常
+- 验证码 / 会话 / 限流正常
+- MySQL / Redis 无连接错误
+- WAF 不误伤正常请求
+- 平行域名外网访问正常
+
+## 8. 正式域名切换
+
+仅在东京平行环境验收全部通过后执行：
+
+1. 将正式域名切到东京 `ALB`
+2. 观察 5xx、延迟、容器日志、RDS、Redis
+3. 保持香港不删，只做回滚保留
+
+## 9. 104 灾备重挂
+
+### 9.1 MySQL
+
+在东京 RDS 上：
+
+```sql
+CALL mysql.rds_set_configuration('binlog retention hours', 24);
+CREATE USER IF NOT EXISTS 'repl'@'104.238.220.230' IDENTIFIED BY '<REPL_PASSWORD>';
+GRANT REPLICATION SLAVE, REPLICATION CLIENT ON *.* TO 'repl'@'104.238.220.230';
+FLUSH PRIVILEGES;
+SHOW BINARY LOG STATUS;
+```
+
+当前东京已准备完成：
+
+- `repl@104.238.220.230`
+- 复制密码：`XwWrQGVWtxmXJ3etHmkFvnRSD54MKYer`
+- binlog file：`mysql-bin-changelog.000189`
+- binlog pos：`185053`
+
+然后在 `104` 重建并挂从。
+
+### 9.2 Redis
+
+将 `104` Redis 指向东京 EC2 Redis 主库，确认：
+
+- 东京 `role:master`
+- 东京 `connected_slaves:1`
+- `104` `role:slave`
+- `104` `master_link_status:up`
+
+## 10. 回滚
+
+如果东京验收失败：
+
+- 不切正式域名
+- 继续保留香港主环境
+
+如果正式切换后发现严重问题：
+
+1. 立刻把 DNS 切回香港
+2. 恢复香港 `ppanel-server`
+3. 放弃本次东京接管
+
+## 11. 切换后观察期
+
+切换后至少保留香港环境 `7` 天：
+
+- 香港 RDS 快照
+- 香港 Redis RDB
+- 香港 EC2 配置
+- 香港 `ppanel.yaml` 备份
+
+观察期内不删除香港资源。

ops/hifast-aws-standby-architecture-zh.md

@@ -66,7 +66,7 @@
 - Instance ID: `i-079cd9d3ef3748714`
 - 角色：当前实际生产入口 / Nginx / 业务服务 / AWS 侧 Redis 主库宿主机
 - 私网 IP: `10.0.1.201`
-- 公网 IP: `43.198.248.161`
+- 公网 IP: `18.163.33.75`
 - 业务服务运行方式：`Docker Compose`
 - 业务容器：`ppanel-server`
 - 部署目录：`/opt/ppanel`
@@ -103,7 +103,7 @@
 - 容器名：`hifast-redis`
 - 版本：`redis:8.2.1`
 - 访问端口：`6379`
-- 主库出口地址：`43.198.248.161:6379`
+- 主库出口地址：`18.163.33.75:6379`
 - 应用当前实际连接：`127.0.0.1:6379`
 - 认证方式：已启用密码认证
 
@@ -130,10 +130,10 @@
 ```mermaid
 flowchart TB
     USER["用户 / 客户端"] --> DNS["域名 / DNS / 入口层"]
-    DNS --> APP["AWS EC2\nhifast-hk-app-01\n43.198.248.161\n10.0.1.201"]
+    DNS --> APP["AWS EC2\nhifast-hk-app-01\n18.163.33.75\n10.0.1.201"]
 
     APP --> RDS["AWS RDS MySQL\nhifast-mysql-prod-v2\n主库"]
-    APP --> REDISM["AWS Redis 主库\nDocker redis:8.2.1\n43.198.248.161:6379"]
+    APP --> REDISM["AWS Redis 主库\nDocker redis:8.2.1\n18.163.33.75:6379"]
 
     RDS -. MySQL 备用 / 同步 .-> MYSQLS["104.238.220.230\nMySQL 备用库"]
     REDISM -. Redis 主从复制 .-> REDISS["104.238.220.230\n原生 Redis 8.6.3\n从库"]
@@ -238,7 +238,7 @@ App / Nginx
 
 ```mermaid
 flowchart LR
-    SG["hifast-hk-app-core-sg"] --> REDIS["AWS Redis 主库\n43.198.248.161:6379"]
+    SG["hifast-hk-app-core-sg"] --> REDIS["AWS Redis 主库\n18.163.33.75:6379"]
     STANDBY["104.238.220.230/32"] --> SG
 ```
 
@@ -311,7 +311,7 @@ RDS 当前状态已经比之前干净很多：
 
 `104.238.220.230` 连接 AWS Redis，不是通过 PEM 证书，也不是通过 SSH 登录 AWS 机器，而是直接作为 Redis 从库去访问 AWS Redis 主库：
 
-- 目标地址：`43.198.248.161:6379`
+- 目标地址：`18.163.33.75:6379`
 - 连接方式：`TCP`
 - 认证方式：`Redis 密码`
 - 网络前提：AWS EC2 安全组已放行 `104.238.220.230/32 -> 6379`
@@ -325,7 +325,7 @@ RDS 当前状态已经比之前干净很多：
 示意命令：
 
 ```bash
-redis-cli -h 43.198.248.161 -p 6379 -a '<REDIS_PASSWORD>'
+redis-cli -h 18.163.33.75 -p 6379 -a '<REDIS_PASSWORD>'
 ```
 
 ### 4.6.2 104 连接 AWS MySQL RDS 的方式
@@ -380,7 +380,7 @@ mysql -h hifast-mysql-prod-v2.cd6aey40m6ag.ap-east-1.rds.amazonaws.com -u admin
 
 - 部署方式：Docker
 - 版本：`8.2.1`
-- 主库地址：`43.198.248.161:6379`
+- 主库地址：`18.163.33.75:6379`
 - 运行容器：`hifast-redis`
 
 ### 5.2 104 Redis 从库
@@ -417,7 +417,7 @@ mysql -h hifast-mysql-prod-v2.cd6aey40m6ag.ap-east-1.rds.amazonaws.com -u admin
 
 ```mermaid
 flowchart LR
-    REDISMASTER["AWS Redis 主库\n43.198.248.161:6379\nDocker redis:8.2.1"]
+    REDISMASTER["AWS Redis 主库\n18.163.33.75:6379\nDocker redis:8.2.1"]
     REDISSLAVE["104.238.220.230\n原生 Redis 8.6.3\nrole: slave"]
     REDISMASTER --> REDISSLAVE
 ```

ops/hifast-current-architecture-zh.md

@@ -0,0 +1,246 @@
+# Hifast 当前架构文档（东京主站版）
+
+最后更新：`2026-05-21`
+
+这份文档只描述**当前真实生效**的架构，不描述理想目标，不混入已经下线或待迁移的香港旧链路。
+
+如果后续东京 `ALB / WAF / 正式域名` 上线，应继续更新这份文档，而不是回头参考旧香港架构文档。
+
+## 1. 当前结论
+
+当前已经实际跑起来的是：
+
+`用户 / 运维 -> 东京 EC2 -> ppanel-server + Redis + observability -> 东京 RDS MySQL`
+
+当前还**没有**实际生效的组件：
+
+- `ALB`
+- `WAF`
+- 正式域名切流
+- `104.238.220.230` 重挂东京 MySQL / Redis 从库
+
+也就是说，东京环境目前是：
+
+- 一台业务 EC2 已可用
+- 一台东京 RDS 已可用
+- 本机 Redis 已可用
+- `ppanel-server` 已成功启动并连通 MySQL / Redis
+- 灾备链路参数已准备好，但 `104` 还没最终挂上去
+
+## 2. 当前真实拓扑
+
+```mermaid
+flowchart TB
+    USER["用户 / 运维"] --> EIP["东京 EC2 公网入口\n3.114.29.208"]
+    EIP --> NGINX["Nginx\nEC2 本机"]
+    NGINX --> APP["ppanel-server\nhost network\n127.0.0.1:8080"]
+    APP --> REDIS["Redis Docker\n127.0.0.1:6379"]
+    APP --> RDS["Tokyo RDS MySQL\nppanel-mysql-jp"]
+    APP --> OBS["Grafana / Loki / Tempo / Prometheus"]
+
+    RDS -. 预留复制 .-> DRMYSQL["104.238.220.230\nMySQL DR\n未最终接入"]
+    REDIS -. 预留复制 .-> DRREDIS["104.238.220.230\nRedis DR\n未最终接入"]
+```
+
+## 3. 云资源清单
+
+### 3.1 Region
+
+- AWS account: `hifastvpn (200810848252)`
+- Region: `ap-northeast-1`
+
+### 3.2 网络
+
+- VPC: `ppanel-jp-prod`
+- VPC ID: `vpc-0846b23b4a7d64eac`
+- CIDR: `10.20.0.0/16`
+
+公有子网：
+
+- `ppanel-jp-public-a` / `subnet-091232bdb53e71490` / `10.20.0.0/24`
+- `ppanel-jp-public-c` / `subnet-01ba0975c525ce8cf` / `10.20.1.0/24`
+
+私有子网：
+
+- `ppanel-jp-private-a` / `subnet-0bd13111c02f0edbe` / `10.20.10.0/24`
+- `ppanel-jp-private-c` / `subnet-0d86c5c756dbc84b2` / `10.20.11.0/24`
+
+### 3.3 安全组
+
+- `ppanel-jp-sg-alb`
+  - `80/tcp <- 0.0.0.0/0`
+  - `443/tcp <- 0.0.0.0/0`
+- `ppanel-jp-sg-ec2`
+  - `80/tcp <- sg-0b3a23c31041a5a5a`
+  - `22/tcp <- 64.118.144.142/32`
+  - `6379/tcp <- 104.238.220.230/32`
+- `ppanel-jp-sg-rds`
+  - `3306/tcp <- sg-01f2a5a81e7505c91`
+  - `3306/tcp <- 104.238.220.230/32`
+
+## 4. 计算与数据库
+
+### 4.1 业务 EC2
+
+- Name: `ppanel-app-jp-01`
+- Instance ID: `i-07839130074cd7ed9`
+- Type: `c7i.xlarge`
+- AZ: `ap-northeast-1c`
+- Private IP: `10.20.1.168`
+- Public IP / Elastic IP: `3.114.29.208`
+- Public DNS: `ec2-3-114-29-208.ap-northeast-1.compute.amazonaws.com`
+- Root volume: `gp3 100GiB`
+- Status: `running`
+
+说明：
+
+- 当前公网入口是这台 EC2 自己
+- 这里绑定的是 `EIP`，不是依赖实例自动分配的临时公网 IP
+- 绑定 EIP 的目的，是保证以后 Redis 主从、白名单、DNS、文档里的公网地址不因为实例变更而漂移
+
+### 4.2 Tokyo RDS
+
+- Identifier: `ppanel-mysql-jp`
+- Engine: `MySQL Community 8.4.8`
+- Class: `db.r7g.xlarge`
+- Storage: `gp3 100GiB`
+- Master user: `admin`
+- Endpoint: `ppanel-mysql-jp.cpo0keikgh80.ap-northeast-1.rds.amazonaws.com`
+- Public access: `enabled`
+- Credential management: `self-managed`
+- Current status: `available`
+
+当前实际连接值：
+
+- Host: `ppanel-mysql-jp.cpo0keikgh80.ap-northeast-1.rds.amazonaws.com`
+- Port: `3306`
+- User: `admin`
+
+### 4.3 Redis
+
+- 部署位置：东京 EC2 本机
+- 部署方式：Docker
+- 容器名：`ppanel-redis`
+- 当前角色：`master`
+- 当前监听：`127.0.0.1:6379`（应用本机访问）
+- 当前对灾备开放：`3.114.29.208:6379`
+
+### 4.4 应用与可观测
+
+业务容器：
+
+- `ppanel-server`
+
+可观测容器：
+
+- `ppanel-grafana`
+- `ppanel-loki`
+- `ppanel-promtail`
+- `ppanel-prometheus`
+- `ppanel-tempo`
+- `ppanel-cadvisor`
+- `ppanel-node-exporter`
+- `ppanel-nginx-exporter`
+
+## 5. 当前部署方式
+
+部署目录：
+
+- `/opt/ppanel`
+
+关键文件：
+
+- `/opt/ppanel/docker-compose.cloud.yml`
+- `/opt/ppanel/configs/ppanel.yaml`
+- `/opt/ppanel/.env`
+
+业务启动方式：
+
+- `ppanel-server` 使用 `docker compose`
+- `network_mode: host`
+
+当前配置指向：
+
+- MySQL -> 东京 RDS
+- Redis -> 本机 Docker Redis
+- Trace -> `127.0.0.1:4317`
+
+## 6. 当前已验证状态
+
+截至 `2026-05-21` 已确认：
+
+- `docker exec ppanel-redis redis-cli -a 'hifast67yj' PING` 返回 `PONG`
+- `MYSQL_PWD=... mysql -h ppanel-mysql-jp.cpo0keikgh80.ap-northeast-1.rds.amazonaws.com -u admin -e "select 1"` 返回正常
+- `docker compose -f /opt/ppanel/docker-compose.cloud.yml up -d ppanel-server` 已成功
+- `docker logs ppanel-server` 无 MySQL / Redis 连接报错
+- `curl http://127.0.0.1:8080/v1/common/heartbeat` 返回成功
+
+可以认为当前东京单站已经具备：
+
+- 服务启动能力
+- 数据库连接能力
+- Redis 连接能力
+- 基础可观测能力
+
+## 7. 当前未落地项
+
+下面这些还属于“目标方案”，不是“当前实际架构”：
+
+- `ALB`
+- `WAF`
+- ACM 证书完成 DNS 验证
+- 正式域名切换到东京
+- `104.238.220.230` 完整接成东京 DR
+
+所以现在请不要把当前架构理解成：
+
+`DNS -> ALB -> WAF -> EC2 -> RDS`
+
+当前真实架构更准确地说是：
+
+`EIP -> EC2(Nginx + ppanel-server + Redis + observability) -> RDS`
+
+## 8. 灾备准备状态
+
+### 8.1 MySQL DR
+
+已准备好：
+
+- DR host: `104.238.220.230`
+- 复制账号：`repl@104.238.220.230`
+- binlog retention hours: `24`
+- current binlog file: `mysql-bin-changelog.000189`
+- current binlog position: `185053`
+
+当前状态：
+
+- 东京侧已准备完成
+- 但 `104` 侧还没有最终执行挂从
+
+### 8.2 Redis DR
+
+已准备好：
+
+- 东京 Redis 主地址：`3.114.29.208:6379`
+- 东京 Redis 当前角色：`role:master`
+- 东京 Redis 当前状态：`connected_slaves:0`
+
+当前状态：
+
+- 东京侧已可作为主库提供同步
+- 但 `104` 侧还没有最终执行 `REPLICAOF`
+
+## 9. 权威文档入口
+
+与当前东京架构直接相关的文档，以这些为准：
+
+- [当前架构文档](./hifast-current-architecture-zh.md)
+- [东京资源清单](../deploy/aws/ap-northeast-1/configs/resource-inventory.current.md)
+- [东京迁移 Runbook](./hifast-aws-jp-migration-runbook-zh.md)
+- [东京切换清单](./hifast-aws-jp-cutover-checklist-zh.md)
+
+下面这些旧文档可以继续保留，但不要作为“当前实际架构”依据：
+
+- 香港旧主站相关文档
+- 仍以 `ap-east-1` 为主语的历史架构说明
+

ops/hifast-s3-backup-runbook-zh.md

@@ -214,6 +214,42 @@ S3_PREFIX=redis bash deploy/scripts/redis_rdb_backup_to_s3.sh
 - 本地临时文件默认只保留 `3` 天
 - 长期保留建议通过 S3 Lifecycle 管理，而不是靠本机 cron 删除
 
+### 9.3 MySQL 每 10 分钟执行一次
+
+如果你要在 `104` 上做高频逻辑备份，仓库里已经补了 `systemd timer` 安装脚本：
+
+- 安装脚本：
+  - [`deploy/scripts/install_mysql_backup_timer.sh`](/Users/Apple/code_vpn/vpn/ppanel-server/deploy/scripts/install_mysql_backup_timer.sh)
+- systemd service：
+  - [`deploy/systemd/hifast-mysql-backup.service`](/Users/Apple/code_vpn/vpn/ppanel-server/deploy/systemd/hifast-mysql-backup.service)
+- systemd timer：
+  - [`deploy/systemd/hifast-mysql-backup.timer`](/Users/Apple/code_vpn/vpn/ppanel-server/deploy/systemd/hifast-mysql-backup.timer)
+
+安装方式：
+
+```bash
+cp deploy/aws/ap-northeast-1/configs/backup-to-s3.env.example /root/backup-to-s3.env
+chmod 600 /root/backup-to-s3.env
+vim /root/backup-to-s3.env
+
+bash deploy/scripts/install_mysql_backup_timer.sh /opt/ppanel /root/backup-to-s3.env
+```
+
+查看状态：
+
+```bash
+systemctl list-timers --all | grep hifast-mysql-backup
+systemctl status hifast-mysql-backup.timer --no-pager -l
+systemctl status hifast-mysql-backup.service --no-pager -l
+journalctl -u hifast-mysql-backup.service -n 50 --no-pager
+```
+
+补充说明：
+
+- 定时表达式是 `OnCalendar=*:0/10`，即每 `10` 分钟执行一次
+- 备份脚本已加 `flock` 锁，上一轮未结束时，下一轮会自动跳过，不会并发打包
+- 高频逻辑备份会持续产生 `mysqldump` 开销，建议只在 `104` 这样的从库或备用库上执行，不要直接打主库
+
 ## 10. 恢复思路
 
 ### 10.1 MySQL

ops/hifast-upload-chain-runbook-zh.md

@@ -0,0 +1,130 @@
+# Hifast 上传链路自检 Runbook
+
+本文档用于排查 `POST /v1/public/file/upload`、`/upload/init`、`/upload/complete` 相关问题。上传链路依赖：
+
+`客户端 -> Nginx -> ppanel-server -> S3/RustFS endpoint`
+
+## 1. 先确认业务服务健康
+
+在测试机执行：
+
+```bash
+curl -k -sS -m 8 -i https://tapi.hifast.biz/v1/common/heartbeat | head -30
+docker ps --format '{{.Names}} {{.Image}} {{.Status}} {{.Ports}}'
+ss -lntp | grep -E ':(80|443|8080|3306|6379)'
+```
+
+预期：
+
+- `/v1/common/heartbeat` 返回 `HTTP 200`，业务 `code=200`
+- `ppanel-server`、`ppanel-mysql`、`ppanel-redis` 运行中
+- Nginx 监听 `80/443`，ppanel 监听 `8080`
+
+## 2. 检查上传配置
+
+测试环境当前业务容器使用挂载配置：
+
+```bash
+docker inspect ppanel-server --format '{{json .Mounts}}'
+docker cp ppanel-server:/app/etc/ppanel.yaml /tmp/ppanel.yaml
+awk '/^S3:/{flag=1} flag && /^[A-Za-z0-9_]+:/{if($1!="S3:") exit} flag{print}' /tmp/ppanel.yaml \
+  | sed -E 's/(AccessKey:).*/\1 ***REDACTED***/; s/(SecretKey:).*/\1 ***REDACTED***/; s/(SessionToken:).*/\1 ***REDACTED***/'
+```
+
+重点确认：
+
+- `S3.Enable: true`
+- `S3.Endpoint` 是 ppanel-server 所在机器可以访问的地址
+- `S3.Bucket` 存在且凭据有 `PutObject` / `HeadObject` 权限
+- `S3.UsePathStyle` 与对象存储实现一致
+- `S3.PublicBaseURL` 只影响返回 URL，不代表写入 endpoint
+
+## 3. 检查对象存储连通性
+
+先从测试机主机网络检查：
+
+```bash
+endpoint='http://107.173.50.22:5017'
+host='107.173.50.22'
+port='5017'
+
+timeout 5 bash -lc "</dev/tcp/${host}/${port}" && echo tcp_ok || echo tcp_fail
+curl -v --connect-timeout 5 --max-time 10 -I "${endpoint}/"
+curl -v --connect-timeout 5 --max-time 10 -I "${endpoint}/hifastvpn"
+ip route get "${host}"
+```
+
+判定：
+
+- TCP 超时：优先查对象存储主机防火墙、安全组、服务监听、源 IP 白名单
+- TCP 通但 HTTP 空响应：优先查 endpoint 协议、反向代理、对象存储进程健康
+- 返回 S3 XML/鉴权错误：网络已通，再查 AK/SK、bucket、path-style 配置
+
+## 4. 检查应用日志
+
+```bash
+docker logs --since 3h ppanel-server 2>&1 \
+  | grep -Ei 'put object failed|upload|s3|timeout|context canceled|error' \
+  | tail -120
+```
+
+典型根因：
+
+- `put object failed ... context canceled` 且请求耗时约 60 秒：上游对象存储请求没有在 Nginx upstream timeout 前完成，通常是 `S3.Endpoint` 不可达或对象存储服务 hang。
+- 立即返回业务错误：通常是 `S3.Enable=false`、Content-Type 不在白名单、bucket/权限错误。
+
+## 5. Nginx 检查
+
+```bash
+grep -RIn 'proxy_pass\|proxy_read_timeout\|client_max_body_size\|tapi.hifast.biz' /etc/nginx/sites-enabled /etc/nginx/conf.d
+nginx -t
+```
+
+注意：单纯放大 `proxy_read_timeout` 只能掩盖现象，不能修复对象存储不可达。
+
+## 6. 修复与回滚
+
+修复优先级：
+
+1. 恢复对象存储 endpoint 的网络访问或服务监听。
+2. 如 endpoint 已迁移，更新 `/root/bindbox/configs/ppanel.yaml` 的 `S3.Endpoint`，重启 `ppanel-server`。
+3. 如果凭据或 bucket 变更，同步更新 `S3.AccessKey`、`S3.SecretKey`、`S3.Bucket`、`S3.UsePathStyle`。
+
+改配置前先备份：
+
+```bash
+cp /root/bindbox/configs/ppanel.yaml /root/bindbox/configs/ppanel.yaml.bak.$(date +%Y%m%d%H%M%S)
+docker restart ppanel-server
+```
+
+回滚：
+
+```bash
+cp /root/bindbox/configs/ppanel.yaml.bak.YYYYMMDDHHMMSS /root/bindbox/configs/ppanel.yaml
+docker restart ppanel-server
+curl -k -sS -m 8 -i https://tapi.hifast.biz/v1/common/heartbeat | head -30
+```
+
+## 7. 验证
+
+使用有效 JWT 和有效签名复测：
+
+```bash
+curl -i -X POST 'https://tapi.hifast.biz/v1/public/file/upload' \
+  -H 'x-app-id: android-client' \
+  -H 'Authorization: <client-jwt>' \
+  -H 'x-signature-version: v101' \
+  -H 'login-type: device' \
+  -H 'x-signature: <sig>' \
+  -H 'x-nonce: <nonce>' \
+  -H 'x-timestamp: <ts>' \
+  -F 'biz_type=app-package' \
+  -F 'file=@nconf.zip;type=application/zip' \
+  --max-time 120
+```
+
+预期：
+
+- HTTP 不再出现 `504 Gateway Time-out`
+- 业务响应 `code=200`
+- `docker logs ppanel-server` 不再出现新的 `put object failed`

pkg/storage/s3.go

@@ -3,6 +3,7 @@ package storage
 import (
 	"context"
 	"fmt"
+	"io"
 	"net/url"
 	"strings"
 	"time"
@@ -22,11 +23,15 @@ type PresignUploadResult struct {
 }
 
 type ObjectMeta struct {
-	ETag         string
+	ETag          string
-	ContentType  string
+	ContentType   string
 	ContentLength int64
 }
 
+type PutObjectResult struct {
+	ETag string
+}
+
 type S3Store struct {
 	cfg     config.S3Config
 	client  *s3.Client
@@ -96,6 +101,20 @@ func (s *S3Store) HeadObject(ctx context.Context, objectKey string) (*ObjectMeta
 	}, nil
 }
 
+func (s *S3Store) PutObject(ctx context.Context, objectKey string, body io.Reader, size int64, contentType string) (*PutObjectResult, error) {
+	resp, err := s.client.PutObject(ctx, &s3.PutObjectInput{
+		Bucket:        aws.String(s.cfg.Bucket),
+		Key:           aws.String(objectKey),
+		Body:          body,
+		ContentLength: aws.Int64(size),
+		ContentType:   aws.String(contentType),
+	})
+	if err != nil {
+		return nil, err
+	}
+	return &PutObjectResult{ETag: strings.Trim(aws.ToString(resp.ETag), "\"")}, nil
+}
+
 func (s *S3Store) BuildObjectURL(objectKey string) string {
 	if s.cfg.PublicBaseURL != "" {
 		return strings.TrimRight(s.cfg.PublicBaseURL, "/") + "/" + strings.TrimLeft(objectKey, "/")

pkg/xerr/errCode.go

@@ -37,6 +37,7 @@ const (
 	FamilyNotExist                uint32 = 20017
 	FamilyStatusInvalid           uint32 = 20018
 	FamilyOwnerOperationForbidden uint32 = 20019
+	WithdrawalStatusInvalid       uint32 = 20020
 )
 
 // Node error
@@ -140,9 +141,12 @@ const (
 )
 
 const (
-	OrderNotExist         uint32 = 61001
+	OrderNotExist                 uint32 = 61001
-	PaymentMethodNotFound uint32 = 61002
+	PaymentMethodNotFound         uint32 = 61002
-	OrderStatusError      uint32 = 61003
+	OrderStatusError              uint32 = 61003
-	InsufficientOfPeriod  uint32 = 61004
+	InsufficientOfPeriod          uint32 = 61004
-	ExistAvailableTraffic uint32 = 61005
+	ExistAvailableTraffic         uint32 = 61005
+	OrderAlreadyRefunded          uint32 = 61006
+	OrderRefundNoSubscription     uint32 = 61007
+	OrderRefundCommissionMismatch uint32 = 61008
 )

pkg/xerr/errMsg.go

@@ -46,6 +46,7 @@ func init() {
 		FamilyNotExist:                "家庭组不存在",
 		FamilyStatusInvalid:           "家庭组状态无效",
 		FamilyOwnerOperationForbidden: "家庭组所有者不允许此操作",
+		WithdrawalStatusInvalid:       "提现状态无效",
 
 		// Node error
 		NodeExist:         "Node already exists",
@@ -98,10 +99,13 @@ func init() {
 		UseridNotMatch:                     "Userid not match",
 
 		// Order error
-		OrderNotExist:         "Order does not exist",
+		OrderNotExist:                 "Order does not exist",
-		PaymentMethodNotFound: "Payment method not found",
+		PaymentMethodNotFound:         "Payment method not found",
-		OrderStatusError:      "Order status error",
+		OrderStatusError:              "Order status error",
-		InsufficientOfPeriod:  "Insufficient number of period",
+		InsufficientOfPeriod:          "Insufficient number of period",
+		OrderAlreadyRefunded:          "Order already refunded",
+		OrderRefundNoSubscription:     "Refund target subscription not found",
+		OrderRefundCommissionMismatch: "Refund commission source not found",
 
 		// Permission error
 		PermissionDenied: "Permission denied",

queue/handler/routes.go

@@ -48,4 +48,7 @@ func RegisterHandlers(mux *asynq.ServeMux, serverCtx *svc.ServiceContext) {
 	// Apple IAP 对账（第二层：5min 扫描 + 第三层：日终全量）
 	mux.Handle(types.SchedulerIAPReconcile, iapLogic.NewReconcileLogic(serverCtx))
 	mux.Handle(types.SchedulerIAPDailyReconcile, iapLogic.NewDailyReconcileLogic(serverCtx))
+
+	// Stuck order recovery
+	mux.Handle(types.SchedulerStuckOrderRecovery, orderLogic.NewStuckOrderRecoveryLogic(serverCtx))
 }

queue/logic/order/activateOrderLogic.go

@@ -7,6 +7,7 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
+	"strings"
 	"time"
 
 	"github.com/perfect-panel/server/internal/logic/admin/group"
@@ -46,7 +47,7 @@ const (
 	OrderStatusPaid     = 2 // Order paid and ready for processing
 	OrderStatusClose    = 3 // Order closed/cancelled
 	OrderStatusFailed   = 4 // Order processing failed
-	OrderStatusClaimed  = 4 // Internal transient claim while a worker processes the order
+	OrderStatusClaimed  = 6 // Internal transient claim while a worker processes the order
 	OrderStatusFinished = 5 // Order successfully completed
 )
 
@@ -92,8 +93,12 @@ func (l *ActivateOrderLogic) ProcessTask(ctx context.Context, task *asynq.Task)
 
 	orderInfo, err := l.claimAndGetOrder(ctx, payload.OrderNo)
 	if err != nil {
-		// 如果订单不存在或状态不对，不重试
 		if errors.Is(err, ErrInvalidOrderStatus) {
+			if strings.Contains(err.Error(), "stuck in claimed") {
+				logger.WithContext(ctx).Error("[ActivateOrderLogic] 订单卡在 claimed，将重试",
+					logger.Field("order_no", payload.OrderNo))
+				return err // 返回错误触发 asynq 重试
+			}
 			logger.WithContext(ctx).Info("[ActivateOrderLogic] 订单状态不是已支付，跳过",
 				logger.Field("order_no", payload.OrderNo))
 			return nil
@@ -116,7 +121,12 @@ func (l *ActivateOrderLogic) ProcessTask(ctx context.Context, task *asynq.Task)
 	)
 
 	if err = l.processOrderByType(ctx, orderInfo, payload.IAPExpireAt); err != nil {
-		l.releaseClaim(ctx, orderInfo.OrderNo)
+		if releaseErr := l.releaseClaim(ctx, orderInfo.OrderNo); releaseErr != nil {
+			logger.WithContext(ctx).Error("[ActivateOrderLogic] releaseClaim also failed, stuck recovery will handle",
+				logger.Field("order_no", orderInfo.OrderNo),
+				logger.Field("release_error", releaseErr.Error()),
+			)
+		}
 		logger.WithContext(ctx).Error("[ActivateOrderLogic] 处理订单失败，将重试",
 			logger.Field("order_no", orderInfo.OrderNo),
 			logger.Field("order_type", orderInfo.Type),
@@ -125,7 +135,12 @@ func (l *ActivateOrderLogic) ProcessTask(ctx context.Context, task *asynq.Task)
 	}
 
 	if err = l.reconcilePostOrderSubscriptions(ctx, orderInfo); err != nil {
-		l.releaseClaim(ctx, orderInfo.OrderNo)
+		if releaseErr := l.releaseClaim(ctx, orderInfo.OrderNo); releaseErr != nil {
+			logger.WithContext(ctx).Error("[ActivateOrderLogic] releaseClaim also failed, stuck recovery will handle",
+				logger.Field("order_no", orderInfo.OrderNo),
+				logger.Field("release_error", releaseErr.Error()),
+			)
+		}
 		logger.WithContext(ctx).Error("[ActivateOrderLogic] 订单订阅兜底合并失败，将重试",
 			logger.Field("order_no", orderInfo.OrderNo),
 			logger.Field("order_type", orderInfo.Type),
@@ -176,6 +191,15 @@ func (l *ActivateOrderLogic) claimAndGetOrder(ctx context.Context, orderNo strin
 		return nil, nil
 	}
 
+	// Detect stuck claimed order — return retryable error so asynq re-tries
+	if orderInfo.Status == OrderStatusClaimed {
+		logger.WithContext(ctx).Error("Order stuck in claimed status",
+			logger.Field("order_no", orderInfo.OrderNo),
+			logger.Field("status", orderInfo.Status),
+		)
+		return nil, fmt.Errorf("order %s stuck in claimed status: %w", orderNo, ErrInvalidOrderStatus)
+	}
+
 	if orderInfo.Status != OrderStatusPaid {
 		logger.WithContext(ctx).Error("Order status error",
 			logger.Field("order_no", orderInfo.OrderNo),
@@ -201,7 +225,7 @@ func (l *ActivateOrderLogic) claimAndGetOrder(ctx context.Context, orderNo strin
 	return &orderInfo, nil
 }
 
-func (l *ActivateOrderLogic) releaseClaim(ctx context.Context, orderNo string) {
+func (l *ActivateOrderLogic) releaseClaim(ctx context.Context, orderNo string) error {
 	if err := l.svc.DB.WithContext(ctx).
 		Model(&order.Order{}).
 		Where("order_no = ? AND status = ?", orderNo, OrderStatusClaimed).
@@ -210,7 +234,9 @@ func (l *ActivateOrderLogic) releaseClaim(ctx context.Context, orderNo string) {
 			logger.Field("error", err.Error()),
 			logger.Field("order_no", orderNo),
 		)
+		return fmt.Errorf("release claim failed for order %s: %w", orderNo, err)
 	}
+	return nil
 }
 
 // processOrderByType routes order processing based on the order type
@@ -563,14 +589,27 @@ func (l *ActivateOrderLogic) finalizeCouponAndOrder(ctx context.Context, orderIn
 		}
 	}
 
-	// Update order status using state-guarded UpdateOrderStatus to prevent double finalization
+	// UpdateOrderStatus uses WHERE status < target, which blocks claimed(6)→finished(5).
-	if err := l.svc.OrderModel.UpdateOrderStatus(ctx, orderInfo.OrderNo, OrderStatusFinished); err != nil {
+	// Use a direct update matching the exact claimed status, then update the full record
-		logger.WithContext(ctx).Error("Update order status failed",
+	// via the model layer to properly invalidate the cache.
+	result := l.svc.DB.WithContext(ctx).
+		Model(&order.Order{}).
+		Where("order_no = ? AND status = ?", orderInfo.OrderNo, OrderStatusClaimed).
+		Update("status", OrderStatusFinished)
+	if result.Error != nil {
+		logger.WithContext(ctx).Error("Update order status from claimed to finished failed",
+			logger.Field("error", result.Error.Error()),
+			logger.Field("order_no", orderInfo.OrderNo),
+		)
+	}
+	// Invalidate order cache regardless of whether the DB update succeeded
+	orderInfo.Status = OrderStatusFinished
+	if err := l.svc.OrderModel.Update(ctx, orderInfo); err != nil {
+		logger.WithContext(ctx).Error("Update order cache after finalization failed",
 			logger.Field("error", err.Error()),
 			logger.Field("order_no", orderInfo.OrderNo),
 		)
 	}
-	orderInfo.Status = OrderStatusFinished
 	commonLogic.SubscriptionTraceInfo(logger.WithContext(ctx), commonLogic.SubscriptionTraceFlowOrder, "order_status_finished",
 		"[SubscriptionFlow] order status updated to finished",
 		commonLogic.OrderTraceFields(orderInfo)...,
@@ -597,7 +636,7 @@ func (l *ActivateOrderLogic) NewPurchase(ctx context.Context, orderInfo *order.O
 		return err
 	}
 
-	if err = validateNewUserOnlyEligibilityAtActivation(ctx, l.svc.DB, orderInfo, sub); err != nil {
+	if err = validateNewUserOnlyEligibilityAtActivation(ctx, l.svc.DB, l.svc.Redis, orderInfo, sub); err != nil {
 		return err
 	}
 
@@ -675,18 +714,23 @@ func (l *ActivateOrderLogic) NewPurchase(ctx context.Context, orderInfo *order.O
 	// 兜底：创建新订阅前，查找用户是否已有同套餐的订阅记录（含过期/赠送），
 	// 有则复用旧记录续期，避免出现重复订阅。
 	// 需要同时检查 UserId 和 SubscriptionUserId，因为家庭组绑定前后 owner 可能不同。
+	// 使用 SELECT ... FOR UPDATE 防止并发下多个 worker 同时选中同一订阅并创建重复记录。
 	if userSub == nil {
 		candidateUserIds := []int64{orderInfo.UserId}
 		if orderInfo.SubscriptionUserId > 0 && orderInfo.SubscriptionUserId != orderInfo.UserId {
 			candidateUserIds = append(candidateUserIds, orderInfo.SubscriptionUserId)
 		}
 		var existingSub user.Subscribe
-		if findErr := l.svc.DB.Model(&user.Subscribe{}).
+		findErr := l.svc.DB.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
-			Where("user_id IN ? AND token != ''", candidateUserIds).
+			return tx.Clauses(clause.Locking{Strength: "UPDATE"}).
-			Order("expire_time DESC").
+				Model(&user.Subscribe{}).
-			Order("updated_at DESC").
+				Where("user_id IN ? AND token != ''", candidateUserIds).
-			Order("id DESC").
+				Order("expire_time DESC").
-			First(&existingSub).Error; findErr == nil {
+				Order("updated_at DESC").
+				Order("id DESC").
+				First(&existingSub).Error
+		})
+		if findErr == nil {
 			// 家庭组场景：订阅 owner 可能变更（如成员注册的试用 → 被家主收归），
 			// 续期前把 user_id 校正为当前订单的 SubscriptionUserId
 			effectiveOwner := orderInfo.UserId
@@ -824,26 +868,52 @@ func (l *ActivateOrderLogic) createGuestUser(ctx context.Context, orderInfo *ord
 	return userInfo, nil
 }
 
-// getTempOrderInfo retrieves temporary order information from Redis cache
+// getTempOrderInfo retrieves temporary order information from Redis cache with DB fallback.
 func (l *ActivateOrderLogic) getTempOrderInfo(ctx context.Context, orderNo string) (*constant.TemporaryOrderInfo, error) {
 	cacheKey := fmt.Sprintf(constant.TempOrderCacheKey, orderNo)
 	data, err := l.svc.Redis.Get(ctx, cacheKey).Result()
-	if err != nil {
+	if err == nil {
-		logger.WithContext(ctx).Error("Get temp order cache failed",
+		var tempOrder constant.TemporaryOrderInfo
-			logger.Field("error", err.Error()),
+		if unmarshalErr := tempOrder.Unmarshal([]byte(data)); unmarshalErr != nil {
-			logger.Field("cache_key", cacheKey),
+			logger.WithContext(ctx).Error("Unmarshal temp order cache failed",
+				logger.Field("error", unmarshalErr.Error()),
+				logger.Field("cache_key", cacheKey),
+				logger.Field("data", data),
+			)
+			return nil, unmarshalErr
+		}
+		return &tempOrder, nil
+	}
+
+	// Redis miss — fall back to DB activation_context field.
+	logger.WithContext(ctx).Infow("Redis cache miss for temp order, falling back to DB",
+		logger.Field("cache_key", cacheKey),
+		logger.Field("error", err.Error()),
+	)
+
+	orderInfo, dbErr := l.svc.OrderModel.FindOneByOrderNo(ctx, orderNo)
+	if dbErr != nil {
+		logger.WithContext(ctx).Error("DB fallback for temp order failed",
+			logger.Field("order_no", orderNo),
+			logger.Field("error", dbErr.Error()),
 		)
-		return nil, err
+		return nil, dbErr
+	}
+
+	if orderInfo.ActivationContext == "" {
+		logger.WithContext(ctx).Error("CRITICAL: activation_context missing in DB and Redis expired; cannot recover guest order",
+			logger.Field("order_no", orderNo),
+		)
+		return nil, errors.New("activation context not found: Redis expired and no DB fallback available")
 	}
 
 	var tempOrder constant.TemporaryOrderInfo
-	if err = tempOrder.Unmarshal([]byte(data)); err != nil {
+	if unmarshalErr := tempOrder.Unmarshal([]byte(orderInfo.ActivationContext)); unmarshalErr != nil {
-		logger.WithContext(ctx).Error("Unmarshal temp order cache failed",
+		logger.WithContext(ctx).Error("Unmarshal DB activation_context failed",
-			logger.Field("error", err.Error()),
+			logger.Field("order_no", orderNo),
-			logger.Field("cache_key", cacheKey),
+			logger.Field("error", unmarshalErr.Error()),
-			logger.Field("data", data),
 		)
-		return nil, err
+		return nil, unmarshalErr
 	}
 
 	return &tempOrder, nil
@@ -1447,7 +1517,40 @@ func (l *ActivateOrderLogic) resolveRenewalActivationSubscription(ctx context.Co
 	}
 	userSub, err := l.getUserSubscription(ctx, orderInfo.SubscribeToken)
 	if err != nil {
-		return nil, err
+		// Fallback: token may have been lost (subscription deleted or owner changed).
+		// Locate the most recent subscription by user_id + subscribe_id with FOR UPDATE
+		// to prevent a concurrent worker from renewing the same record twice.
+		targetUserID := orderInfo.UserId
+		if orderInfo.SubscriptionUserId > 0 {
+			targetUserID = orderInfo.SubscriptionUserId
+		}
+		var fallbackSub user.Subscribe
+		txErr := l.svc.DB.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+			return tx.Clauses(clause.Locking{Strength: "UPDATE"}).
+				Model(&user.Subscribe{}).
+				Where("user_id = ? AND subscribe_id = ?", targetUserID, orderInfo.SubscribeId).
+				Where("status IN ?", []int64{0, 1, 2, 3}).
+				Order("expire_time DESC").
+				Order("updated_at DESC").
+				Order("id DESC").
+				First(&fallbackSub).Error
+		})
+		if txErr != nil {
+			logger.WithContext(ctx).Error("CRITICAL: Renewal activation token and fallback lookup both failed",
+				logger.Field("token_error", err.Error()),
+				logger.Field("fallback_error", txErr.Error()),
+				logger.Field("order_no", orderInfo.OrderNo),
+				logger.Field("target_user_id", targetUserID),
+				logger.Field("subscribe_id", orderInfo.SubscribeId),
+			)
+			return nil, fmt.Errorf("renewal activation subscription not found by token or user_id+subscribe_id for order %s: %w", orderInfo.OrderNo, err)
+		}
+		logger.WithContext(ctx).Info("Renewal token lookup failed; found subscription via fallback user_id+subscribe_id",
+			logger.Field("order_no", orderInfo.OrderNo),
+			logger.Field("fallback_subscribe_id", fallbackSub.Id),
+			logger.Field("target_user_id", targetUserID),
+		)
+		userSub = &fallbackSub
 	}
 	if orderInfo.UserId <= 0 {
 		return userSub, nil
@@ -1743,25 +1846,50 @@ func (l *ActivateOrderLogic) RedemptionActivate(ctx context.Context, orderInfo *
 		return err
 	}
 
-	// 3. 从Redis获取兑换码信息
+	// 3. 从Redis获取兑换码信息，Redis缺失时回查DB
-	cacheKey := fmt.Sprintf("redemption_order:%s", orderInfo.OrderNo)
-	data, err := l.svc.Redis.Get(ctx, cacheKey).Result()
-	if err != nil {
-		logger.WithContext(ctx).Error("Get redemption cache failed",
-			logger.Field("error", err.Error()),
-			logger.Field("cache_key", cacheKey),
-		)
-		return err
-	}
-
 	var redemptionData struct {
 		RedemptionCodeId int64  `json:"redemption_code_id"`
 		UnitTime         string `json:"unit_time"`
 		Quantity         int64  `json:"quantity"`
 	}
-	if err = json.Unmarshal([]byte(data), &redemptionData); err != nil {
+
-		logger.WithContext(ctx).Error("Unmarshal redemption cache failed", logger.Field("error", err.Error()))
+	cacheKey := fmt.Sprintf("redemption_order:%s", orderInfo.OrderNo)
-		return err
+	data, redisErr := l.svc.Redis.Get(ctx, cacheKey).Result()
+	if redisErr == nil {
+		if err = json.Unmarshal([]byte(data), &redemptionData); err != nil {
+			logger.WithContext(ctx).Error("Unmarshal redemption cache failed", logger.Field("error", err.Error()))
+			return err
+		}
+	} else {
+		// Redis miss — fall back to DB activation_context field.
+		logger.WithContext(ctx).Infow("Redis cache miss for redemption order, falling back to DB",
+			logger.Field("cache_key", cacheKey),
+			logger.Field("error", redisErr.Error()),
+		)
+
+		if orderInfo.ActivationContext == "" {
+			logger.WithContext(ctx).Error("CRITICAL: activation_context missing in DB and Redis expired; cannot recover redemption order",
+				logger.Field("order_no", orderInfo.OrderNo),
+			)
+			return errors.New("activation context not found: Redis expired and no DB fallback available")
+		}
+
+		var fullContext struct {
+			Type             string `json:"type"`
+			RedemptionCodeId int64  `json:"redemption_code_id"`
+			UnitTime         string `json:"unit_time"`
+			Quantity         int64  `json:"quantity"`
+		}
+		if err = json.Unmarshal([]byte(orderInfo.ActivationContext), &fullContext); err != nil {
+			logger.WithContext(ctx).Error("Unmarshal DB activation_context failed",
+				logger.Field("order_no", orderInfo.OrderNo),
+				logger.Field("error", err.Error()),
+			)
+			return err
+		}
+		redemptionData.RedemptionCodeId = fullContext.RedemptionCodeId
+		redemptionData.UnitTime = fullContext.UnitTime
+		redemptionData.Quantity = fullContext.Quantity
 	}
 
 	// 4. 幂等性检查：查询是否已有兑换记录