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

docs: organize contracts by business domain

Browse Source
This commit is contained in:
ouyangxq
2026-09-04 16:44:08 +08:00
parent 703f869841
commit 40492cdae8
79 changed files with 916 additions and 852 deletions
Download Patch File Download Diff File Expand all files Collapse all files
财务管理/F1人工财务契约审查与门禁.md
+3 -3
View File
@@ -4,7 +4,7 @@
> 审查范围：Finance Java、Finance 建库 SQL、统一增量 SQL、Admin/Client Finance API、File Java/测试、`openapi/finance-f1-manual-v1.yaml`
> 结论：F0/F1 基础代码已经实现，当前处于专项修复与契约收敛阶段；不是整体未开发。修复项完成前尚未达到完整联调验收/测试放行。
> 范围重定：领导验收改为《财务一期五页产品与接口验收契约》中的 5 页。本文 D1-D11 继续作为既有人工接口专项门禁，并新增来源链路和五页门禁。
> 范围重定：领导验收改为《财务核心五页产品与接口验收契约》中的 5 页。本文 D1-D11 继续作为既有人工接口专项门禁，并新增来源链路和五页门禁。
## 1. 已确认且已对齐
@@ -92,7 +92,7 @@
| D11 | 客户状态可见性 | **后端完成。** 客户账单只见 `ISSUED/PARTIALLY_PAID/PAID`；客户收款只见 `CONFIRMED`，使用 `ClientReceipt` 专用 DTO 并去除凭证、操作人和内部字段；脱敏测试通过 | 后端门禁关闭；保留跨客户与序列化回归 |
| D12 | Finance 费用来源写入 | **后端完成。** 内部事件入口、令牌鉴权、Inbox 幂等、Firstleg 快照回查、来源写入/替代/作废均已实现；非作废事件必须 `PUBLISHED`，未发布返回 `FIN-EVT-015`；金额必须 `>0`，零/负返回 `FIN-EVT-010`；专项 10/10、Finance 全量 35/35 通过 | 后端门禁关闭；保留真实跨服务 HTTP 冒烟 |
| D13 | 柜子费用来源 | **后端完成并验证。** Firstleg 已有柜子费用模型、审核/参与结算/作废、事件、Relay 和内部快照；Firstleg 相关 17/17、Finance 柜子来源消费测试通过 | 后端门禁关闭；测试环境补真实跨服务事件冒烟 |
| D14 | 一期 5 页 | **FAIL / 一期 P0 未关闭。** 11 个目标 operation 契约已冻结；实现状态不再写入 OpenAPI 或主契约，G1-G4 证据矩阵当前均未放行 | G1-G4 分别完成组内全部后端直接行为测试和 Admin 真实接入，证据矩阵更新为 `PASS` 后再完成五页端到端验收 |
| D14 | 订单与客户 5 页 | **FAIL / 订单与客户 P0 未关闭。** 11 个目标 operation 契约已冻结；实现状态不再写入 OpenAPI 或主契约，G1-G4 证据矩阵当前均未放行 | G1-G4 分别完成组内全部后端直接行为测试和 Admin 真实接入，证据矩阵更新为 `PASS` 后再完成五页端到端验收 |
## 4. 非阻断但需锁定的契约说明
@@ -107,7 +107,7 @@
进入前后端联调前至少满足：
1. D1-D8、D10-D13 已具备后端直接证据；D14 当前 FAIL，G1-G4 任一组未同时通过后端行为测试与 Admin 真实接入，均不得通过一期完整联调验收。
1. D1-D8、D10-D13 已具备后端直接证据；D14 当前 FAIL，G1-G4 任一组未同时通过后端行为测试与 Admin 真实接入，均不得通过订单与客户完整联调验收。
2. D2 已固定为首期非分页数组；后续若改服务端分页须另行升级契约。
3. 幂等门禁已关闭；后续写 operation 继续复用同参重放、异参冲突和恢复语义。
4. Finance 集成测试覆盖：默认 30 天、CNY 拒绝、出账冻结、300 分 3 单、超额/跨客户/草稿拒绝、部分收款到收清、调整修订、已收不可作废。
财务管理/F1人工账单收款成本接口契约.md
+1 -1
View File
@@ -5,7 +5,7 @@
> 状态：目标契约；以《F1人工财务契约审查与门禁》为开发/联调准入依据
> OpenAPI：`openapi/finance-f1-manual-v1.yaml`
> 一期 5 页产品与新增接口以《财务一期五页产品与接口验收契约》和 `openapi/finance-phase1-five-pages-v1.yaml` 为准；本文保留现有人工账单、收款和成本能力的细化契约。
> 订单与客户 5 页产品与新增接口以《财务核心五页产品与接口验收契约》和 `openapi/finance-core-five-pages-v1.yaml` 为准；本文保留现有人工账单、收款和成本能力的细化契约。
## 1. 首期边界
财务管理/Firstleg-Finance跨服务契约.md
+2 -2
View File
@@ -2,9 +2,9 @@
> 版本：V0.4（费用作废命令与事件回流对齐）
> 日期：2026-08-20
> 状态：技术边界和一期产品口径已确认；Firstleg 事件/Relay/快照、Finance Inbox/来源写入及 Finance 发起的业务作废闭环均已实现。
> 状态：技术边界和订单与客户产品口径已确认；Firstleg 事件/Relay/快照、Finance Inbox/来源写入及 Finance 发起的业务作废闭环均已实现。
本文是 `firstleg-service` 与已落地 `finance-service` 之间的费用来源技术契约。产品范围以《财务一期五页产品与接口验收契约》为准。
本文是 `firstleg-service` 与已落地 `finance-service` 之间的费用来源技术契约。产品范围以《财务核心五页产品与接口验收契约》为准。
## 1. 事实依据与当前实现差异
财务管理/README.md
+31 -31
View File
@@ -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 | 当前已发布头程费用是否自动进入待对账池 | 是，但仍由财务选择并生成账单 |
财务管理/openapi/finance-phase1-five-pages-v1.yaml → 财务管理/openapi/finance-core-five-pages-v1.yaml
+5 -5
View File
@@ -3,10 +3,10 @@ info:
title: Finance Phase 1 Five-page Acceptance API
version: 1.0.0-draft
description: >-
一期领导验收 5 页目标契约：客户账户、客户应收应付、客户对账单、结算单应收、
订单与客户领导验收 5 页目标契约：客户账户、客户应收应付、客户对账单、结算单应收、
结算单应付。只支持 CNY。费用分析、利润表、钱包、预收和充值不属于本契约。
本文件冻结一期目标契约及后续确认的费用编辑审核、客户确认和应收统计扩展。实现与
Admin 接入证据单独维护在财务一期P0实现证据矩阵.md，不得因代码文件出现反复修改本契约。
本文件冻结订单与客户目标契约及后续确认的费用编辑审核、客户确认和应收统计扩展。实现与
Admin 接入证据单独维护在财务核心P0实现证据矩阵.md，不得因代码文件出现反复修改本契约。
servers:
- url: /api
x-product-scope:
@@ -46,8 +46,8 @@ x-customer-account-ui-contract:
x-phase1-p0-contract:
status: FROZEN
rule: 所有已列 operation 均为当前目标契约；实现状态不得写入本文件。
contract: ../财务一期P0操作契约与验收用例.md
evidenceMatrix: ../财务一期P0实现证据矩阵.md
contract: ../财务核心P0操作契约与验收用例.md
evidenceMatrix: ../财务核心P0实现证据矩阵.md
x-idempotency-contract:
scope: method + normalizedPath + resolvedCustomerId + completeQueryAndBody
sameKeySameRequest: replay original result
财务管理/财务历史迁移与上线验收方案.md
+2 -2
View File
@@ -12,7 +12,7 @@
本方案用于把 Finance 上线前已经存在于 Firstleg 的历史对客费用，安全地接入独立 `finance-service` 和 `baiyue_finance`，并定义 F0/F1 从测试、灰度到正式启用的验收门禁。
本方案不把“费用已发送/已发布”推断为“客户尚欠款”，也不把二期计费状态推断为财务结算状态。历史迁移分成三个明确步骤：
本方案不把“费用已发送/已发布”推断为“客户尚欠款”，也不把入库测量与计费计费状态推断为财务结算状态。历史迁移分成三个明确步骤：
```text
Firstleg 历史费用候选集
@@ -71,7 +71,7 @@ Firstleg 历史费用候选集
### 3.1 候选来源
首批只处理能够追溯到 Firstleg 已发布对客费用版本的 `RECEIVABLE` 数据。当前二期费用用于证明业务计费结果，不直接证明应收、收款或核销事实。
首批只处理能够追溯到 Firstleg 已发布对客费用版本的 `RECEIVABLE` 数据。当前入库测量与计费费用用于证明业务计费结果，不直接证明应收、收款或核销事实。
每条候选记录至少应能提供：
财务管理/财务开工门禁与F0-F1任务清单.md
+5 -5
View File
@@ -9,7 +9,7 @@
Finance 的服务拆分、独立数据库、基础表、权限、人工账单/收款/成本接口及 Admin/Client 基础页面已经落地。后端真实体积快照、归属、成本凭证、revision、双权限上传、费用来源事件/Relay/快照、固定 DTO、完整幂等、File fail-closed、客户收款 DTO 和稳定错误码已经完成并通过专项测试；当前继续收口 Admin 最终契约适配和五页剩余 operation。
F0 的平台主体、首期仅 RMB/CNY、自定义账期、编号、费用冻结、无历史迁移、客户角色和首期简化审批已经确认。一期领导验收固定为 5 页；客户账户为派生财务往来总览，不做钱包/充值，费用分析和利润表不做。详见[财务一期五页产品与接口验收契约](财务一期五页产品与接口验收契约.md)。
F0 的平台主体、首期仅 RMB/CNY、自定义账期、编号、费用冻结、无历史迁移、客户角色和首期简化审批已经确认。订单与客户领导验收固定为 5 页；客户账户为派生财务往来总览，不做钱包/充值，费用分析和利润表不做。详见[财务核心五页产品与接口验收契约](财务核心五页产品与接口验收契约.md)。
## 二、文档交付状态
@@ -48,7 +48,7 @@ G0 允许：完善 API/OpenAPI、数据库迁移草案、契约测试样例、
当前按以下冻结口径修复和补测：
- `财务一期P0操作契约与验收用例.md` 中的 11 个 operation 全部为一期 P0；目标契约不跟随开发中间态修改，G1-G4 证据矩阵任一组未同时通过后端行为测试和 Admin 真实接入时均不得关闭；
- `财务核心P0操作契约与验收用例.md` 中的 11 个 operation 全部为订单与客户 P0；目标契约不跟随开发中间态修改，G1-G4 证据矩阵任一组未同时通过后端行为测试和 Admin 真实接入时均不得关闭；
- 账单聚合维度（首期固定 RMB/CNY）和账期计算规则冻结；
- 平台出账、关闭、重开和线下异议录入状态冻结；客户首期只读；
@@ -56,9 +56,9 @@ G0 允许：完善 API/OpenAPI、数据库迁移草案、契约测试样例、
- 预收、多收、手续费、退款、反核销的处理方式冻结；
- 至少准备一组真实或脱敏费用来源样本，能够完成费用→账单→应收→收款→核销回归。
### G3/G4：一期应付与排除项门禁
### G3/G4：订单与客户应付与排除项门禁
结算单应付纳入一期，但必须有供应商和真实 PAYABLE 来源。客户账户只做派生查询。发票、费用分析、利润、汇率和月结不属于一期，禁止保留假入口。
结算单应付纳入订单与客户，但必须有供应商和真实 PAYABLE 来源。客户账户只做派生查询。发票、费用分析、利润、汇率和月结不属于订单与客户，禁止保留假入口。
## 四、F0/F1 任务清单
@@ -89,7 +89,7 @@ G0 允许：完善 API/OpenAPI、数据库迁移草案、契约测试样例、
### 本轮不再等待产品确认
- 一期只支持 CNY，验收 5 页及其真实费用来源、对账、应收/应付和人工收付款链路。
- 订单与客户只支持 CNY，验收 5 页及其真实费用来源、对账、应收/应付和人工收付款链路。
- 客户账户是派生总览；发票、费用分析、利润、汇率、月结不属于本轮。
- 首发不迁移历史，不阻塞 F1 修复。
财务管理/财务服务边界设计.md
+1 -1
View File
@@ -1,6 +1,6 @@
# 财务服务边界设计
> **范围说明**：本文只作为 Finance 独立服务/独立数据库的技术边界依据。文中的钱包、充值、发票、费用分析和利润属于长期模型，不属于一期；一期唯一产品范围以《财务一期五页产品与接口验收契约》为准。
> **范围说明**：本文只作为 Finance 独立服务/独立数据库的技术边界依据。文中的钱包、充值、发票、费用分析和利润属于长期模型，不属于订单与客户；订单与客户唯一产品范围以《财务核心五页产品与接口验收契约》为准。
> 决策日期：2026-08-10
> 决策状态：技术已确认
财务管理/财务一期P0实现证据矩阵.md → 财务管理/财务核心P0实现证据矩阵.md
+4 -4
View File
@@ -1,7 +1,7 @@
# 财务一期 P0 实现证据矩阵
# 财务核心 P0 实现证据矩阵
> 日期：2026-08-11
> 目标契约：`openapi/finance-phase1-five-pages-v1.yaml`、`财务一期P0操作契约与验收用例.md`
> 日期：2026-08-11
> 目标契约：`openapi/finance-core-five-pages-v1.yaml`、`财务核心P0操作契约与验收用例.md`
> 使用规则：本文件只记录验收证据，不反向修改目标契约；Controller 文件、编译成功或开发中间态均不能单独关闭门禁
## 1. 状态更新规则
@@ -15,7 +15,7 @@
## 2. G1-G4 稳定验收表
| 分组 | 一期 P0 operation | 后端行为测试放行条件 | Admin 真实接入放行条件 | 当前可复核证据 | 结论 |
| 分组 | 订单与客户 P0 operation | 后端行为测试放行条件 | Admin 真实接入放行条件 | 当前可复核证据 | 结论 |
|---|---|---|---|---|---|
| G1 客户账户 | `listDerivedCustomerAccounts`、`listDerivedCustomerAccountLedger` | 派生金额、分页筛选、日期边界、停用客户历史、跨客户隔离、固定 DTO/追踪字段测试全部通过 | 客户账户列表、筛选、详情入口、流水筛选均调用真实接口；无钱包、充值、预收或余额写入口 | 后端 G1 专项 4/4、Admin G1 专项 15/15、Finance 专项 21/21、Admin typecheck、IAM 166/166、IAM 权限契约 3/3、Finance 权限契约 2/2 通过；统一 SQL 已同步权限目录且未默认授予角色 | `PASS` |
| G2 费用来源 | `getFinanceFeeSource`、`reviewFinanceFeeSource`、`updateFeeSourceSettlementInclusion` | 详情、PENDING 审核、非法状态、expectedVersion、占用冻结、完整幂等、跨客户隐藏和 CNY 条件全部通过 | 客户应收应付页详情、审核、参与/禁止结算使用真实接口；权限和服务端错误态可见，不存在假成功 | 后端 G2 专项 9/9、Admin G2 专项 21/21、Admin typecheck/build、IAM 166/166、IAM 权限契约 3/3、Finance 权限契约 2/2 通过；统一 SQL 已同步权限目录且未默认授予角色 | `PASS` |
财务管理/财务一期P0操作契约与验收用例.md → 财务管理/财务核心P0操作契约与验收用例.md
+8 -8
View File
@@ -1,9 +1,9 @@
# 财务一期 P0 操作契约与验收用例
# 财务核心 P0 操作契约与验收用例
> 日期：2026-08-11
> 适用范围：一期财务闭环及后续确认的费用编辑审核、客户确认操作
> 状态口径：以下 11 项全部是一期 P0，目标契约已冻结；实现和 Admin 接入证据只维护在 `财务一期P0实现证据矩阵.md`
> 机器契约：`openapi/finance-phase1-five-pages-v1.yaml`
> 日期：2026-08-11
> 适用范围：订单与客户财务闭环及后续确认的费用编辑审核、客户确认操作
> 状态口径：以下 11 项全部是订单与客户 P0，目标契约已冻结；实现和 Admin 接入证据只维护在 `财务核心P0实现证据矩阵.md`
> 机器契约：`openapi/finance-core-five-pages-v1.yaml`
## 1. 统一冻结规则
@@ -32,11 +32,11 @@
| P0-10 | `getSettlement` | `SettlementIdPath` | `SettlementDetailEnvelope<SettlementDetail>` | AR/AP view 二选一并与单据方向匹配 | 返回结算单、来源快照、revision 和收付款记录；没有对应方向权限时 HTTP 403。验收 AC-22、AC-23 |
| P0-11 | `createSettlementPayment` | `CreateSettlementPaymentRequest` | `SettlementDetailEnvelope<SettlementDetail>` | `platform:finance:payment:create` | 只允许 PAYABLE 的 ISSUED/PARTIALLY_PAID；金额不得超过余额，凭证 File fail-closed；更新为 PARTIALLY_PAID/PAID。验收 AC-24 至 AC-26 |
`createReceiptWithAllocations` 已实现，不计入上述 11 项，但仍属于一期 P0 回归门禁：一笔 300 元收款可人工分配到同一客户 3 张各 100 元应收结算单并共用凭证；跨客户、草稿、超额、非 CNY、无有效凭证必须拒绝。
`createReceiptWithAllocations` 已实现，不计入上述 11 项，但仍属于订单与客户 P0 回归门禁：一笔 300 元收款可人工分配到同一客户 3 张各 100 元应收结算单并共用凭证；跨客户、草稿、超额、非 CNY、无有效凭证必须拒绝。
### 2.1 契约与证据分离
本文件不记录 Controller、编译和测试中间态，也不使用 `NOT_IMPLEMENTED/IN_PROGRESS/IMPLEMENTED` 标记。G1-G4 后端行为测试和 Admin 真实接入证据统一见 `财务一期P0实现证据矩阵.md`；开发过程不得反向修改本文件冻结的路径、DTO、状态机和验收标准。
本文件不记录 Controller、编译和测试中间态，也不使用 `NOT_IMPLEMENTED/IN_PROGRESS/IMPLEMENTED` 标记。G1-G4 后端行为测试和 Admin 真实接入证据统一见 `财务核心P0实现证据矩阵.md`；开发过程不得反向修改本文件冻结的路径、DTO、状态机和验收标准。
## 3. 状态机
@@ -80,7 +80,7 @@ ISSUED --VOID--> VOIDED（已收付金额=0）
VOIDED --REOPEN--> ISSUED（新 revision）
```
一期不处理预收、多收、退款、手续费、自动银行对账或汇率折算。人工收付款只能分配到同客户、同方向、CNY 且已出账的结算单。
订单与客户不处理预收、多收、退款、手续费、自动银行对账或汇率折算。人工收付款只能分配到同客户、同方向、CNY 且已出账的结算单。
## 4. 请求字段条件
财务管理/财务一期五页产品与接口验收契约.md → 财务管理/财务核心五页产品与接口验收契约.md
+14 -14
View File
@@ -1,16 +1,16 @@
# 财务一期五页产品与接口验收契约
# 财务核心五页产品与接口验收契约
> 日期：2026-08-11
> 状态：产品范围已确认；一期 11 个 P0 operation 的目标契约已冻结；实现与 Admin 接入只按独立 G1-G4 证据矩阵验收，当前未放行
> 领导验收范围：客户账户、客户应收应付、客户对账单、结算单应收、结算单应付
> 日期：2026-08-11
> 状态：产品范围已确认；订单与客户 11 个 P0 operation 的目标契约已冻结；实现与 Admin 接入只按独立 G1-G4 证据矩阵验收，当前未放行
> 领导验收范围：客户账户、客户应收应付、客户对账单、结算单应收、结算单应付
> 原型依据：`docs/悦/货代SAAS平台后台/货代SaaS平台原型.html`
> 目标 OpenAPI：`openapi/finance-phase1-five-pages-v1.yaml`；当前人工接口继续参考 `openapi/finance-f1-manual-v1.yaml`。
> 11 个 P0 操作的 DTO、状态机、权限、幂等、错误码、隔离和验收用例以 `财务一期P0操作契约与验收用例.md` 为准；实现证据只维护在 `财务一期P0实现证据矩阵.md`。
> 目标 OpenAPI：`openapi/finance-core-five-pages-v1.yaml`；当前人工接口继续参考 `openapi/finance-f1-manual-v1.yaml`。
> 11 个 P0 操作的 DTO、状态机、权限、幂等、错误码、隔离和验收用例以 `财务核心P0操作契约与验收用例.md` 为准；实现证据只维护在 `财务核心P0实现证据矩阵.md`。
## 1. 一期范围结论
## 1. 订单与客户范围结论
一期只交付原型中的以下 5 页，并实现页面结构、字段、筛选、详情和状态：
订单与客户只交付原型中的以下 5 页，并实现页面结构、字段、筛选、详情和状态：
1. 客户账户。
2. 客户应收应付。
@@ -20,7 +20,7 @@
明确不做：费用分析、利润表、钱包、预收、手动充值、自动扣款余额、汇率、外币、发票、月结、银行自动对账。未实现能力不得保留按钮、菜单、路由或模拟成功入口。
所有金额只使用 CNY。原型中的 USD、汇率、开票日期、利润审批、利润金额仅为历史原型字段，一期删除。
所有金额只使用 CNY。原型中的 USD、汇率、开票日期、利润审批、利润金额仅为历史原型字段，订单与客户删除。
客户对账单、应收结算单、应付结算单统一使用短业务编号：`REC-YYMMDD-NNNN`、`AR-YYMMDD-NNNN`、`AP-YYMMDD-NNNN`。日期按北京时间的单据创建日计算，各单据类型分别按日从 `0001` 递增；编号生成后不可修改，作废也不回收。
@@ -45,7 +45,7 @@
## 3. 五页验收矩阵
| 页面 | 原型结构和筛选 | 一期字段 | 一期操作 | 状态与验收 |
| 页面 | 原型结构和筛选 | 订单与客户字段 | 订单与客户操作 | 状态与验收 |
|---|---|---|---|---|
| 客户账户 | 汇总卡、客户列表、账户详情、流水详情；客户名称/编号、账户状态、余额条件、流水类型和日期 | 客户基本信息、客户编号、联系人、电话、未收余额、待出账金额、本期已收金额、总成本、已付成本、待付金额、账户状态、最后变动时间；流水号、时间、业务类型、关联单据、应收/应付变动、变动后未收余额、操作人、备注 | 详情、查询、重置、导出；**无充值、扣款或余额调整** | 运营资金只认三类：待收客户款=正式 AR outstanding，不叠加待出账；待付供应商款=AP outstanding+未制单有效 ON_ACCOUNT 来源并按来源去重；已线下支付供应商款=AP paid+有效 DIRECT_PAID，明细区分账期付款和现场已付。不存在客户线下支付分类，也不新增已收客户款卡片 |
| 客户应收应付 | 工具栏、组合查询、选中汇总、费用列表、费用详情、审核进度、关联业务、操作记录 | 客户、费用单号、是否已生成对账单、审核状态、应收/应付、结算方式、已付时间/方式/凭证、入仓码/柜次号、业务状态、费用类型、金额、业务发生日、来源类型、来源版本 | 详情、编辑草稿/驳回项、提交审核、审核通过/拒绝、调整、作废、按截止时间或勾选生成；不提供“是否结算”开关 | PAYABLE 必须区分 ON_ACCOUNT/DIRECT_PAID；前者可进入 AP，后者只计成本且排除 AP；同一来源版本只能识别一次成本 |
@@ -57,7 +57,7 @@
### 3.1 五页现状/目标差异
| 页面 | 当前仓库事实 | 一期目标 | 差异等级 |
| 页面 | 当前仓库事实 | 订单与客户目标 | 差异等级 |
|---|---|---|---|
| 客户账户 | 后端已新增 `/customer-accounts/{customerId}` 和固定读 DTO；无列表接口 | 派生财务往来汇总、详情和流水，无任何充值/余额写入口 | IMPLEMENTED（单客户查询）；列表/筛选仍缺，Finance DTO 测试通过 |
| 客户应收应付 | `/fee-sources` 固定 DTO、Firstleg 事件/快照和 `fin_fee_source` 写入均已实现 | 真实入库/柜子费用来源池，支持编辑、提交、审核、调整、作废、详情和生成对账单 | 审核通过自动成为结算候选，不提供人工结算开关 |
@@ -96,7 +96,7 @@ flowchart LR
当前柜子费用来源表/实体、Controller、审核/调整/作废服务、自动发布事件、Relay 和内部快照已经实现。Firstleg 的真实柜次体积快照同时服务 Finance 整柜成本分摊，但仍不能由 Admin 手工提交的订单归属或体积替代。
一期至少需要业务侧模型：
订单与客户至少需要业务侧模型：
- `containerFeeId/version`、`containerId/containerNo`、费用方向、费用项目、业务日、CNY 金额。
- 应付来源必须有供应商；应收来源必须有客户分摊结果。
@@ -151,11 +151,11 @@ Finance 必须通过 Inbox 幂等消费来源版本，或通过受保护的快
## 7. 专项优先级
### P0：一期验收硬阻断
### P0：订单与客户验收硬阻断
1. 财务 operation 全部通过直接行为测试：账户列表/流水；费用来源详情及编辑审核闭环；对账单生成、审核、出账、客户确认、调整/作废；应收/应付结算单生成与详情；人工收付款登记。人工收款继续覆盖 300 元分配 3 张 100 元应收单等回归。
2. 对账单、应收/应付结算单、付款和 revision 所需数据模型与唯一约束同步落地，不能只做空 Controller。
3. 详细冻结契约见 `财务一期P0操作契约与验收用例.md`；不得把其中任何一项标为 P1、后续优化或假入口。
3. 详细冻结契约见 `财务核心P0操作契约与验收用例.md`；不得把其中任何一项标为 P1、后续优化或假入口。
### P1：领导验收前必须完成
财务管理/财务管理产品确认版差异与剩余待确认.md
+6 -6
View File
@@ -4,7 +4,7 @@
> 复核日期：2026-08-10
> 用途：把产品回填内容转成可开发口径；不替代产品原始回传表。
> **降级说明（2026-08-11）**：本文保留首次回填复核过程，不再作为一期范围入口。当前范围和冲突处理以《财务一期五页产品与接口验收契约》为准；原文中的“仍待确认”“F3 整体暂缓”“成本/利润统计”均不得覆盖已确认的五页范围。
> **降级说明（2026-08-11）**：本文保留首次回填复核过程，不再作为订单与客户范围入口。当前范围和冲突处理以《财务核心五页产品与接口验收契约》为准；原文中的“仍待确认”“F3 整体暂缓”“成本/利润统计”均不得覆盖已确认的五页范围。
## 一、回传表复核结论
@@ -12,7 +12,7 @@
其中，以下内容可直接纳入正式文档：
- 一期页面固定为客户账户、客户应收应付、客户对账单、结算单应收、结算单应付；客户账户只是派生财务往来总览，不做钱包/预收；发票和外部接口不做。
- 订单与客户页面固定为客户账户、客户应收应付、客户对账单、结算单应收、结算单应付；客户账户只是派生财务往来总览，不做钱包/预收；发票和外部接口不做。
- 供应商付款为线下付款并上传凭证；单票成本直接归属单票，整柜清关、拖车等公共成本按柜内体积分摊。
- 首期账单只支持 RMB/CNY；每个客户维护自己的账期配置，默认 30 天。
- 收款全部由财务人工填写表单并上传收款图片；一笔 300 元可由财务分别填入 3 张 100 元账单，关联同一张凭证。
@@ -36,17 +36,17 @@
| 事项 | 暂缓口径 |
|---|---|
| F2-01、F2-03、F2-04 | 供应商在线确认、自动付款等能力暂缓；一期仍须交付结算单应付页、真实 PAYABLE 来源和人工付款凭证链路 |
| F3-01 至 F3-04 | 一期建设客户账户派生总览页，但不建设钱包余额、充值、冻结、自动扣款或退款对象 |
| F2-01、F2-03、F2-04 | 供应商在线确认、自动付款等能力暂缓；订单与客户仍须交付结算单应付页、真实 PAYABLE 来源和人工付款凭证链路 |
| F3-01 至 F3-04 | 订单与客户建设客户账户派生总览页，但不建设钱包余额、充值、冻结、自动扣款或退款对象 |
| F3-05 至 F3-07 | 发票和外部开票/银行接口首期线下处理；只保留未来扩展位 |
| F4-04 | 费用分析和利润表一期不进菜单/路由；后续重新立项时再定义权限 |
| F4-04 | 费用分析和利润表订单与客户不进菜单/路由；后续重新立项时再定义权限 |
## 四、当前放行判断
- F0 技术方案和客户主体/成员边界已经冻结，可以继续做 Finance 服务骨架、数据库迁移草案、事件契约和权限矩阵设计。
- F1 客户应收的核心产品口径已补齐；账期日期算法、账单单据粒度和收款字段可按本文默认值直接写入契约。
- F2/F4 的产品口径已补齐；开发前只需把人工成本/收款表单字段、凭证关联和体积分摊公式写入接口与验收契约。
- F3 钱包/充值/发票能力可暂缓；客户账户派生总览属于一期五页，不得整体暂缓。
- F3 钱包/充值/发票能力可暂缓；客户账户派生总览属于订单与客户五页，不得整体暂缓。
因此，本轮已没有新的核心产品问题；剩余工作是把确认版 XLSX 的状态归一化，并在接口/验收契约中补充账期日期算法、收款表单字段、收款凭证与账单分配关系、成本来源字段和体积分摊公式。
财务管理/财务管理产品确认表.md
+22 -22
View File
@@ -1,15 +1,15 @@
# 财务管理产品确认表
> 版本：V1.1
> 创建日期：2026-08-10
> 状态：一期 5 页范围已确认
> 版本：V1.1
> 创建日期：2026-08-10
> 状态：订单与客户 5 页范围已确认
> 适用范围：客户账户、客户应收应付、客户对账单、结算单应收、结算单应付
> 技术方案说明：服务边界、跨服务访问、事件幂等、金额存储、状态留痕和正式模块发布方式已按当前仓库架构直接确认，不再要求产品确认；以 XLSX 的“技术结论”工作表为准。
正式技术决策见：[财务服务边界设计](财务服务边界设计.md)。
一期领导验收及接口事实以[财务一期五页产品与接口验收契约](财务一期五页产品与接口验收契约.md)为准；本文后续 F2-F4 历史问题不自动进入一期。
订单与客户领导验收及接口事实以[财务核心五页产品与接口验收契约](财务核心五页产品与接口验收契约.md)为准；本文后续 F2-F4 历史问题不自动进入订单与客户。
产品回传版 XLSX 的逐项复核和剩余确认门禁见：[财务管理产品确认版差异与剩余待确认](财务管理产品确认版差异与剩余待确认.md)。
@@ -44,7 +44,7 @@
| 实施复杂度 | 首期全部由平台财务人工填写账单、收款和成本表单并上传凭证；不建设自动银行对账、自动核销、复杂审批、钱包、发票或总账 |
| 审批复杂度 | 首期不做强制双人复核和金额分级审批；保留独立权限、操作原因和完整审计 |
| 成员停用 | 客户子用户停用只撤销访问权限；客户账单、应收、余额等仍归客户企业，不触发财务单据转交；历史保留操作人快照 |
| 一期页面 | 只做客户账户、客户应收应付、客户对账单、结算单应收、结算单应付；费用分析和利润表不进菜单/路由 |
| 订单与客户页面 | 只做客户账户、客户应收应付、客户对账单、结算单应收、结算单应付；费用分析和利润表不进菜单/路由 |
| 客户账户性质 | 财务往来派生总览，不是钱包；删除手动充值、预收、可消费余额和自动扣款入口 |
| 费用来源链路 | 入库单费用和柜子费用审核通过后自动发布到 Finance 来源池并成为结算候选；不保留人工“是否结算”标记 |
@@ -53,13 +53,13 @@
| 编号 | 范围 | 建议结论 | 最终结论 | 状态 |
|---|---|---|---|---|
| S1 | 客户账户 | 做预充值、冻结、解冻、扣款、退款和账户流水；账户余额与应收核销分开，任何抵扣都产生核销记录 | 只做账单、收款和应收应付来源派生的财务往来总览；不做钱包、预收、充值和自动扣款 | 已确认 |
| S2 | 客户应收 | 做客户费用池、对账单、应收单、到期/逾期、收款、部分核销、结清、反核销 | 纳入一期 5 页；平台财务操作，客户只读 | 已确认 |
| S2 | 客户应收 | 做客户费用池、对账单、应收单、到期/逾期、收款、部分核销、结清、反核销 | 纳入订单与客户 5 页；平台财务操作，客户只读 | 已确认 |
| S3 | 客户应付 | 仅在确有平台向客户付款的业务场景时启用；否则不开放菜单和数据方向 | 客户应收应付页按来源方向展示；没有真实 PAYABLE 来源时为空，不造模拟数据 | 已确认 |
| S4 | 客户对账单 | 按客户 + 币种 + 账期生成，支持平台内部复核、发送、关闭和财务重开；客户只读查看 | 平台财务出账，客户只读，异议线下反馈 | 已确认 |
| S5 | 供应商应付 | 做供应商成本池、供应商对账、应付单、付款、付款核销和反核销 | 结算单应付纳入一期；只使用具有供应商和真实来源的 CNY 应付费用，付款人工登记 | 已确认 |
| S6 | 发票 | 做发票申请、开票登记、票号/文件关联、红冲和作废；不直接假定外部开票平台 | 一期不做，不设计菜单、路由或按钮 | 已确认 |
| S7 | 费用分析 | 按费用项目、客户、供应商、期间统计发生额、已结算额和余额，支持钻取来源单据 | 一期不做，不进菜单/路由 | 已确认 |
| S8 | 利润 | 支持客户、货柜、单票、月份维度；收入、成本、分摊、汇率和利润率必须可追溯 | 一期不做，不进菜单/路由；应付页删除利润字段和利润审批 | 已确认 |
| S5 | 供应商应付 | 做供应商成本池、供应商对账、应付单、付款、付款核销和反核销 | 结算单应付纳入订单与客户；只使用具有供应商和真实来源的 CNY 应付费用，付款人工登记 | 已确认 |
| S6 | 发票 | 做发票申请、开票登记、票号/文件关联、红冲和作废；不直接假定外部开票平台 | 订单与客户不做，不设计菜单、路由或按钮 | 已确认 |
| S7 | 费用分析 | 按费用项目、客户、供应商、期间统计发生额、已结算额和余额，支持钻取来源单据 | 订单与客户不做，不进菜单/路由 | 已确认 |
| S8 | 利润 | 支持客户、货柜、单票、月份维度；收入、成本、分摊、汇率和利润率必须可追溯 | 订单与客户不做，不进菜单/路由；应付页删除利润字段和利润审批 | 已确认 |
## 三、F0 财务底座确认
@@ -104,7 +104,7 @@
| F1-07 | 核销关系 | 支持一笔收款核销多张应收、一张应收被多笔收款核销；禁止跨币种和超额 | 一笔客户付款可分配到多张账单；财务分别填写各账单对应金额并关联同一收款凭证；首期不处理预收、多收、手续费、退款 | 已确认 |
| F1-08 | 反核销/作废 | 独立高风险权限，填写原因并保留原记录；不物理删除 | 首期不做复杂反核销；未收单据可作废，已出账调整/作废重开必须留原因、版本和原记录 | 已确认 |
| F1-09 | 出账后调整 | 已出账冻结；平台财务通过调整/作废重开形成新版本，保留原金额和原因 | 仅平台财务手工调整，不允许客户修改 | 已确认 |
| F1-10 | 预收/多收/手续费/退款 | 单独建模为预收、其他应付款或退款，不直接冲减应收金额 | 一期全部不做；不设计钱包或预收入口 | 已确认 |
| F1-10 | 预收/多收/手续费/退款 | 单独建模为预收、其他应付款或退款，不直接冲减应收金额 | 订单与客户全部不做；不设计钱包或预收入口 | 已确认 |
| F1-11 | 应收款统计表 | 按结算单生成自然月和客户汇总 CNY 正式应收 | 展示应收总额、已收合计、余额未收，支持打印和异步 Excel；不做 FBA 渠道拆分、USD、编辑或零头减免 | 已确认 |
## 五、F2 供应商应付与结算确认
@@ -113,11 +113,11 @@
|---|---|---|---|---|
| F2-01 | 成本来源 | 只有具备 Warehouse 供应商、真实业务来源、审核和 CNY 正金额的 PAYABLE 来源才能进入应付池 | 供应商必须为 `ACTIVE`，名称只取 Warehouse 快照；费用项目 `supplierCategory` 为空时允许任意启用供应商，非空时严格匹配类别 | 已确认 |
| F2-02 | 成本确认节点 | 费用审核通过后自动发布并进入 Finance 结算候选，确认后冻结成本快照 | 不保留“参与结算”开关；来源版本冻结 | 已确认 |
| F2-03 | 供应商账单 | DRAFT → INTERNAL_REVIEW → SENT → CONFIRMED → CLOSED；差异走争议/补差/冲销 | 一期不单独做供应商对账页，直接在结算单应付中生成、审核和付款 | 已确认 |
| F2-03 | 供应商账单 | DRAFT → INTERNAL_REVIEW → SENT → CONFIRMED → CLOSED；差异走争议/补差/冲销 | 订单与客户不单独做供应商对账页，直接在结算单应付中生成、审核和付款 | 已确认 |
| F2-04 | 应付状态 | OPEN → PARTIALLY_PAID → PAID；到期增加 OVERDUE 标记 | DRAFT → PENDING_REVIEW → ISSUED → PARTIALLY_PAID → PAID；可拒绝/作废并留痕 | 已确认 |
| F2-05 | 付款与核销 | 付款单独登记，支持多对多付款核销；禁止跨币种和超额 | 平台财务人工登记付款表单和凭证；不得跨供应商或超额 | 已确认 |
| F2-06 | 审批 | 应付确认和付款前复核使用独立权限；是否需要金额分级审批待确认 | 使用独立审核权限；一期不做金额分级或强制双人 | 已确认 |
| F2-07 | 预付/押金/代付/退款 | 不混入普通应付余额，单独建模并保留关联单据 | 一期不做 | 已确认 |
| F2-06 | 审批 | 应付确认和付款前复核使用独立权限；是否需要金额分级审批待确认 | 使用独立审核权限；订单与客户不做金额分级或强制双人 | 已确认 |
| F2-07 | 预付/押金/代付/退款 | 不混入普通应付余额，单独建模并保留关联单据 | 订单与客户不做 | 已确认 |
| F2-08 | 当前人工 PAYABLE 明细 | 仅作为待补充来源，不得直接视为供应商应付闭环 | 没有供应商、审核和发布事实的明细不得进入结算单应付 | 已确认 |
| F2-09 | 账期应付与已付成本 | 费用方向只表示收付对象，支付时点另建字段 | `direction` 保持 `RECEIVABLE/PAYABLE`；PAYABLE 必填 `settlementMode=ON_ACCOUNT/DIRECT_PAID`。ON_ACCOUNT 进入 AP，DIRECT_PAID 只计成本且永不进入 AP 或待付金额 | 已确认 |
| F2-10 | 已付成本凭证 | 已付事实必须具备时间、方式和可追溯证据 | DIRECT_PAID 必填 `paidAt`、`paymentMethod`；方式限 `ONLINE/BANK_TRANSFER/CASH/OTHER`，`paymentReferenceNo` 与付款凭证至少一项 | 已确认 |
@@ -131,7 +131,7 @@
| F3-01 | 账户余额性质 | 明确是客户预付款余额还是平台内部授信；充值必须有到账凭证，余额变更原子落流水 | 不是资金余额；客户账户页只展示账单、收款和费用来源派生指标 | 已确认 |
| F3-02 | 账户与应收关系 | 账户扣款可以核销应收，但不得直接修改应收原金额；余额、扣款、核销三条记录均保留 | 不做账户扣款；收款只通过结算单分配更新未收余额 | 已确认 |
| F3-03 | 冻结与解冻 | 明确冻结触发、解冻人、原因、部分冻结和失败补偿 | 不做钱包冻结/解冻；待出账金额由合格未出账来源派生 | 已确认 |
| F3-04 | 退款 | 退款必须关联原充值/收款，记录审批、到账方式、退款凭证和余额恢复规则 | 一期不做充值和退款 | 已确认 |
| F3-04 | 退款 | 退款必须关联原充值/收款，记录审批、到账方式、退款凭证和余额恢复规则 | 订单与客户不做充值和退款 | 已确认 |
| F3-05 | 发票主体 | 明确开票主体、税率、含税/未税、发票类型和客户抬头校验 | 待填写 | 待确认 |
| F3-06 | 开票流程 | 申请 → 审核 → 开票登记 → 票据/文件关联；红冲、作废不可删除原票 | 待填写 | 待确认 |
| F3-07 | 外部平台 | 首版可人工登记，外部开票平台和银行流水接口另定接入契约 | 待填写 | 待确认 |
@@ -140,13 +140,13 @@
| 编号 | 需要确认的事项 | 建议结论 | 最终结论 | 状态 |
|---|---|---|---|---|
| F4-01 | 收入口径 | 按已确认/已发布应收还是已收款确认收入，二者报表分开显示 | 费用分析/利润表一期不做 | 已确认 |
| F4-02 | 成本口径 | 按已确认应付还是已付款确认成本，二者报表分开显示 | 费用分析/利润表一期不做；来源成本仍用于应付结算 | 已确认 |
| F4-03 | 分摊维度 | 支持客户、订单、单票、柜次、费用项目；明确公共成本分摊算法 | 一期只为来源和结算保留真实分摊，不开发利润分析页面 | 已确认 |
| F4-04 | 汇率 | 明确交易日、账单日或月末汇率，以及本位币和汇兑损益 | 一期只支持 CNY，不做汇率 | 已确认 |
| F4-05 | 期间锁定 | 月结后报表冻结；调整通过新期间补差/冲销反映 | 一期不做月结 | 已确认 |
| F4-06 | 利润维度 | 客户、货柜、单票、月份均支持；每个结果可钻取到收入、成本、分摊和原始单据 | 一期不做利润表 | 已确认 |
| F4-07 | 导出与权限 | 导出按财务数据权限控制，客户不可见供应商成本和内部利润 | 一期无利润菜单、路由或权限 | 已确认 |
| F4-01 | 收入口径 | 按已确认/已发布应收还是已收款确认收入，二者报表分开显示 | 费用分析/利润表订单与客户不做 | 已确认 |
| F4-02 | 成本口径 | 按已确认应付还是已付款确认成本，二者报表分开显示 | 费用分析/利润表订单与客户不做；来源成本仍用于应付结算 | 已确认 |
| F4-03 | 分摊维度 | 支持客户、订单、单票、柜次、费用项目；明确公共成本分摊算法 | 订单与客户只为来源和结算保留真实分摊，不开发利润分析页面 | 已确认 |
| F4-04 | 汇率 | 明确交易日、账单日或月末汇率，以及本位币和汇兑损益 | 订单与客户只支持 CNY，不做汇率 | 已确认 |
| F4-05 | 期间锁定 | 月结后报表冻结；调整通过新期间补差/冲销反映 | 订单与客户不做月结 | 已确认 |
| F4-06 | 利润维度 | 客户、货柜、单票、月份均支持；每个结果可钻取到收入、成本、分摊和原始单据 | 订单与客户不做利润表 | 已确认 |
| F4-07 | 导出与权限 | 导出按财务数据权限控制，客户不可见供应商成本和内部利润 | 订单与客户无利润菜单、路由或权限 | 已确认 |
## 八、全量验收主链路
财务管理/财务领域模型与数据字典.md
+2 -2
View File
@@ -1,11 +1,11 @@
# 财务领域模型与数据字典（F0/F1 首版）
> **范围说明**：本文包含长期数据模型候选。钱包、充值、发票、费用分析和利润表不属于一期，不得据此建菜单、路由或接口；一期数据模型以《财务一期五页产品与接口验收契约》为准。
> **范围说明**：本文包含长期数据模型候选。钱包、充值、发票、费用分析和利润表不属于订单与客户，不得据此建菜单、路由或接口；订单与客户数据模型以《财务核心五页产品与接口验收契约》为准。
> 版本：V0.1（开发前设计稿）
> 日期：2026-08-10
> 范围：F0 财务底座、F1 客户应收与对账；F2-F4 预留
> 关联：[财务服务边界设计](财务服务边界设计.md)、[财务管理产品确认表](财务管理产品确认表.md)、[二期费用项目数据归属决策记录](../二期/二期费用项目数据归属决策记录.md)
> 关联：[财务服务边界设计](财务服务边界设计.md)、[财务管理产品确认表](财务管理产品确认表.md)、[入库测量与计费费用项目数据归属决策记录](../入库测量与计费/入库测量与计费费用项目数据归属决策记录.md)
## 1. 阅读和决策标记
财务管理/财务领域模型与跨服务契约.md
+1 -1
View File
@@ -1,6 +1,6 @@
# 财务领域模型与跨服务契约（历史合并稿）
> **历史文档，非一期实施依据**：本合并稿已被《财务领域模型与数据字典》《Firstleg-Finance 跨服务契约》和《财务一期五页产品与接口验收契约》替代。钱包、充值、发票、费用分析和利润模型不属于一期。
> **历史文档，非订单与客户实施依据**：本合并稿已被《财务领域模型与数据字典》《Firstleg-Finance 跨服务契约》和《财务核心五页产品与接口验收契约》替代。钱包、充值、发票、费用分析和利润模型不属于订单与客户。
> 文档状态：已被拆分替代，仅保留历史设计过程，不作为后续实施依据
> 替代文档：[财务领域模型与数据字典](财务领域模型与数据字典.md)、[Firstleg-Finance 跨服务契约](Firstleg-Finance跨服务契约.md)