yml2213
0de0fd7b58
- 原 108/111/112/113/114 合并为 108_finance_cost_integrity： 成本异常归档、人工成本完整性、影子总账、商品页/模板查询索引 - 原 115 注释迁移改为 111_work_order_share_cancel_reason_comment - 新增 reconcile-migration-history.sql，用于已跑旧 112–115 的库 重建 schema_migrations 顺序，不重复执行 DDL - 已验证：001→111、101→111 两条升级路径； 旧 115 与新 111 的 pg_dump schema 完全一致 - 测试/文档迁移编号同步到 103–111 验证：backend check 853（849 pass / 4 skip）；frontend check 172 + build。
191 lines
17 KiB
Markdown
191 lines
17 KiB
Markdown
# order_site 文档索引
|
||
|
||
> 最后校准：2026-10-26，代码基线 `dev`（合并 `dev1023` + 人工成本完整性修复，迁移基线收敛为 `103`–`111`；**未部署生产**）。
|
||
> 数据基线：生产 dump `backups/postgres/order_site-20261022-092601.dump`（数据 2026-07-10 ~ 2026-10-22）；测试/本地旧编号已到 115，生产按收敛后的 101 → 111 路径执行。历史全量数字仅作基线，**上线验收以 [财务上线初始化与验收-2026-10-26.md](财务上线初始化与验收-2026-10-26.md) 为准**。
|
||
> 本文是 `docs/` 的唯一入口。**财务与履约口径以 [财务与履约口径总纲-2026-10-23.md](财务与履约口径总纲-2026-10-23.md) 为准**；数据模型看 [成本中心与履约模型.md](成本中心与履约模型.md)，接口看 [成本中心API契约.md](成本中心API契约.md)。
|
||
> 新增文档必须在下表登记状态；过期文档不再直接改写结论，统一移入 `docs/archive/`。
|
||
|
||
## 一、先记住六条口径
|
||
|
||
### 1. 来源只有三个，不是四个
|
||
|
||
| sourceKey | 包含的数据通道 | 说明 |
|
||
| --- | --- | --- |
|
||
| `kuaishou-91` | 91 回调 + 快手 send-code | **同一个来源的两条通道**：91 是订单骨架权威源，快手 send-code 是数据补全源与兜底源；共享店铺键空间与同一套匹配上下文 |
|
||
| `pdd` | 拼多多订单同步 | 两段式 `pdd_raw_orders → orders` |
|
||
| `douyin-mashida` | 抖音码速达推送 | 抖店订单、DYC 券、H5/兑换页 |
|
||
|
||
**不要把 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. 一个订单 = 骨架 + 买家凭证 + 一个履约方式
|
||
|
||
- 骨架：`orders` + `order_items`
|
||
- 买家凭证：快手电子凭证（`kuaishou_industry_vouchers`）或抖音券（`redeem_certificates`）
|
||
- 履约方式只有四种：`affiliate_dash` 自动发货、`work_orders` 接单平台、`legacy_platform` 已下线历史平台、`manual` 人工
|
||
- **电子凭证只是核销码，不参与履约方式判定**；有核销码的订单仍可能是自动发货/接单平台/人工
|
||
- 判定顺序固定：工单 → 自动发货任务 → 历史平台任务 → 其余为人工
|
||
- 人工块必须进入人工支出与成本快照，不能静默消失
|
||
|
||
### 3. 履约方式与成本模型必须分开
|
||
|
||
- `fulfillment_mode` 回答“谁执行”；`cost_model` 回答“成本怎么算”
|
||
- 自动发货：`affiliate_purchase`
|
||
- 接单平台：`work_order_reward`
|
||
- 人工：`manual_actual`（逐单实际金额）
|
||
- 历史平台：`legacy_cost`（历史未采集则显式标记）
|
||
- 电子凭证不建成本项，也不作为成本类型
|
||
- 未确认成本时保持 `cost_missing`，不默认 0
|
||
|
||
### 4. 成本只在一个地方改
|
||
|
||
- 商品主数据：`product_catalog`
|
||
- 渠道 SKU 映射：`channel_product_mappings`
|
||
- 成本金额：只在 `cost_versions` 改，按生效日期新增版本
|
||
- 订单/工单/人工单只保存 `cost_snapshot_id`，历史成本永不回写
|
||
- 自动发货、接单平台、人工客服共用同一个成本解析器；匹配不到成本进入 `cost_missing`，不默认 0
|
||
|
||
### 5. 人工成本只有一条链路
|
||
|
||
```text
|
||
订单列表/详情「确认履约」→ 扣客服积分/备用金 → 写 cost_snapshots（manual_case）
|
||
```
|
||
|
||
| 名称 | 业务含义 | 当前状态 |
|
||
| --- | --- | --- |
|
||
| `manual_expenses` | **客服备用金支出明细**：客服从自己的备用金里充值/采购/赔偿，减少客服余额 | 已实施（迁移 100）；确认履约的现金支出也写这里 |
|
||
| `cost_snapshots` | **人工成本的唯一落点**：`subject_type='manual_case'`，`subject_id=order_item_id`（资金来源写 metadata） | 已实施（迁移 104 + 111） |
|
||
|
||
**没有独立的登记单，也没有审批与报销环节。** `manual_expense_records` / `manual_expense_events` 已随迁移 `104` 归并下线（这两张表在生产 102 上从未创建）。后续做财务系统时，人工成本的钱与账都从这条链路走，不要再另造一张人工支出表。
|
||
|
||
### 6. 历史人工直接放弃，上线后必须全覆盖
|
||
|
||
- 历史人工支出找不回来，**直接放弃**：不补录、不做样本校准、不阻塞上线；
|
||
- 上线后每一笔人工单必须有处理人、实际金额、备用金支出与成本快照；
|
||
- 人工单无成本记录、人工单未扣备用金、金额与备用金流水不一致，均不允许关账。
|
||
|
||
### 7. 文档状态
|
||
|
||
| 状态 | 含义 |
|
||
| --- | --- |
|
||
| 现行 | 与当前代码一致，改动代码时必须同步更新 |
|
||
| 方案 | 尚未实施，但作为下一阶段实现依据 |
|
||
| 参考 | 外部协议、历史数据或解释性材料，不作为实现依据 |
|
||
| 历史 | 只用于追溯，不得作为实现依据；位于 `docs/archive/` |
|
||
|
||
## 二、财务系统当前进度
|
||
|
||
| 模块 | 状态 | 事实 |
|
||
| --- | --- | --- |
|
||
| 客服备用金台账 | **已实施 P0** | 迁移 `100/101/107`；账户、流水、支出、对账；编号 `FA-<用户名>`；客服只能使用本人账户 |
|
||
| 后台用户中文显示名 | **已实施** | `admin_users.display_name`，备用金姓名触发器同步；审计、登录记录、任务处理人优先显示中文名 |
|
||
| 商品主数据 + 渠道 SKU 映射 | **已实施 P0/P1** | 2,017 个标准商品、4,897 条映射：`tpl:` 710、`man:` 1,195、`aff:` 49、`wo:` 63；订单项已按履约证据/人工内部 SKU 归一 |
|
||
| 成本中心 | **已实施 P0** | 迁移 `104`；710 个规则级版本 + 2 个全局占位版本；工单成本快照 151,939 条，其中 actual 129,430、estimated 22,509 |
|
||
| 销售事实 / 订单毛利 | **已实施 P0** | 迁移 `105`；375,447 项、收入 ¥3,143.61 万、成本 ¥572.95 万、毛利 ¥2,570.66 万；`sales_daily_facts.fulfillment_mode` |
|
||
| 人工成本录入（确认履约） | **已实施 P0（2026-10-26 单事务 + 防重复）** | 确认即扣积分/备用金并写 `actual` 快照；钱与成本同事务、订单项级唯一；无登记单/审批/报销 |
|
||
| 人工 SKU 配置自动匹配 | **已实施（2026-10-26）** | 保存配置立即回填 + 定时 rematch + 确认时按 SKU 兜底匹配 |
|
||
| 人工缺成本监控 | **已实施（2026-10-26）** | `manual_cost_missing`：首次人工配置之后的订单项未确认即入队，确认后自动收口 |
|
||
| 履约方式统一 | **已实施 P0** | 迁移 `105`；375,447 项全部回填：接单平台 153,148、人工 115,194、历史平台 53,901、自动发货 53,204 |
|
||
| 人工商品归一 | **已实施 P1（本次快照恢复执行）** | 人工 115,194 项已归一为 1,195 个 `man:<内部SKU>` 商品；历史人工支出仍不补录 |
|
||
| 影子总账 | **已实施 P0（2026-10-26）** | `finance_accounts/journal_entries/journal_lines/periods`；销售事实按日凭证 + 手工凭证 + 试算平衡；不接管钱包余额 |
|
||
| 成本异常归档 | **已实施** | 迁移 `108`；已处理异常超 60 天搬入 `cost_exceptions_archive`，open 行不归档；`COST_EXCEPTION_RETENTION_DAYS` 可调 |
|
||
| 平台对账 / 期间关账 | **已实施 P0** | 平台账单 JSON 导入匹配、差异明细、标记解决；关账/反关账；见 `/admin/finance/ledger` |
|
||
| 平台退款 API | **部分实施** | 快手行业（91）同意退款已接入；抖音/拼多多暂未接 API，仍手工登记 |
|
||
|
||
> 分支状态（2026-10-26）：`dev` 已合并 `dev1023` 与人工成本完整性修复，迁移基线收敛为 `103`–`111`（原 108–115 的财务/性能补丁合并进 108）；临时库从 001 全量执行与从 101 升级均待验收。**未推送、未部署生产**；生产口径仍以 `main` 为准。上线前按 [财务上线初始化与验收-2026-10-26.md](财务上线初始化与验收-2026-10-26.md) 初始化资金与人工 SKU。
|
||
> 财务与履约口径以 [财务与履约口径总纲-2026-10-23.md](财务与履约口径总纲-2026-10-23.md) 为准。
|
||
|
||
## 三、统一实施顺序
|
||
|
||
```text
|
||
0. 统一履约事实（fulfillment_mode + 成本模型正交） 已完成 P0（迁移 105）
|
||
1. 商品主数据 + 渠道 SKU 映射 已完成 P0（仅自动发货/接单平台）
|
||
2. 成本中心 + 销售事实 已完成 P0
|
||
2.5 人工成本链路收敛（确认履约 → 扣积分/备用金 → 写快照） 已完成 P0（迁移 104/107/111）
|
||
3. 人工商品归一与上线后人工成本全覆盖 已完成代码；生产数据需上线后配置 SKU（历史不补录）
|
||
4. 退款冲减与异常队列 已完成手工退款 + 快手平台退款；人工缺成本已入队
|
||
5. 影子总账（销售事实 + 手工凭证） 已完成 P0（迁移 108）
|
||
6. 平台对账、期间关账 已完成 P0（手工账单导入）；平台自动拉单未实施
|
||
```
|
||
|
||
**第 0 步已完成。** 迁移、回填、代码改造与验收结果见 [成本中心与履约模型](成本中心与履约模型.md) §六、§八。下一步只做第 3 步人工商品归一，不要同时改退款或总账。
|
||
|
||
## 四、当前必须拍板
|
||
|
||
| # | 问题 | 当前结论 | 影响 |
|
||
| --- | --- | --- | --- |
|
||
| 1 | 收入金额口径 | ✅ 用户实付（`orders.total_amount`） | 收入基数 |
|
||
| 2 | 收入确认时点 | ✅ 先按 `paid_at` 归属销售日；成本在快照生成后回填 | 利润表与预收账款 |
|
||
| 3 | 打手报酬 | ✅ 支出/成本，总额法 | 履约成本 |
|
||
| 4 | 退款/仲裁 | ✅ 暂不实现，只预留反向凭证 | 后续冲减 |
|
||
| 5 | 人工支出如何入账 | ✅ 逐单实际金额；从客服备用金扣款；客服只能用本人账户 | 人工成本与备用金 |
|
||
| 6 | 历史人工支出 | ✅ **不补录**，只取少量样本校准 | 上线范围 |
|
||
| 7 | 电子凭证是否作为分类 | ✅ **不作为履约/成本分类**，只是核销码状态 | 报表口径 |
|
||
| 8 | 平台服务费/支付通道费 | ⏳ 待定 | 费用科目与对账 |
|
||
| 9 | 寄卖货款成本确认时点 | ⏳ 待定 | 存货/采购成本 |
|
||
| 10 | 是否需要发票/税务、是否多币种 | ⏳ 待定 | 当前按 CNY、无税务实现 |
|
||
|
||
## 五、现行与参考文档
|
||
|
||
| 文档 | 状态 | 用途 |
|
||
| --- | --- | --- |
|
||
| [财务与履约口径总纲-2026-10-23.md](财务与履约口径总纲-2026-10-23.md) | **现行唯一口径** | 履约方式、成本模型、人工全覆盖、历史策略、实施顺序、运营日检与验收 SQL |
|
||
| [成本中心与履约模型.md](成本中心与履约模型.md) | 现行 | 商品、成本版本、快照、异常、销售事实的数据模型；迁移 `103`–`111`；履约回填；迁移基线与本地库同步；索引与性能 |
|
||
| [成本中心API契约.md](成本中心API契约.md) | 现行 | 成本中心接口字段替换总表、枚举、模块边界（后端 5 模块 + 前端 4 个固定 Tab） |
|
||
| [人工支出与备用金.md](人工支出与备用金.md) | 现行（P0 已实施） | 确认履约流程/权限、客服备用金台账、本人账户与编号规则 |
|
||
| [财务上线初始化与验收-2026-10-26.md](财务上线初始化与验收-2026-10-26.md) | **现行上线手册** | 迁移后资金/人工 SKU 初始化、验收 SQL、日常监控 |
|
||
| [财务系统集成方案.md](财务系统集成方案.md) | 现行方案（影子总账 P0 已实施） | 复式记账、总账表、对账、关账；P1/P2 平台自动对账待接 |
|
||
| [影子总账说明.md](影子总账说明.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 自动履约接口与字段 |
|
||
| [履约配置/cloudtentacles发货平台.md](履约配置/cloudtentacles发货平台.md) | 历史参考 | 已下线通道的第三方接口样例，不代表现行实现 |
|
||
| [91卡券/6.开发设计.md](91卡券/6.开发设计.md) | 现行 | `kuaishou-91` 来源的 91 侧接入设计 |
|
||
| [抖音-码速达/00-总览.md](抖音-码速达/00-总览.md) | 现行 | 抖音码速达接入总览与增量记录 |
|
||
| [抖音-码速达/12-按SKU分类改造总设计.md](抖音-码速达/12-按SKU分类改造总设计.md) | 现行 | 抖音三层分流与载体唯一 |
|
||
| [部署启动与数据库重建.md](部署启动与数据库重建.md) | 现行 | 本地/生产启动、迁移、重建 |
|
||
| [数据库备份与恢复.md](数据库备份与恢复.md) | 现行 | 备份、恢复、OSS |
|
||
| [数据库SQL约束与运维.md](数据库SQL约束与运维.md) | 现行 | SQL 护栏与生产观测 |
|
||
|
||
### SQL 草案（未接入迁移）
|
||
|
||
草案只作设计与复盘依据；接入 `apps/backend/src/db/migrations/` 时再拆成 `NNN_slug.sql`，并先跑 `npm run check:sql`。
|
||
|
||
| 文件 | 用途 | 接入前必须处理 |
|
||
| --- | --- | --- |
|
||
| [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` 取代，仅作设计追溯 |
|
||
| [archive/2026-10-23/2026-10-17-人工支出登记-DDL草案.sql](archive/2026-10-23/2026-10-17-人工支出登记-DDL草案.sql) | `manual_fulfillment_cases`、`manual_expense_records`、`manual_expense_events` | **已作废**：`manual_expense_records` / `manual_expense_events` 已随迁移 `104` 归并下线，人工成本改走「人工录单 → 扣备用金 → 写快照」；文件已移入 archive |
|
||
|
||
## 六、厂商协议与外部资料
|
||
|
||
这些目录是平台方文档或抓取资料，**不作为本项目实现说明**：
|
||
|
||
| 目录 | 内容 |
|
||
| --- | --- |
|
||
| `91卡券/` | 91 卡券公开接口、签名、加密示例（项目接入结论见 `91卡券/6.开发设计.md`） |
|
||
| `行业电子凭证/` | 快手电子凭证接口、售后、测试指南 |
|
||
| `发货平台-2/` | 早期发货平台协议，现行为 `affiliate_dash`；保留作历史接口对照 |
|
||
| `抖音-码速达/接口API/` | 抖音码速达出网接口 |
|
||
| `抖音-码速达/消息推送/` | 抖音码速达推送消息字段与签名 |
|
||
|
||
## 七、历史文档
|
||
|
||
| 位置 | 说明 |
|
||
| --- | --- |
|
||
| [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 篇文档 |
|
||
|
||
## 八、维护规则
|
||
|
||
1. 改代码影响业务口径时，先改现行文档，再提交代码。
|
||
2. 文档头部必须写「状态 + 最后校准日期 + 代码基线」。
|
||
3. 旧分析不要在原文件上继续堆结论；新建当期报告，旧文件移入 `docs/archive/<日期>/`。
|
||
4. 行号只用于当期基线；跨版本引用优先写文件与函数名。
|
||
5. 新增来源时只加一个 `ProductMatchSourceKey` + 一个适配器；**91 + 快手 send-code 永远算一个 `kuaishou-91`**。
|
||
6. 成本金额只改 `cost_versions`，不要在多个业务表直接改价；历史订单只读 `cost_snapshots`。
|
||
7. 报表维度统一用 `canonical_product_id + shop_id + stat_date`，不要直接用原始 `sku_code` 或 `orders.total_amount`。
|
||
8. 新增 SQL 草案放 `docs/drafts/`，命名 `<日期>-<主题>.sql`；**不得**直接放进 `apps/backend/src/db/migrations/`（后端启动会自动迁移），接入时再拆编号并先跑 `npm run check:sql`。
|
||
9. 财务系统实现顺序以本索引 §三 为准；单篇文档里的分期若与本索引冲突，以本索引为准。
|