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、汇率、开票日期、利润审批、利润金额仅为历史原型字段，一期删除。

客户对账单、应收结算单、应付结算单统一使用短业务编号：`REC-YYMMDD-NNNN`、`AR-YYMMDD-NNNN`、`AP-YYMMDD-NNNN`。日期按北京时间的单据创建日计算，各单据类型分别按日从 `0001` 递增；编号生成后不可修改，作废也不回收。

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

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

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

派生公式：

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

## 3. 五页验收矩阵

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

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

### 3.1 五页现状/目标差异

| 页面 | 当前仓库事实 | 一期目标 | 差异等级 |
|---|---|---|---|
| 客户账户 | 后端已新增 `/customer-accounts/{customerId}` 和固定读 DTO；无列表接口 | 派生财务往来汇总、详情和流水，无任何充值/余额写入口 | IMPLEMENTED（单客户查询）；列表/筛选仍缺，Finance DTO 测试通过 |
| 客户应收应付 | `/fee-sources` 固定 DTO、Firstleg 事件/快照和 `fin_fee_source` 写入均已实现 | 真实入库/柜子费用来源池，支持编辑、提交、审核、调整、作废、详情和生成对账单 | 审核通过自动成为结算候选，不提供人工结算开关 |
| 客户对账单 | 后端已新增 `/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. 费用来源到结算全链路

```mermaid
flowchart LR
    I["入库单费用项"] --> R["审核"]
    C["柜子费用项"] --> R
    R --> 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 消费者和来源快照写入已经实现。费用来源采用编辑、提交、审核、调整、作废闭环；审核通过后自动发布，不再提供参与结算开关。

### 4.2 柜子费用项

当前柜子费用来源表/实体、Controller、审核/调整/作废服务、自动发布事件、Relay 和内部快照已经实现。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/版本/金额，因此生成对账单/结算单时还必须改为只选择本地合格来源并由服务端取金额。

目标写入条件：

```text
reviewStatus = APPROVED
publicationStatus = PUBLISHED
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` | 已有 |
| 入库费用发布 | 审核通过后自动发布，无独立人工开关 | 已确认 |
| 柜子费用 | `/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-sources` 及 edit/submit/review/adjust/void | 已实现编辑审核闭环；无“是否结算”接口 |
| 客户对账单 | `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、方向、客户、供应商、订单/入库/柜次、业务日、费用项、数量/单价/金额、审核、发布、状态、占用单据 | 不保存人工结算开关；供应商 ID/名称与可空类别约束均来自上游不可变快照 |
| `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. 财务 operation 全部通过直接行为测试：账户列表/流水；费用来源详情及编辑审核闭环；对账单生成、审核、出账、客户确认、调整/作废；应收/应付结算单生成与详情；人工收付款登记。人工收款继续覆盖 300 元分配 3 张 100 元应收单等回归。
2. 对账单、应收/应付结算单、付款和 revision 所需数据模型与唯一约束同步落地，不能只做空 Controller。
3. 详细冻结契约见 `财务一期P0操作契约与验收用例.md`；不得把其中任何一项标为 P1、后续优化或假入口。

### P1：领导验收前必须完成

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

## 8. 当前确认项

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