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
@@ -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 }