order_site 文档索引
最后校准：2026-10-24，代码基线 dev @ 790de676 + 本地未提交修复（未推送、未部署生产）。
数据基线：生产 dump backups/postgres/order_site-20261022-092601.dump（数据 2026-07-10 ~ 2026-10-22）；本地已按真实升级路径从生产迁移 101 升到 107，并完成商品、成本快照、销售事实初始化。
本文是 docs/ 的唯一入口。财务与履约口径以 财务与履约口径总纲-2026-10-23.md 为准；数据模型看 成本中心与履约模型.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. 人工成本只有一条链路
| 名称 |
业务含义 |
当前状态 |
manual_expenses |
客服备用金支出明细：客服从自己的备用金里充值/采购/赔偿，减少客服余额 |
已实施（迁移 100）；确认履约的现金支出也写这里 |
cost_snapshots |
人工成本的唯一落点：subject_type='manual_case'，subject_id=manual_expenses.id |
已实施（迁移 104） |
没有独立的登记单，也没有审批与报销环节。 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-24 入口收敛到订单页） |
人工履约页已下线；确认即扣积分/备用金并写 actual 快照；无登记单/审批/报销 |
| 履约方式统一 |
已实施 P0 |
迁移 105；375,447 项全部回填：接单平台 153,148、人工 115,194、历史平台 53,901、自动发货 53,204 |
| 人工商品归一 |
已实施 P1（本次快照恢复执行） |
人工 115,194 项已归一为 1,195 个 man:<内部SKU> 商品；历史人工支出仍不补录 |
| 影子总账 |
未实施 |
现有财务页仍是 UNION ALL 业务事件拼装，不是复式总账 |
| 退款冲减 / 平台对账 / 期间关账 |
未实施 |
仅方案 |
分支状态（2026-10-25）：dev @ 465a9f65 之上完成迁移收敛（10 → 5，103–107），并已与 main 的 worker-hall 改动合并。本地库按「清 schema_migrations 103–112 后重跑」对齐，升级结果与全新构建的 schema 完全一致；生产 101 → 107 的路径已验证。未推送、未部署生产；生产口径仍以 main 为准。
财务与履约口径以 财务与履约口径总纲-2026-10-23.md 为准。
三、统一实施顺序
第 0 步已完成。 迁移、回填、代码改造与验收结果见 成本中心与履约模型 §六、§八。下一步只做第 3 步人工商品归一，不要同时改退款或总账。
四、当前必须拍板
| # |
问题 |
当前结论 |
影响 |
| 1 |
收入金额口径 |
✅ 用户实付（orders.total_amount） |
收入基数 |
| 2 |
收入确认时点 |
✅ 先按 paid_at 归属销售日；成本在快照生成后回填 |
利润表与预收账款 |
| 3 |
打手报酬 |
✅ 支出/成本，总额法 |
履约成本 |
| 4 |
退款/仲裁 |
✅ 暂不实现，只预留反向凭证 |
后续冲减 |
| 5 |
人工支出如何入账 |
✅ 逐单实际金额；从客服备用金扣款；客服只能用本人账户 |
人工成本与备用金 |
| 6 |
历史人工支出 |
✅ 不补录，只取少量样本校准 |
上线范围 |
| 7 |
电子凭证是否作为分类 |
✅ 不作为履约/成本分类，只是核销码状态 |
报表口径 |
| 8 |
平台服务费/支付通道费 |
⏳ 待定 |
费用科目与对账 |
| 9 |
寄卖货款成本确认时点 |
⏳ 待定 |
存货/采购成本 |
| 10 |
是否需要发票/税务、是否多币种 |
⏳ 待定 |
当前按 CNY、无税务实现 |
五、现行与参考文档
SQL 草案（未接入迁移）
草案只作设计与复盘依据；接入 apps/backend/src/db/migrations/ 时再拆成 NNN_slug.sql，并先跑 npm run check:sql。
六、厂商协议与外部资料
这些目录是平台方文档或抓取资料，不作为本项目实现说明：
| 目录 |
内容 |
91卡券/ |
91 卡券公开接口、签名、加密示例（项目接入结论见 91卡券/6.开发设计.md） |
行业电子凭证/ |
快手电子凭证接口、售后、测试指南 |
发货平台-2/ |
早期发货平台协议，现行为 affiliate_dash；保留作历史接口对照 |
抖音-码速达/接口API/ |
抖音码速达出网接口 |
抖音-码速达/消息推送/ |
抖音码速达推送消息字段与签名 |
七、历史文档
八、维护规则
- 改代码影响业务口径时，先改现行文档，再提交代码。
- 文档头部必须写「状态 + 最后校准日期 + 代码基线」。
- 旧分析不要在原文件上继续堆结论；新建当期报告，旧文件移入
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。
- 财务系统实现顺序以本索引 §三 为准；单篇文档里的分期若与本索引冲突，以本索引为准。
yml2213
ad1e1bc884