dachui/order_site
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(finance): 现行财务文档收敛为 5 篇，履约口径只定义一次

Browse Source 
原 9 篇 3,647 行，履约分类口径在总纲、模型文档、交接总结里重复三遍，
且仍留着"三块履约""按小时人工成本"等已作废表述。本次收敛为 5 篇
1,778 行：

- 财务与履约口径总纲-2026-10-23.md（300 行）：唯一口径来源
  七条硬口径、三个正交维度、真实履约构成、成本模型规则、人工全覆盖、
  实施顺序、进度、验收 SQL、防回归清单
- 成本中心与履约模型.md（471 行）：数据模型、迁移 103–107、履约回填、
  销售事实、本地库原地改造、索引与性能
- 成本中心API契约.md（270 行）：字段替换总表、枚举、前后端模块边界
- 人工支出与备用金.md（218 行）：人工支出登记字段/状态机/权限 +
  客服备用金台账
- 财务系统集成方案.md：复式总账层（未实施）

旧的 4 篇（成本中心与三块履约模型、人工支出登记落地方案、
客服备用金台账实施方案、财务履约改造交接总结）移入
docs/archive/2026-10-23/ 并加归档提示。

履约分类判定 SQL 只在总纲保留一份，其它文档改为链接。
This commit is contained in:
yml2213
2026-10-23 16:06:40 +08:00
parent 63ae32d18c
commit 43f402cf72
15 changed files with 1103 additions and 337 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/README.md
+21 -21
View File
@@ -1,7 +1,7 @@
# order_site 文档索引
> 最后校准：2026-10-23，代码基线 `dev @ 5d1ba115 + 迁移 103–114`。
> 本文是 `docs/` 的唯一入口。**财务与履约口径以 [财务与履约口径总纲-2026-10-23.md](财务与履约口径总纲-2026-10-23.md) 为准**；接手改造先读 [财务履约改造交接总结-2026-10-23.md](财务履约改造交接总结-2026-10-23.md)，本文只做索引与速查。
> 最后校准：2026-10-23，代码基线 `feat/finance-rewrite @ 7557de6d + 迁移 103–107`。
> 本文是 `docs/` 的唯一入口。**财务与履约口径以 [财务与履约口径总纲-2026-10-23.md](财务与履约口径总纲-2026-10-23.md) 为准**；数据模型看 [成本中心与履约模型.md](成本中心与履约模型.md)，接口看 [成本中心API契约.md](成本中心API契约.md)。
> 新增文档必须在下表登记状态；过期文档不再直接改写结论，统一移入 `docs/archive/`。
## 一、先记住六条口径
@@ -48,7 +48,7 @@
| 名称 | 业务含义 | 当前状态 |
| --- | --- | --- |
| `manual_expenses` | **客服备用金支出明细**：客服从自己的备用金里充值/采购/赔偿，减少客服余额 | 已实施（迁移 100） |
| `manual_expense_records` | **公司人工支出/垫付登记**：按订单/成本项记录公司实际付出去的钱、付款人、收款人、凭证、审批 | 已实施 P0（迁移 111） |
| `manual_expense_records` | **公司人工支出/垫付登记**：按订单/成本项记录公司实际付出去的钱、付款人、收款人、凭证、审批 | 已实施 P0（迁移 106） |
后续做财务系统时，**不要把 `manual_expenses` 直接改名或复用为 `manual_expense_records`**。两者业务含义、审批链和报表口径不同，必须通过 `fund_expense_id` 关联；新人工支出登记会先扣备用金，再写人工支出记录。
@@ -71,24 +71,24 @@
| 模块 | 状态 | 事实 |
| --- | --- | --- |
| 客服备用金台账 | **已实施 P0** | 迁移 `100/101/113`；账户、流水、支出、对账；编号 `FA-<用户名>`；客服只能使用本人账户 |
| 客服备用金台账 | **已实施 P0** | 迁移 `100/101/106`；账户、流水、支出、对账；编号 `FA-<用户名>`；客服只能使用本人账户 |
| 后台用户中文显示名 | **已实施** | `admin_users.display_name`，备用金姓名触发器同步；审计、登录记录、任务处理人优先显示中文名 |
| 商品主数据 + 渠道 SKU 映射 | **已实施 P0（dev 分支）** | 745 个标准商品、4,426 条映射；只覆盖自动发货 38 个 + 接单平台 707 个。人工 11,349 项虽已归一但全部挂 `tpl:*` 模板商品，需在 P1 复核；人工/历史平台专用商品尚未建立 |
| 成本中心 | **已实施 P0（dev 分支）** | 迁移 `104/105/107/108/110/112`；38 个商品级版本 + 662 个规则级版本；人工走 `sys_manual_service` 实际快照 |
| 销售事实 / 订单毛利 | **已实施 P0（dev 分支）** | 迁移 `109`；94 天事实收入 ¥2,650.87 万、成本 ¥950.27 万；四种履约方式已统一读 `fulfillment_mode` |
| 公司人工支出登记 | **已实施 P0（dev 分支）** | 迁移 `111`；登记时强制扣客服备用金并写 `fund_expense_id`；客服只能使用本人账户 |
| 履约方式统一 | **已实施 P0（dev 分支）** | 迁移 `114`；316,585 项已回填；订单页、成本快照、销售事实只读 `fulfillment_mode`；人工项带核销码仍显示人工 |
| 商品主数据 + 渠道 SKU 映射 | **已实施 P0** | 745 个标准商品、4,426 条映射；只覆盖自动发货 38 个 + 接单平台 707 个。人工 11,349 项虽已归一但全部挂 `tpl:*` 模板商品，需在 P1 复核；人工专用商品尚未建立 |
| 成本中心 | **已实施 P0** | 迁移 `104`；`cost_items.cost_model` 取代 `cost_type + carrier_type`；38 个商品级版本 + 662 个规则级版本；人工走 `sys_manual_service` 实际快照 |
| 销售事实 / 订单毛利 | **已实施 P0** | 迁移 `105`；94 天事实收入 ¥2,650.87 万、成本 ¥950.27 万；`sales_daily_facts.fulfillment_mode` |
| 公司人工支出登记 | **已实施 P0** | 迁移 `106`；登记时强制扣客服备用金并写 `fund_expense_id`；客服只能使用本人账户 |
| 履约方式统一 | **已实施 P0** | 迁移 `107`；316,585 项已回填，四项计数与总纲 §二 一致；订单页、成本快照、销售事实只读 `fulfillment_mode` |
| 人工商品归一 | **未实施（P1）** | 人工单按 `spec.skuId` 建 `man:<skuId>`；历史 11,349 项 `tpl:*` 商品待复核 |
| 影子总账 | 未实施 | 现有财务页仍是 `UNION ALL` 业务事件拼装，不是复式总账 |
| 退款冲减 / 平台对账 / 期间关账 | 未实施 | 仅方案 |
> 分支状态（2026-10-23）：`dev` 领先 `main` 20+ 个提交，迁移 `103–114` 尚未合并、未部署生产；生产口径仍以 `main` 为准。
> 分支状态（2026-10-23）：重写分支 `feat/finance-rewrite` 把原 `103–114` 十二个迁移合并为 `103–107` 五个；本地库已按新 schema 原地改造并重跑回填，**尚未合并到 `dev`、未部署生产**；生产口径仍以 `main` 为准。
> 财务与履约口径以 [财务与履约口径总纲-2026-10-23.md](财务与履约口径总纲-2026-10-23.md) 为准。
## 三、统一实施顺序
```text
0. 统一履约事实（fulfillment_mode + 成本模型） 已完成 P0（迁移 114）
0. 统一履约事实（fulfillment_mode + 成本模型正交） 已完成 P0（迁移 107）
1. 商品主数据 + 渠道 SKU 映射 已完成 P0（仅自动发货/接单平台）
2. 成本中心 + 销售事实 已完成 P0
3. 人工商品归一与上线后人工成本全覆盖 未实施（下一阶段）
@@ -97,7 +97,7 @@
6. 平台对账、报表、期间关账 未实施
```
**第 0 步已完成。** 迁移、回填、代码改造与验收结果见 [总纲 §八](财务与履约口径总纲-2026-10-23.md#八p0-实施记录统一履约事实)。下一步只做第 3 步人工商品归一，不要同时改退款或总账。
**第 0 步已完成。** 迁移、回填、代码改造与验收结果见 [成本中心与履约模型](成本中心与履约模型.md) §六、§八。下一步只做第 3 步人工商品归一，不要同时改退款或总账。
## 四、当前必须拍板
@@ -118,14 +118,13 @@
| 文档 | 状态 | 用途 |
| --- | --- | --- |
| [财务与履约口径总纲-2026-10-23.md](财务与履约口径总纲-2026-10-23.md) | **现行唯一口径** | 履约方式、成本模型、人工全覆盖、历史策略、P0 迁移/回填/代码清单、运营日检与验收 SQL |
| [财务履约改造交接总结-2026-10-23.md](财务履约改造交接总结-2026-10-23.md) | **交接摘要** | 本次改了什么、关键数字、下一步 P0、运营硬要求、验证命令与阅读顺序 |
| [项目全量分析报告-2026-10-17.md](项目全量分析报告-2026-10-17.md) | 历史参考 | 2026-10-17 架构与风险；财务口径以总纲为准 |
| [财务与履约口径总纲-2026-10-23.md](财务与履约口径总纲-2026-10-23.md) | **现行唯一口径** | 履约方式、成本模型、人工全覆盖、历史策略、实施顺序、运营日检与验收 SQL |
| [成本中心与履约模型.md](成本中心与履约模型.md) | 现行 | 商品、成本版本、快照、异常、销售事实的数据模型；迁移 `103–107`；履约回填；本地库原地改造；索引与性能 |
| [成本中心API契约.md](成本中心API契约.md) | 现行 | 成本中心接口字段替换总表、枚举、模块边界（后端 5 模块 + 前端 8 面板） |
| [人工支出与备用金.md](人工支出与备用金.md) | 现行（P0 已实施） | 人工支出登记字段/状态机/权限、客服备用金台账、本人账户与编号规则 |
| [财务系统集成方案.md](财务系统集成方案.md) | 现行方案（总账未实施） | 复式记账、总账表、对账、关账 |
| [成本中心与履约方式模型.md](成本中心与三块履约模型.md) | 现行（文件名保留） | 商品、成本快照、销售事实；履约分类以总纲为准 |
| [人工支出登记落地方案-2026-10-17.md](人工支出登记落地方案-2026-10-17.md) | 现行（P0 已实施） | 人工支出字段、入口、状态机、权限、备用金衔接 |
| [影子总账说明.md](影子总账说明.md) | 现行说明（未实施） | 影子总账是什么、和钱包流水的区别、对账与转正标准 |
| [客服备用金台账实施方案-2026-10-18.md](客服备用金台账实施方案-2026-10-18.md) | **已实施 P0** | 备用金账户、流水、支出、对账、本人账户与编号规则 |
| [项目全量分析报告-2026-10-17.md](项目全量分析报告-2026-10-17.md) | 历史参考 | 2026-10-17 架构与风险；财务口径以总纲为准 |
| [接单模板匹配引擎重构设计.md](接单模板匹配引擎重构设计.md) | 现行（P0/P1 已实施） | `kuaishou-91 / pdd / douyin-mashida` 三来源匹配引擎 |
| [履约配置/多发货平台与电子凭证整体链路.md](履约配置/多发货平台与电子凭证整体链路.md) | 现行 | 进单、履约、领取、电子凭证的整体链路 |
| [affiliate-dash-发货平台/affiliate-dash对接.md](affiliate-dash-发货平台/affiliate-dash对接.md) | 现行 | affiliate-dash 自动履约接口与字段 |
@@ -143,9 +142,9 @@
| 文件 | 用途 | 接入前必须处理 |
| --- | --- | --- |
| [drafts/2026-10-17-载体判定与人工块量化.sql](drafts/2026-10-17-载体判定与人工块量化.sql) | 载体分布/人工块量化查询、`carrier_type` 判定与回填 | 只读查询可直接用；DDL 部分按当前迁移号顺延，不占用 100/101 |
| [drafts/2026-10-17-成本中心与销售事实-DDL草案.sql](drafts/2026-10-17-成本中心与销售事实-DDL草案.sql) | `product_catalog`、`channel_product_mappings`、`cost_items/versions/snapshots/exceptions`、`sales_daily_facts` | 商品、成本、销售事实均已落地（`103–109`）；系统成本项在 `110`；草案仅作设计追溯，不再作为建表依据 |
| [drafts/2026-10-17-人工支出登记-DDL草案.sql](drafts/2026-10-17-人工支出登记-DDL草案.sql) | `manual_fulfillment_cases`、`manual_expense_records`、`manual_expense_events` | 人工支出登记已落地为 `111`；轻量人工 case 仍为草案 |
| [drafts/2026-10-17-载体判定与人工块量化.sql](drafts/2026-10-17-载体判定与人工块量化.sql) | 载体分布/人工块量化查询、`carrier_type` 判定与回填 | **已过时**：`carrier_type` 已从商品/成本/快照/异常表删除；只读查询里的口径结论已吸收进总纲 §二 |
| [drafts/2026-10-17-成本中心与销售事实-DDL草案.sql](drafts/2026-10-17-成本中心与销售事实-DDL草案.sql) | `product_catalog`、`channel_product_mappings`、`cost_items/versions/snapshots/exceptions`、`sales_daily_facts` | 已落地为 `103`–`105`；草案里的 `carrier_type` 已被 `cost_model` / `fulfillment_mode` 取代，仅作设计追溯 |
| [drafts/2026-10-17-人工支出登记-DDL草案.sql](drafts/2026-10-17-人工支出登记-DDL草案.sql) | `manual_fulfillment_cases`、`manual_expense_records`、`manual_expense_events` | 人工支出登记已落地为 `106`；轻量人工 case 仍为草案 |
## 六、厂商协议与外部资料
@@ -165,6 +164,7 @@
| --- | --- |
| [archive/README.md](archive/README.md) | 2026-10-08 及更早的阶段分析、寄卖方案、性能快照、一次性迁移检查脚本；2026-10-17 复核文档 |
| [archive/2026-10-17/载体判定与成本中心落地-复核与草案.md](archive/2026-10-17/载体判定与成本中心落地-复核与草案.md) | 2026-10-17 第二轮复核与数据量化；结论已吸收进现行成本中心文档，仅作历史追溯 |
| [archive/2026-10-23/](archive/2026-10-23/) | 2026-10-23 重写前的四篇：`成本中心与三块履约模型`、`人工支出登记落地方案`、`客服备用金台账实施方案`、`财务履约改造交接总结`；结论已分别并入现行 5 篇文档 |
## 八、维护规则