# order_site 文档索引

> 最后校准：2026-10-17，代码基线 `main @ 6850bc64`。
> 本文是 `docs/` 的唯一入口。新增文档必须在上表登记状态；过期文档不再直接改写结论，统一移入 `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`。

### 2. 一个订单 = 骨架 + 买家凭证 + 一个执行载体

- 骨架：`orders` + `order_items`
- 买家凭证：快手电子凭证（`kuaishou_industry_vouchers`）或抖音券（`redeem_certificates`）
- 执行载体只有三种：`affiliate_dash` 自动发货、`work_orders` 工单、`manual` 人工客服
- 三者业务上互斥；无自动任务且无工单的已支付订单项就是人工块，必须进入人工 case，不能静默消失

### 3. 成本只在一个地方改

- 商品主数据：`product_catalog`
- 渠道 SKU 映射：`channel_product_mappings`
- 成本金额：只在 `cost_versions` 改，按生效日期新增版本
- 订单/工单/人工单只保存 `cost_snapshot_id`，历史成本永不回写
- 自动发货、接单平台、人工客服共用同一个成本解析器；匹配不到成本进入 `cost_missing`，不默认 0

### 4. 文档状态

| 状态 | 含义 |
| --- | --- |
| 现行 | 与当前代码一致，改动代码时必须同步更新 |
| 参考 | 厂商协议、外部接口文档，按平台版本更新 |
| 历史 | 只用于追溯，不得作为实现依据；位于 `docs/archive/` |

## 二、现行文档

| 文档 | 状态 | 用途 |
| --- | --- | --- |
| [项目全量分析报告-2026-10-17.md](项目全量分析报告-2026-10-17.md) | 现行 | 当前架构、业务链路、风险与改进路线 |
| [载体判定与成本中心落地-复核与草案-2026-10-17.md](载体判定与成本中心落地-复核与草案-2026-10-17.md) | 现行（复核+草案） | 只读克隆量化载体分布与人工块、对上一轮结论的复核与修正、两份 SQL 草案说明 |
| [人工支出登记落地方案-2026-10-17.md](人工支出登记落地方案-2026-10-17.md) | 现行（方案） | 以订单为入口的支出登记：字段级预填分工、交互入口、状态机与权限、校验与异常队列、分阶段落地 |
| [成本中心与三块履约模型.md](成本中心与三块履约模型.md) | 现行（方案） | 自动发货/接单平台/人工客服三块、统一成本中心、销售事实与人工监管 |
| [财务系统集成方案.md](财务系统集成方案.md) | 现行（方案） | 财务系统边界、复式记账模型、分期落地 |
| [影子总账说明.md](影子总账说明.md) | 现行（方案） | 影子总账的定义、运行方式、对账与转正标准 |
| [接单模板匹配引擎重构设计.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` 判定与回填、守恒校验、人工成本区间 |
| [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` 建表草案 |
| [drafts/2026-10-17-人工支出登记-DDL草案.sql](drafts/2026-10-17-人工支出登记-DDL草案.sql) | `manual_fulfillment_cases`、`manual_expense_records`（付款项目/金额/订单号/付款人/凭证）、`manual_expense_events`；依赖成本中心草案，须在其后应用 |

## 三、厂商协议与外部资料

这些目录是平台方文档或抓取资料，**不作为本项目实现说明**：

| 目录 | 内容 |
| --- | --- |
| `91卡券/` | 91 卡券公开接口、签名、加密示例（项目接入结论见 `91卡券/6.开发设计.md`） |
| `行业电子凭证/` | 快手电子凭证接口、售后、测试指南 |
| `发货平台-2/` | 早期发货平台协议，现行为 `affiliate_dash`；保留作历史接口对照 |
| `抖音-码速达/接口API/` | 抖音码速达出网接口 |
| `抖音-码速达/消息推送/` | 抖音码速达推送消息字段与签名 |

## 四、历史文档

| 位置 | 说明 |
| --- | --- |
| [archive/README.md](archive/README.md) | 2026-10-08 及更早的阶段分析、寄卖方案、性能快照、一次性迁移检查脚本 |

## 五、维护规则

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`。