docs(finance): register wallet recharge workflow

开发环境独立任务协作登记.md

@@ -25,20 +25,35 @@
 
 | task_id | project_id | 展示名称 | 长期职责 |
 |---|---|---|---|
-| `01a05b10-a5fc-7d51-8203-c671f3a823ad` | `6f874ec3-d3b2-49bd-8625-327f4d685f98` | 【开发总控】全流程开发 | 接收当前系统端到端全流程开发任务，冻结跨端契约和串行批次，协调本表专项完成实现、定向测试和构建；代码门禁通过后按本表授权操作开发数据库、通过 Jenkins 部署开发环境并执行真实 HTTP 验收；不操作测试或生产环境。 |
+| `01a06c0b-0515-7c60-b329-77342b54e666` | `6f874ec3-d3b2-49bd-8625-327f4d685f98` | 【开发总控】全流程开发 | 接收当前系统端到端全流程开发任务，冻结跨端契约和串行批次，协调本表专项完成实现、定向测试和构建；代码门禁通过后按本表授权操作开发数据库、通过 Jenkins 部署开发环境并执行真实 HTTP 验收；不操作测试或生产环境。 |
 
 长期专项：
 
 | task_id | parent_task_id | project_id | 展示名称 | 唯一长期职责 |
 |---|---|---|---|---|
-| `01a05b23-bfc6-7121-a6f2-7fc14ee456a3` | `01a05b10-a5fc-7d51-8203-c671f3a823ad` | `6f874ec3-d3b2-49bd-8625-327f4d685f98` | 【开发全流程前端】Admin | `apps/admin-web/` 全部平台管理页面、路由、API、权限消费、测试与构建；不修改 Client、PDA、后端或 SQL。 |
+| `01a05b23-bfc6-7121-a6f2-7fc14ee456a3` | `01a06c0b-0515-7c60-b329-77342b54e666` | `6f874ec3-d3b2-49bd-8625-327f4d685f98` | 【开发全流程前端】Admin | `apps/admin-web/` 全部平台管理页面、路由、API、权限消费、测试与构建；不修改 Client、PDA、后端或 SQL。 |
-| `01a05b23-c20f-7f52-8a26-543f1563f0f8` | `01a05b10-a5fc-7d51-8203-c671f3a823ad` | `6f874ec3-d3b2-49bd-8625-327f4d685f98` | 【开发全流程前端】Client | `apps/client-web/` 全部客户工作台页面、路由、API、权限消费、测试与构建；不修改 Admin、PDA、后端或 SQL。 |
+| `01a05b23-c20f-7f52-8a26-543f1563f0f8` | `01a06c0b-0515-7c60-b329-77342b54e666` | `6f874ec3-d3b2-49bd-8625-327f4d685f98` | 【开发全流程前端】Client | `apps/client-web/` 全部客户工作台页面、路由、API、权限消费、测试与构建；不修改 Admin、PDA、后端或 SQL。 |
-| `01a05b78-6e28-7460-babf-3a87331f6dd4` | `01a05b10-a5fc-7d51-8203-c671f3a823ad` | `6f874ec3-d3b2-49bd-8625-327f4d685f98` | 【开发全流程前端】海外PDA | `apps/pda-overseas-uniapp/` 全部海外仓现场作业、真实 API、恢复、扫码、幂等、测试与构建；派送仍由 Admin/Client 承载。 |
+| `01a05b78-6e28-7460-babf-3a87331f6dd4` | `01a06c0b-0515-7c60-b329-77342b54e666` | `6f874ec3-d3b2-49bd-8625-327f4d685f98` | 【开发全流程前端】海外PDA | `apps/pda-overseas-uniapp/` 全部海外仓现场作业、真实 API、恢复、扫码、幂等、测试与构建；派送仍由 Admin/Client 承载。 |
-| `01a05b23-c5ff-77c3-8f77-ceb4f4c40de2` | `01a05b10-a5fc-7d51-8203-c671f3a823ad` | `6f874ec3-d3b2-49bd-8625-327f4d685f98` | 【开发全流程后端】Lastleg | `baiyue-firstleg/lastleg-service/` 海外尾程、入仓、库存、换标、转运、废弃、排车、出库、派送、一件代发、异常、回访及海外业务的接口、OpenAPI、SQL、权限强制和测试。 |
+| `01a05b23-c5ff-77c3-8f77-ceb4f4c40de2` | `01a06c0b-0515-7c60-b329-77342b54e666` | `6f874ec3-d3b2-49bd-8625-327f4d685f98` | 【开发全流程后端】Lastleg | `baiyue-firstleg/lastleg-service/` 海外尾程、入仓、库存、换标、转运、废弃、排车、出库、派送、一件代发、异常、回访及海外业务的接口、OpenAPI、SQL、权限强制和测试。 |
-| `01a05b23-c7f8-72e0-bb3c-afbbf1c7f9e7` | `01a05b10-a5fc-7d51-8203-c671f3a823ad` | `6f874ec3-d3b2-49bd-8625-327f4d685f98` | 【开发全流程后端】IAM权限 | `baiyue-firstleg/iam/` 及必要 common-security 的平台/客户全流程权限资源、角色初始化、授权快照、OpenAPI、SQL 和测试；不修改 Lastleg 业务或前端。 |
+| `01a05b23-c7f8-72e0-bb3c-afbbf1c7f9e7` | `01a06c0b-0515-7c60-b329-77342b54e666` | `6f874ec3-d3b2-49bd-8625-327f4d685f98` | 【开发全流程后端】IAM权限 | `baiyue-firstleg/iam/` 及必要 common-security 的平台/客户全流程权限资源、角色初始化、授权快照、OpenAPI、SQL 和测试；不修改 Lastleg 业务或前端。 |
 
 验收与部署任务不常驻登记。只有用户明确要求开始验收、准备部署或执行验收时，才另行决定是否创建；开发任务不得代行。
 
+## 当前节点：一件代发客户资金账户（充值先行）
+
+本节点先跑通客户充值申请、平台审核、平台手工充值/扣款、余额与流水；微信/支付宝商户支付回调、订单消费、冻结/解冻及自动扣费后续另批处理。付款渠道仅展示已配置的静态收款二维码，客户提交金额、付款方式和付款截图后进入待审核。
+
+资金口径固定为 CNY：`可用余额 = 实际余额 - 冻结金额`。本批冻结金额持久化且初始为 0；充值审核通过或平台手工充值原子增加实际余额和可用余额，平台手工扣款原子减少实际余额和可用余额且不得超过可用余额。每次成功变动必须生成唯一业务单号和不可变流水；同一幂等键同载荷重试返回原结果，不同载荷冲突，重复审核不得重复入账。
+
+| 工作包 | 执行任务 | 写入范围 | 交付目标 | 依赖与集成边界 |
+|---|---|---|---|---|
+| `WALLET-BE-FINANCE` | 【开发总控】全流程开发 | `baiyue-firstleg/finance/`、Finance OpenAPI、模块 SQL 与统一增量 SQL、必要 Finance/File 内部客户端 | 新增客户资金账户、充值申请和资金流水主账；提供客户账户/流水/充值申请接口及平台账户列表/详情、待审充值、审核、手工充值/扣款接口；实现客户隔离、金额校验、权限、幂等、乐观并发与测试 | Finance 拥有余额和流水；付款截图经 Finance 调用 File 内部 `FINANCE_VOUCHER` 保存；不接支付回调、不接订单消费 |
+| `WALLET-FE-CLIENT` | 【开发全流程前端】Client | `apps/client-web/src/modules/finance/` 及该模块路由、导航和测试 | 新增客户资金账户页，显示实际/冻结/可用余额和流水；按原型完成金额选择、微信/支付宝静态二维码、付款截图上传、提交待审核及状态反馈 | 客户范围只取登录态；只调用 `/api/client/finance/v1/**`，无二维码配置时明确不可提交，不模拟支付成功 |
+| `WALLET-FE-ADMIN` | 【开发全流程前端】Admin | `apps/admin-web/src/modules/finance/` 及对应测试 | 将客户账户页收敛为三余额账户；详情中待审核客户充值置顶并提供审核，保留流水；列表/详情提供手工充值和手工扣款，操作列固定首列 | 只消费 Finance 正式 API；审核、充值、扣款分别受写权限控制；不在前端计算或兜底余额 |
+| `WALLET-BE-IAM` | 【开发全流程后端】IAM权限 | `baiyue-firstleg/iam/` 及必要权限初始化 SQL、OpenAPI 和测试 | 新增并初始化客户账户查看/充值申请和平台充值审核/账户调账权限，保持列表只读与写操作分离 | 企业负责人默认获得客户账户查看和充值申请权限；平台财务角色按现有初始化规则获得审核与调账权限，不修改 Finance 业务 |
+
+完成门禁：Finance、IAM 定向测试通过，Admin/Client 定向测试、类型检查和生产构建通过，跨端 DTO 与权限码一致；专项不提交、不推送、不部署、不操作数据库或真实 HTTP，由开发总控统一集成后再进入开发环境部署与验收。
+
 ## 当前 P0 全流程补齐批次
 
 本批只处理原型盘点确认的 P0，不混入 Admin 经营分析、销售管理、官网、小程序、独立 APP 或全量视觉验收。现有文档业务域改名属于总控在途改动，各专项必须保留，不得暂存、提交、覆盖或回滚。

财务管理/README.md

@@ -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 当前实现

财务管理/openapi/finance-wallet-v1.yaml

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