docs/财务管理

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

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

产品/业务逐项确认请使用：财务管理产品确认表。

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

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

开发前总控门禁与 F0/F1 任务清单：财务开工门禁与F0-F1任务清单。

详细设计材料：

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

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

一、结论

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

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

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

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

已发布费用
  -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 先处理当前已经有可靠来源的对客头程费用：

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

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 费用明细

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

8.2 对账单

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

8.3 应收与核销

应收：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. 形成《历史费用迁移与上线方案》，避免已有线下结算数据被重复出账。