feat: 移除“租户管理员为用户充值 / 每租户一套余额”能力：余额统一为全局用户余额

2025-12-23 10:59:59 +08:00
parent dd7bcdfb98
commit a80c9b759b
39 changed files with 566 additions and 1869 deletions
--- a/backend/docs/swagger.yaml
+++ b/backend/docs/swagger.yaml
@@ -111,11 +111,9 @@ definitions:
  consts.OrderType:
    enum:
    - content_purchase
-    - topup
    type: string
    x-enum-varnames:
    - OrderTypeContentPurchase
-    - OrderTypeTopup
  consts.Role:
    enum:
    - user
@@ -146,7 +144,6 @@ definitions:
    - TenantJoinRequestStatusRejected
  consts.TenantLedgerType:
    enum:
-    - credit_topup
    - debit_purchase
    - credit_refund
    - freeze
@@ -154,7 +151,6 @@ definitions:
    - adjustment
    type: string
    x-enum-varnames:
-    - TenantLedgerTypeCreditTopup
    - TenantLedgerTypeDebitPurchase
    - TenantLedgerTypeCreditRefund
    - TenantLedgerTypeFreeze
@@ -188,75 +184,6 @@ definitions:
    - UserStatusPendingVerify
    - UserStatusVerified
    - UserStatusBanned
-  dto.AdminBatchTopupForm:
-    properties:
-      batch_idempotency_key:
-        description: BatchIdempotencyKey 批次幂等键：必须填写；用于重试同一批次时保证不会重复入账。
-        type: string
-      items:
-        description: Items 充值明细列表：至少 1 条；单批次条数在业务侧限制（避免拖垮系统）。
-        items:
-          $ref: '#/definitions/dto.AdminBatchTopupItem'
-        type: array
-    type: object
-  dto.AdminBatchTopupItem:
-    properties:
-      amount:
-        description: Amount 充值金额：单位分；必须 > 0。
-        type: integer
-      idempotency_key:
-        description: |-
-          IdempotencyKey 幂等键（可选）：为空时后端会用 batch_idempotency_key 派生生成；
-          建议前端/调用方提供稳定值，便于重试时保持结果一致。
-        type: string
-      reason:
-        description: Reason 充值原因（可选）：用于审计与追溯。
-        type: string
-      user_id:
-        description: UserID 目标用户ID：必须属于当前租户，否则该条充值失败。
-        type: integer
-    type: object
-  dto.AdminBatchTopupResponse:
-    properties:
-      failed:
-        description: Failed 失败条数。
-        type: integer
-      items:
-        description: Items 明细结果列表：与请求 items 顺序一致，便于前端逐条展示。
-        items:
-          $ref: '#/definitions/dto.AdminBatchTopupResultItem'
-        type: array
-      success:
-        description: Success 成功条数。
-        type: integer
-      total:
-        description: Total 总条数：等于 items 长度。
-        type: integer
-    type: object
-  dto.AdminBatchTopupResultItem:
-    properties:
-      amount:
-        description: Amount 充值金额（单位分）。
-        type: integer
-      error_code:
-        description: ErrorCode 错误码：失败时返回；成功时为 0。
-        type: integer
-      error_message:
-        description: ErrorMessage 错误信息：失败时返回；成功时为空。
-        type: string
-      idempotency_key:
-        description: IdempotencyKey 实际使用的幂等键：可能为客户端传入，也可能为后端派生生成。
-        type: string
-      ok:
-        description: OK 是否成功：true 表示该条充值已成功入账或命中幂等成功结果。
-        type: boolean
-      order_id:
-        description: OrderID 生成的订单ID：成功时返回；失败时为 0。
-        type: integer
-      user_id:
-        description: UserID 目标用户ID。
-        type: integer
-    type: object
  dto.AdminLedgerItem:
    properties:
      ledger:
@@ -448,19 +375,6 @@ definitions:
        description: Role 角色：member/tenant_admin。
        type: string
    type: object
-  dto.AdminTopupForm:
-    properties:
-      amount:
-        description: Amount is the topup amount in cents (CNY 分); must be > 0.
-        type: integer
-      idempotency_key:
-        description: IdempotencyKey ensures the topup request is processed at most
-          once.
-        type: string
-      reason:
-        description: Reason is the human-readable topup reason used for audit.
-        type: string
-    type: object
  dto.ContentAssetAttachForm:
    properties:
      asset_id:
@@ -760,6 +674,12 @@ definitions:
    type: object
  dto.UserItem:
    properties:
+      balance:
+        description: 全局可用余额：分/最小货币单位；用户在所有已加入租户内共享该余额；默认 0
+        type: integer
+      balance_frozen:
+        description: 全局冻结余额：分/最小货币单位；用于下单冻结等；默认 0
+        type: integer
      created_at:
        type: string
      deleted_at:
@@ -1077,7 +997,7 @@ definitions:
      type:
        allOf:
        - $ref: '#/definitions/consts.OrderType'
-        description: 订单类型：content_purchase（购买内容）/topup（充值）等；当前默认 content_purchase
+        description: 订单类型：content_purchase（购买内容）等；当前默认 content_purchase
      updated_at:
        description: 更新时间：默认 now()；状态变更/退款写入时更新
        type: string
@@ -1244,7 +1164,7 @@ definitions:
        description: 业务引用ID：与 biz_ref_type 配合使用（例如 orders.id）；用于对账与审计
        type: integer
      biz_ref_type:
-        description: 业务引用类型：order/refund/topup/etc；与 biz_ref_id 组成可选的结构化幂等/追溯键
+        description: 业务引用类型：order/refund/etc；与 biz_ref_id 组成可选的结构化幂等/追溯键
        type: string
      created_at:
        description: 创建时间：默认 now()
@@ -1278,7 +1198,7 @@ definitions:
      type:
        allOf:
        - $ref: '#/definitions/consts.TenantLedgerType'
-        description: 流水类型：credit_topup/debit_purchase/credit_refund/freeze/unfreeze/adjustment；不同类型决定余额/冻结余额的变更方向
+        description: 流水类型：debit_purchase/credit_refund/freeze/unfreeze/adjustment；不同类型决定余额/冻结余额的变更方向
      updated_at:
        description: 更新时间：默认 now()
        type: string
@@ -1288,11 +1208,6 @@ definitions:
    type: object
  models.TenantUser:
    properties:
-      balance:
-        type: integer
-      balance_frozen:
-        description: 冻结余额：分/最小货币单位；下单冻结时从可用余额转入，最终扣款或回滚时转出；默认 0
-        type: integer
      created_at:
        type: string
      id:
@@ -1312,6 +1227,12 @@ definitions:
    type: object
  models.User:
    properties:
+      balance:
+        description: 全局可用余额：分/最小货币单位；用户在所有已加入租户内共享该余额；默认 0
+        type: integer
+      balance_frozen:
+        description: 全局冻结余额：分/最小货币单位；用于下单冻结等；默认 0
+        type: integer
      created_at:
        type: string
      deleted_at:
@@ -2004,7 +1925,7 @@ paths:
        type: integer
      - description: |-
          BizRefType 按业务引用类型过滤（可选）。
-          约定：当前业务写入为 "order"；未来可扩展为 refund/topup 等。
+          约定：当前业务写入为 "order"；未来可扩展为 refund 等。
        in: query
        name: biz_ref_type
        type: string
@@ -2023,7 +1944,7 @@ paths:
        type: integer
      - description: |-
          OperatorUserID 按操作者用户ID过滤（可选）。
-          典型场景：后台检索“某个管理员发起的充值/退款”等敏感操作流水。
+          典型场景：后台检索“某个管理员发起的退款/调账”等敏感操作流水。
        in: query
        name: operator_user_id
        type: integer
@@ -2037,7 +1958,6 @@ paths:
        type: integer
      - description: Type 按流水类型过滤（可选）。
        enum:
-        - credit_topup
        - debit_purchase
        - credit_refund
        - freeze
@@ -2047,7 +1967,6 @@ paths:
        name: type
        type: string
        x-enum-varnames:
-        - TenantLedgerTypeCreditTopup
        - TenantLedgerTypeDebitPurchase
        - TenantLedgerTypeCreditRefund
        - TenantLedgerTypeFreeze
@@ -2340,16 +2259,14 @@ paths:
        - OrderStatusRefunded
        - OrderStatusCanceled
        - OrderStatusFailed
-      - description: Type 订单类型（可选）：content_purchase/topup 等。
+      - description: Type 订单类型（可选）：content_purchase 等。
        enum:
        - content_purchase
-        - topup
        in: query
        name: type
        type: string
        x-enum-varnames:
        - OrderTypeContentPurchase
-        - OrderTypeTopup
      - description: UserID 下单用户ID（可选）：按买家用户ID精确过滤。
        in: query
        name: user_id
@@ -2403,6 +2320,9 @@ paths:
    post:
      consumes:
      - application/json
+      description: |-
+        该接口只负责将订单从 paid 推进到 refunding，并提交异步退款任务；退款入账与权益回收由 worker 异步完成。
+        重复请求幂等：订单处于 refunding/refunded 时会返回当前订单状态，不会重复入账/重复回收权益。
      parameters:
      - description: Tenant Code
        in: path
@@ -2509,16 +2429,14 @@ paths:
        - OrderStatusRefunded
        - OrderStatusCanceled
        - OrderStatusFailed
-      - description: Type 订单类型（可选）：content_purchase/topup 等。
+      - description: Type 订单类型（可选）：content_purchase 等。
        enum:
        - content_purchase
-        - topup
        in: query
        name: type
        type: string
        x-enum-varnames:
        - OrderTypeContentPurchase
-        - OrderTypeTopup
      - description: UserID 下单用户ID（可选）：按买家用户ID精确过滤。
        in: query
        name: user_id
@@ -2685,64 +2603,6 @@ paths:
      summary: 设置成员角色（租户管理）
      tags:
      - Tenant
-  /t/{tenantCode}/v1/admin/users/{userID}/topup:
-    post:
-      consumes:
-      - application/json
-      parameters:
-      - description: Tenant Code
-        in: path
-        name: tenantCode
-        required: true
-        type: string
-      - description: UserID
-        format: int64
-        in: path
-        name: userID
-        required: true
-        type: integer
-      - description: Form
-        in: body
-        name: form
-        required: true
-        schema:
-          $ref: '#/definitions/dto.AdminTopupForm'
-      produces:
-      - application/json
-      responses:
-        "200":
-          description: OK
-          schema:
-            $ref: '#/definitions/models.Order'
-      summary: 为租户成员充值（租户管理）
-      tags:
-      - Tenant
-  /t/{tenantCode}/v1/admin/users/topup/batch:
-    post:
-      consumes:
-      - application/json
-      parameters:
-      - description: Tenant Code
-        in: path
-        name: tenantCode
-        required: true
-        type: string
-      - description: Form
-        in: body
-        name: form
-        required: true
-        schema:
-          $ref: '#/definitions/dto.AdminBatchTopupForm'
-      produces:
-      - application/json
-      responses:
-        "200":
-          description: OK
-          schema:
-            $ref: '#/definitions/dto.AdminBatchTopupResponse'
-      summary: 批量为租户成员充值（租户管理）
-      tags:
-      - Tenant
  /t/{tenantCode}/v1/contents:
    get:
      consumes: