docs/财务管理/财务一期五页产品与接口验收契约.md

财务一期五页产品与接口验收契约

日期：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。

1. 一期范围结论

一期只交付原型中的以下 5 页，并实现页面结构、字段、筛选、详情和状态：

1. 客户账户。
2. 客户应收应付。
3. 客户对账单。
4. 结算单应收。
5. 结算单应付。

明确不做：费用分析、利润表、钱包、预收、手动充值、自动扣款余额、汇率、外币、发票、月结、银行自动对账。未实现能力不得保留按钮、菜单、路由或模拟成功入口。

所有金额只使用 CNY。原型中的 USD、汇率、开票日期、利润审批、利润金额仅为历史原型字段，一期删除。

2. 客户账户冲突处理（已确认）

原型客户账户是“预充值余额 + 冻结 + 可用余额 + 手动充值”的钱包模型，与此前确认的“不做钱包/预收”冲突。产品已确认按以下方案处理，不再等待额外产品结论：

• 页面保留“客户账户”名称和客户汇总/详情/流水结构，但定位为客户财务往来总览，不是资金账户。
• 删除“手动充值”按钮、充值弹窗、充值方式和充值凭证号；不设计充值 API。
• 不显示可消费额度，不允许业务系统按余额自动扣款。
• 原型钱包指标改为财务派生指标：未收余额、待出账金额、本期已收金额；列表和详情使用相同口径。
• 流水只来自费用来源纳入/排除、对账单生成/调整/作废、结算单生效和人工收付款登记，不允许直接修改余额。

派生公式：

指标	公式
未收余额	生效应收结算单应收金额合计 - 已收金额合计
待出账金额	AVAILABLE + APPROVED + settlementIncluded=true 且未进入有效对账单的应收费用来源金额合计
本期已收金额	查询期间内有效收款分配金额合计
应付余额	生效应付结算单应付金额合计 - 已付金额合计

3. 五页验收矩阵

页面	原型结构和筛选	一期字段	一期操作	状态与验收
客户账户	汇总卡、客户列表、账户详情、流水详情；客户名称/编号、账户状态、余额条件、流水类型和日期	客户基本信息、客户编号、联系人、电话、未收余额、待出账金额、本期已收金额、应付余额、账户状态、最后变动时间；流水号、时间、业务类型、关联单据、应收/应付变动、变动后未收余额、操作人、备注	详情、查询、重置、导出；无充值、扣款或余额调整	客户主体正常/停用只影响访问和新业务；所有金额可由来源、单据和收付款逐笔追溯，禁止直接写余额
客户应收应付	工具栏、组合查询、选中汇总、费用列表、费用详情、审核进度、关联业务、操作记录	客户、费用单号、是否已生成对账单、参与结算、审核状态、应收/应付、入仓码/柜次号、业务状态、费用类型、金额、业务发生日、来源类型、来源版本	详情、审核通过、审核拒绝、编辑未审核人工项、参与结算/禁止结算、按截止时间或勾选生成；已发布来源不可删除，只能作废/调整	PENDING -> APPROVED/REJECTED；只有 APPROVED + INCLUDED + AVAILABLE + CNY 可生成；同一来源版本不能重复进入有效单据
客户对账单	查询区、主表、账单明细、支付历史；审核状态、账单编号、客户、柜次、结算起止日、是否结清、创建日期、最后收款时间	对账单号、客户、期间、账期、CNY、总应收、已收、未收、最后收款时间、是否结清、备注、创建/更新人时间；明细保留入仓单/柜次、业务日、计费量、费用项、金额、来源版本	生成草稿、详情、导出、审核通过、审核拒绝、作废；不提供发票和汇率操作	DRAFT -> PENDING_REVIEW -> APPROVED/REJECTED/VOIDED；审核通过后来源冻结，调整必须留 revision；支付历史只读展示有效收款
结算单应收	汇总卡、筛选、列表、详情、费用明细、收款记录；收款状态、客户、结算单号	结算单号、客户、CNY、应收、已收、余额、关联对账单、业务期间、生成日、到期日、收款状态、制单人、状态	从已出账对账单生成、详情、部分收款、导出、作废/重开；不保留高级查询假入口	生成后直接 ISSUED -> PARTIALLY_PAID -> PAID；来源已在对账单阶段审核，结算单不重复增加假审批；未收款可作废，调整保留 revision
结算单应付	汇总卡、供应商筛选、列表、详情、费用明细、付款记录	结算单号、供应商、费用类型、CNY、应付、已付、余额、来源期间、生成日、到期日、付款状态、制单人、状态	从审核通过且参与结算的应付来源生成、详情、部分付款、导出、作废/重开；删除利润分析和利润审批按钮	生成后直接 ISSUED -> PARTIALLY_PAID -> PAID；不重复增加结算单审批；作废/重开保留 revision，付款为人工登记和凭证图片

表格“操作”列必须位于第一列。原型中未形成真实闭环的“新增、生成账单、高级查询、快捷导出”等按钮，只有在对应接口和权限完成后才显示。

3.1 五页现状/目标差异

页面	当前仓库事实	一期目标	差异等级
客户账户	后端已新增 /customer-accounts/{customerId} 和固定读 DTO；无列表接口	派生财务往来汇总、详情和流水，无任何充值/余额写入口	IMPLEMENTED（单客户查询）；列表/筛选仍缺，Finance DTO 测试通过
客户应收应付	/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 个 P0 operation 不在本契约记录开发中间态；是否放行只看 G1-G4 后端行为测试与 Admin 真实接入证据。

4. 费用来源到结算全链路

flowchart LR
    I["入库单费用项"] --> R["审核"]
    C["柜子费用项"] --> R
    R --> S["参与结算/禁止结算"]
    S --> P["发布不可变来源版本"]
    P --> X["Finance Inbox"]
    X --> F["fin_fee_source"]
    F --> A["客户应收应付费用池"]
    A --> B["客户对账单"]
    B --> AR["结算单应收"]
    A --> AP["结算单应付"]
    AR --> CR["人工收款与分配"]
    AP --> CP["人工付款与凭证"]
    CR --> CA["客户账户派生汇总/流水"]
    CP --> CA

4.1 入库单费用项

现有 fl_inbound_fee_detail 已具备客户、入库单、方向、业务日、费用项快照、计费量、单价、金额、审核、发布和 settlement_included 字段；已有列表、新增、编辑、删除、审核通过和驳回接口。

当前 Firstleg 来源发布、调整/作废事件、Relay、Finance 消费者和来源快照写入已经实现并通过测试。Finance 五页内的费用来源详情、二次审核和参与结算操作仍按一期 P0 补齐；这些操作不得绕过已发布不可变来源版本或覆盖上游业务事实。

4.2 柜子费用项

当前柜子费用来源表/实体、Controller、审核/参与结算/作废服务、发布事件、Relay 和内部快照已经实现，相关定向测试 17/17 通过。Firstleg 的真实柜次体积快照同时服务 Finance 整柜成本分摊，但仍不能由 Admin 手工提交的订单归属或体积替代。

一期至少需要业务侧模型：

• containerFeeId/version、containerId/containerNo、费用方向、费用项目、业务日、CNY 金额。
• 应付来源必须有供应商；应收来源必须有客户分摊结果。
• 审核状态、参与结算状态、发布状态、作废/调整原因和操作审计。
• 柜内跨客户时，业务侧按真实体积形成不可变客户分摊行；Finance 只接收客户级来源，不自行猜测客户归属。

建议新增 fl_container_fee_detail + fl_container_fee_allocation，或建立统一 fl_business_fee_source；这是技术选型，不改变上述产品字段和验收结果。

4.3 Finance 来源池

当前 FinanceFeeSourceEventService 已通过 POST /internal/finance/v1/fee-source-events 消费 Firstleg 事件，回查不可变快照，并在本地事务中写 fin_inbox_event 与 fin_fee_source。相同事件和内容返回原来源；同事件异内容冲突；调整写新版本并把旧 AVAILABLE 版本标为 SUPERSEDED；作废只标 VOIDED，不删除历史。现有人工账单入口仍允许 Admin 提交来源 ID/版本/金额，因此生成对账单/结算单时还必须改为只选择本地合格来源并由服务端取金额。

目标写入条件：

reviewStatus = APPROVED
publicationStatus = PUBLISHED
settlementIncluded = true
sourceStatus = ACTIVE
currency = CNY
amount > 0
customer/supplier/business reference complete

Finance 必须通过 Inbox 幂等消费来源版本，或通过受保护的快照接口拉取后落库；禁止 Admin 直接构造来源金额。来源调整新增版本，已进入有效单据的旧版本不覆盖。

5. 目标接口矩阵

页面/链路	目标接口	当前状态
入库费用审核	`POST /api/platform/v1/inbounds/{inboundId}/fee-details/{detailId}/approve	reject`
入库费用参与结算	PUT /api/platform/v1/inbounds/{inboundId}/fee-details/{detailId}/settlement-inclusion	缺失
入库费用发布	POST /api/platform/v1/inbounds/{inboundId}/fee-details/{detailId}/publish	通用入口缺失
柜子费用	/api/platform/v1/loading-plans/{loadingPlanId}/fee-details/**	模型、审核/调整/作废、事件、Relay 和快照已实现；Firstleg 相关 17/17 定向测试通过
Finance 来源接入	POST /internal/finance/v1/fee-source-events	已实现并验证；来源专项 10/10、Finance 全量 35/35、Firstleg 相关 17/17 通过
客户账户	GET /api/platform/finance/v1/customer-accounts/{customerId}	已实现固定 DTO 单客户查询并通过测试；列表接口仍缺失
客户应收应付	GET /api/platform/finance/v1/fee-pool?customerId=&direction=	已实现固定 DTO 查询并通过测试；详情、审核和参与结算操作仍缺失
客户对账单	GET /api/platform/finance/v1/statements?customerId=、GET /api/platform/finance/v1/bills/{billId}	已实现固定 DTO 查询并通过测试；生成/审核操作仍缺失
结算单应收	GET /api/platform/finance/v1/receivable-settlements?customerId=	已实现固定 DTO 查询并通过测试；生成与页面动作仍缺失
应收人工收款	GET/POST /api/platform/finance/v1/receipts	已实现平台固定 DTO、多账单分配、合计校验、共用凭证和 File fail-closed；测试通过
结算单应付	GET /api/platform/finance/v1/payable-settlements?customerId=	已实现固定 DTO 查询并通过测试；应付生成、审核和付款仍缺失

6. 最小数据模型

模型	必要字段	当前缺口
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
fin_settlement_line	结算单、对账单/来源行、费用项和金额快照	当前账单行只覆盖部分 AR
fin_payment/分配	收/付款、对象、日期、方式、凭证、金额、分配、操作人	收款已有；付款缺失
账户视图	客户、未收、待出账、本期已收、应付、最后变动	应由上述表聚合，不新增可写余额表

7. 专项优先级

P0：一期验收硬阻断

1. 以下 11 个 operation 全部实现并通过直接行为测试：账户列表/流水；费用来源详情/审核/参与结算；对账单生成及出账/调整/作废；应收/应付结算单生成；结算单详情；人工付款登记。人工收款已实现但必须继续通过 300 元分配 3 张 100 元应收单等 P0 回归。
2. 对账单、应收/应付结算单、付款和 revision 所需数据模型与唯一约束同步落地，不能只做空 Controller。
3. 详细冻结契约见 财务一期P0操作契约与验收用例.md；不得把其中任何一项标为 P1、后续优化或假入口。

P1：领导验收前必须完成

1. 5 页 Admin 菜单、路由、字段、筛选、详情、状态和权限。
2. 删除费用分析、利润表、手动充值、利润审批、汇率/外币/发票及所有假入口。
3. 来源金额与对账单/结算单金额逐层勾稽报告。
4. 跨客户、跨供应商、重复来源、已占用来源、调整/作废和并发版本测试。
5. Finance → Firstleg/File 真实 HTTP 冒烟和 5 页端到端验收。

8. 当前确认项

客户账户冲突已由产品确认：采用派生财务往来总览，不做钱包/预收/充值。当前没有遗留的核心产品冲突；剩余均为接口、数据模型和实现门禁。