order_site/docs

order_site 文档索引

最后校准：2026-10-27，代码基线 dev（合并 dev1023 + 人工成本完整性修复 + 财务 P0 控制，迁移基线收敛为 103–105；未部署生产）。 数据基线：生产 dump backups/postgres/order_site-20261022-092601.dump（数据 2026-07-10 ~ 2026-10-22）；本地已校准到 105（103 财务基础、104 财务控制/L1、105 拼单/寄卖客服），生产按收敛后的 102 → 105 路径执行。历史全量数字仅作基线，上线验收以 财务上线初始化与验收-2026-10-26.md 为准。 本文是 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. 人工成本只有一条链路

订单列表/详情「确认履约」→ 扣客服积分/备用金 → 写 cost_snapshots（manual_case）

名称	业务含义	当前状态
manual_expenses	客服备用金支出明细：客服从自己的备用金里充值/采购/赔偿，减少客服余额	已实施（迁移 100）；确认履约的现金支出也写这里
cost_snapshots	人工成本的唯一落点：subject_type='manual_case'，subject_id=order_item_id（资金来源写 metadata）	已实施（迁移 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	迁移 103；710 个规则级版本 + 2 个全局占位版本；工单成本快照 151,939 条，其中 actual 129,430、estimated 22,509
销售事实 / 订单毛利	已实施 P0	迁移 103；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	迁移 103；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-27）：dev 已合并 dev1023 与人工成本完整性修复，迁移收敛为 103–105（103 财务基础、104 财务控制/L1、105 拼单/寄卖客服）；已验证 001→105 与 102→105 两条升级路径。未推送、未部署生产；生产口径仍以 main 为准。上线前按 财务上线初始化与验收-2026-10-26.md 初始化资金与人工 SKU。 财务与履约口径以 财务与履约口径总纲-2026-10-23.md 为准。

三、统一实施顺序

0. 统一履约事实（fulfillment_mode + 成本模型正交）   已完成 P0（迁移 103）
1. 商品主数据 + 渠道 SKU 映射                        已完成 P0（仅自动发货/接单平台）
2. 成本中心 + 销售事实                              已完成 P0
2.5 人工成本链路收敛（确认履约 → 扣积分/备用金 → 写快照）   已完成 P0（迁移 104）
3. 人工商品归一与上线后人工成本全覆盖                已完成代码；生产数据需上线后配置 SKU（历史不补录）
4. 退款冲减与异常队列                               已完成手工退款 + 快手平台退款；人工缺成本已入队
5. 影子总账（销售事实 + 手工凭证）                    已完成 P0（迁移 108）
6. 平台对账、期间关账                              已完成 P0（手工账单导入）；平台自动拉单未实施

第 0 步已完成。 迁移、回填、代码改造与验收结果见 成本中心与履约模型 §六、§八。下一步只做第 3 步人工商品归一，不要同时改退款或总账。

四、当前必须拍板

#	问题	当前结论	影响
1	收入金额口径	✅ 用户实付（orders.total_amount）	收入基数
2	收入确认时点	✅ 先按 paid_at 归属销售日；成本在快照生成后回填	利润表与预收账款
3	打手报酬	✅ 支出/成本，总额法	履约成本
4	退款/仲裁	✅ 暂不实现，只预留反向凭证	后续冲减
5	人工支出如何入账	✅ 逐单实际金额；从客服备用金扣款；客服只能用本人账户	人工成本与备用金
6	历史人工支出	✅ 不补录，只取少量样本校准	上线范围
7	电子凭证是否作为分类	✅ 不作为履约/成本分类，只是核销码状态	报表口径
8	平台服务费/支付通道费	⏳ 待定	费用科目与对账
9	寄卖货款成本确认时点	⏳ 待定	存货/采购成本
10	是否需要发票/税务、是否多币种	⏳ 待定	当前按 CNY、无税务实现

五、现行与参考文档

文档	状态	用途
财务与履约口径总纲-2026-10-23.md	现行唯一口径	履约方式、成本模型、人工全覆盖、历史策略、实施顺序、运营日检与验收 SQL
成本中心与履约模型.md	现行	商品、成本版本、快照、异常、销售事实的数据模型；迁移 103–105；履约回填；迁移基线与本地库同步；索引与性能
成本中心API契约.md	现行	成本中心接口字段替换总表、枚举、模块边界（后端 5 模块 + 前端 4 个固定 Tab）
人工支出与备用金.md	现行（P0 已实施）	确认履约流程/权限、客服备用金台账、本人账户与编号规则
财务上线初始化与验收-2026-10-26.md	现行上线手册	迁移后资金/人工 SKU 初始化、验收 SQL、日常监控
财务系统集成方案.md	现行方案（影子总账 P0 已实施）	复式记账、总账表、对账、关账；P1/P2 平台自动对账待接
财务系统深度分析-2026-10-27.md	参考（一次性审计，不改变现行口径）	2026-10-27 代码/数据/权限审计、风险清单与上线前修复路线
dev合并main评估-2026-10-27.md	参考（合并评估）	dev 领先 main 的改动、迁移收敛、生产规模升级实测与发布检查清单
财务代码审计复核-2026-10-27.md	参考（代码复核）	对“旧报表重复扣减、总账 DELETE、钱包 BIGINT、死锁”等结论的逐条校正与补充
打手重复奖励核对-2026-10-27.md	待人工核对	8 组疑似重复奖励、16 条流水、多计 ¥196.20；含 84886 寄卖误报说明
影子总账说明.md	现行说明（P0 已实施）	影子总账是什么、和钱包流水的区别、对账与转正标准
项目全量分析报告-2026-10-17.md	历史参考	2026-10-17 架构与风险；财务口径以总纲为准
接单模板匹配引擎重构设计.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 判定与回填	已过时：carrier_type 已从商品/成本/快照/异常表删除；只读查询里的口径结论已吸收进总纲 §二
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	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	2026-10-08 及更早的阶段分析、寄卖方案、性能快照、一次性迁移检查脚本；2026-10-17 复核文档
archive/2026-10-17/载体判定与成本中心落地-复核与草案.md	2026-10-17 第二轮复核与数据量化；结论已吸收进现行成本中心文档，仅作历史追溯
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. 财务系统实现顺序以本索引 §三 为准；单篇文档里的分期若与本索引冲突，以本索引为准。