docs: organize contracts by business domain

2026-09-04 16:44:08 +08:00
parent 703f869841
commit 40492cdae8
79 changed files with 916 additions and 852 deletions
@@ -1,8 +1,8 @@
 # 财务管理闭环盘点与范围建议

-> 盘点日期：2026-08-10  
-> 当前状态：F0/F1 已有 Finance 服务、数据库、权限、Admin/Client 页面和基础接口；一期 11 个 P0 operation 的目标契约已冻结，本地实现验收按独立 G1-G4 证据矩阵均为 `PASS`；真实 MySQL、测试环境 HTTP 冒烟和领导页面验收仍需单独执行
-> 盘点范围：二期入库计费现状、平台后台财务原型、Admin/Client/Firstleg 当前实现  
+> 盘点日期：2026-08-10
+> 当前状态：F0/F1 已有 Finance 服务、数据库、权限、Admin/Client 页面和基础接口；订单与客户 11 个 P0 operation 的目标契约已冻结，本地实现验收按独立 G1-G4 证据矩阵均为 `PASS`；真实 MySQL、测试环境 HTTP 冒烟和领导页面验收仍需单独执行
+> 盘点范围：入库计费现状、平台后台财务原型、Admin/Client/Firstleg 当前实现
 > 结论口径：本文区分“代码已实现”“原型展示”和“建议范围”；原型功能不自动成为开发范围。

 ## 费用来源扩展确认（2026-09-02）
@@ -35,21 +35,21 @@ Finance 全链路测试环境实跑报告为 `baiyue-firstleg/reports/finance-fu

 开发前总控门禁与 F0/F1 任务清单：[财务开工门禁与F0-F1任务清单](财务开工门禁与F0-F1任务清单.md)。

-一期领导验收唯一范围入口：[财务一期五页产品与接口验收契约](财务一期五页产品与接口验收契约.md)。
+订单与客户领导验收唯一范围入口：[财务核心五页产品与接口验收契约](财务核心五页产品与接口验收契约.md)。

-一期 11 个 P0 操作、状态机与验收用例：[财务一期 P0 操作契约与验收用例](财务一期P0操作契约与验收用例.md)。
+订单与客户 11 个 P0 操作、状态机与验收用例：[财务核心 P0 操作契约与验收用例](财务核心P0操作契约与验收用例.md)。

-一期实现与 Admin 接入证据（不反向修改目标契约）：[财务一期 P0 实现证据矩阵](财务一期P0实现证据矩阵.md)。
+订单与客户实现与 Admin 接入证据（不反向修改目标契约）：[财务核心 P0 实现证据矩阵](财务核心P0实现证据矩阵.md)。

-文档优先级：五页验收契约和本轮产品确认 > 五页目标 OpenAPI > 既有人工 F1 契约/门禁 > 领域模型、历史全量规划和迁移文档。旧文档用于追溯，不得据此把钱包、充值、发票、费用分析或利润表重新纳入一期。
+文档优先级：五页验收契约和本轮产品确认 > 五页目标 OpenAPI > 既有人工 F1 契约/门禁 > 领域模型、历史全量规划和迁移文档。旧文档用于追溯，不得据此把钱包、充值、发票、费用分析或利润表重新纳入订单与客户。

 旧文档降级规则：

-| 文档/章节 | 当前用途 | 一期实施约束 |
+| 文档/章节 | 当前用途 | 订单与客户实施约束 |
 |---|---|---|
 | 本文第六节起的“历史全量规划” | 保存早期盘点和演进背景 | 与五页契约冲突时全部失效，不作为菜单、路由、字段或接口依据 |
 | `财务领域模型与跨服务契约.md` | 历史合并稿 | 已被数据字典和跨服务契约替代 |
-| `财务服务边界设计.md`、`财务领域模型与数据字典.md` | 服务边界和长期模型参考 | 其中钱包、充值、发票、费用分析、利润模型不属于一期 |
+| `财务服务边界设计.md`、`财务领域模型与数据字典.md` | 服务边界和长期模型参考 | 其中钱包、充值、发票、费用分析、利润模型不属于订单与客户 |
 | `财务历史迁移与上线验收方案.md`、`财务F0实施任务拆分.md` | 历史迁移、底座任务追溯 | 不得覆盖五页范围和当前实现状态 |

 详细设计材料：
@@ -61,10 +61,10 @@ Finance 全链路测试环境实跑报告为 `baiyue-firstleg/reports/finance-fu
 - [Firstleg-Finance跨服务契约](Firstleg-Finance跨服务契约.md)
 - [F1 人工账单、收款、成本接口契约](F1人工账单收款成本接口契约.md)
 - [F1 人工财务契约审查与门禁](F1人工财务契约审查与门禁.md)
- [财务一期五页产品与接口验收契约](财务一期五页产品与接口验收契约.md)
- [财务一期五页 OpenAPI](openapi/finance-phase1-five-pages-v1.yaml)
- [财务一期 P0 操作契约与验收用例](财务一期P0操作契约与验收用例.md)
- [财务一期 P0 实现证据矩阵](财务一期P0实现证据矩阵.md)
+- [财务核心五页产品与接口验收契约](财务核心五页产品与接口验收契约.md)
+- [财务核心五页 OpenAPI](openapi/finance-core-five-pages-v1.yaml)
+- [财务核心 P0 操作契约与验收用例](财务核心P0操作契约与验收用例.md)
+- [财务核心 P0 实现证据矩阵](财务核心P0实现证据矩阵.md)
 - [财务历史迁移与上线验收方案](财务历史迁移与上线验收方案.md)
 - [财务F0实施任务拆分](财务F0实施任务拆分.md)

@@ -101,21 +101,21 @@ Finance 全链路测试环境实跑报告为 `baiyue-firstleg/reports/finance-fu

 此前基础链路已完成 Firstleg 真实柜次体积快照、客户归属、成本凭证校验、revision、双权限上传、费用来源事件/Relay/快照、Finance `fin_fee_source` 消费写入和完整幂等。在此基础上，固定五页所需的 11 个目标 operation、Admin 页面动作与 IAM 权限目录现已闭环，G1-G4 本地门禁均为 `PASS`；最终直接证据包括 Finance 聚合 82/82、G3 16/16、G4 18/18、收款及 AR 同步 12/12、IAM 168/168、Admin 财务专项 60/60、Admin 全量 654/654 及 Admin 构建通过。真实 MySQL 执行、测试环境 HTTP 冒烟和领导页面验收仍需单独完成，未经当前对话明确授权不触发 Jenkins。

-一期范围已重新冻结为原型 5 页：客户账户、客户应收应付、客户对账单、结算单应收、结算单应付。费用分析、利润表、发票和钱包不做，也不保留菜单、路由或假按钮。客户账户改为账单、收款和应收应付来源派生的财务往来总览，不做充值/预收。
+订单与客户范围已重新冻结为原型 5 页：客户账户、客户应收应付、客户对账单、结算单应收、结算单应付。费用分析、利润表、发票和钱包不做，也不保留菜单、路由或假按钮。客户账户改为账单、收款和应收应付来源派生的财务往来总览，不做充值/预收。

 ## 二、事实来源与边界

 本次按以下资料核对：

-1. 二期需求文档明确二期只做头程计费，不自动形成应收、应付、对账单、收付款、核销、发票、利润或总账。
+1. 入库测量与计费需求文档明确入库测量与计费只做头程计费，不自动形成应收、应付、对账单、收付款、核销、发票、利润或总账。
 2. 平台后台原型提供财务管理全量参考，但其中数据和交互主要由单页 HTML 内的静态数据及前端脚本驱动。
 3. 当前代码用于证明“已经实现什么”，不反向扩大产品范围。

 主要依据：

- `docs/二期/二期计费财务需求确认表.md`
- `docs/二期/二期V2需求确认清单.md`
- `docs/二期/二期需求优化版-v2-测量计费入库主流程.md`
+- `docs/入库测量与计费/入库测量与计费计费财务需求确认表.md`
+- `docs/入库测量与计费/入库测量与计费V2需求确认清单.md`
+- `docs/入库测量与计费/入库测量与计费需求优化版-v2-测量计费入库主流程.md`
 - `docs/悦/货代SAAS平台后台/货代SaaS平台原型.html`
 - `apps/admin-web/src/modules/inbounds/`
 - `apps/admin-web/src/modules/fee-items/`
@@ -163,13 +163,13 @@ Firstleg 已有 `fl_inbound_fee_detail`，包含：

 | 原型模块 | 原型展示的主要能力 | 当前代码状态 | 是否能直接纳入首期 |
 |---|---|---|---|
-| 客户账户 | 原型为余额、冻结、可用余额和充值流水 | 未实现 | 一期保留汇总/详情/流水结构，但改为未收、待出账、本期已收等派生指标；删除充值/钱包能力 |
+| 客户账户 | 原型为余额、冻结、可用余额和充值流水 | 未实现 | 订单与客户保留汇总/详情/流水结构，但改为未收、待出账、本期已收等派生指标；删除充值/钱包能力 |
 | 客户应收应付 | 费用明细、编辑审核、按截止时间或勾选生成账单 | 已接入真实费用来源和编辑审核闭环 | 作为应收应付费用池 |
 | 客户对账单 | 账期、汇率、应收、已收、结清、明细和支付历史 | 未实现 | 可作为应收闭环核心，但汇率和开票先暂缓 |
 | 结算单应收 | 应收、已收、余额、到期日、审批、部分收款 | 未实现 | 可合并进账单/应收单，避免首期重复建模 |
-| 结算单应付 | 供应商应付、已付、余额、审批、部分付款、利润 | 未实现；上游成本来源不完整 | 一期纳入，但删除利润字段/按钮；必须先补真实供应商应付来源和付款凭证链路 |
-| 费用分析 | 内外部费用对比、趋势和明细 | 未实现 | 一期明确不做，不进菜单/路由 |
-| 利润表 | 按客户、货柜、单票、月份统计收入、成本、利润率 | 未实现 | 一期明确不做，不进菜单/路由 |
+| 结算单应付 | 供应商应付、已付、余额、审批、部分付款、利润 | 未实现；上游成本来源不完整 | 订单与客户纳入，但删除利润字段/按钮；必须先补真实供应商应付来源和付款凭证链路 |
+| 费用分析 | 内外部费用对比、趋势和明细 | 未实现 | 订单与客户明确不做，不进菜单/路由 |
+| 利润表 | 按客户、货柜、单票、月份统计收入、成本、利润率 | 未实现 | 订单与客户明确不做，不进菜单/路由 |

 原型还出现了发票抬头、开票日期、汇率、支付方式、收付款凭证号等字段。它们只说明未来可能需要，不代表当前产品已经确认税务、外币折算、资金或发票边界。

@@ -190,13 +190,13 @@ Firstleg 已有 `fl_inbound_fee_detail`，包含：

 ## 六、全量财务规划与交付顺序

-### 6.1 历史全量规划（不作为一期范围）
+### 6.1 历史全量规划（不作为订单与客户范围）

-以下内容只保留为历史分析。若与《财务一期五页产品与接口验收契约》冲突，以五页契约为准。
+以下内容只保留为历史分析。若与《财务核心五页产品与接口验收契约》冲突，以五页契约为准。

 | 目标域 | 业务结果 | 主要来源 | 不能提前假定的口径 |
 |---|---|---|---|
-| 客户账户 | 客户财务往来派生汇总、详情和流水 | 账单、收款和应收应付来源 | 一期不建设钱包、充值、预收或自动扣款 |
+| 客户账户 | 客户财务往来派生汇总、详情和流水 | 账单、收款和应收应付来源 | 订单与客户不建设钱包、充值、预收或自动扣款 |
 | 客户应收 | 客户欠款、到期、逾期、结清 | 已发布对客费用、补差/冲销 | 收入确认节点和账期规则 |
 | 客户应付 | 客户代垫或返还类应付款（如确有业务） | 业务费用或人工单据 | 产品是否真的存在“平台向客户付款”的场景 |
 | 客户对账单 | 期间内费用汇总、明细、平台出账和客户确认 | 应收/应付费用池 | 一张账单是否允许混合方向、混合币种 |
@@ -204,7 +204,7 @@ Firstleg 已有 `fl_inbound_fee_detail`，包含：
 | 结算单应付 | 供应商成本、付款、余额和结清 | 供应商费用、运力/仓储/报关成本 | 成本确认、供应商账期、审批和付款方式 |
 | 收付款与核销 | 到账/付款凭证，部分结算、反核销 | 银行流水或人工登记 | 是否首期接银行流水，是否允许一笔多单核销 |
 | 发票 | 开票申请、开具、红冲、作废和关联 | 已确认应收/收款 | 税率、含税/未税、开票主体、外部平台 |
-| 费用分析 | 历史规划，一期不做 | 应收应付台账 | 不进入一期菜单、路由和验收 |
+| 费用分析 | 历史规划，订单与客户不做 | 应收应付台账 | 不进入订单与客户菜单、路由和验收 |
 | 利润 | 客户/单票/柜次/月度收入、成本、利润率 | 应收收入 + 应付成本 + 分摊 | 汇率、成本分摊、收入成本确认时间 |

 ### 6.2 分阶段交付顺序
@@ -216,8 +216,8 @@ Firstleg 已有 `fl_inbound_fee_detail`，包含：
 | F0 财务底座 | 独立 Finance 服务/数据库、财务主体、客户/供应商往来单位、币种、费用科目、期间、权限、审计、幂等、金额精度 | 所有后续对象使用同一基础口径 | 服务边界已技术确认；产品确认主体、币种、权限和编码 |
 | F1 应收与客户对账 | 应收费用池、平台出账、客户确认、结算单应收、收款登记、核销、反核销 | 费用 → 账单 → 客户确认 → 应收 → 收款 → 结清 | 当前已发布对客费用来源 |
 | F2 应付与供应商结算 | 成本费用池、供应商账单、结算单应付、付款登记、付款核销、应付调整 | 成本 → 供应商账单 → 应付 → 付款 → 结清 | 供应商主数据和真实成本来源 |
-| F3 客户账户与发票 | 一期只做派生客户账户总览；发票暂缓 | 账户只读聚合，不维护资金余额 | 发票不属于一期 |
-| F4 分析与利润 | 一期不做 | 不建设菜单、路由或假入口 | 后续重新立项 |
+| F3 客户账户与发票 | 订单与客户只做派生客户账户总览；发票暂缓 | 账户只读聚合，不维护资金余额 | 发票不属于订单与客户 |
+| F4 分析与利润 | 订单与客户不做 | 不建设菜单、路由或假入口 | 后续重新立项 |

 阶段之间可以并行做页面原型和契约设计，但生产数据链路必须按 F0 → F1/F2 → F3 → F4 验收。F4 不能用原型静态数字先行替代真实台账。

@@ -246,9 +246,9 @@ F1 建议页面：
 4. 核销记录：每笔收款对应哪些应收、核销金额、剩余余额、反核销历史。
 5. 客户侧账单：查看明细、收款与未结余额，并在线确认本人已出账账单；不做在线争议。

-以下历史排除清单已被 2026-08-11 的五页范围取代。结算单应付现在属于一期；其余未确认能力继续排除：
+以下历史排除清单已被 2026-08-11 的五页范围取代。结算单应付现在属于订单与客户；其余未确认能力继续排除：

- 供应商在线确认和自动付款（应付结算单与人工付款属于一期）；
+- 供应商在线确认和自动付款（应付结算单与人工付款属于订单与客户）；
 - 客户预充值、余额冻结和自动扣款；
 - 发票申请、开票和税务接口；
 - 多币种折算与汇兑损益；
@@ -273,7 +273,7 @@ F1 建议页面：

 | 编号 | 待确认问题 | 建议默认值 |
 |---|---|---|
-| F1 | 一期领导验收范围 | 固定为客户账户、客户应收应付、客户对账单、结算单应收、结算单应付；费用分析和利润表不做 |
+| F1 | 订单与客户领导验收范围 | 固定为客户账户、客户应收应付、客户对账单、结算单应收、结算单应付；费用分析和利润表不做 |
 | F2 | 账单生成维度 | 客户 + 币种 + 账期；不同币种不合并 |
 | F3 | 哪些费用可以进入账单 | `APPROVED + PUBLISHED + AVAILABLE + CNY + amount>0` 且未出账；无人工结算开关 |
 | F4 | 当前已发布头程费用是否自动进入待对账池 | 是，但仍由财务选择并生成账单 |