Merge branch 'test' of http://8.163.30.128:10082/admin/docs into test
This commit is contained in:
+76
-6
@@ -25,20 +25,48 @@
|
||||
|
||||
| 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 业务或前端。 |
|
||||
| `01a079b6-b279-7aa3-ba2f-6556dbb44790` | `01a06c0b-0515-7c60-b329-77342b54e666` | `6f874ec3-d3b2-49bd-8625-327f4d685f98` | 【开发全流程后端】Firstleg头程履约 | `baiyue-firstleg/firstleg/` 国内头程入库、测量、计费、分柜、装柜、PDA 服务端门禁、出仓等 Firstleg 履约接口、DTO、Service、Mapper、模块 OpenAPI、模块 SQL 与测试；不修改 Order、IAM、前端或统一增量 SQL。 |
|
||||
| `01a079b6-b5fa-7fe3-82b5-59c4712a6d4c` | `01a06c0b-0515-7c60-b329-77342b54e666` | `6f874ec3-d3b2-49bd-8625-327f4d685f98` | 【开发全流程后端】Order订单域 | `baiyue-firstleg/order/` 头程订单主数据、统一订单查询聚合、订单状态与动作、内部 Firstleg 客户端 DTO、Order OpenAPI、模块 SQL 与测试；不修改 Firstleg、IAM、前端或统一增量 SQL。 |
|
||||
|
||||
验收与部署任务不常驻登记。只有用户明确要求开始验收、准备部署或执行验收时，才另行决定是否创建；开发任务不得代行。
|
||||
|
||||
## 当前节点：一件代发客户资金账户（充值先行）
|
||||
|
||||
本节点先跑通客户充值申请、平台审核、平台手工充值/扣款、余额与流水；微信/支付宝商户支付回调、订单消费、冻结/解冻及自动扣费后续另批处理。付款渠道仅展示已配置的静态收款二维码，客户提交金额、付款方式和付款截图后进入待审核。
|
||||
|
||||
资金口径固定为 CNY：`可用授信 = 授信额度 - 已用授信 - 冻结授信`，`总可用余额 = 实际余额 + 授信额度 - 已用授信 - 冻结金额`。冻结金额包含实际资金冻结与授信冻结；扣款先使用未冻结实际资金，再使用授信，充值先归还已用授信，再增加实际余额。初始授信由 Finance 环境配置统一设置，平台可按客户调整。每次成功变动必须生成唯一业务单号和不可变流水；同一幂等键同载荷重试返回原结果，不同载荷冲突，重复审核不得重复入账。
|
||||
|
||||
| 工作包 | 执行任务 | 写入范围 | 交付目标 | 依赖与集成边界 |
|
||||
|---|---|---|---|---|
|
||||
| `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，由开发总控统一集成后再进入开发环境部署与验收。
|
||||
|
||||
### 资金账户节点结果（2026-09-05）
|
||||
|
||||
- Backend 已在 `dev` 完成 Finance 主账、充值申请、不可变流水、File 凭证代理、客户隔离、幂等、乐观并发及 IAM 四项独立权限，最终提交为 `37183ac2`；Finance 全量 162 项、最终运行时兜底行为 4 项及 IAM 定向 18 项测试通过。开发统一增量 SQL 执行结果为 `PASS`，确认 3 张资金表、45 个字段、4 项权限资源和 4 项默认授权，未重建或删除数据库。
|
||||
- Client 提交 `e814902`、`719a642`，完成三余额、流水、充值申请和金额/渠道/截图提交弹窗；全量 267 项测试及生产构建通过。Admin 提交 `68fca1b`、`fb4cab6`，完成客户账户列表/详情、待审置顶、凭证预览、审核与手工充值/扣款，并消除详情初始化重复请求；全量 1691 项测试、最终页面定向 17 项及生产构建通过。
|
||||
- 开发部署最终结果：Backend Jenkins `#171`（下游 Finance `#26`）、Admin `#45`、Client `#45` 均为 `SUCCESS`；Admin、Client 与国内 API 健康检查均返回 HTTP 200。开发环境以 `DEPLOY_ENV=development` 启用明确标注“开发示例、不可付款”的静态二维码，其他部署环境保持默认关闭。
|
||||
- 真实 HTTP 验收使用客户登录态提交 PNG 付款截图：创建返回 `PENDING`，相同幂等键重放返回原申请，不同载荷返回 `FIN-IDEMPOTENCY-CONFLICT`；凭证下载为 HTTP 200 `image/png`；审核后余额从 ¥15 增至 ¥115，重复审核返回 `FIN-WALLET-409`；另一申请驳回后余额不变。手工充值 ¥25、扣款 ¥10 成功并生成流水，超额扣款返回 `FIN-WALLET-INSUFFICIENT`；最终 `实际余额 ¥115 = 冻结金额 ¥0 + 可用余额 ¥115`。
|
||||
- 已按 `1920×1080`、浏览器缩放 `100%` 验收 Client 资金账户、流水、充值记录与充值弹窗，以及 Admin 客户筛选、账户详情、充值记录、凭证和手工充值/扣款表单。Client 资金页的账户、流水、申请、渠道接口各请求 1 次；Admin 去重修复后详情流水与充值申请接口各请求 1 次，未发现遮挡或横向溢出。
|
||||
- 授信与冻结结算扩展已完成：Backend 提交 `ba4407eb`、权限断言修复 `ede63fac`，Admin 提交 `92b24cc`，Client 提交 `46a91fb`，财务契约提交 `08a80e7`。Finance 提供服务令牌保护的账户查询、冻结、结算和释放内部接口；初始化授信配置为 `FINANCE_WALLET_DEFAULT_CREDIT_LIMIT`，默认 `0.00`。
|
||||
- 最新开发部署为 Backend Jenkins `#173`（下游 Finance `#29`）、Admin `#46`、Client `#47`，均为 `SUCCESS`。国内统一增量从首行完整执行并取得 `migration_status=PASS`；真实 HTTP 授信回归 `13/13` 通过，验证授信调整、现金优先扣款、额度下限门禁、充值优先归还授信及最终余额恢复。验收后账户为实际余额 `¥115.00`、冻结金额 `¥0.00`、授信额度/已用授信/冻结授信均为 `¥0.00`、总可用余额 `¥115.00`。Client 提交 `85871d5` 将账户接口返回前的六项金额从误导性的 `¥0.00` 收敛为 `¥—`；专项测试、类型检查和生产构建通过。重新按 `1920×1080` 验收后六张余额卡均在视口内，账户、流水、充值申请、充值渠道接口各请求 1 次，Admin/Client 控制台无错误。
|
||||
- 资金账户扩展测试提交 `8400636d`、`f62283fb`：补充被冻结现金不可扣用、充值不释放冻结授信、授信占用与冻结金额非法状态、默认授信配置失败关闭，以及内部服务令牌拒绝和冻结/结算/释放请求转发共 9 项场景；Finance 全量测试更新为 `174/174` 通过。本批仅新增测试，不修改运行时代码、数据库或部署产物。
|
||||
|
||||
## 当前 P0 全流程补齐批次
|
||||
|
||||
本批只处理原型盘点确认的 P0，不混入 Admin 经营分析、销售管理、官网、小程序、独立 APP 或全量视觉验收。现有文档业务域改名属于总控在途改动，各专项必须保留，不得暂存、提交、覆盖或回滚。
|
||||
@@ -82,3 +110,45 @@
|
||||
- 最新开发环境真实 HTTP 全流程报告 `baiyue-firstleg/reports/admin-test-env-acceptance-20260904091729.json` 结果为 `PASS`：`8082/8082` 断言通过、`112` 次模块运行、`92` 个唯一模块、`4937` 个唯一请求，`failed=0`、`skippedModules=0`、`deploymentBlockers=0`。17 项覆盖说明均为非阻断项：设备能力 1 项、非版本化文档契约 1 项、外部第三方 9 项、无法通过公开接口稳定构造的 fixture 6 项。
|
||||
- 内置浏览器复验覆盖 Client 海外贴标、仓储转运、货物废弃、退货换标的列表、详情或新建表单，以及 Admin 海外尾程、入库、排车、出库、派送、换标、托盘、库存、进销存、异常和客户回访列表；页面真实 API 加载成功且无控制台错误。复验发现并修复进销存页面暴露内部 DTO 说明、英文库存变动代码和操作人内部占位的问题，Admin 提交 `39ade43` 已在提交前合并最新 `origin/release/test` 并推送；`233/233` 个测试文件、`1685/1685` 条测试、类型检查和生产构建通过，开发 Jenkins `admin-web-dev #43` 为 `SUCCESS`，`/healthz` 返回 HTTP 200，部署后页面显示中文业务类型且内部文案不再出现。
|
||||
- 海外 PDA H5 再次使用开发网关验证登录、工作台、拆柜收货、托盘、盘点、移库、换标、库存/库位/托盘查询、排车、出库、历史、个人中心及“退出确认→退出→重新登录”；全部正式入口可加载，无权限或请求错误，托盘管理页未回归“PDA 广播扫码与 H5 人工输入均可使用”。本次浏览器工具固定视口不替代已登记的 `390×844` 截图证据；Android 广播扫码、相机与弱网恢复仍保留为设备验收项。
|
||||
|
||||
|
||||
## 当前节点：海外业务资金与托盘费用闭环（2026-09-05）
|
||||
|
||||
本节点按当前对话冻结以下口径：海外采购订单号为客户名称拼音首字母（最多8位大写）+北京时间日期YYYYMMDD+客户当日4位序号；采购签收文件与费用凭证归属采购订单，费用逐条冻结，整单实收入库完成后逐条结算。换标创建时按CNY费用冻结，资金冻结成功后才允许开始作业，完成结算，驳回或取消释放。跨区域资金操作只经 WalletCommandRequestedV1 / WalletCommandCompletedV1 的双向 Outbox/Inbox 事件，不由海外服务直连国内 Finance。
|
||||
|
||||
国内托盘统计以活动库位预占或占用事实判定“占用”，其余有效托盘为“闲置”；海外托盘使用 IDLE/OCCUPIED/SCRAPPED 权威状态。拆柜打托成本按最终实物托盘单价合计，以同一来源柜各客户实际收货体积分摊，四舍五入到分，最后一条吸收尾差并保证总额守恒。
|
||||
|
||||
| 工作包 | 写入范围 | 交付目标 |
|
||||
|---|---|---|
|
||||
| `OVERSEAS-WALLET-EVENTS` | common-event-contract、event-bridge-service、finance、lastleg-service及两区SQL | 双向资金指令、结果事件与幂等可靠投递 |
|
||||
| `PROCUREMENT-RELABEL-FUNDING` | Lastleg/File/Admin及必要Client | 采购编号、签收文件、费用凭证及逐条资金状态；换标费用冻结/结算/释放 |
|
||||
| `PALLET-SUMMARY` | 国内Warehouse、海外Warehouse、Admin | 总数、闲置、占用统计及筛选一致性 |
|
||||
| `DESTUFF-PALLET-COST` | Lastleg、Finance事件、Admin/PDA必要展示 | 按实托数计成本并按客户实收体积分摊，金额守恒 |
|
||||
|
||||
完成门禁：受影响后端测试、Mapper和SQL合同、Admin/Client测试及构建通过；随后执行开发数据库增量、Jenkins开发部署、真实HTTP，以及Admin/Client 1920×1080和涉及PDA 390×848验收并核对请求次数。
|
||||
|
||||
### 海外业务资金与托盘费用节点结果（2026-09-05）
|
||||
|
||||
- Backend 已完成并推送 `5fbd2bbd`、`718a54ec`、`3c535731`、`af785241`、`81917423`、`64bf5aa0`：落地双向钱包事件、Finance 指令消费与结果定时投递、海外采购编号/文件/费用冻结结算、换标费用冻结结算释放、国内外托盘统计及拆柜打托成本分摊。修复了跨区消费地址未绑定、两端事件哈希字段长度不足和 Finance 结果 Outbox 未启用调度三个真实联调问题。Finance 177 项、Lastleg 559 项（2 项跳过）、海外 Warehouse 55 项、Event Bridge 47 项及受影响合同测试通过；Mapper 263 项、AGENTS 876 项与国内/海外统一增量 SQL 合同通过。4 项既有 OpenAPI 合同失败与本节点无关，未作为本节点通过项记录。
|
||||
- Admin 已完成并推送 `ccf16b8`、`fedfdd2`、`d310f37`，补齐采购详情文件/费用、托盘汇总和换标资金状态，并修复海外托盘首屏不加载汇总及采购操作记录暴露内部操作人 ID。Client 已完成并推送 `b13295f`，提交采购客户身份与换标费用。Admin 全量 1692 项、Client 全量 267 项测试及两端类型检查、生产构建通过。
|
||||
- 开发数据库国内与海外统一增量均从首行执行并返回 `PASS`；`fin_wallet_command_inbox.payload_hash` 与 `ll_wallet_event_inbox.payload_hash` 均确认为 `varchar(71)`。未重建、清空或删除数据库。
|
||||
- 开发部署完成：Backend 父任务 `#176`、Event Bridge `#34`、Finance `#35`、Lastleg `#68`、Admin `#49`、Client `#48` 及本批其他受影响服务均成功，Finance 与 Lastleg 容器使用对应最终提交并保持健康。两次父任务因外部镜像仓库登录失败显示 `UNSTABLE`，随后改用已配置的内部镜像仓库直接部署受影响服务并取得 `SUCCESS`，未修改密钥或环境配置。
|
||||
- 真实 HTTP 与数据库闭环通过：采购单 `ICS202609050001` 按客户拼音首字母规则生成，签收文件、付款凭证与费用 `PF2096250732063727618` 已关联；费用 `¥0.01` 从冻结进入结算。换标单 `RL-ONT-20260905-860034` 创建后冻结 `¥0.01`，完成作业后结算。Finance 四条钱包指令均为 `SUCCEEDED`，四条结果事件均为 `PUBLISHED`，两笔 Hold 均为 `SETTLED`；账户最终实际余额 `¥114.98`、冻结金额 `¥0.00`、总可用余额 `¥114.98`，流水 `AC-260905-0030` 至 `AC-260905-0033` 完整记录两组冻结与消费。
|
||||
- 国内托盘真实汇总为总数 `510`、闲置 `44`、占用 `466`；海外托盘为总数 `250`、闲置 `100`、占用 `98`、报废 `52`。Admin、Client、国内 API、海外 API 健康检查均为 HTTP 200。
|
||||
- 已按 `1920×1080`、浏览器缩放 `100%` 验收 Admin 采购列表/详情、国内与海外托盘、换标列表，以及 Client 采购、贴标申请和资金账户；采购和托盘页面的业务请求按一次列表、一次汇总及必要字典/权限请求发出，未发现重复业务请求。Client 最终显示 `¥114.98 / ¥0.00 / ¥114.98`，换标单置于首行并显示“已完成”。本批未修改或部署国内、海外 PDA 前端，因此不触发 `390×848` 页面门禁；拆柜完成后的费用触发点由 Lastleg 服务测试与开发部署覆盖。
|
||||
- 2026-09-06 已把本节点纳入默认全量真实 HTTP 脚本：自动创建并登录本轮客户，初始化授信、人工充值，完成采购审核、签收/凭证上传、费用冻结结算，两笔收费换标的结算与释放，核对 Client 账户/账本、国内外托盘汇总、拆柜打托分摊和跨区 Finance 金额守恒。最终报告 `admin-test-env-acceptance-20260906031556.json` 为 `3229/3229` 条断言通过、48 个唯一模块、2001 个唯一真实请求、0 跳过、0 失败；脚本全量离线合同 `621/621` 通过。仅 Android 广播扫码、相机、弱网恢复及第三方验证码页面保留人工/设备验收。
|
||||
- 自动化回归发现并修复拆柜打托费用任务只扫描最旧 50 个已完成柜、被历史零价托盘长期阻塞的问题，现按最新完成时间优先处理；Lastleg 560 项测试通过（2 项跳过），开发 Jenkins `backend-java-dev #179` 与 `baiyue-firstleg-dev-lastleg-service #69` 均为 `SUCCESS`。Backend 最终提交为 `20b3074c`、`0fbab098`、`54af43a9`，均已推送 `dev`。
|
||||
|
||||
## 当前节点：头程订单扣货闭环（2026-09-07）
|
||||
|
||||
本节点按当前对话冻结以下口径：扣货对象为 Firstleg 入库单，不改变 Order 主状态；平台人员可在尚未发生实物拣货前扣货或解除扣货，两个动作均要求原因、幂等键和期望版本，并在同一事务写当前快照与不可变历史。动作可选上传一份关联凭证，文件必须按当前客户、入库单和 `INBOUND_HOLD_EVIDENCE` 精确归属，只有已经进入不可变历史的凭证允许下载。扣货后必须阻断智能排柜候选与人工分配、预装确认、PDA 任务创建或启动、PDA 拣货、装柜模型桥接、PDA 资源结算、异步完成收口和国内出仓；尚未生成入库单、已发生实物拣货、已装柜或已派送的订单不得手工扣货。统一订单字段直接收敛为 `holdFlag/currentHoldReason`，不保留 `holdCargo/holdReason` 别名。
|
||||
|
||||
| 工作包 | 执行任务 | 写入范围 | 交付目标 | 依赖与集成边界 |
|
||||
|---|---|---|---|---|
|
||||
| `HOLD-BE-FIRSTLEG` | 【开发全流程后端】Firstleg头程履约 | `baiyue-firstleg/firstleg/` 的扣货命令、历史查询、履约门禁、模块 OpenAPI、模块 SQL 与测试 | 提供扣货/解除扣货接口，落实客户归属、独立权限、幂等、乐观并发、不可变历史和实物作业前置门禁；所有下游履约写入口按服务端权威扣货状态失败关闭 | 先冻结平台接口及内部统一订单 DTO 字段并通知 Order、Admin；不修改 Order、IAM、前端或统一增量 SQL |
|
||||
| `HOLD-BE-ORDER` | 【开发全流程后端】Order订单域 | `baiyue-firstleg/order/` 的 Firstleg 内部客户端 DTO、统一订单响应、Order OpenAPI 与测试 | 将 Firstleg `holdFlag/currentHoldReason` 透传到统一订单列表/详情，删除未落地的旧字段语义，不复制扣货状态机 | 只消费 Firstleg 冻结 DTO；不提供扣货写接口，不修改 Firstleg、IAM、前端或统一增量 SQL |
|
||||
| `HOLD-FE-ADMIN` | 【开发全流程前端】Admin | `apps/admin-web/src/modules/unified-orders/`、必要 `modules/inbounds/` API 暴露与对应测试 | 在订单详情“其他”页签增加独立扣货控制、状态标识、原因/凭证弹窗和历史展示；尚未生成入库单或无权限时只读；成功后刷新详情与列表 | 快递信息、内部备注、箱子计费不并入扣货统一提交；只消费正式 Firstleg/Order API，不在前端推导可扣货状态 |
|
||||
| `HOLD-BE-IAM` | 【开发全流程后端】IAM权限 | `baiyue-firstleg/iam/` 的权限资源、默认角色授权、模块 OpenAPI、模块 SQL 与测试 | 新增 `platform:firstleg:inbound:hold` 独立写权限并按现有平台管理员规则初始化；保持查看权限与扣货写权限分离 | 不修改 Firstleg、Order、统一增量 SQL或前端；权限码冻结后通知 Firstleg、Admin |
|
||||
| `HOLD-BE-FILE` | 【开发总控】全流程开发 | `baiyue-firstleg/file/` 的通用业务文件类别与测试、Firstleg 专用文件客户端和归属校验 | 提供客户作用域的扣货凭证上传、精确引用校验和已关联凭证下载，拒绝跨客户、跨入库单及未进入历史的文件 | File 只保存文件与精确归属，不读取 Firstleg 业务表；凭证可见性和不可变历史仍由 Firstleg 决定 |
|
||||
|
||||
完成门禁：Firstleg、Order、IAM 定向测试通过，Mapper 与模块 SQL/OpenAPI 合同通过，Admin 定向测试、类型检查和生产构建通过；开发总控统一维护业务契约与统一增量 SQL、执行跨端 DTO/权限核对和 Git 集成。当前各仓库在本批下发前由开发总控恢复到 `dev`，按登记门禁获取并合并最新测试分支；专项不自行切换分支，不提交、不推送、不部署、不操作数据库或真实 HTTP。本批代码门禁完成后再单独决定开发数据库、Jenkins 开发部署与真实 HTTP/1920×1080 人工验收。
|
||||
|
||||
@@ -45,6 +45,13 @@
|
||||
- 重复提交同一操作必须保持幂等，不能伪造新的状态历史或绕过前置门禁。
|
||||
- `LOADED` 是国内出仓终点；本版本不增加“派送中”，也不允许国内运营人员手工推进 `DELIVERED`。
|
||||
|
||||
### 入库单扣货门禁
|
||||
|
||||
- 扣货是 Firstleg 入库单的独立履约控制，不新增或改变 Order 六个主状态。统一订单列表与详情只透传 `holdFlag/currentHoldReason`；尚未生成入库单时两字段为 `null`，不得使用 `holdCargo/holdReason` 兼容别名。
|
||||
- 平台人员只能在尚未发生实物拣货、装柜或出仓事实时扣货或解除扣货。两个动作都要求原因、`Idempotency-Key` 和当前入库单 `expectedVersion`；成功后入库版本递增，并在同一事务更新当前快照、写入不可变 `HOLD/RELEASE` 历史。
|
||||
- 扣货状态为真时，服务端必须从智能排柜候选排除该入库单，并阻断人工分配或调整、同柜组分配、预装确认、PDA 任务创建或启动、PDA 拣货和工作托盘、装柜证据与完成、国内出仓。各入口直接读取 Firstleg 权威状态并失败关闭，前端不得自行推导资格。
|
||||
- 查询扣货快照和历史使用 `platform:firstleg:inbound:list`；扣货与解除使用独立写权限 `platform:firstleg:inbound:hold`。查看权限不会自动获得写权限，默认只授予平台管理员。
|
||||
|
||||
## 四、客户确认和差异
|
||||
|
||||
客户确认、差异沟通和客服补充说明均为非阻断操作：
|
||||
|
||||
@@ -1,5 +1,11 @@
|
||||
# 财务管理闭环盘点与范围建议
|
||||
|
||||
## 当前确认：一件代发客户资金账户（2026-09-05）
|
||||
|
||||
当前对话已将资金账户作为一件代发的前置节点重新纳入范围，并覆盖本文后续历史章节中“钱包不做”的旧结论。首批固定为 CNY。账户分别保存实际余额、冻结金额、授信额度、已用授信和冻结授信；`总可用余额 = 实际余额 + 授信额度 - 已用授信 - 冻结金额`，`可用授信 = 授信额度 - 已用授信 - 冻结授信`。扣款及业务冻结先使用未冻结的实际资金，再使用授信；充值先归还已用授信，剩余金额增加实际余额。
|
||||
|
||||
客户选择固定或自定义金额，查看后台配置的微信/支付宝静态收款码，付款后上传 JPG/PNG 截图形成待审核申请。平台在客户账户明细顶部审核或驳回，也可手工充值、扣款和设置客户授信额度；每次变动写不可变账户流水。新账户授信额度读取 `baiyue.finance.wallet.default-credit-limit`，默认 `0.00`，平台设置的客户额度随后独立持久化。Finance 还提供仅服务令牌可访问、按业务类型和业务单号幂等的冻结、结算和释放接口，供一件代发等模块接入。审核、账户更新、流水、冻结记录和幂等结果在 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,254 @@
|
||||
openapi: 3.0.3
|
||||
info:
|
||||
title: 客户资金账户、授信与充值 API
|
||||
version: 1.1.0
|
||||
description: |
|
||||
CNY 资金账户支持静态收款码、付款截图申请、平台审核、手工充扣、授信额度及业务冻结/结算/释放。
|
||||
总可用余额 = 实际余额 + 授信额度 - 已用授信 - 冻结金额；业务扣款先使用未冻结的实际资金，再使用授信。
|
||||
充值先归还已用授信，剩余部分增加实际余额。新账户授信额度由
|
||||
`baiyue.finance.wallet.default-credit-limit` 初始化，默认 `0.00`，平台可按客户调整。
|
||||
paths:
|
||||
/api/client/finance/v1/account:
|
||||
get:
|
||||
summary: 查询当前客户资金账户
|
||||
responses:
|
||||
'200':
|
||||
description: 成功
|
||||
content:
|
||||
application/json:
|
||||
schema: { $ref: '#/components/schemas/WalletAccountEnvelope' }
|
||||
/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: 成功 }
|
||||
/api/platform/finance/v1/accounts/{customerId}/credit-limit:
|
||||
put:
|
||||
summary: 设置客户授信额度
|
||||
parameters:
|
||||
- $ref: '#/components/parameters/CustomerId'
|
||||
- $ref: '#/components/parameters/IdempotencyKey'
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema: { $ref: '#/components/schemas/CreditLimitRequest' }
|
||||
responses:
|
||||
'200': { description: 成功并生成授信调整流水 }
|
||||
/internal/finance/v1/wallet/accounts/{customerId}:
|
||||
get:
|
||||
summary: 业务模块查询客户资金账户
|
||||
parameters:
|
||||
- $ref: '#/components/parameters/InternalServiceToken'
|
||||
- $ref: '#/components/parameters/CustomerId'
|
||||
responses:
|
||||
'200': { description: 成功 }
|
||||
/internal/finance/v1/wallet/accounts/{customerId}/holds:
|
||||
post:
|
||||
summary: 按业务单冻结资金，先冻结实际资金再冻结授信
|
||||
parameters:
|
||||
- $ref: '#/components/parameters/InternalServiceToken'
|
||||
- $ref: '#/components/parameters/IdempotencyKey'
|
||||
- $ref: '#/components/parameters/CustomerId'
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema: { $ref: '#/components/schemas/WalletFreezeRequest' }
|
||||
responses:
|
||||
'200': { description: 成功；同一客户、业务类型和业务单号只允许一条冻结记录 }
|
||||
/internal/finance/v1/wallet/accounts/{customerId}/holds/{businessType}/{businessNo}/settle:
|
||||
post:
|
||||
summary: 结算已冻结资金
|
||||
parameters:
|
||||
- $ref: '#/components/parameters/InternalServiceToken'
|
||||
- $ref: '#/components/parameters/IdempotencyKey'
|
||||
- $ref: '#/components/parameters/CustomerId'
|
||||
- $ref: '#/components/parameters/BusinessType'
|
||||
- $ref: '#/components/parameters/BusinessNo'
|
||||
requestBody:
|
||||
content:
|
||||
application/json:
|
||||
schema: { $ref: '#/components/schemas/WalletHoldActionRequest' }
|
||||
responses:
|
||||
'200': { description: 成功；实际冻结转为实际扣减，授信冻结转为已用授信 }
|
||||
/internal/finance/v1/wallet/accounts/{customerId}/holds/{businessType}/{businessNo}/release:
|
||||
post:
|
||||
summary: 释放已冻结资金
|
||||
parameters:
|
||||
- $ref: '#/components/parameters/InternalServiceToken'
|
||||
- $ref: '#/components/parameters/IdempotencyKey'
|
||||
- $ref: '#/components/parameters/CustomerId'
|
||||
- $ref: '#/components/parameters/BusinessType'
|
||||
- $ref: '#/components/parameters/BusinessNo'
|
||||
requestBody:
|
||||
content:
|
||||
application/json:
|
||||
schema: { $ref: '#/components/schemas/WalletHoldActionRequest' }
|
||||
responses:
|
||||
'200': { description: 成功；实际资金和授信恢复为可用 }
|
||||
components:
|
||||
parameters:
|
||||
IdempotencyKey:
|
||||
name: Idempotency-Key
|
||||
in: header
|
||||
required: true
|
||||
schema: { type: string, maxLength: 128 }
|
||||
InternalServiceToken:
|
||||
name: X-Internal-Service-Token
|
||||
in: header
|
||||
required: true
|
||||
schema: { type: string, writeOnly: true }
|
||||
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]*$' }
|
||||
BusinessType:
|
||||
name: businessType
|
||||
in: path
|
||||
required: true
|
||||
schema: { type: string, pattern: '^[A-Z][A-Z0-9_]{1,31}$' }
|
||||
BusinessNo:
|
||||
name: businessNo
|
||||
in: path
|
||||
required: true
|
||||
schema: { type: string, minLength: 1, maxLength: 128 }
|
||||
schemas:
|
||||
WalletAccountEnvelope:
|
||||
type: object
|
||||
properties:
|
||||
data: { $ref: '#/components/schemas/WalletAccount' }
|
||||
WalletAccount:
|
||||
type: object
|
||||
required: [currencyCode, actualBalance, frozenBalance, availableBalance, creditLimit, creditUsed, creditFrozen, availableCredit, version]
|
||||
properties:
|
||||
currencyCode: { type: string, enum: [CNY] }
|
||||
actualBalance: { type: number, format: decimal, minimum: 0 }
|
||||
frozenBalance: { type: number, format: decimal, minimum: 0, description: 实际资金冻结与授信冻结合计 }
|
||||
availableBalance: { type: number, format: decimal, minimum: 0, description: 实际可用资金与可用授信合计 }
|
||||
creditLimit: { type: number, format: decimal, minimum: 0 }
|
||||
creditUsed: { type: number, format: decimal, minimum: 0 }
|
||||
creditFrozen: { type: number, format: decimal, minimum: 0 }
|
||||
availableCredit: { type: number, format: decimal, minimum: 0 }
|
||||
version: { type: integer, minimum: 0 }
|
||||
updatedAt: { type: string, format: date-time, nullable: true }
|
||||
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 }
|
||||
CreditLimitRequest:
|
||||
type: object
|
||||
required: [creditLimit, expectedAccountVersion]
|
||||
properties:
|
||||
creditLimit: { type: number, format: decimal, minimum: 0 }
|
||||
remark: { type: string, maxLength: 500 }
|
||||
expectedAccountVersion: { type: integer, minimum: 0 }
|
||||
WalletFreezeRequest:
|
||||
type: object
|
||||
required: [amount, businessType, businessNo]
|
||||
properties:
|
||||
amount: { type: number, format: decimal, minimum: 0.01 }
|
||||
businessType: { type: string, minLength: 1, maxLength: 64 }
|
||||
businessNo: { type: string, minLength: 1, maxLength: 128 }
|
||||
remark: { type: string, maxLength: 500 }
|
||||
WalletHoldActionRequest:
|
||||
type: object
|
||||
properties:
|
||||
remark: { type: string, maxLength: 500 }
|
||||
Reference in New Issue
Block a user