docs(finance): register wallet recharge workflow

2026-09-05 08:34:40 +08:00
parent e5609107f3
commit 015d8f4b13
3 changed files with 156 additions and 6 deletions
@@ -1,5 +1,11 @@
 # 财务管理闭环盘点与范围建议

+## 当前确认：一件代发客户资金账户（2026-09-05）
+
+当前对话已将资金账户作为一件代发的前置节点重新纳入范围，并覆盖本文后续历史章节中“钱包不做”的旧结论。首批固定为 CNY，满足 `实际余额 = 冻结金额 + 可用余额`；冻结金额本批只持久化和展示，暂不接消费。
+
+客户选择固定或自定义金额，查看后台配置的微信/支付宝静态收款码，付款后上传 JPG/PNG 截图形成待审核申请。平台在客户账户明细顶部审核或驳回，也可手工充值、扣款；每次变动写不可变账户流水。审核、账户更新、流水和幂等结果在 Finance 单事务内完成，文件内容仍归 File 服务。接口契约见 [客户资金账户 OpenAPI](openapi/finance-wallet-v1.yaml)。
+
 > 盘点日期：2026-08-10
 > 当前状态：F0/F1 已有 Finance 服务、数据库、权限、Admin/Client 页面和基础接口；订单与客户 11 个 P0 operation 的目标契约已冻结，本地实现验收按独立 G1-G4 证据矩阵均为 `PASS`；真实 MySQL、测试环境 HTTP 冒烟和领导页面验收仍需单独执行
 > 盘点范围：入库计费现状、平台后台财务原型、Admin/Client/Firstleg 当前实现
@@ -0,0 +1,129 @@
+openapi: 3.0.3
+info:
+  title: 客户资金账户与充值 API
+  version: 1.0.0
+  description: 静态收款码、付款截图申请、平台审核及手工充值扣款。当前币种固定 CNY，消费暂不接入。
+paths:
+  /api/client/finance/v1/account:
+    get:
+      summary: 查询当前客户资金账户
+      responses:
+        '200': { description: 成功 }
+  /api/client/finance/v1/account/ledger:
+    get:
+      summary: 查询当前客户账户流水
+      parameters:
+        - { name: page, in: query, schema: { type: integer, default: 1 } }
+        - { name: size, in: query, schema: { type: integer, default: 20 } }
+      responses:
+        '200': { description: 成功 }
+  /api/client/finance/v1/recharge-channels:
+    get:
+      summary: 查询静态收款码配置
+      responses:
+        '200': { description: 成功 }
+  /api/client/finance/v1/recharge-requests:
+    get:
+      summary: 查询当前客户充值申请，待审核优先
+      responses:
+        '200': { description: 成功 }
+    post:
+      summary: 上传付款截图并提交充值申请
+      parameters:
+        - $ref: '#/components/parameters/IdempotencyKey'
+      requestBody:
+        required: true
+        content:
+          multipart/form-data:
+            schema:
+              type: object
+              required: [amount, paymentMethod, file]
+              properties:
+                amount: { type: number, format: decimal, minimum: 0.01 }
+                paymentMethod: { type: string, enum: [WECHAT, ALIPAY] }
+                file: { type: string, format: binary, description: JPG 或 PNG }
+      responses:
+        '200': { description: 提交成功 }
+  /api/client/finance/v1/recharge-requests/{requestId}/voucher:
+    get:
+      summary: 预览当前客户充值凭证
+      parameters:
+        - $ref: '#/components/parameters/RequestId'
+      responses:
+        '200': { description: 图片内容 }
+  /api/platform/finance/v1/accounts/{customerId}/recharge-requests:
+    get:
+      summary: 查询客户充值申请，待审核优先
+      parameters:
+        - $ref: '#/components/parameters/CustomerId'
+      responses:
+        '200': { description: 成功 }
+  /api/platform/finance/v1/recharge-requests/{requestId}/review:
+    post:
+      summary: 审核或驳回充值申请
+      parameters:
+        - $ref: '#/components/parameters/RequestId'
+        - $ref: '#/components/parameters/IdempotencyKey'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/RechargeReviewRequest' }
+      responses:
+        '200': { description: 成功 }
+  /api/platform/finance/v1/recharge-requests/{requestId}/voucher:
+    get:
+      summary: 平台预览充值凭证
+      parameters:
+        - $ref: '#/components/parameters/RequestId'
+      responses:
+        '200': { description: 图片内容 }
+  /api/platform/finance/v1/accounts/{customerId}/adjustments:
+    post:
+      summary: 平台手工充值或扣款
+      parameters:
+        - $ref: '#/components/parameters/CustomerId'
+        - $ref: '#/components/parameters/IdempotencyKey'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/AccountAdjustmentRequest' }
+      responses:
+        '200': { description: 成功 }
+components:
+  parameters:
+    IdempotencyKey:
+      name: Idempotency-Key
+      in: header
+      required: true
+      schema: { type: string, maxLength: 128 }
+    CustomerId:
+      name: customerId
+      in: path
+      required: true
+      schema: { type: string, pattern: '^[1-9][0-9]*$' }
+    RequestId:
+      name: requestId
+      in: path
+      required: true
+      schema: { type: string, pattern: '^[1-9][0-9]*$' }
+  schemas:
+    RechargeReviewRequest:
+      type: object
+      required: [decision, expectedVersion]
+      properties:
+        decision: { type: string, enum: [APPROVE, REJECT] }
+        remark: { type: string, maxLength: 500, description: 驳回时必填 }
+        expectedVersion: { type: integer, minimum: 0 }
+    AccountAdjustmentRequest:
+      type: object
+      required: [type, amount, occurredDate, remark, expectedAccountVersion]
+      properties:
+        type: { type: string, enum: [RECHARGE, DEDUCTION] }
+        amount: { type: number, format: decimal, minimum: 0.01 }
+        occurredDate: { type: string, format: date }
+        paymentMethod: { type: string, maxLength: 32 }
+        referenceNo: { type: string, maxLength: 128 }
+        remark: { type: string, maxLength: 500 }
+        expectedAccountVersion: { type: integer, minimum: 0 }