docs/财务管理/财务对账结算P1闭环.md

财务对账结算 P1 闭环

1. P1 目标与结论

P1 解决费用进入 Finance 应收应付池之后的完整财务流转。当前测试环境已经通过真实业务造数和真实 HTTP 验收，费用池、客户对账单、应收结算单、应付结算单、收款、付款及导出链路可以作为后续财务建设的稳定基础。

统一链路如下：

PUBLISHED 费用来源
  -> Finance 幂等入池
  -> AVAILABLE 待出单
  -> 客户对账单（草稿 / 审核 / 出账 / 客户确认）
  -> 应收或应付结算单
  -> 部分收款 / 全额收款，或部分付款 / 全额付款
  -> 客户账户与不可变流水同步更新

PAYABLE + DIRECT_PAID 只进入已确认成本，不进入 AP 待结算池。已由资金账户结算的应收来源标记为已结算，不得再次生成对账单。

2. 出单规则

对象	选择条件	分组口径	结果
客户对账单	RECEIVABLE + AVAILABLE，客户、币种和业务日期符合条件	客户 + 币种 + 账期	费用来源被占用，不能重复出单
应收结算单	已出账且有效的客户对账单	客户 + 币种	可登记一笔收款分配多张应收单
应付结算单	PAYABLE + AVAILABLE + ON_ACCOUNT	供应商 + 币种 + 业务期间	可部分付款或全额付款
直接已付成本	PAYABLE + DIRECT_PAID	客户 + 供应商 + 业务来源	保存成本和支付证据，不生成 AP

创建时服务端重新校验来源状态、客户、供应商、币种和占用关系。相同来源不能进入两张有效单据；跨客户、跨供应商或混合币种请求必须原子拒绝。

3. 单据生命周期

客户对账单支持草稿创建、修改、审核、驳回、重开、出账、客户确认、调整新版本和作废。客户只能读取并确认本企业已经出账且等待确认的单据，确认必须携带当前版本和幂等键。

AR/AP 结算单支持出单、部分收付、全额收付、未发生收付时作废和作废后重开。已经发生收付款的结算单不能作废；超额收款或付款必须拒绝且金额不漂移。

费用来源一旦进入有效对账单或结算单，其当前版本被冻结。来源侧编辑、调整和作废均被拒绝，历史金额只能通过财务单据调整形成新版本，不覆盖原记录。

4. 金额与并发不变量

1. 对账单明细合计等于对账单总额，应收结算单合计等于对应已出账金额。
2. 应付结算单明细合计等于所选供应商 ON_ACCOUNT 应付来源合计。
3. 每次收付款后，已收/已付 + 未收/未付 = 单据总额。
4. 公共柜费各客户分摊合计等于柜费总额；客户分摊和供应商应付分别保存。
5. 相同幂等键、相同载荷返回同一结果；相同键、不同载荷返回冲突。
6. 写操作携带当前版本；旧版本并发请求被拒绝，单据、来源和账户流水保持零漂移。
7. 平台不能把第二客户的收款、付款或来源分配到第一客户单据；客户也不能读取或确认其他客户单据。

5. 页面与数据口径

平台财务主流程由客户账户、客户应收应付、客户对账单、结算单应收、结算单应付五个页面承载。客户工作台提供资金账户与对账单查询，账单明细按真实入仓码关联头程业务详情。

客户账户页是 Finance 主账汇总，展示待收、待出账、本期已收、总成本、已线下支付供应商款和待付供应商款；资金账户余额、授信、冻结和充值仍按当前资金账户契约独立保存，不能用对账单派生值覆盖。

所有列表和详情使用业务编号；数据库 ID 仅用于接口引用。八类财务导出从异步下载中心生成真实 XLSX，并遵守筛选、权限、长整型字符串精度、并发任务门禁和失败信息可见规则。

6. P1 验收证据

测试环境最终全链报告：baiyue-firstleg/reports/admin-test-env-acceptance-20260909103401.json。

验收项	结果
真实 HTTP 全链	1518/1518，通过；902 个真实请求，10 个模块
来源类型	KG 自动运费、CBM 自动运费、单票人工应收/应付、柜级公共费用、海外 DIRECT_PAID
对账单	按勾选/日期生成、幂等、驳回重开、审核出账、客户确认、调整、作废
结算	3 张 AR、1 张 AP；部分/全额收付、超额拒绝、作废重开
冻结与隔离	已占用来源禁止变更；跨客户读、确认、收款和付款均拒绝
导出	8 类真实 XLSX、权限、筛选、长 ID、并发限制和 Provider 失败可见均通过
本地 Finance 聚合测试	200/200，通过
Admin 财务专项测试	157/157，通过；生产构建通过
Client 全量测试	277/277，通过；生产构建通过
Finance HTTP 合同脚本	69/69，通过

7. 本轮收口修正

P1 没有发现 Finance 单据状态机或金额处理缺陷。发现并修正的是全链验收造数不完整：

• 自动费用订单现在绑定价格簿中的精确 KG/CBM 价格组合，并向客户估价请求传入对应 chargeMode。
• 不包税自动计费先从真实入库单读取 businessType，再通过正式 API 检查或创建匹配的客户计费规则。
• CBM 测量样本使用真实体积重高于实重的数据，确保验证实际 VOLUME_CBM 路径。
• 柜级费用使用独立的第六票测量订单，避免已发送费用的冻结规则阻断装柜关系变化。
• 装柜完成前冻结托盘标签会锁定并写入标签快照，因此该命令使用可写事务，避免只读事务导致真实装柜完成失败。
• 自动费用造数只选择已配置内部编号且被 ACTIVE 价格簿覆盖的 FBA 仓；测试环境 ABE3 已通过正式仓库接口补齐内部编号。

这些修正只增强验收数据和证据，不绕过生产权限、状态机、幂等、服务边界或数据库约束。