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

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

> 日期：2026-08-11  
> 状态：产品范围已确认；Finance 来源链与五页查询契约已实现并验证，剩余 11 个目标 operation、Admin 五页接入及跨服务 HTTP 冒烟待完成  
> 领导验收范围：客户账户、客户应收应付、客户对账单、结算单应收、结算单应付  
> 原型依据：`docs/悦/货代SAAS平台后台/货代SaaS平台原型.html`

> 目标 OpenAPI：`openapi/finance-phase1-five-pages-v1.yaml`；当前人工接口继续参考 `openapi/finance-f1-manual-v1.yaml`。

## 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、应收、已收、余额、关联对账单、业务期间、生成日、到期日、收款状态、制单人、状态 | 从审核通过对账单生成、详情、部分收款、导出、作废/重开；不保留高级查询假入口 | `DRAFT -> ISSUED -> PARTIALLY_PAID -> PAID`，未收款可作废；出账后冻结，调整保留 revision；收款人工表单和图片沿用 F1 契约 |
| 结算单应付 | 汇总卡、供应商筛选、列表、详情、费用明细、付款记录 | 结算单号、供应商、费用类型、CNY、应付、已付、余额、来源期间、生成日、到期日、付款状态、制单人、审核人、状态 | 从审核通过且参与结算的应付来源生成、详情、审核、部分付款、导出、作废/重开；删除利润分析和利润审批按钮 | `DRAFT -> PENDING_REVIEW -> ISSUED -> PARTIALLY_PAID -> PAID`，拒绝/作废保留记录；付款为人工登记和凭证图片 |

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

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

| 页面 | 当前仓库事实 | 一期目标 | 差异等级 |
|---|---|---|---|
| 客户账户 | 后端已新增 `/customer-accounts/{customerId}` 和固定读 DTO；无列表接口 | 派生财务往来汇总、详情和流水，无任何充值/余额写入口 | IMPLEMENTED（单客户查询）；列表/筛选仍缺，Finance DTO 测试通过 |
| 客户应收应付 | `/fee-pool` 固定 DTO、Firstleg 事件/快照和 `fin_fee_source` 写入均已实现并验证 | 真实入库/柜子费用来源池，支持审核、参与结算、详情和生成对账单 | 查询与来源入池已实现；详情/页面操作仍是 P0/P1 |
| 客户对账单 | 后端已新增 `/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 个目标 operation、Admin 五页接入和测试环境跨服务冒烟。

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

```mermaid
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` 字段；已有列表、新增、编辑、删除、审核通过和驳回接口。

仍缺：

- 通用费用的“参与结算/禁止结算”接口和原因、操作人、版本控制。
- 非 FBA 头程运费的统一发布动作；当前发布主要由 FBA 费用发送流程触发。
- 费用调整/作废事件及旧版本替代规则的完整实现。
- Finance 消费者和来源快照写入。

### 4.2 柜子费用项

当前工作树已新增柜子费用来源表/实体、Controller、审核/参与结算/作废服务、发布事件和内部快照代码；这些文件尚未形成通过测试的稳定基线。既有 Firstleg 柜次体积快照仍只服务 Finance 人工整柜成本分摊，不能替代新来源模型的审核和不可变发布链路。

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

- `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
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 快照和版本状态；供应商顶层字段及对账单占用关系仍待后续模型落地 |
| `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. 入库费用独立的参与结算/禁止结算和通用发布动作；柜子费用来源模型已完成，不再列为阻断。
2. 客户对账单、应收结算单、应付结算单的数据模型、状态机和剩余 11 个 operation。

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

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

## 8. 当前确认项

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