# 财务管理闭环盘点与范围建议

> 盘点日期：2026-08-10  
> 当前状态：开发前详细设计，未进入业务开发
> 盘点范围：二期入库计费现状、平台后台财务原型、Admin/Client/Firstleg 当前实现  
> 结论口径：本文区分“代码已实现”“原型展示”和“建议范围”；原型功能不自动成为开发范围。

产品/业务逐项确认请使用：[财务管理产品确认表](财务管理产品确认表.md)。

产品回传后的差异和剩余门禁见：[财务管理产品确认版差异与剩余待确认](财务管理产品确认版差异与剩余待确认.md)。

技术边界已确认：[财务服务边界设计](财务服务边界设计.md)。Finance 采用独立服务和独立数据库，Firstleg 仅提供业务费用来源。

开发前总控门禁与 F0/F1 任务清单：[财务开工门禁与F0-F1任务清单](财务开工门禁与F0-F1任务清单.md)。

详细设计材料：

- [财务来源接入现状](财务来源接入现状.md)
- [财务领域模型与数据字典](财务领域模型与数据字典.md)
- [Firstleg-Finance跨服务契约](Firstleg-Finance跨服务契约.md)
- [F1 人工账单、收款、成本接口契约](F1人工账单收款成本接口契约.md)
- [财务历史迁移与上线验收方案](财务历史迁移与上线验收方案.md)
- [财务F0实施任务拆分](财务F0实施任务拆分.md)

历史合并稿：[财务领域模型与跨服务契约](财务领域模型与跨服务契约.md) 已由“领域模型与数据字典”和“Firstleg-Finance 跨服务契约”两份文档替代，不作为后续实施依据。

## 一、结论

当前首期已确定采用人工简化方案：平台财务人工填写账单、收款和成本表单并上传凭证，客户只读；首期不做银行自动对账、自动核销任务、复杂审批、客户钱包、发票、供应商在线结算、汇率、月结或总账。完整原型能力仅作为后续扩展参考，不作为本期开工范围。

当前已经实现了从入库测量数据到对客头程费用发布的**业务计费闭环**：

```text
测量/称重
  -> 测量审核
  -> 计费规则匹配
  -> 费用试算与快照
  -> 发布对客费用
  -> 客户只读查看
  -> 完成入库
```

当前尚未实现从费用到资金结清的**财务闭环**：

```text
已发布费用
  -X-> 对账单
  -X-> 应收单
  -X-> 收款记录
  -X-> 核销
  -X-> 结清/反核销
```

因此，“已经算出重量、体积和金额”只说明已经有可进入财务流程的费用来源，不代表已经形成应收、账单或收款。现状可以支撑财务一期以“客户应收”为起点继续建设，但不能直接宣称财务管理已经闭环。

本轮确认“全部都需要做”后，目标范围升级为覆盖原型财务菜单的完整财务域：客户账户、客户应收应付、客户对账单、结算单应收、结算单应付、收付款与核销、费用分析、发票和利润报表。仍建议按依赖关系分阶段交付，避免在应收、应付、钱包和利润各自造一套金额口径。

## 二、事实来源与边界

本次按以下资料核对：

1. 二期需求文档明确二期只做头程计费，不自动形成应收、应付、对账单、收付款、核销、发票、利润或总账。
2. 平台后台原型提供财务管理全量参考，但其中数据和交互主要由单页 HTML 内的静态数据及前端脚本驱动。
3. 当前代码用于证明“已经实现什么”，不反向扩大产品范围。

主要依据：

- `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/`
- `apps/admin-web/src/prototype/modules/finance/`
- `apps/client-web/src/modules/first-leg/`
- `apps/client-web/src/modules/finance/`
- `baiyue-firstleg/firstleg/`

## 三、当前已经具备什么

### 3.1 可作为财务上游的业务数据

| 能力 | 当前状态 | 可复用价值 | 不能代表什么 |
|---|---|---|---|
| 实测重量、体积、计费量 | 已实现 | 作为费用计算依据和业务快照 | 不是财务凭证 |
| 客户计费规则、船司价格 | 已实现 | 产生确定的对客头程价格 | 船司价格不等于供应商应付 |
| 费用试算、确认、发布 | 已实现 | 形成版本化对客费用快照 | 不等于应收单或账单 |
| 费用调整 | 已实现 | 已发布费用调整生成新版本并留原因 | 尚未定义已出账或已核销后的调整方式 |
| 客户侧费用查看 | 已实现 | 客户能看到入库及已发布费用结果 | 客户尚不能确认账单、提出争议或查看核销结果 |
| 费用项目主数据 | 已实现 | 支持费用编码、分类、国内/国际、提货/仓库应收应付属性 | 费用项目属性不自动生成财务记录 |
| 入库费用明细 | 后端已实现 | 支持人工新增、编辑、删除、审核、自动发布的入库运费明细 | 尚无跨入库单财务台账和结算生命周期 |
| 权限与审计基础 | 部分具备 | 费用明细查看、编辑、删除、审核已有权限和业务审计 | 财务制单、复核、收款、核销、反核销权限尚未定义 |

### 3.2 当前费用明细的真实边界

Firstleg 已有 `fl_inbound_fee_detail`，包含：

- 入库单、费用项目、方向、业务发生日、币种、单价、金额；
- 重量、体积、计费量等业务快照；
- 审核状态、审核人、驳回原因；
- 发布状态、发布时间、是否参与结算；
- 自动计费来源的费用单号和版本。

但当前仍存在以下断点：

- 自动发布链路只生成 `RECEIVABLE` 对客运费。
- 人工明细虽然允许选择 `PAYABLE`，但模型没有完整供应商/往来单位、付款条件、成本归属等应付结算字段。
- 人工明细审核通过后没有“发布并纳入结算”的完整状态迁移；新建时 `settlementIncluded=false`，现有接口没有形成账单的操作。
- 已发布应收明细只能按单个入库单查询，未形成按客户、币种、账期聚合的财务台账。
- 没有冻结、出账、核销后的费用变更规则，无法保证历史账单金额稳定。

## 四、原型中有什么

平台后台原型的财务菜单包含以下能力：

| 原型模块 | 原型展示的主要能力 | 当前代码状态 | 是否能直接纳入首期 |
|---|---|---|---|
| 客户账户 | 余额、冻结金额、可用余额、充值、扣款流水 | 未实现 | 否，这是预存款/钱包模型，需单独确认资金合规和扣款规则 |
| 客户应收应付 | 费用明细、审核、参与结算、按截止时间或勾选生成账单 | 仅有入库费用明细后端基础；无正式财务页面 | 可裁剪为应收费用池 |
| 客户对账单 | 账期、汇率、应收、已收、结清、明细和支付历史 | 未实现 | 可作为应收闭环核心，但汇率和开票先暂缓 |
| 结算单应收 | 应收、已收、余额、到期日、审批、部分收款 | 未实现 | 可合并进账单/应收单，避免首期重复建模 |
| 结算单应付 | 供应商应付、已付、余额、审批、部分付款、利润 | 未实现；上游成本来源不完整 | 否，建议后续独立阶段 |
| 费用分析 | 内外部费用对比、趋势和明细 | 未实现 | 否，依赖稳定应收/应付口径 |
| 利润表 | 按客户、货柜、单票、月份统计收入、成本、利润率 | 未实现 | 否，依赖应收、成本、汇率及分摊规则 |

原型还出现了发票抬头、开票日期、汇率、支付方式、收付款凭证号等字段。它们只说明未来可能需要，不代表当前产品已经确认税务、外币折算、资金或发票边界。

当前 Admin 中财务导航整体为隐藏状态，路由指向 `src/prototype/` 占位页；Client 的“应付账单”也标记为 `release: 'prototype'`。这些页面不可作为已交付能力。

## 五、当前闭环断点

| 序号 | 断点 | 直接影响 |
|---|---|---|
| 1 | 没有财务费用池的跨订单查询和筛选 | 财务无法集中选择待出账费用 |
| 2 | 没有费用冻结/锁定规则 | 账单生成后上游调整可能改变应收依据 |
| 3 | 没有对账单及唯一编号、账期、版本 | 无法向客户确认一个确定期间的应收集合 |
| 4 | 没有平台财务调整、作废重开和线下异议记录机制 | 客户反馈金额有误时无法在保留历史的前提下纠错 |
| 5 | 没有应收单及到期规则 | 无法管理待收、部分收款、逾期和结清 |
| 6 | 没有收款记录和凭证 | 无法证明资金已到账 |
| 7 | 没有核销与反核销 | 收款不能对应到具体账单或费用，也无法纠错 |
| 8 | 没有跨单据审计链 | 无法从入库费用追溯到对账、收款和核销 |
| 9 | 没有财务级幂等和并发约束 | 重复生成账单、重复核销和超额核销风险无法控制 |
| 10 | 没有财务报表口径 | 原型统计数字无法由真实台账可靠计算 |

## 六、全量财务规划与交付顺序

### 6.1 全量目标域

| 目标域 | 业务结果 | 主要来源 | 不能提前假定的口径 |
|---|---|---|---|
| 客户账户 | 预存、冻结、扣款、退款、账户流水 | 客户充值、业务扣款 | 是否采用钱包作为应收结算方式、资金归属和退款规则 |
| 客户应收 | 客户欠款、到期、逾期、结清 | 已发布对客费用、补差/冲销 | 收入确认节点和账期规则 |
| 客户应付 | 客户代垫或返还类应付款（如确有业务） | 业务费用或人工单据 | 产品是否真的存在“平台向客户付款”的场景 |
| 客户对账单 | 期间内费用汇总、明细、平台出账和客户只读查看 | 应收/应付费用池 | 一张账单是否允许混合方向、混合币种 |
| 结算单应收 | 可审批、可收款、可核销的应收结算单 | 已确认客户账单 | 与客户对账单是一对一还是一对多 |
| 结算单应付 | 供应商成本、付款、余额和结清 | 供应商费用、运力/仓储/报关成本 | 成本确认、供应商账期、审批和付款方式 |
| 收付款与核销 | 到账/付款凭证，部分结算、反核销 | 银行流水或人工登记 | 是否首期接银行流水，是否允许一笔多单核销 |
| 发票 | 开票申请、开具、红冲、作废和关联 | 已确认应收/收款 | 税率、含税/未税、开票主体、外部平台 |
| 费用分析 | 按费用项目、客户、供应商、期间分析 | 应收应付台账 | 统计按发生制还是结算制 |
| 利润 | 客户/单票/柜次/月度收入、成本、利润率 | 应收收入 + 应付成本 + 分摊 | 汇率、成本分摊、收入成本确认时间 |

### 6.2 分阶段交付顺序

全量目标建议拆成五个可验收阶段：

| 阶段 | 交付范围 | 关键闭环 | 前置依赖 |
|---|---|---|---|
| F0 财务底座 | 独立 Finance 服务/数据库、财务主体、客户/供应商往来单位、币种、费用科目、期间、权限、审计、幂等、金额精度 | 所有后续对象使用同一基础口径 | 服务边界已技术确认；产品确认主体、币种、权限和编码 |
| F1 应收与客户对账 | 应收费用池、平台出账、客户只读查看、结算单应收、收款登记、核销、反核销 | 费用 → 账单 → 应收 → 收款 → 结清 | 当前已发布对客费用来源 |
| F2 应付与供应商结算 | 成本费用池、供应商账单、结算单应付、付款登记、付款核销、应付调整 | 成本 → 供应商账单 → 应付 → 付款 → 结清 | 供应商主数据和真实成本来源 |
| F3 客户账户与发票 | 充值、冻结、扣款、退款、账户流水；开票申请、开票登记、红冲/作废 | 账户余额与应收核销可选联动；应收与发票可追溯 | 资金/税务主体、开票平台和合规口径 |
| F4 分析与利润 | 费用分析、收入成本汇总、客户/单票/柜次/月度利润、利润率、导出 | 应收与应付同源统计，结果可追溯 | F1/F2 结算数据、汇率和分摊规则 |

阶段之间可以并行做页面原型和契约设计，但生产数据链路必须按 F0 → F1/F2 → F3 → F4 验收。F4 不能用原型静态数字先行替代真实台账。

### 6.3 F1 最小财务闭环

F1 先处理当前已经有可靠来源的对客头程费用：

```text
已审核并发布的应收费用明细
  -> 进入待对账费用池
  -> 按客户 + 币种 + 账期生成对账单
  -> 内部复核
  -> 客户只读查看（异议线下反馈）
  -> 平台财务出账后形成应收
  -> 登记实际收款
  -> 将收款核销到应收
  -> 全额核销后结清
  -> 错误时按权限反核销并留审计
```

F1 建议页面：

1. 应收费用池：查询、审核状态、是否参与结算、争议/排除原因。
2. 客户对账单：生成、明细、内部复核、发送、关闭；平台财务可重开或调整。
3. 应收与收款：应收余额、到期日、收款登记、附件/凭证号、部分核销。
4. 核销记录：每笔收款对应哪些应收、核销金额、剩余余额、反核销历史。
5. 客户侧账单：只读明细、查看收款与未结余额；异议通过线下渠道反馈。

F1 暂不包含（在 F2-F4 交付）：

- 供应商应付与付款；
- 客户预充值、余额冻结和自动扣款；
- 发票申请、开票和税务接口；
- 多币种折算与汇兑损益；
- 利润表、利润率和总账；
- 银行流水自动认领；
- 复杂费用分摊和会计凭证。

### 6.4 全量阶段的范围门禁

| 范围 | 开工门禁 |
|---|---|
| 客户账户 | 明确充值是否真实入账、冻结/解冻、退款、自动扣款和资金对账责任；不得直接拿账户余额抵消应收而不留核销记录 |
| 客户应收应付 | 明确客户作为付款方还是收款方；没有真实业务场景的方向不建菜单和数据 |
| 供应商应付 | 必须有供应商主数据、成本来源凭证、审批人、付款方式和付款责任主体 |
| 收付款核销 | 明确人工登记与银行流水的边界；收款、付款、核销、反核销分开授权 |
| 发票 | 明确开票主体、税率、含税/未税、红冲/作废和外部开票平台；未确认前只保留接口扩展位 |
| 费用分析/利润 | 先冻结汇率、收入成本确认日、成本分摊和跨币种折算；报表必须能钻取到原始费用和结算单 |

## 七、必须先确认的产品问题

以下结论没有确认前，只能做可逆的模型和页面设计，不能进入完整开发：

| 编号 | 待确认问题 | 建议默认值 |
|---|---|---|
| F1 | 全量范围是否按 F0 → F1 → F2 → F3 → F4 分阶段交付 | 是，目标范围全部保留；先完成 F0，再按依赖验收，不因先做应收而删除应付、账户、发票和利润 |
| F2 | 账单生成维度 | 客户 + 币种 + 账期；不同币种不合并 |
| F3 | 哪些费用可以进入账单 | `APPROVED + PUBLISHED + settlementIncluded=true` 且未作废、未出账 |
| F4 | 当前已发布头程费用是否自动进入待对账池 | 是，但仍由财务选择并生成账单 |
| F5 | 账单生成后上游费用能否直接调整 | 不能；应走补差单/冲销单并保留原账单 |
| F6 | 客户是否需要在线确认和提出争议 | 首期不需要；客户只读查看，异议线下反馈，由平台财务手动处理 |
| F7 | 是否需要内部复核 | 建议制单与复核权限分离，首期允许同人需业务明确 |
| F8 | 收付款是人工登记还是接银行流水 | F1/F2 先人工登记，F3 再接银行流水；必须保存到账日/付款日、方式、凭证号和附件 |
| F9 | 一笔收款能否核销多张应收，一张应收能否被多次收款 | 两者都允许，禁止累计核销超过余额 |
| F10 | 反核销和作废权限 | 独立高风险权限，必须填写原因并完整审计 |
| F11 | 到期日如何计算 | 由客户结算条款或账单确认日 + 账期天数计算 |
| F12 | 历史已发布费用如何迁移 | 仅迁移满足入池条件且尚未形成线下已结算事实的费用 |

## 八、建议状态模型

状态应按对象拆分，避免把费用、账单和资金状态混为一个字段。

### 8.1 费用明细

```text
DRAFT -> PENDING -> APPROVED -> PUBLISHED -> BILLED
                  -> REJECTED
PUBLISHED/BILLED -> ADJUSTED（通过补差或冲销，不覆盖原记录）
```

### 8.2 对账单

```text
DRAFT -> REVIEWED -> SENT -> CONFIRMED -> CLOSED
                     -> DISPUTED -> DRAFT/VOIDED
```

### 8.3 应收与核销

```text
应收：OPEN -> PARTIALLY_SETTLED -> SETTLED
                 -> OVERDUE
收款：DRAFT -> CONFIRMED -> PARTIALLY_ALLOCATED -> FULLY_ALLOCATED
核销：ACTIVE -> REVERSED
```

“收款已登记”与“应收已核销”必须分开。只有核销完成后，对应应收余额才减少；反核销恢复余额，但不得删除原记录。

## 九、关键数据与约束建议

首期至少需要以下独立对象，不能只在现有费用明细表上继续追加字段：

| 对象 | 核心职责 |
|---|---|
| 财务费用来源 | 引用不可变的业务费用版本，保存来源服务、来源单据、来源版本和来源幂等键 |
| 对账单 | 客户、币种、账期、状态、版本、金额合计和确认信息 |
| 对账单明细 | 关联费用来源并保存出账时快照；一条有效费用只能进入一张有效账单 |
| 应收单 | 应收金额、已核销金额、余额、到期日和状态 |
| 收款单 | 到账金额、币种、日期、方式、凭证号、附件和登记/确认人 |
| 核销记录 | 收款单、应收单、核销金额、操作人、时间和幂等键 |
| 反核销记录 | 原核销记录、原因、审批/操作人和恢复金额 |
| 财务操作日志 | 对账、确认、争议、收款、核销、反核销和作废的完整历史 |

必须具备的约束：

- 金额统一使用定点小数，币种使用 ISO 三位码；不同币种首期禁止合并和直接核销。
- 长整型 ID 按字符串跨前端传输。
- 所有写操作带幂等键和乐观锁版本。
- 同一费用来源版本只能进入一个未作废的账单明细。
- 核销累计金额不得超过收款可用余额或应收未结余额。
- 出账、核销后禁止物理删除；调整、作废和反核销必须保留原记录。
- 客户隔离由服务端登录上下文保证；平台员工操作目标客户时必须显式选择客户并校验权限。
- 客户不可看到供应商成本、内部备注、审核意见和平台凭证附件。

## 十、原型需要修正或裁剪的地方

后续做正式页面时，不建议直接照搬原型：

1. “客户应收应付”把客户应收和供应商应付混在同一概念下，应按交易对手和职责拆分。
2. “客户对账单”和“结算单应收”字段大量重复，首期应定义清晰的一对一或一对多关系，避免两套金额状态并存。
3. 原型中的“支付历史”在应收场景应统一使用“收款/核销记录”，避免收付款术语混用。
4. 原型允许直接登记部分收付款，但没有展示确认、撤销、反核销、超额校验和并发冲突。
5. 客户账户充值与应收结算不是同一个闭环，不能用余额字段代替收款和核销台账。
6. 利润表直接展示结果，但没有收入确认、成本来源、外币折算和分摊规则，当前结果不可审计。
7. 所有正式业务表格的“操作”列应放在第一列；原型部分旧页面需要按仓库统一规则调整。

## 十一、完成标准

只有同时满足以下条件，才可以称为“客户应收财务闭环”：

- 每笔应收都能追溯到已审核、已发布且不可变的费用来源版本；
- 能生成、复核、发送并确认客户对账单；
- 能形成有到期日和余额的应收；
- 支持一次或多次收款及多对多核销；
- 支持部分核销、全额结清、反核销和作废；
- 所有金额变化均可审计，重复提交和并发操作不会多记账；
- Admin 与 Client 对同一账单、应收余额和状态的展示一致；
- 越权、跨客户、不同币种、超额核销、已出账费用调整等异常路径有服务端硬校验；
- 使用真实 API 完成至少一条“费用 -> 对账 -> 应收 -> 收款 -> 核销 -> 结清”回归，并验证反核销恢复余额。

## 十二、下一步文档工作

在写代码前建议依次完成：

1. 由产品/业务填写 F1-F12，冻结首期范围。
2. 形成《客户应收闭环需求确认表》，明确页面、角色、状态和异常处理。
3. 使用《财务管理产品确认表》完成 S1-S8、F0-F4 的产品确认。
4. 服务边界、领域模型草案和跨服务契约草案已经形成；下一步由产品填写 XLSX，按《财务开工门禁与 F0/F1 任务清单》放行 G1/G2，不再重复讨论是否拆服务。
5. 形成《客户应收接口与权限契约》，包括错误码、幂等、数据范围和审计事件。
6. 形成《历史费用迁移与上线方案》，避免已有线下结算数据被重复出账。