html/docs
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

优化

Browse Source
This commit is contained in:
ouyangxq
2026-08-11 18:17:02 +08:00
parent 767ffe8544
commit 60d2f8e097
8 changed files with 407 additions and 89 deletions
Download Patch File Download Diff File Expand all files Collapse all files
财务管理/财务一期五页产品与接口验收契约.md
+13 -16
View File
@@ -1,11 +1,12 @@
# 财务一期五页产品与接口验收契约
> 日期：2026-08-11
> 状态：产品范围已确认；Finance 来源链与五页查询契约已实现并验证，剩余 11 个目标 operation、Admin 五页接入及跨服务 HTTP 冒烟待完成
> 状态：产品范围已确认；Finance 来源链与部分五页查询契约已实现并验证；当前 11 个 `NOT_IMPLEMENTED` operation 全部为一期 P0 阻断，禁止排到后续
> 领导验收范围：客户账户、客户应收应付、客户对账单、结算单应收、结算单应付
> 原型依据：`docs/悦/货代SAAS平台后台/货代SaaS平台原型.html`
> 目标 OpenAPI：`openapi/finance-phase1-five-pages-v1.yaml`；当前人工接口继续参考 `openapi/finance-f1-manual-v1.yaml`。
> 11 个 P0 操作的 DTO、状态机、权限、幂等、错误码、隔离和验收用例以 `财务一期P0操作契约与验收用例.md` 为准。
## 1. 一期范围结论
@@ -47,8 +48,8 @@
| 客户账户 | 汇总卡、客户列表、账户详情、流水详情；客户名称/编号、账户状态、余额条件、流水类型和日期 | 客户基本信息、客户编号、联系人、电话、未收余额、待出账金额、本期已收金额、应付余额、账户状态、最后变动时间；流水号、时间、业务类型、关联单据、应收/应付变动、变动后未收余额、操作人、备注 | 详情、查询、重置、导出；**无充值、扣款或余额调整** | 客户主体正常/停用只影响访问和新业务；所有金额可由来源、单据和收付款逐笔追溯，禁止直接写余额 |
| 客户应收应付 | 工具栏、组合查询、选中汇总、费用列表、费用详情、审核进度、关联业务、操作记录 | 客户、费用单号、是否已生成对账单、参与结算、审核状态、应收/应付、入仓码/柜次号、业务状态、费用类型、金额、业务发生日、来源类型、来源版本 | 详情、审核通过、审核拒绝、编辑未审核人工项、参与结算/禁止结算、按截止时间或勾选生成；已发布来源不可删除，只能作废/调整 | `PENDING -> APPROVED/REJECTED`；只有 `APPROVED + INCLUDED + AVAILABLE + CNY` 可生成；同一来源版本不能重复进入有效单据 |
| 客户对账单 | 查询区、主表、账单明细、支付历史；审核状态、账单编号、客户、柜次、结算起止日、是否结清、创建日期、最后收款时间 | 对账单号、客户、期间、账期、CNY、总应收、已收、未收、最后收款时间、是否结清、备注、创建/更新人时间；明细保留入仓单/柜次、业务日、计费量、费用项、金额、来源版本 | 生成草稿、详情、导出、审核通过、审核拒绝、作废；不提供发票和汇率操作 | `DRAFT -> PENDING_REVIEW -> APPROVED/REJECTED/VOIDED`；审核通过后来源冻结，调整必须留 revision；支付历史只读展示有效收款 |
| 结算单应收 | 汇总卡、筛选、列表、详情、费用明细、收款记录；收款状态、客户、结算单号 | 结算单号、客户、CNY、应收、已收、余额、关联对账单、业务期间、生成日、到期日、收款状态、制单人、状态 | 从审核通过对账单生成、详情、部分收款、导出、作废/重开；不保留高级查询假入口 | `DRAFT -> ISSUED -> PARTIALLY_PAID -> PAID`，未收款可作废；出账后冻结，调整保留 revision；收款人工表单和图片沿用 F1 契约 |
| 结算单应付 | 汇总卡、供应商筛选、列表、详情、费用明细、付款记录 | 结算单号、供应商、费用类型、CNY、应付、已付、余额、来源期间、生成日、到期日、付款状态、制单人、审核人、状态 | 从审核通过且参与结算的应付来源生成、详情、审核、部分付款、导出、作废/重开；删除利润分析和利润审批按钮 | `DRAFT -> PENDING_REVIEW -> ISSUED -> PARTIALLY_PAID -> PAID`，拒绝/作废保留记录；付款为人工登记和凭证图片 |
| 结算单应收 | 汇总卡、筛选、列表、详情、费用明细、收款记录；收款状态、客户、结算单号 | 结算单号、客户、CNY、应收、已收、余额、关联对账单、业务期间、生成日、到期日、收款状态、制单人、状态 | 从已出账对账单生成、详情、部分收款、导出、作废/重开；不保留高级查询假入口 | 生成后直接 `ISSUED -> PARTIALLY_PAID -> PAID`；来源已在对账单阶段审核，结算单不重复增加假审批；未收款可作废，调整保留 revision |
| 结算单应付 | 汇总卡、供应商筛选、列表、详情、费用明细、付款记录 | 结算单号、供应商、费用类型、CNY、应付、已付、余额、来源期间、生成日、到期日、付款状态、制单人、状态 | 从审核通过且参与结算的应付来源生成、详情、部分付款、导出、作废/重开；删除利润分析和利润审批按钮 | 生成后直接 `ISSUED -> PARTIALLY_PAID -> PAID`；不重复增加结算单审批；作废/重开保留 revision，付款为人工登记和凭证图片 |
表格“操作”列必须位于第一列。原型中未形成真实闭环的“新增、生成账单、高级查询、快捷导出”等按钮，只有在对应接口和权限完成后才显示。
@@ -57,12 +58,12 @@
| 页面 | 当前仓库事实 | 一期目标 | 差异等级 |
|---|---|---|---|
| 客户账户 | 后端已新增 `/customer-accounts/{customerId}` 和固定读 DTO；无列表接口 | 派生财务往来汇总、详情和流水，无任何充值/余额写入口 | IMPLEMENTED（单客户查询）；列表/筛选仍缺，Finance DTO 测试通过 |
| 客户应收应付 | `/fee-pool` 固定 DTO、Firstleg 事件/快照和 `fin_fee_source` 写入均已实现并验证 | 真实入库/柜子费用来源池，支持审核、参与结算、详情和生成对账单 | 查询与来源入池已实现；详情/页面操作仍是 P0/P1 |
| 客户应收应付 | `/fee-pool` 固定 DTO、Firstleg 事件/快照和 `fin_fee_source` 写入均已实现并验证 | 真实入库/柜子费用来源池，支持审核、参与结算、详情和生成对账单 | 查询与来源入池已实现；详情、审核、参与结算均为一期 P0 |
| 客户对账单 | 后端已新增 `/statements` 和 `/bills/{billId}` 固定读 DTO 路径；独立生成/审核模型仍缺失 | 按截止时间或勾选合格来源生成，支持审核、明细、支付历史和 revision | IN_PROGRESS/P0 |
| 结算单应收 | 后端已新增 `/receivable-settlements` 固定读 DTO 路径；`fin_bill + fin_receipt` 已有人工状态能力 | 关联审核通过的客户对账单，按原型结构形成应收结算页 | IN_PROGRESS/P0 适配 |
| 结算单应付 | 后端已新增 `/payable-settlements` 固定读 DTO 路径并读取人工成本；付款单和完整供应商来源池仍缺失 | 从真实 PAYABLE 来源生成，审核后人工登记付款与凭证 | IN_PROGRESS/P0 |
Finance 来源写入不再是阻断：内部事件入口、Inbox 幂等、Firstleg 入库/柜子快照、`fin_fee_source` 新版本写入/替代/作废、`PUBLISHED + amount>0` 入池校验、五页固定 DTO、完整幂等、File fail-closed、Client 脱敏和稳定错误码均已实现并通过测试。剩余主要阻断转为 11 个目标 operation、Admin 五页接入和测试环境跨服务冒烟。
Finance 来源写入不再是阻断：内部事件入口、Inbox 幂等、Firstleg 入库/柜子快照、`fin_fee_source` 新版本写入/替代/作废、`PUBLISHED + amount>0` 入池校验、部分五页固定 DTO、完整幂等、File fail-closed、Client 脱敏和稳定错误码均已实现并通过测试。当前 11 个目标 operation 是一期 P0，不是可延期的“剩余优化”；此外还需完成 Admin 五页接入和测试环境跨服务冒烟。
## 4. 费用来源到结算全链路
@@ -88,16 +89,11 @@ flowchart LR
现有 `fl_inbound_fee_detail` 已具备客户、入库单、方向、业务日、费用项快照、计费量、单价、金额、审核、发布和 `settlement_included` 字段；已有列表、新增、编辑、删除、审核通过和驳回接口。
仍缺：
- 通用费用的“参与结算/禁止结算”接口和原因、操作人、版本控制。
- 非 FBA 头程运费的统一发布动作；当前发布主要由 FBA 费用发送流程触发。
- 费用调整/作废事件及旧版本替代规则的完整实现。
- Finance 消费者和来源快照写入。
当前 Firstleg 来源发布、调整/作废事件、Relay、Finance 消费者和来源快照写入已经实现并通过测试。Finance 五页内的费用来源详情、二次审核和参与结算操作仍按一期 P0 补齐；这些操作不得绕过已发布不可变来源版本或覆盖上游业务事实。
### 4.2 柜子费用项
当前工作树已新增柜子费用来源表/实体、Controller、审核/参与结算/作废服务、发布事件和内部快照代码；这些文件尚未形成通过测试的稳定基线。既有 Firstleg 柜次体积快照仍只服务 Finance 人工整柜成本分摊，不能替代新来源模型的审核和不可变发布链路。
当前柜子费用来源表/实体、Controller、审核/参与结算/作废服务、发布事件、Relay 和内部快照已经实现，相关定向测试 17/17 通过。Firstleg 的真实柜次体积快照同时服务 Finance 整柜成本分摊，但仍不能由 Admin 手工提交的订单归属或体积替代。
一期至少需要业务侧模型：
@@ -146,7 +142,7 @@ Finance 必须通过 Inbox 幂等消费来源版本，或通过受保护的快
| 模型 | 必要字段 | 当前缺口 |
|---|---|---|
| `fin_fee_source` | 来源系统/类型/ID/版本/hash、方向、客户、供应商、订单/入库/柜次、业务日、费用项、数量/单价/金额、审核/参与结算快照、状态、占用单据 | 已有写入、类型、方向、柜次、费用编码、hash、完整 JSON 快照和版本状态；供应商顶层字段及对账单占用关系仍待后续模型落地 |
| `fin_fee_source` | 来源系统/类型/ID/版本/hash、方向、客户、供应商、订单/入库/柜次、业务日、费用项、数量/单价/金额、审核/参与结算快照、状态、占用单据 | 已有写入、类型、方向、柜次、费用编码、hash、完整 JSON 快照和版本状态；供应商顶层字段及对账单占用关系属于本期 P0 数据模型，不得延后 |
| `fin_reconciliation_statement` | 对账单号、客户、期间、账期、CNY 总额、状态、审核、版本、备注 | 缺失 |
| `fin_reconciliation_line` | 对账单、feeSourceId/version/hash、业务与计费快照、金额 | 缺失 |
| `fin_settlement` | AR/AP、客户/供应商、来源对账单、期间、到期日、总额、已收付、余额、状态、版本 | 当前 `fin_bill` 仅覆盖部分 AR |
@@ -156,10 +152,11 @@ Finance 必须通过 Inbox 幂等消费来源版本，或通过受保护的快
## 7. 专项优先级
### P0：不开工或不联调就无法闭环
### P0：一期验收硬阻断
1. 入库费用独立的参与结算/禁止结算和通用发布动作；柜子费用来源模型已完成，不再列为阻断。
2. 客户对账单、应收结算单、应付结算单的数据模型、状态机和剩余 11 个 operation。
1. 以下 11 个 operation 全部实现并通过直接行为测试：账户列表/流水；费用来源详情/审核/参与结算；对账单生成及出账/调整/作废；应收/应付结算单生成；结算单详情；人工付款登记。人工收款已实现但必须继续通过 300 元分配 3 张 100 元应收单等 P0 回归。
2. 对账单、应收/应付结算单、付款和 revision 所需数据模型与唯一约束同步落地，不能只做空 Controller。
3. 详细冻结契约见 `财务一期P0操作契约与验收用例.md`；不得把其中任何一项标为 P1、后续优化或假入口。
### P1：领导验收前必须完成