优化
This commit is contained in:
+41
-24
@@ -1,7 +1,7 @@
|
||||
# 财务管理闭环盘点与范围建议
|
||||
|
||||
> 盘点日期：2026-08-10
|
||||
> 当前状态：F0/F1 已有 Finance 服务、数据库、权限、Admin/Client 页面和基础接口实现；专项契约与闭环缺口修复中
|
||||
> 当前状态：F0/F1 已有 Finance 服务、数据库、权限、Admin/Client 页面和基础接口；费用来源主链、固定 DTO、脱敏、凭证 fail-closed 和稳定错误码已通过后端验证，剩余为五页页面与未实现 operation 收口
|
||||
> 盘点范围：二期入库计费现状、平台后台财务原型、Admin/Client/Firstleg 当前实现
|
||||
> 结论口径：本文区分“代码已实现”“原型展示”和“建议范围”；原型功能不自动成为开发范围。
|
||||
|
||||
@@ -13,6 +13,19 @@
|
||||
|
||||
开发前总控门禁与 F0/F1 任务清单：[财务开工门禁与F0-F1任务清单](财务开工门禁与F0-F1任务清单.md)。
|
||||
|
||||
一期领导验收唯一范围入口：[财务一期五页产品与接口验收契约](财务一期五页产品与接口验收契约.md)。
|
||||
|
||||
文档优先级：五页验收契约和本轮产品确认 > 五页目标 OpenAPI > 既有人工 F1 契约/门禁 > 领域模型、历史全量规划和迁移文档。旧文档用于追溯，不得据此把钱包、充值、发票、费用分析或利润表重新纳入一期。
|
||||
|
||||
旧文档降级规则：
|
||||
|
||||
| 文档/章节 | 当前用途 | 一期实施约束 |
|
||||
|---|---|---|
|
||||
| 本文第六节起的“历史全量规划” | 保存早期盘点和演进背景 | 与五页契约冲突时全部失效，不作为菜单、路由、字段或接口依据 |
|
||||
| `财务领域模型与跨服务契约.md` | 历史合并稿 | 已被数据字典和跨服务契约替代 |
|
||||
| `财务服务边界设计.md`、`财务领域模型与数据字典.md` | 服务边界和长期模型参考 | 其中钱包、充值、发票、费用分析、利润模型不属于一期 |
|
||||
| `财务历史迁移与上线验收方案.md`、`财务F0实施任务拆分.md` | 历史迁移、底座任务追溯 | 不得覆盖五页范围和当前实现状态 |
|
||||
|
||||
详细设计材料：
|
||||
|
||||
- [财务来源接入现状](财务来源接入现状.md)
|
||||
@@ -20,6 +33,8 @@
|
||||
- [Firstleg-Finance跨服务契约](Firstleg-Finance跨服务契约.md)
|
||||
- [F1 人工账单、收款、成本接口契约](F1人工账单收款成本接口契约.md)
|
||||
- [F1 人工财务契约审查与门禁](F1人工财务契约审查与门禁.md)
|
||||
- [财务一期五页产品与接口验收契约](财务一期五页产品与接口验收契约.md)
|
||||
- [财务一期五页 OpenAPI](openapi/finance-phase1-five-pages-v1.yaml)
|
||||
- [财务历史迁移与上线验收方案](财务历史迁移与上线验收方案.md)
|
||||
- [财务F0实施任务拆分](财务F0实施任务拆分.md)
|
||||
|
||||
@@ -54,9 +69,9 @@
|
||||
-> 客户只读查询
|
||||
```
|
||||
|
||||
当前仍需修复：固定响应 DTO、收款/成本凭证 fail-closed 校验、Firstleg 真实体积快照与客户归属校验、完整幂等请求哈希与恢复、客户收款专用 DTO，以及 Admin 客户账期和修订历史查询。完成《F1人工财务契约审查与门禁》中的测试门禁后，才能宣称 F1 人工财务闭环通过验收。
|
||||
后端当前已完成 Firstleg 真实柜次体积快照、客户归属、成本凭证校验、revision、双权限上传、费用来源事件/Relay/快照、Finance `fin_fee_source` 消费写入和完整幂等；Finance 35/35、Firstleg 549/549（2 skip）、File 114/114、Gateway 26/26、IAM 163/163、Phase3/PDA SQL 12/12、Order SQL 3/3，均 BUILD SUCCESS。当前剩余是 Admin 客户账期/revision 与五页页面动作，以及 11 个目标 operation；完成《F1人工财务契约审查与门禁》剩余门禁后才能宣称一期页面闭环通过验收。
|
||||
|
||||
本轮确认“全部都需要做”后，目标范围升级为覆盖原型财务菜单的完整财务域：客户账户、客户应收应付、客户对账单、结算单应收、结算单应付、收付款与核销、费用分析、发票和利润报表。仍建议按依赖关系分阶段交付，避免在应收、应付、钱包和利润各自造一套金额口径。
|
||||
一期范围已重新冻结为原型 5 页：客户账户、客户应收应付、客户对账单、结算单应收、结算单应付。费用分析、利润表、发票和钱包不做，也不保留菜单、路由或假按钮。客户账户改为账单、收款和应收应付来源派生的财务往来总览，不做充值/预收。
|
||||
|
||||
## 二、事实来源与边界
|
||||
|
||||
@@ -118,38 +133,40 @@ Firstleg 已有 `fl_inbound_fee_detail`，包含：
|
||||
|
||||
| 原型模块 | 原型展示的主要能力 | 当前代码状态 | 是否能直接纳入首期 |
|
||||
|---|---|---|---|
|
||||
| 客户账户 | 余额、冻结金额、可用余额、充值、扣款流水 | 未实现 | 否，这是预存款/钱包模型，需单独确认资金合规和扣款规则 |
|
||||
| 客户账户 | 原型为余额、冻结、可用余额和充值流水 | 未实现 | 一期保留汇总/详情/流水结构，但改为未收、待出账、本期已收等派生指标；删除充值/钱包能力 |
|
||||
| 客户应收应付 | 费用明细、审核、参与结算、按截止时间或勾选生成账单 | 仅有入库费用明细后端基础；无正式财务页面 | 可裁剪为应收费用池 |
|
||||
| 客户对账单 | 账期、汇率、应收、已收、结清、明细和支付历史 | 未实现 | 可作为应收闭环核心，但汇率和开票先暂缓 |
|
||||
| 结算单应收 | 应收、已收、余额、到期日、审批、部分收款 | 未实现 | 可合并进账单/应收单，避免首期重复建模 |
|
||||
| 结算单应付 | 供应商应付、已付、余额、审批、部分付款、利润 | 未实现；上游成本来源不完整 | 否，建议后续独立阶段 |
|
||||
| 费用分析 | 内外部费用对比、趋势和明细 | 未实现 | 否，依赖稳定应收/应付口径 |
|
||||
| 利润表 | 按客户、货柜、单票、月份统计收入、成本、利润率 | 未实现 | 否，依赖应收、成本、汇率及分摊规则 |
|
||||
| 结算单应付 | 供应商应付、已付、余额、审批、部分付款、利润 | 未实现；上游成本来源不完整 | 一期纳入，但删除利润字段/按钮；必须先补真实供应商应付来源和付款凭证链路 |
|
||||
| 费用分析 | 内外部费用对比、趋势和明细 | 未实现 | 一期明确不做，不进菜单/路由 |
|
||||
| 利润表 | 按客户、货柜、单票、月份统计收入、成本、利润率 | 未实现 | 一期明确不做，不进菜单/路由 |
|
||||
|
||||
原型还出现了发票抬头、开票日期、汇率、支付方式、收付款凭证号等字段。它们只说明未来可能需要，不代表当前产品已经确认税务、外币折算、资金或发票边界。
|
||||
|
||||
当前 Admin 已有正式财务路由、账单详情/草稿修改/出账/调整/作废、人工收款和成本页面及真实凭证上传调用，Client 已有正式只读账单页面；但 Admin 未接客户账期和修订历史，成本仍允许人工填写柜内体积，File 全量测试在发现阶段失败，后端成本凭证校验也未接通，因此只能视为修复中的实现，不能视为已验收交付。
|
||||
当前 Admin 已有正式财务路由、账单详情/草稿修改/出账/调整/作废、人工收款和成本页面及真实凭证上传调用，Client 已有正式只读账单页面。后端已改为根据 `containerId` 调 Firstleg 体积快照并完成成本凭证校验，但 Admin 仍强制人工填写并提交柜内订单体积，且未接客户账期和 revision，因此前端创建闭环尚未与最终契约对齐。
|
||||
|
||||
## 五、当前修复中缺口
|
||||
|
||||
| 序号 | 断点 | 直接影响 |
|
||||
|---|---|---|
|
||||
| 1 | Finance 仍直接返回 JDBC `Map/List<Map>` | 字段和响应结构未形成稳定 DTO，前端依赖临时适配 |
|
||||
| 2 | 凭证已可上传，但成本未校验，收款校验存在 fail-open，且 File 全量测试故障 | Admin 收款/成本真实创建闭环不能放行 |
|
||||
| 3 | 整柜分摊已落库，但体积由请求人工填写且归属未向 Firstleg 校验 | 分摊结果不可证明来自真实柜次快照 |
|
||||
| 1 | 五页读接口、平台/客户固定 DTO 和追踪响应已实现 | Finance 35/35 BUILD SUCCESS；本轮使用现有 Surefire 报告核对，不重新执行 Maven |
|
||||
| 2 | 收款和成本均已校验凭证，但 `fileClient == null` 时仍 fail-open | File 客户端缺失时可能绕过凭证校验 |
|
||||
| 3 | 后端已使用 Firstleg 真实体积快照，Admin 仍要求人工填写并提交体积 | 页面与最终请求契约不一致，产生无效输入和误导 |
|
||||
| 4 | 幂等已有 SHA-256 与同参重放，但未覆盖完整规范化请求，缺 PROCESSING 恢复测试 | 仍可能误判同参或无法恢复中间态 |
|
||||
| 5 | 客户账单已过滤可见状态，收款列表仍暴露平台字段且未按可见账单过滤 | 客户只读边界仍不完整 |
|
||||
| 6 | Admin 已接账单动作，但未接客户账期、修订历史，整柜仍人工填体积 | 平台财务页面仍非完整闭环 |
|
||||
| 6 | Admin 已接账单动作，但未接客户账期、revision，整柜仍人工填体积 | 平台财务页面仍非完整闭环 |
|
||||
| 7 | 业务错误码仍以通用错误和中文消息为主 | 前端无法稳定区分版本、幂等、凭证和归属错误 |
|
||||
| 8 | 修订快照已有表和写入逻辑，但缺少查询展示 | 调整历史尚不能由产品和测试人员核对 |
|
||||
| 8 | revision 后端查询已落地，Admin 尚未接展示 | 调整历史仍不能在产品页面核对 |
|
||||
|
||||
## 六、全量财务规划与交付顺序
|
||||
|
||||
### 6.1 全量目标域
|
||||
### 6.1 历史全量规划（不作为一期范围）
|
||||
|
||||
以下内容只保留为历史分析。若与《财务一期五页产品与接口验收契约》冲突，以五页契约为准。
|
||||
|
||||
| 目标域 | 业务结果 | 主要来源 | 不能提前假定的口径 |
|
||||
|---|---|---|---|
|
||||
| 客户账户 | 预存、冻结、扣款、退款、账户流水 | 客户充值、业务扣款 | 是否采用钱包作为应收结算方式、资金归属和退款规则 |
|
||||
| 客户账户 | 客户财务往来派生汇总、详情和流水 | 账单、收款和应收应付来源 | 一期不建设钱包、充值、预收或自动扣款 |
|
||||
| 客户应收 | 客户欠款、到期、逾期、结清 | 已发布对客费用、补差/冲销 | 收入确认节点和账期规则 |
|
||||
| 客户应付 | 客户代垫或返还类应付款（如确有业务） | 业务费用或人工单据 | 产品是否真的存在“平台向客户付款”的场景 |
|
||||
| 客户对账单 | 期间内费用汇总、明细、平台出账和客户只读查看 | 应收/应付费用池 | 一张账单是否允许混合方向、混合币种 |
|
||||
@@ -157,7 +174,7 @@ Firstleg 已有 `fl_inbound_fee_detail`，包含：
|
||||
| 结算单应付 | 供应商成本、付款、余额和结清 | 供应商费用、运力/仓储/报关成本 | 成本确认、供应商账期、审批和付款方式 |
|
||||
| 收付款与核销 | 到账/付款凭证，部分结算、反核销 | 银行流水或人工登记 | 是否首期接银行流水，是否允许一笔多单核销 |
|
||||
| 发票 | 开票申请、开具、红冲、作废和关联 | 已确认应收/收款 | 税率、含税/未税、开票主体、外部平台 |
|
||||
| 费用分析 | 按费用项目、客户、供应商、期间分析 | 应收应付台账 | 统计按发生制还是结算制 |
|
||||
| 费用分析 | 历史规划，一期不做 | 应收应付台账 | 不进入一期菜单、路由和验收 |
|
||||
| 利润 | 客户/单票/柜次/月度收入、成本、利润率 | 应收收入 + 应付成本 + 分摊 | 汇率、成本分摊、收入成本确认时间 |
|
||||
|
||||
### 6.2 分阶段交付顺序
|
||||
@@ -169,8 +186,8 @@ Firstleg 已有 `fl_inbound_fee_detail`，包含：
|
||||
| F0 财务底座 | 独立 Finance 服务/数据库、财务主体、客户/供应商往来单位、币种、费用科目、期间、权限、审计、幂等、金额精度 | 所有后续对象使用同一基础口径 | 服务边界已技术确认；产品确认主体、币种、权限和编码 |
|
||||
| F1 应收与客户对账 | 应收费用池、平台出账、客户只读查看、结算单应收、收款登记、核销、反核销 | 费用 → 账单 → 应收 → 收款 → 结清 | 当前已发布对客费用来源 |
|
||||
| F2 应付与供应商结算 | 成本费用池、供应商账单、结算单应付、付款登记、付款核销、应付调整 | 成本 → 供应商账单 → 应付 → 付款 → 结清 | 供应商主数据和真实成本来源 |
|
||||
| F3 客户账户与发票 | 充值、冻结、扣款、退款、账户流水；开票申请、开票登记、红冲/作废 | 账户余额与应收核销可选联动；应收与发票可追溯 | 资金/税务主体、开票平台和合规口径 |
|
||||
| F4 分析与利润 | 费用分析、收入成本汇总、客户/单票/柜次/月度利润、利润率、导出 | 应收与应付同源统计，结果可追溯 | F1/F2 结算数据、汇率和分摊规则 |
|
||||
| F3 客户账户与发票 | 一期只做派生客户账户总览；发票暂缓 | 账户只读聚合，不维护资金余额 | 发票不属于一期 |
|
||||
| F4 分析与利润 | 一期不做 | 不建设菜单、路由或假入口 | 后续重新立项 |
|
||||
|
||||
阶段之间可以并行做页面原型和契约设计，但生产数据链路必须按 F0 → F1/F2 → F3 → F4 验收。F4 不能用原型静态数字先行替代真实台账。
|
||||
|
||||
@@ -199,9 +216,9 @@ F1 建议页面：
|
||||
4. 核销记录：每笔收款对应哪些应收、核销金额、剩余余额、反核销历史。
|
||||
5. 客户侧账单：只读明细、查看收款与未结余额；异议通过线下渠道反馈。
|
||||
|
||||
F1 暂不包含（在 F2-F4 交付）：
|
||||
以下历史排除清单已被 2026-08-11 的五页范围取代。结算单应付现在属于一期；其余未确认能力继续排除：
|
||||
|
||||
- 供应商应付与付款；
|
||||
- 供应商在线确认和自动付款（应付结算单与人工付款属于一期）；
|
||||
- 客户预充值、余额冻结和自动扣款；
|
||||
- 发票申请、开票和税务接口；
|
||||
- 多币种折算与汇兑损益；
|
||||
@@ -213,20 +230,20 @@ F1 暂不包含（在 F2-F4 交付）：
|
||||
|
||||
| 范围 | 开工门禁 |
|
||||
|---|---|
|
||||
| 客户账户 | 明确充值是否真实入账、冻结/解冻、退款、自动扣款和资金对账责任；不得直接拿账户余额抵消应收而不留核销记录 |
|
||||
| 客户账户 | 已确认只做派生财务往来总览；禁止充值、冻结/解冻、退款、自动扣款和可写余额 |
|
||||
| 客户应收应付 | 明确客户作为付款方还是收款方；没有真实业务场景的方向不建菜单和数据 |
|
||||
| 供应商应付 | 必须有供应商主数据、成本来源凭证、审批人、付款方式和付款责任主体 |
|
||||
| 收付款核销 | 明确人工登记与银行流水的边界；收款、付款、核销、反核销分开授权 |
|
||||
| 发票 | 明确开票主体、税率、含税/未税、红冲/作废和外部开票平台；未确认前只保留接口扩展位 |
|
||||
| 费用分析/利润 | 先冻结汇率、收入成本确认日、成本分摊和跨币种折算；报表必须能钻取到原始费用和结算单 |
|
||||
|
||||
## 七、必须先确认的产品问题
|
||||
## 七、已确认的产品结论（历史问题关闭结果）
|
||||
|
||||
以下结论没有确认前，只能做可逆的模型和页面设计，不能进入完整开发：
|
||||
下表原为产品问题清单，现按本轮确认结果保留。不得再把这些条目解释为待产品确认；实现仍受真实费用来源链路和专项技术门禁约束。
|
||||
|
||||
| 编号 | 待确认问题 | 建议默认值 |
|
||||
|---|---|---|
|
||||
| F1 | 全量范围是否按 F0 → F1 → F2 → F3 → F4 分阶段交付 | 是，目标范围全部保留；先完成 F0，再按依赖验收，不因先做应收而删除应付、账户、发票和利润 |
|
||||
| F1 | 一期领导验收范围 | 固定为客户账户、客户应收应付、客户对账单、结算单应收、结算单应付；费用分析和利润表不做 |
|
||||
| F2 | 账单生成维度 | 客户 + 币种 + 账期；不同币种不合并 |
|
||||
| F3 | 哪些费用可以进入账单 | `APPROVED + PUBLISHED + settlementIncluded=true` 且未作废、未出账 |
|
||||
| F4 | 当前已发布头程费用是否自动进入待对账池 | 是，但仍由财务选择并生成账单 |
|
||||
|
||||
Reference in New Issue
Block a user