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

docs: 统一财务与履约口径并新增总纲

Browse Source
This commit is contained in:
yml2213
2026-10-23 13:17:30 +08:00
parent fac34c8420
commit fb80cad695
11 changed files with 798 additions and 118 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/README.md
+59 -33
View File
@@ -1,9 +1,10 @@
# order_site 文档索引
> 最后校准：2026-10-23，代码基线 `dev @ a7f60414 + 财务 103–113`。
> 本文是 `docs/` 的唯一入口。新增文档必须在上表登记状态；过期文档不再直接改写结论，统一移入 `docs/archive/`。
> 最后校准：2026-10-23，代码基线 `dev @ fac34c84 + 迁移 103–113`。
> 本文是 `docs/` 的唯一入口。**财务与履约口径以 [财务与履约口径总纲-2026-10-23.md](财务与履约口径总纲-2026-10-23.md) 为准**；接手改造先读 [财务履约改造交接总结-2026-10-23.md](财务履约改造交接总结-2026-10-23.md)，本文只做索引与速查。
> 新增文档必须在下表登记状态；过期文档不再直接改写结论，统一移入 `docs/archive/`。
## 一、先记住五条口径
## 一、先记住六条口径
### 1. 来源只有三个，不是四个
@@ -15,14 +16,26 @@
**不要把 91 与快手 send-code 拆成两个来源、两个适配器或两条业务线。** 产品匹配层的唯一来源键是 `kuaishou-91`（`apps/backend/src/services/product-match/types.ts`），适配器是 `adapters/kuaishou-91.ts`。但订单表与成本映射里存储的 `provider` 仍是 `orders.provider = 91kaquan`；成本中心会把 `91 / open_91 / kuaishou-91` 这些别名归一为 `91kaquan`，映射键必须按落库值建。
### 2. 一个订单 = 骨架 + 买家凭证 + 一个执行载体
### 2. 一个订单 = 骨架 + 买家凭证 + 一个履约方式
- 骨架：`orders` + `order_items`
- 买家凭证：快手电子凭证（`kuaishou_industry_vouchers`）或抖音券（`redeem_certificates`）
- 执行载体只有三种：`affiliate_dash` 自动发货、`work_orders` 工单、`manual` 人工客服
- 三者业务上互斥；无自动任务且无工单的已支付订单项就是人工块，必须进入人工 case，不能静默消失
- 履约方式只有四种：`affiliate_dash` 自动发货、`work_orders` 接单平台、`legacy_platform` 已下线历史平台、`manual` 人工
- **电子凭证只是核销码，不参与履约方式判定**；有核销码的订单仍可能是自动发货/接单平台/人工
- 判定顺序固定：工单 → 自动发货任务 → 历史平台任务 → 其余为人工
- 人工块必须进入人工支出与成本快照，不能静默消失
### 3. 成本只在一个地方改
### 3. 履约方式与成本模型必须分开
- `fulfillment_mode` 回答“谁执行”；`cost_model` 回答“成本怎么算”
- 自动发货：`affiliate_purchase`
- 接单平台：`work_order_reward`
- 人工：`manual_actual`（逐单实际金额）
- 历史平台：`legacy_cost`（历史未采集则显式标记）
- 电子凭证不建成本项，也不作为成本类型
- 未确认成本时保持 `cost_missing`，不默认 0
### 4. 成本只在一个地方改
- 商品主数据：`product_catalog`
- 渠道 SKU 映射：`channel_product_mappings`
@@ -30,16 +43,22 @@
- 订单/工单/人工单只保存 `cost_snapshot_id`，历史成本永不回写
- 自动发货、接单平台、人工客服共用同一个成本解析器；匹配不到成本进入 `cost_missing`，不默认 0
### 4. 两个“人工支出”不是一回事
### 5. 两个“人工支出”不是一回事
| 名称 | 业务含义 | 当前状态 |
| --- | --- | --- |
| `manual_expenses` | **客服备用金支出明细**：客服从自己的备用金里充值/采购/赔偿，减少客服余额 | 已实施（迁移 100） |
| `manual_expense_records` | **公司人工支出/垫付登记**：按订单/成本项记录公司实际付出去的钱、付款人、收款人、凭证、审批 | 已实施 P0（迁移 111） |
后续做财务系统时，**不要把 `manual_expenses` 直接改名或复用为 `manual_expense_records`**。两者业务含义、审批链和报表口径不同，应通过 `fund_expense_id` 建立关联。
后续做财务系统时，**不要把 `manual_expenses` 直接改名或复用为 `manual_expense_records`**。两者业务含义、审批链和报表口径不同，必须通过 `fund_expense_id` 关联；新人工支出登记会先扣备用金，再写人工支出记录。
### 5. 文档状态
### 6. 历史人工支出不补录，上线后必须全覆盖
- 历史人工支出只取少量样本做校准，不补录、不阻塞上线；
- 上线后每一笔人工单必须有处理人、实际金额、备用金支出与成本快照；
- 人工单无成本记录、人工支出无 `fund_expense_id`、金额与备用金流水不一致，均不允许关账。
### 7. 文档状态
| 状态 | 含义 |
| --- | --- |
@@ -52,29 +71,32 @@
| 模块 | 状态 | 事实 |
| --- | --- | --- |
| 客服备用金台账 | **已实施 P0** | `fund_accounts` / `fund_entries` / `manual_expenses` / `fund_reconciliations`；后台页面、权限、审计已完成 |
| 客服备用金台账 | **已实施 P0** | 迁移 `100/101/113`；账户、流水、支出、对账；编号 `FA-<用户名>`；客服只能使用本人账户 |
| 后台用户中文显示名 | **已实施** | `admin_users.display_name`，备用金姓名触发器同步；审计、登录记录、任务处理人优先显示中文名 |
| 商品主数据 + 渠道 SKU 映射 | **已实施 P0（dev 分支）** | 迁移 `103`（映射消歧在 `106`）；`product_catalog` / `channel_product_mappings`，后台「商品与成本」页支持维护、历史订单项回填与按载体分区 |
| 成本中心 | **已实施 P0（dev 分支）** | 迁移 `104/105/107/108/110/112`；`cost_items` / `cost_versions` / `cost_snapshots` / `cost_exceptions` 支持版本、预览、快照、异常队列、自动发货价格导入；自动发货订单项按履约任务 SKU 直接归一为 `aff:<skuCode>`（不建渠道映射），接单平台按工单模板回填商品并为 662 个模板生成规则级发单金额版本，人工按支出登记写入实际快照 |
| 销售事实 / 订单毛利 | **已实施 P0（dev 分支）** | 迁移 `109`；`sales_daily_facts` 按店铺×日期×标准商品×载体汇总，未归一商品单独成行；后台新增「销售毛利」页，成本缺失会显式告警 |
| 公司人工支出登记 | **已实施 P0（dev 分支）** | 迁移 `111`；`manual_expense_records` / `manual_expense_events`，后台「人工支出」页支持登记、审批、驳回、报销；与客服备用金 `manual_expenses` 通过 `fund_expense_id` 关联 |
| 商品主数据 + 渠道 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 万；人工/历史平台分类口径待统一 |
| 公司人工支出登记 | **已实施 P0（dev 分支）** | 迁移 `111`；登记时强制扣客服备用金并写 `fund_expense_id`；客服只能使用本人账户 |
| 履约方式统一 | **未实施** | 订单页、销售事实、成本快照仍各自推断；需要持久化 `fulfillment_mode` |
| 影子总账 | 未实施 | 现有财务页仍是 `UNION ALL` 业务事件拼装，不是复式总账 |
| 平台对账 / 期间关账 | 未实施 | 仅方案 |
| 退款冲减 / 平台对账 / 期间关账 | 未实施 | 仅方案 |
> 分支状态（2026-10-22）：商品主数据、渠道映射、成本中心、成本快照运行层、销售事实与公司人工支出登记在 `dev` 分支（原 `feat/cost-center-wip` 已合并），**尚未合并 `main`、未部署生产**；生产口径仍以 `main` 为准。
> 分支状态（2026-10-23）：`dev` 领先 `main` 20 个提交，迁移 `103–113` 尚未合并、未部署生产；生产口径仍以 `main` 为准。
> 财务与履约口径以 [财务与履约口径总纲-2026-10-23.md](财务与履约口径总纲-2026-10-23.md) 为准。
## 三、统一实施顺序
```text
1. 商品主数据 + 渠道 SKU 映射 已完成 P0
2. 成本中心 + 销售事实（先接收入与标准成本） 已完成 P0（迁移 108/109）
3. 订单毛利 / 店铺日报 已完成 P0（销售毛利页，成本缺失显式告警）
4. 公司人工支出登记（桥接现有客服备用金支出） 已完成 P0（迁移 111）
5. 影子总账（订单、工单、押金、提现、寄卖、售后） 未实施
6. 平台对账、报表、期间关账 未实施
0. 统一履约事实（fulfillment_mode + 成本模型） 未实施，最高优先级
1. 商品主数据 + 渠道 SKU 映射 已完成 P0（仅自动发货/接单平台）
2. 成本中心 + 销售事实 已完成 P0
3. 人工商品归一与上线后人工成本全覆盖 未实施
4. 退款冲减与异常队列 未实施
5. 影子总账（订单、工单、押金、提现、寄卖、售后） 未实施
6. 平台对账、报表、期间关账 未实施
```
**不要跳过 1–3 直接做影子总账。** 没有商品归一、成本版本和订单损益，影子账只能记“总额”，无法回答“哪个店铺、哪个商品、哪条履约链路赚钱”。
**不要跳过第 0 步直接做人工成本或总账。** 没有统一履约事实，人工、电子凭证、历史平台会继续互相串味。第 0 步的迁移、回填、代码清单和验收 SQL 已写到 [总纲 §八](财务与履约口径总纲-2026-10-23.md#八p0-开工清单统一履约事实)，按那份清单逐项执行即可。
## 四、当前必须拍板
@@ -84,21 +106,25 @@
| 2 | 收入确认时点 | ✅ 先按 `paid_at` 归属销售日；成本在快照生成后回填 | 利润表与预收账款 |
| 3 | 打手报酬 | ✅ 支出/成本，总额法 | 履约成本 |
| 4 | 退款/仲裁 | ✅ 暂不实现，只预留反向凭证 | 后续冲减 |
| 5 | 人工支出如何入账 | ✅ 以人工支出登记为入口；需与客服备用金支出桥接 | 人工成本与应付垫付人 |
| 6 | 平台服务费/支付通道费 | ⏳ 待定 | 费用科目与对账 |
| 7 | 寄卖货款成本确认时点 | ⏳ 待定 | 存货/采购成本 |
| 8 | 是否需要发票/税务、是否多币种 | ⏳ 待定 | 当前按 CNY、无税务实现 |
| 5 | 人工支出如何入账 | ✅ 逐单实际金额；从客服备用金扣款；客服只能用本人账户 | 人工成本与备用金 |
| 6 | 历史人工支出 | ✅ **不补录**，只取少量样本校准 | 上线范围 |
| 7 | 电子凭证是否作为分类 | ✅ **不作为履约/成本分类**，只是核销码状态 | 报表口径 |
| 8 | 平台服务费/支付通道费 | ⏳ 待定 | 费用科目与对账 |
| 9 | 寄卖货款成本确认时点 | ⏳ 待定 | 存货/采购成本 |
| 10 | 是否需要发票/税务、是否多币种 | ⏳ 待定 | 当前按 CNY、无税务实现 |
## 五、现行与参考文档
| 文档 | 状态 | 用途 |
| --- | --- | --- |
| [项目全量分析报告-2026-10-17.md](项目全量分析报告-2026-10-17.md) | 参考 | 当前架构、业务链路、风险与改进路线；代码基线早于备用金实现，涉及财务部分以本索引为准 |
| [财务系统集成方案.md](财务系统集成方案.md) | 现行方案（未实施） | 财务系统边界、复式记账模型、核心表、API、分期落地 |
| [成本中心与三块履约模型.md](成本中心与三块履约模型.md) | 现行（P0 已实施） | 自动发货/接单平台/人工客服三块、商品映射、成本中心与销售事实 |
| [人工支出登记落地方案-2026-10-17.md](人工支出登记落地方案-2026-10-17.md) | 现行（P0 已实施） | 公司人工支出登记：字段、入口、状态机、权限、与备用金/成本中心/总账的衔接 |
| [财务与履约口径总纲-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 架构与风险；财务口径以总纲为准 |
| [财务系统集成方案.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-18.md](客服备用金台账实施方案-2026-10-18.md) | **已实施 P0** | 备用金账户、流水、支出、对账、本人账户与编号规则 |
| [接单模板匹配引擎重构设计.md](接单模板匹配引擎重构设计.md) | 现行（P0/P1 已实施） | `kuaishou-91 / pdd / douyin-mashida` 三来源匹配引擎 |
| [履约配置/多发货平台与电子凭证整体链路.md](履约配置/多发货平台与电子凭证整体链路.md) | 现行 | 进单、履约、领取、电子凭证的整体链路 |
| [affiliate-dash-发货平台/affiliate-dash对接.md](affiliate-dash-发货平台/affiliate-dash对接.md) | 现行 | affiliate-dash 自动履约接口与字段 |