From 015d8f4b13a4ecedd3f34686300bc49138c18644 Mon Sep 17 00:00:00 2001 From: ouyangxq <775153912@qq.com> Date: Sat, 5 Sep 2026 08:34:40 +0800 Subject: [PATCH] docs(finance): register wallet recharge workflow --- 开发环境独立任务协作登记.md | 27 +++-- 财务管理/README.md | 6 ++ 财务管理/openapi/finance-wallet-v1.yaml | 129 ++++++++++++++++++++++++ 3 files changed, 156 insertions(+), 6 deletions(-) create mode 100644 财务管理/openapi/finance-wallet-v1.yaml diff --git a/开发环境独立任务协作登记.md b/开发环境独立任务协作登记.md index 8f4e40f..aeb9fc0 100644 --- a/开发环境独立任务协作登记.md +++ b/开发环境独立任务协作登记.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-c20f-7f52-8a26-543f1563f0f8` | `01a05b10-a5fc-7d51-8203-c671f3a823ad` | `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 承载。 | -| `01a05b23-c5ff-77c3-8f77-ceb4f4c40de2` | `01a05b10-a5fc-7d51-8203-c671f3a823ad` | `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-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` | `01a06c0b-0515-7c60-b329-77342b54e666` | `6f874ec3-d3b2-49bd-8625-327f4d685f98` | 【开发全流程前端】Client | `apps/client-web/` 全部客户工作台页面、路由、API、权限消费、测试与构建；不修改 Admin、PDA、后端或 SQL。 | +| `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` | `01a06c0b-0515-7c60-b329-77342b54e666` | `6f874ec3-d3b2-49bd-8625-327f4d685f98` | 【开发全流程后端】Lastleg | `baiyue-firstleg/lastleg-service/` 海外尾程、入仓、库存、换标、转运、废弃、排车、出库、派送、一件代发、异常、回访及海外业务的接口、OpenAPI、SQL、权限强制和测试。 | +| `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 或全量视觉验收。现有文档业务域改名属于总控在途改动，各专项必须保留，不得暂存、提交、覆盖或回滚。 diff --git a/财务管理/README.md b/财务管理/README.md index 8303e15..2684465 100644 --- a/财务管理/README.md +++ b/财务管理/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 当前实现 diff --git a/财务管理/openapi/finance-wallet-v1.yaml b/财务管理/openapi/finance-wallet-v1.yaml new file mode 100644 index 0000000..4ab8178 --- /dev/null +++ b/财务管理/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 }