yml2213
7bacb7d5eb
合并本轮全部文档改动（原 5 个 docs 提交压成 1 个）。 口径与索引： - 新增 docs/README.md 文档总索引：三来源口径（91 + 快手 send-code = kuaishou-91）、 「一个订单 = 骨架 + 买家凭证 + 一个执行载体」、成本只改一处、文档状态机 - 过期阶段文档移入 docs/archive/2026-10-08/（保留内容，不删除） 分析报告： - docs/项目全量分析报告-2026-10-17.md：架构、五条业务链路、P0/P1/P2 风险与改进路线 - docs/载体判定与成本中心落地-复核与草案-2026-10-17.md：生产只读克隆量化、上一轮结论复核与 4 处修正 方案文档： - docs/成本中心与三块履约模型.md：三块执行载体、标准商品、成本版本与快照、人工支出登记 - docs/财务系统集成方案.md：复式记账模型、分录表、分期落地 - docs/影子总账说明.md：影子期与转正期的边界、对账与转正标准 SQL 草案（docs/drafts/，未接入迁移）： - 载体判定与人工块量化.sql：量化查询、carrier_type 判定与回填、守恒校验 - 成本中心与销售事实-DDL草案.sql：product_catalog / channel_product_mappings / cost_items / cost_versions / cost_snapshots / cost_exceptions / sales_daily_facts - 人工支出登记-DDL草案.sql：manual_fulfillment_cases / manual_expense_records / manual_expense_events 业务口径确认（2026-10-17）： - 收入 = 用户实付（orders.total_amount），与快手 paymentFen 数据核验 100% 一致 - 打手报酬 = 支出/成本（最终提现打款），按总额法 - 人工块以「支出可追溯」为先，SLA 监管延后 - 退款/仲裁暂未接入，先预留字段与反向冲正关系 三份草案已在一次性沙箱库按依赖顺序零错误应用（10 张新表、27 个 CHECK 约束）。
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 | 现行（复核+草案） | 只读克隆量化载体分布与人工块、对上一轮结论的复核与修正、两份 SQL 草案说明 |
| 成本中心与三块履约模型.md | 现行（方案） | 自动发货/接单平台/人工客服三块、统一成本中心、销售事实与人工监管 |
| 财务系统集成方案.md | 现行（方案） | 财务系统边界、复式记账模型、分期落地 |
| 影子总账说明.md | 现行（方案） | 影子总账的定义、运行方式、对账与转正标准 |
| 接单模板匹配引擎重构设计.md | 现行（P0/P1 已实施） | kuaishou-91 / pdd / douyin-mashida 三来源匹配引擎 |
| 履约配置/多发货平台与电子凭证整体链路.md | 现行 | 进单、履约、领取、电子凭证的整体链路 |
| affiliate-dash-发货平台/affiliate-dash对接.md | 现行 | affiliate-dash 自动履约接口与字段 |
| 履约配置/cloudtentacles发货平台.md | 历史参考 | 已下线通道的第三方接口样例，不代表现行实现 |
| 91卡券/6.开发设计.md | 现行 | kuaishou-91 来源的 91 侧接入设计 |
| 抖音-码速达/00-总览.md | 现行 | 抖音码速达接入总览与增量记录 |
| 抖音-码速达/12-按SKU分类改造总设计.md | 现行 | 抖音三层分流与载体唯一 |
| 部署启动与数据库重建.md | 现行 | 本地/生产启动、迁移、重建 |
| 数据库备份与恢复.md | 现行 | 备份、恢复、OSS |
| 数据库SQL约束与运维.md | 现行 | SQL 护栏与生产观测 |
SQL 草案（未接入迁移）
草案只作设计与复盘依据；接入 apps/backend/src/db/migrations/ 时再拆成 NNN_slug.sql，并先跑 npm run check:sql。
| 文件 | 用途 |
|---|---|
| drafts/2026-10-17-载体判定与人工块量化.sql | 载体分布/人工块量化查询、carrier_type 判定与回填、守恒校验、人工成本区间 |
| 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 | manual_fulfillment_cases、manual_expense_records（付款项目/金额/订单号/付款人/凭证）、manual_expense_events；依赖成本中心草案，须在其后应用 |
三、厂商协议与外部资料
这些目录是平台方文档或抓取资料，不作为本项目实现说明：
| 目录 | 内容 |
|---|---|
91卡券/ |
91 卡券公开接口、签名、加密示例（项目接入结论见 91卡券/6.开发设计.md） |
行业电子凭证/ |
快手电子凭证接口、售后、测试指南 |
发货平台-2/ |
早期发货平台协议，现行为 affiliate_dash；保留作历史接口对照 |
抖音-码速达/接口API/ |
抖音码速达出网接口 |
抖音-码速达/消息推送/ |
抖音码速达推送消息字段与签名 |
四、历史文档
| 位置 | 说明 |
|---|---|
| archive/README.md | 2026-10-08 及更早的阶段分析、寄卖方案、性能快照、一次性迁移检查脚本 |
五、维护规则
- 改代码影响业务口径时，先改现行文档，再提交代码。
- 文档头部必须写「状态 + 最后校准日期 + 代码基线」。
- 旧分析不要在原文件上继续堆结论；新建当期报告，旧文件移入
docs/archive/<日期>/。 - 行号只用于当期基线；跨版本引用优先写文件与函数名。
- 新增来源时只加一个
ProductMatchSourceKey+ 一个适配器；91 + 快手 send-code 永远算一个kuaishou-91。 - 成本金额只改
cost_versions，不要在多个业务表直接改价；历史订单只读cost_snapshots。 - 报表维度统一用
canonical_product_id + shop_id + stat_date，不要直接用原始sku_code或orders.total_amount。 - 新增 SQL 草案放
docs/drafts/，命名<日期>-<主题>.sql；不得直接放进apps/backend/src/db/migrations/（后端启动会自动迁移），接入时再拆编号并先跑npm run check:sql。