order_site/docs

order_site 文档索引

最后校准：2026-10-23，代码基线 dev @ a7f60414 + 财务 103–113。 本文是 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。但订单表与成本映射里存储的 provider 仍是 orders.provider = 91kaquan；成本中心会把 91 / open_91 / kuaishou-91 这些别名归一为 91kaquan，映射键必须按落库值建。

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. 两个“人工支出”不是一回事

名称	业务含义	当前状态
manual_expenses	客服备用金支出明细：客服从自己的备用金里充值/采购/赔偿，减少客服余额	已实施（迁移 100）
manual_expense_records	公司人工支出/垫付登记：按订单/成本项记录公司实际付出去的钱、付款人、收款人、凭证、审批	已实施 P0（迁移 111）

后续做财务系统时，不要把 manual_expenses 直接改名或复用为 manual_expense_records。两者业务含义、审批链和报表口径不同，应通过 fund_expense_id 建立关联。

5. 文档状态

状态	含义
现行	与当前代码一致，改动代码时必须同步更新
方案	尚未实施，但作为下一阶段实现依据
参考	外部协议、历史数据或解释性材料，不作为实现依据
历史	只用于追溯，不得作为实现依据；位于 docs/archive/

二、财务系统当前进度

模块	状态	事实
客服备用金台账	已实施 P0	fund_accounts / fund_entries / manual_expenses / fund_reconciliations；后台页面、权限、审计已完成
后台用户中文显示名	已实施	admin_users.display_name，备用金姓名触发器同步；审计、登录记录、任务处理人优先显示中文名
商品主数据 + 渠道 SKU 映射	已实施 P0（dev 分支）	迁移 103（映射消歧在 106）；product_catalog / channel_product_mappings，后台「商品与成本」页支持维护、历史订单项回填与按载体分区
成本中心	已实施 P0（dev 分支）	迁移 104/105/107/108/110/112；cost_items / cost_versions / cost_snapshots / cost_exceptions 支持版本、预览、快照、异常队列、自动发货价格导入；自动发货订单项按履约任务 SKU 直接归一为 aff:<skuCode>（不建渠道映射），接单平台按工单模板回填商品并为 662 个模板生成规则级发单金额版本，人工按支出登记写入实际快照
销售事实 / 订单毛利	已实施 P0（dev 分支）	迁移 109；sales_daily_facts 按店铺×日期×标准商品×载体汇总，未归一商品单独成行；后台新增「销售毛利」页，成本缺失会显式告警
公司人工支出登记	已实施 P0（dev 分支）	迁移 111；manual_expense_records / manual_expense_events，后台「人工支出」页支持登记、审批、驳回、报销；与客服备用金 manual_expenses 通过 fund_expense_id 关联
影子总账	未实施	现有财务页仍是 UNION ALL 业务事件拼装，不是复式总账
平台对账 / 期间关账	未实施	仅方案

分支状态（2026-10-22）：商品主数据、渠道映射、成本中心、成本快照运行层、销售事实与公司人工支出登记在 dev 分支（原 feat/cost-center-wip 已合并），尚未合并 main、未部署生产；生产口径仍以 main 为准。

三、统一实施顺序

1. 商品主数据 + 渠道 SKU 映射                 已完成 P0
2. 成本中心 + 销售事实（先接收入与标准成本）   已完成 P0（迁移 108/109）
3. 订单毛利 / 店铺日报                        已完成 P0（销售毛利页，成本缺失显式告警）
4. 公司人工支出登记（桥接现有客服备用金支出） 已完成 P0（迁移 111）
5. 影子总账（订单、工单、押金、提现、寄卖、售后） 未实施
6. 平台对账、报表、期间关账                   未实施

不要跳过 1–3 直接做影子总账。 没有商品归一、成本版本和订单损益，影子账只能记“总额”，无法回答“哪个店铺、哪个商品、哪条履约链路赚钱”。

四、当前必须拍板

#	问题	当前结论	影响
1	收入金额口径	✅ 用户实付（orders.total_amount）	收入基数
2	收入确认时点	✅ 先按 paid_at 归属销售日；成本在快照生成后回填	利润表与预收账款
3	打手报酬	✅ 支出/成本，总额法	履约成本
4	退款/仲裁	✅ 暂不实现，只预留反向凭证	后续冲减
5	人工支出如何入账	✅ 以人工支出登记为入口；需与客服备用金支出桥接	人工成本与应付垫付人
6	平台服务费/支付通道费	⏳ 待定	费用科目与对账
7	寄卖货款成本确认时点	⏳ 待定	存货/采购成本
8	是否需要发票/税务、是否多币种	⏳ 待定	当前按 CNY、无税务实现

五、现行与参考文档

文档	状态	用途
项目全量分析报告-2026-10-17.md	参考	当前架构、业务链路、风险与改进路线；代码基线早于备用金实现，涉及财务部分以本索引为准
财务系统集成方案.md	现行方案（未实施）	财务系统边界、复式记账模型、核心表、API、分期落地
成本中心与三块履约模型.md	现行（P0 已实施）	自动发货/接单平台/人工客服三块、商品映射、成本中心与销售事实
人工支出登记落地方案-2026-10-17.md	现行（P0 已实施）	公司人工支出登记：字段、入口、状态机、权限、与备用金/成本中心/总账的衔接
影子总账说明.md	现行说明（未实施）	影子总账是什么、和钱包流水的区别、对账与转正标准
客服备用金台账实施方案-2026-10-18.md	已实施 P0	客服备用金账户、流水、支出、对账、权限与上线记录
接单模板匹配引擎重构设计.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 判定与回填	只读查询可直接用；DDL 部分按当前迁移号顺延，不占用 100/101
drafts/2026-10-17-成本中心与销售事实-DDL草案.sql	product_catalog、channel_product_mappings、cost_items/versions/snapshots/exceptions、sales_daily_facts	商品、成本、销售事实均已落地（103–109）；系统成本项在 110；草案仅作设计追溯，不再作为建表依据
drafts/2026-10-17-人工支出登记-DDL草案.sql	manual_fulfillment_cases、manual_expense_records、manual_expense_events	人工支出登记已落地为 111；轻量人工 case 仍为草案

六、厂商协议与外部资料

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

目录	内容
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 第二轮复核与数据量化；结论已吸收进现行成本中心文档，仅作历史追溯

八、维护规则

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. 财务系统实现顺序以本索引 §三 为准；单篇文档里的分期若与本索引冲突，以本索引为准。