diff --git a/docs/README.md b/docs/README.md index 7165c71e..039b6766 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,7 +1,7 @@ # order_site 文档索引 > 最后校准：2026-10-24，代码基线 `dev @ 790de676 + 本地未提交修复`（**未推送、未部署生产**）。 -> 数据基线：生产 dump `backups/postgres/order_site-20261022-092601.dump`（数据 2026-07-10 ~ 2026-10-22）；本地已按真实升级路径从生产迁移 101 升到 112，并完成商品、成本快照、销售事实初始化。 +> 数据基线：生产 dump `backups/postgres/order_site-20261022-092601.dump`（数据 2026-07-10 ~ 2026-10-22）；本地已按真实升级路径从生产迁移 101 升到 107，并完成商品、成本快照、销售事实初始化。 > 本文是 `docs/` 的唯一入口。**财务与履约口径以 [财务与履约口径总纲-2026-10-23.md](财务与履约口径总纲-2026-10-23.md) 为准**；数据模型看 [成本中心与履约模型.md](成本中心与履约模型.md)，接口看 [成本中心API契约.md](成本中心API契约.md)。 > 新增文档必须在下表登记状态；过期文档不再直接改写结论，统一移入 `docs/archive/`。 @@ -55,7 +55,7 @@ | `manual_expenses` | **客服备用金支出明细**：客服从自己的备用金里充值/采购/赔偿，减少客服余额 | 已实施（迁移 100）；确认履约的现金支出也写这里 | | `cost_snapshots` | **人工成本的唯一落点**：`subject_type='manual_case'`，`subject_id=manual_expenses.id` | 已实施（迁移 104） | -**没有独立的登记单，也没有审批与报销环节。** `manual_expense_records` / `manual_expense_events` 已随迁移 `108` 删除。后续做财务系统时，人工成本的钱与账都从这条链路走，不要再另造一张人工支出表。 +**没有独立的登记单，也没有审批与报销环节。** `manual_expense_records` / `manual_expense_events` 已随迁移 `104` 归并下线（这两张表在生产 102 上从未创建）。后续做财务系统时，人工成本的钱与账都从这条链路走，不要再另造一张人工支出表。 ### 6. 历史人工直接放弃，上线后必须全覆盖 @@ -76,27 +76,27 @@ | 模块 | 状态 | 事实 | | --- | --- | --- | -| 客服备用金台账 | **已实施 P0** | 迁移 `100/101/106`；账户、流水、支出、对账；编号 `FA-<用户名>`；客服只能使用本人账户 | +| 客服备用金台账 | **已实施 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** | 迁移 `107`；375,447 项全部回填：接单平台 153,148、人工 115,194、历史平台 53,901、自动发货 53,204 | +| 履约方式统一 | **已实施 P0** | 迁移 `105`；375,447 项全部回填：接单平台 153,148、人工 115,194、历史平台 53,901、自动发货 53,204 | | 人工商品归一 | **已实施 P1（本次快照恢复执行）** | 人工 115,194 项已归一为 1,195 个 `man:<内部SKU>` 商品；历史人工支出仍不补录 | | 影子总账 | 未实施 | 现有财务页仍是 `UNION ALL` 业务事件拼装，不是复式总账 | | 退款冲减 / 平台对账 / 期间关账 | 未实施 | 仅方案 | -> 分支状态（2026-10-24）：工作区基于 `dev @ 790de676`，本地有迁移兼容性、批量回填和成本快照列映射修复，**未提交、未推送、未部署生产**。本地库已用 `order_site-20261022-092601.dump` 重建：生产 101 → dev 112、履约方式回填、商品/映射/成本/销售事实初始化全部完成；生产口径仍以 `main` 为准。 +> 分支状态（2026-10-25）：`dev @ 465a9f65` 之上完成迁移收敛（10 → 5，`103`–`107`），并已与 `main` 的 worker-hall 改动合并。本地库按「清 `schema_migrations` 103–112 后重跑」对齐，升级结果与全新构建的 schema 完全一致；生产 101 → 107 的路径已验证。**未推送、未部署生产**；生产口径仍以 `main` 为准。 > 财务与履约口径以 [财务与履约口径总纲-2026-10-23.md](财务与履约口径总纲-2026-10-23.md) 为准。 ## 三、统一实施顺序 ```text -0. 统一履约事实（fulfillment_mode + 成本模型正交） 已完成 P0（迁移 107） +0. 统一履约事实（fulfillment_mode + 成本模型正交） 已完成 P0（迁移 105） 1. 商品主数据 + 渠道 SKU 映射 已完成 P0（仅自动发货/接单平台） 2. 成本中心 + 销售事实 已完成 P0 -2.5 人工成本链路收敛（确认履约 → 扣积分/备用金 → 写快照） 已完成 P0（迁移 106/108） +2.5 人工成本链路收敛（确认履约 → 扣积分/备用金 → 写快照） 已完成 P0（迁移 104/107） 3. 人工商品归一与上线后人工成本全覆盖 未实施（下一阶段） 4. 退款冲减与异常队列 未实施 5. 影子总账（订单、工单、押金、提现、寄卖、售后） 未实施 @@ -125,7 +125,7 @@ | 文档 | 状态 | 用途 | | --- | --- | --- | | [财务与履约口径总纲-2026-10-23.md](财务与履约口径总纲-2026-10-23.md) | **现行唯一口径** | 履约方式、成本模型、人工全覆盖、历史策略、实施顺序、运营日检与验收 SQL | -| [成本中心与履约模型.md](成本中心与履约模型.md) | 现行 | 商品、成本版本、快照、异常、销售事实的数据模型；迁移 `103–107`；履约回填；本地库原地改造；索引与性能 | +| [成本中心与履约模型.md](成本中心与履约模型.md) | 现行 | 商品、成本版本、快照、异常、销售事实的数据模型；迁移 `103`–`107`；履约回填；迁移基线与本地库同步；索引与性能 | | [成本中心API契约.md](成本中心API契约.md) | 现行 | 成本中心接口字段替换总表、枚举、模块边界（后端 5 模块 + 前端 8 面板） | | [人工支出与备用金.md](人工支出与备用金.md) | 现行（P0 已实施） | 确认履约流程/权限、客服备用金台账、本人账户与编号规则 | | [财务系统集成方案.md](财务系统集成方案.md) | 现行方案（总账未实施） | 复式记账、总账表、对账、关账 | @@ -150,7 +150,7 @@ | --- | --- | --- | | [drafts/2026-10-17-载体判定与人工块量化.sql](drafts/2026-10-17-载体判定与人工块量化.sql) | 载体分布/人工块量化查询、`carrier_type` 判定与回填 | **已过时**：`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` | 已落地为 `103`–`105`；草案里的 `carrier_type` 已被 `cost_model` / `fulfillment_mode` 取代，仅作设计追溯 | -| [archive/2026-10-23/2026-10-17-人工支出登记-DDL草案.sql](archive/2026-10-23/2026-10-17-人工支出登记-DDL草案.sql) | `manual_fulfillment_cases`、`manual_expense_records`、`manual_expense_events` | **已作废**：`manual_expense_records` / `manual_expense_events` 已随迁移 `108` 删除，人工成本改走「人工录单 → 扣备用金 → 写快照」；文件已移入 archive | +| [archive/2026-10-23/2026-10-17-人工支出登记-DDL草案.sql](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 | ## 六、厂商协议与外部资料 diff --git a/docs/人工支出与备用金.md b/docs/人工支出与备用金.md index a6aa276c..6e0eae8a 100644 --- a/docs/人工支出与备用金.md +++ b/docs/人工支出与备用金.md @@ -3,7 +3,7 @@ > 状态：**现行（P0 已实施，未部署生产）**。 > 最后校准：2026-10-24 > **2026-10-24 变更**：独立「人工履约」页面已下线，订单列表/详情里的「人工录单」改为「确认履约」；`/finance/manual-order-cost*` 接口已删除。资金链路不变（扣积分/备用金 → 写 `manual_case` 快照）。 -> 代码基线：`dev @ 43f402cf + 迁移 100/101/106/108`（已合并到 `dev`，**未推送、未部署生产**） +> 代码基线：`dev @ 43f402cf + 迁移 100/101/104/107`（已合并到 `dev`，**未推送、未部署生产**） > **业务口径以 [财务与履约口径总纲-2026-10-23.md](财务与履约口径总纲-2026-10-23.md) 为准**；本文只负责人工录单的字段、流程、权限与备用金台账。 > 本文合并自原《人工支出登记落地方案-2026-10-17.md》与《客服备用金台账实施方案-2026-10-18.md》。 @@ -26,7 +26,7 @@ 结论： -1. **没有单独的登记单表**。`manual_expense_records` 与 `manual_expense_events` 已随迁移 `108` 删除。 +1. **没有单独的登记单表**。`manual_expense_records` 与 `manual_expense_events` 已随迁移 `104` 归并下线。 2. **没有审批、没有报销**。订单页「人工录单」一次操作完成"扣钱 + 记成本"，录入即计入毛利。 3. 客服侧收口的是"备用金余额与用途"：钱从谁的备用金出、付给谁、有没有凭证，全在 `manual_expenses` + `fund_entries`。 4. 客服角色只能用本人备用金账户（后端越权直接 403）；管理员/财务可代录到指定客服账户。 @@ -56,7 +56,7 @@ | --- | --- | | 数据库 | 迁移 `100_fund_accounts.sql`：`fund_accounts` / `fund_entries` / `manual_expenses` / `fund_reconciliations` | | 显示名 | 迁移 `101_admin_display_name.sql`：`admin_users.display_name`，备用金 `owner_name` 由触发器同步 | -| 账户编号 | 迁移 `106_fund_account_no_readable.sql`：`FA-<大写用户名>`（如 `FA-KF_1`、`FA-JIAJIALI`），重名追加 `-2`、`-3` | +| 账户编号 | 迁移 `107_manual_fulfillment.sql`：`FA-<大写用户名>`（如 `FA-KF_1`、`FA-JIAJIALI`），重名追加 `-2`、`-3` | | 后端 | `admin-fund-service.ts`、`routes/admin/fund.ts`；金额全部用分，写操作使用事务与行锁 | | 前端 | `AdminFundPage.tsx`、`FundManagementView.tsx`、`FundSupportView.tsx`；管理端与客服端分流 | | 权限 | `fund.view / fund.issue / fund.expense / fund.reconcile / fund.adjust / fund.export` | @@ -102,7 +102,7 @@ - 组件：`apps/frontend/src/components/admin/ManualOrderCostModal.tsx` - 订单入口：订单列表/详情「人工录单」打开弹窗，锁定订单号、选择订单项与备用金账户、填写本单实际金额；支持深链 `/admin/orders/:orderId?manualCost=1` - 权限：登记 `fund.expense` / `finance.config`；客服角色自动锁定本人账户 -- **已删除**：迁移 `106_manual_expense_records.sql` 建的登记单表（迁移 `108` 删表）、`manual-expense-service.ts`、`AdminManualExpensePage.tsx`、`/admin/manual-expenses` 页面与菜单 +- **已删除**：迁移 `106_manual_expense_records.sql` 建的登记单表（迁移 `104` 归并下线）、`manual-expense-service.ts`、`AdminManualExpensePage.tsx`、`/admin/manual-expenses` 页面与菜单 ### 3.2 资金流与成本流（同一事务） diff --git a/docs/履约配置/多发货平台与电子凭证整体链路.md b/docs/履约配置/多发货平台与电子凭证整体链路.md index 39bfa128..9884fe2b 100644 --- a/docs/履约配置/多发货平台与电子凭证整体链路.md +++ b/docs/履约配置/多发货平台与电子凭证整体链路.md @@ -1,6 +1,6 @@ # 多发货平台与电子凭证整体链路 -> 状态：现行。最后校准：2026-10-23（代码基线 `dev @ 5d1ba115 + 迁移 103–114`；履约方式已统一落库）。 +> 状态：现行。最后校准：2026-10-23（代码基线 `dev @ 5d1ba115 + 迁移 `103`–`107`；履约方式已统一落库）。 > 财务与履约总口径见 [财务与履约口径总纲-2026-10-23.md](../财务与履约口径总纲-2026-10-23.md)。 > 来源口径：本系统只有三个订单来源——`kuaishou-91`、`pdd`、`douyin-mashida`。**91 回调与快手 send-code 是同一个 `kuaishou-91` 来源的两条数据通道**（91=骨架权威源，快手 send-code=补全/兜底源），不是一个来源加另一个来源。 diff --git a/docs/影子总账说明.md b/docs/影子总账说明.md index 90deaf4a..91362dd5 100644 --- a/docs/影子总账说明.md +++ b/docs/影子总账说明.md @@ -2,7 +2,7 @@ > 状态：**现行说明（未实施）** > 最后校准：2026-10-23 -> 代码基线：`dev @ 43f402cf + 迁移 103–109`（已合并到 `dev`，**未推送、未部署生产**） +> 代码基线：`dev @ 43f402cf + 迁移 `103`–`107`（已合并到 `dev`，**未推送、未部署生产**） > 配套方案：[财务系统集成方案.md](财务系统集成方案.md) > **总口径以 [财务与履约口径总纲-2026-10-23.md](财务与履约口径总纲-2026-10-23.md) 为准。** > 前置：统一履约事实、商品主数据、渠道映射、成本中心与销售事实；实施顺序以总纲第六节为准。 diff --git a/docs/成本中心API契约.md b/docs/成本中心API契约.md index b25ffa75..874b1c1b 100644 --- a/docs/成本中心API契约.md +++ b/docs/成本中心API契约.md @@ -1,8 +1,8 @@ # 成本中心 API 契约 > 状态：**现行**。后端服务与前端页面都必须严格按此实现，不得各自发挥。 -> 最后校准：2026-10-23 -> 代码基线：`dev @ 43f402cf + 迁移 103–109`（已合并到 `dev`，**未推送、未部署生产**） +> 最后校准：2026-10-25 +> 代码基线：`dev @ 465a9f65` + 迁移 `103`–`107`（已合并到 `dev`，**未推送、未部署生产**） > 详细业务口径见 [财务与履约口径总纲-2026-10-23.md](财务与履约口径总纲-2026-10-23.md)；数据模型见 [成本中心与履约模型.md](成本中心与履约模型.md)。 ## 一、字段替换总表 diff --git a/docs/成本中心与履约模型.md b/docs/成本中心与履约模型.md index 5451d056..aee86fd1 100644 --- a/docs/成本中心与履约模型.md +++ b/docs/成本中心与履约模型.md @@ -1,9 +1,9 @@ # 成本中心与履约模型 > 状态：**现行**。商品主数据、成本中心、成本快照、销售事实、履约事实均已落地。 -> 最后校准：2026-10-24 -> 代码基线：`dev @ 790de676 + 本地未提交修复`（**未推送、未部署生产**） -> 数据基线：生产 dump `order_site-20261022-092601.dump`（2026-07-10 ~ 2026-10-22）；本地已升级到迁移 112，并完成商品、映射、成本快照与销售事实初始化 +> 最后校准：2026-10-25 +> 代码基线：`dev @ 465a9f65 + 迁移合并`（**未推送、未部署生产**） +> 数据基线：生产 dump `order_site-20261022-092601.dump`（2026-07-10 ~ 2026-10-22）；本地已升级到迁移 107，并完成商品、映射、成本快照与销售事实初始化 > **业务口径以 [财务与履约口径总纲-2026-10-23.md](财务与履约口径总纲-2026-10-23.md) 为准**；本文只负责数据模型、迁移与运维。 > 接口字段见 [成本中心API契约.md](成本中心API契约.md)。 @@ -32,23 +32,27 @@ orders ──┬── order_items ──── fulfillment_mode (唯一履约 --- -## 一、迁移基线：12 个合并为 5 个（+ 1 个清理迁移） +## 一、迁移基线：10 个收敛为 5 个 -原 `dev` 分支上，商品与成本中心用 12 个迁移（`103`–`114`，1,087 行）分批落地，字段反复摇摆。2026-10-23 重写为 5 个： +原 `dev` 分支上，商品、成本中心、人工履约用 10 个迁移（`103`–`112`，1,275 行）分批落地，字段反复摇摆。其中： + +- `108`（下线人工支出登记）与 `109`（隔离历史快照主体）在「生产 102 → 当前」的唯一升级路径上是**空操作**； +- `111` 是给 `104` 自身种子打的补丁（draft 占位改 active 占位）； +- `112` 的 `resolution_note` 列本就属于异常表。 + +2026-10-25 收敛为 5 个（合计 1,151 行）： | 迁移 | 内容 | 行数 | | --- | --- | ---: | | `103_product_catalog.sql` | `product_catalog`（无载体列）+ `channel_product_mappings`（含匹配键）+ `order_items` 商品/归一字段 | 152 | -| `104_cost_center.sql` | `cost_items`（`cost_model`）+ `cost_versions` + `cost_snapshots`（无载体列）+ `cost_exceptions`（无载体列）+ 订单项收入固化 + 系统成本项 | 476 | -| `105_sales_daily_facts.sql` | `sales_daily_facts`（`fulfillment_mode`） | 104 | -| `106_fund_account_no_readable.sql` | 备用金账户编号可读化（`FA-<用户名>`） | 51 | -| `107_order_item_fulfillment_mode.sql` | `order_items.fulfillment_mode` 三列 | 48 | -| `108_drop_manual_expense_records.sql` | 下线人工支出登记单与审批报销状态机（删两张表） | 66 | -| `109_isolate_legacy_manual_snapshots.sql` | 隔离历史人工快照的主体 id（改负数） | 44 | +| `104_cost_center.sql` | `cost_items`（`cost_model`）+ `cost_versions` + `cost_snapshots` + `cost_exceptions`（含 `resolution_note`）+ 订单项收入固化 + 系统成本项 + 遗留占位清理 | 503 | +| `105_sales_daily_facts.sql` | `order_items.fulfillment_mode` 三列 + `sales_daily_facts` | 166 | +| `106_order_refunds.sql` | `order_refunds` 退款表 | 38 | +| `107_manual_fulfillment.sql` | 人工 SKU 登记/配置 + 三平台积分钱包 + 备用金账户编号可读化 | 292 | -> `106` 原名 `106_manual_expense_records.sql`，2026-10-23 因下线人工支出登记链而改为 `106_fund_account_no_readable.sql`；`108` 是配套的清理迁移。 +**合并原则**：同一批上线的结构性 DDL 才合并；数据回填与业务口径注释跟着所属表走。`103` 保持独立（商品主数据是成本与销售事实的共同上游），`106` 保持独立（退款是独立业务线）。 -**关于迁移 109（重要坑）**：人工成本快照的主体从「人工支出登记单 id」改成「客服备用金支出单 id」（`manual_expenses.id`），两套 id 空间各自从 1 开始会撞车。历史孤儿快照保留原 `subject_id` 会与新建的 `manual_expenses.id` 撞唯一索引 `uq_cost_snapshots_active_subject_item`，导致 `INSERT ... ON CONFLICT DO NOTHING` 静默跳过——**钱从备用金扣了、成本快照却没写成**。迁移 109 把来源为旧登记链的历史快照主体改成负数，与正数的 `manual_expenses.id` 彻底隔离。 +**关于历史人工快照的负数 `subject_id`（重要坑，已固化在 `104` 的列注释里）**：人工成本快照的主体从「人工支出登记单 id」改成「客服备用金支出单 id」（`manual_expenses.id`），两套 id 空间各自从 1 开始会撞车。撞上唯一索引 `uq_cost_snapshots_active_subject_item` 后，`INSERT ... ON CONFLICT DO NOTHING` 会静默跳过——**钱从备用金扣了、成本快照却没写成**。历史孤儿快照的主体一律用负数，与正数的 `manual_expenses.id` 彻底隔离；新建链路不再产生负数主体。 ### 1.1 字段替换对照 @@ -253,7 +257,7 @@ resolved_at, superseded_at, created_at - 匹配不到成本时写 `cost_missing` 异常，**不能默认 0**； - 履约方式不存快照里，需要时 join `order_items.fulfillment_mode`； - 人工单的快照主体是 `subject_type='manual_case'` + `subject_id=manual_expenses.id`（客服备用金支出单），**没有独立的登记单表**； -- 负数 `subject_id` 表示历史孤儿快照（已由迁移 109 隔离），金额保留供毛利参考，不与新链路争主体 id。 +- 负数 `subject_id` 表示历史孤儿快照（约定固化在迁移 `104` 的列注释里），金额保留供毛利参考，不与新链路争主体 id。 ### 3.5 `cost_exceptions` @@ -411,43 +415,22 @@ WHERE oi.id = d.id --- -## 八、本地库原地改造（2026-10-23 已执行） +## 八、迁移基线与本地库同步（2026-10-25 更新） -生产尚未执行过 `103–114`，本地库需要从旧 schema 改到新 schema。改造脚本：`scripts/rewrite-local-db-2026-10-23.sql`（列级改造）+ 迁移 `108`（删人工支出登记两表）。 +生产尚未执行过 `103` 及之后的迁移。本地库与代码对齐有两条路径： -改造矩阵（列级 `ALTER`，不重建表、不动源表）： +1. **全新升级**：从生产 dump 恢复到 `101` / `102`，直接 `npm run db:migrate` 升到 `107`； +2. **已有本地库**：清掉 `schema_migrations` 里 `103`–`112` 的记录后重跑。所有迁移都是 `IF NOT EXISTS`，数据步骤幂等： -| 表 | 改造 | -| --- | --- | -| `product_catalog` | 删 `carrier_type` | -| `cost_items` | `cost_type` + `carrier_type` → `cost_model`；`auto_purchase` 编码统一为 `sys_affiliate_purchase` | -| `cost_snapshots` | 删 `carrier_type`、删未使用的 `manual_case_id` | -| `cost_exceptions` | 删 `carrier_type` | -| `sales_daily_facts` | `carrier_type` → `fulfillment_mode`（改名） | -| `manual_expense_records` / `manual_expense_events` | 整表删除（迁移 `108`）；成本快照主体改挂 `manual_expenses.id` | -| `work_product_rules` | 删 `legacy_cost_source` | -| `order_items` | **不动**（履约事实、收入固化、商品指向全部保留） | - -执行顺序： - -```bash -# 1. 备份（已完成） -# backups/postgres/order_site_pre_rewrite_20261023.dump -# 2. 删旧迁移记录 + 列级改造 -docker exec -i order_site-postgres-1 psql -U postgres -d order_site \ - -v ON_ERROR_STOP=1 < scripts/rewrite-local-db-2026-10-23.sql -# 3. 应用新迁移 103–109 -npm run db:migrate -# 4. 重跑履约回填（幂等） -npm run fulfillment:backfill -# 5. 分窗口重算销售事实 -npm run finance:sync -- --mode=facts --from=2026-07-10 --to=2026-08-08 -# ...按 30 天窗口依次执行 +```sql +DELETE FROM schema_migrations WHERE name ~ '^(10[3-9]|11[0-2])_'; ``` -改造后数据量核对（2026-10-23，迁移 `108` 执行后复验）：商品 745、映射 4,426、成本项 3、成本版本 702、快照 158,764、异常 248,878、销售事实 14,798、备用金支出 2、订单项 316,585 —— 与改造前一致。`manual_expense_records`（1 条测试数据）与 `manual_expense_events`（2 条）随迁移 `108` 一并删除。 +2026-10-25 实测：按第 2 条路径升级后的库，与全新构建的库 **schema 完全一致**（`pg_dump --schema-only` 仅随机 token 不同），种子数据（3 个系统成本项、2 个全局占位版本、4 个人工履约档案）也一致。 -`check-sql-guard.ts` 对 `103`–`114` 段迁移放开字节校验（这一组在分支内整体重写）；`001`–`102` 仍必须保持字节不变。 +旧的逐列改造脚本 `scripts/rewrite-local-db-2026-10-23.sql` 已随迁移合并作废，移入 [archive/2026-10-23/](archive/2026-10-23/)；只在追溯当时 `carrier_type → cost_model` / `fulfillment_mode` 的改造矩阵时查阅，**不要在新环境执行**。 + +`check-sql-guard.ts` 改为以 `main` 为基线校验迁移字节：**已发布的迁移不可修改**，未合并分支上的新迁移仍可重写；基线可用 `MIGRATION_BASELINE_REF` 覆盖，找不到基线时跳过该项检查。 --- diff --git a/docs/接单模板匹配引擎重构设计.md b/docs/接单模板匹配引擎重构设计.md index aa61c064..0d56cdf7 100644 --- a/docs/接单模板匹配引擎重构设计.md +++ b/docs/接单模板匹配引擎重构设计.md @@ -1,6 +1,6 @@ # 接单模板匹配引擎重构设计 -> 目标读者：后端 / 后台运营。状态：**P0 + P1 已实施；P2 / P3 待办**。最后校准：2026-10-23（代码基线 `dev @ 43f402cf + 迁移 103–109`；匹配业务逻辑未变）。 +> 目标读者：后端 / 后台运营。状态：**P0 + P1 已实施；P2 / P3 待办**。最后校准：2026-10-23（代码基线 `dev @ 43f402cf + 迁移 `103`–`107`；匹配业务逻辑未变）。 > > 一句话：把「订单信息 → 接单模板（价格/拼单/要求）」的匹配，从散落的多个消费点、平台判断和"店铺必填"的绑定表里，收敛为**一个平台无关的引擎**：匹配条件完全由**订单信息**表达，**店铺只是可选条件之一**，新增来源只加一个适配器 + 一组配置。 > diff --git a/docs/财务与履约口径总纲-2026-10-23.md b/docs/财务与履约口径总纲-2026-10-23.md index 58051045..d878f39d 100644 --- a/docs/财务与履约口径总纲-2026-10-23.md +++ b/docs/财务与履约口径总纲-2026-10-23.md @@ -3,7 +3,7 @@ > 状态：**现行唯一口径**。本文是财务、成本、履约分类的总入口；其他文档与本文件冲突时，以本文为准。 > 最后校准：2026-10-24 > 代码基线：`dev @ 790de676 + 本地未提交修复`（**未推送、未部署生产**） -> 数据基线：生产 dump `order_site-20261022-092601.dump`（2026-07-10 ~ 2026-10-22）；本地已升级到迁移 112，并完成履约方式、商品、成本快照与销售事实初始化 +> 数据基线：生产 dump `order_site-20261022-092601.dump`（2026-07-10 ~ 2026-10-22）；本地已升级到迁移 107，并完成履约方式、商品、成本快照与销售事实初始化 > 适用范围：订单接入、履约判定、商品归一、成本快照、销售事实、人工录单、备用金、后续总账与对账。 --- @@ -160,22 +160,22 @@ P0 的具体迁移、回填、代码清单与验收 SQL 见 [成本中心与履 | 订单页人工录单，按单实际金额 | **已实施** | `74b62f34` | | 人工支出从客服备用金扣款 | **已实施** | `2aeb789e` | | 客服只能使用本人备用金账户 | **已实施** | `a7f60414` | -| 备用金账户编号 `FA-<用户名>` | **已实施** | `fac34c84` + 迁移 `106_fund_account_no_readable` | +| 备用金账户编号 `FA-<用户名>` | **已实施** | `fac34c84` + 迁移 `107_manual_fulfillment` | | 订单页只展示平台判断 SKU | **已实施** | `c38cd8ca`、`cd9bb141` | -| `order_items.fulfillment_mode` 持久化 | **已实施** | 迁移 `107` + 统一决策服务 | +| `order_items.fulfillment_mode` 持久化 | **已实施** | 迁移 `105` + 统一决策服务 | | 订单页 / 成本快照 / 销售事实统一读字段 | **已实施** | `admin-order-read-helpers`、`sales-facts-service`、`cost-snapshot-sync-service` | | 本地 316,585 项回填 | **已实施** | `fulfillment:backfill`，四项计数与 §二 一致 | -| 成本模型与履约方式正交（去 `carrier_type`） | **已实施（本地库已改造）** | 迁移 `103–107` 重写；`cost_items.cost_model` | -| 12 个迁移合并为 5 个 | **已实施** | `103_product_catalog` ~ `107_order_item_fulfillment_mode` | -| 人工成本链路收敛为「人工录单 → 扣备用金 → 写快照」 | **已实施（本地库已改造）** | 迁移 `108_drop_manual_expense_records`；下线登记单与审批报销 | +| 成本模型与履约方式正交（去 `carrier_type`） | **已实施（本地库已改造）** | 迁移 `103`–`107` 重写；`cost_items.cost_model` | +| 10 个迁移收敛为 5 个 | **已实施** | `103_product_catalog` ~ `107_manual_fulfillment` | +| 人工成本链路收敛为「人工录单 → 扣备用金 → 写快照」 | **已实施（本地库已改造）** | 迁移 `104`；登记单与审批报销已下线，口径固化在成本中心迁移 | | 人工商品归一 `man:` | **已实施（本地库已归一）** | `manual-product-normalization-service` + `POST /cost-center/manual-products/normalize`；1,116 个 `man:` 商品、91,606 个人工订单项归一，人工未归一 = 0 | | 人工商品归一后的销售事实 | **已实施** | 94 天分 30 天窗口重算：26,507 行；人工 ¥1,219.20 万收入全部按 `man:` 商品归集 | -| 退款冲减、异常闭环 | **已实施（手动登记先行）** | 迁移 `112_order_refunds`；订单页「退款登记」（整单/指定商品、可撤销）；销售事实按有效退款冲减；全额退完后自动关闭该订单项成本异常并写 `resolution_note` | +| 退款冲减、异常闭环 | **已实施（手动登记先行）** | 迁移 `106_order_refunds`；订单页「退款登记」（整单/指定商品、可撤销）；销售事实按有效退款冲减；全额退完后自动关闭该订单项成本异常并写 `resolution_note` | | 平台退款 API 接入 | **未实施** | 预留 `order_refunds.source='api'/'platform'` 与 `external_ref` | | 影子总账、对账、关账 | **未实施** | §六 P3 | > 历史平台仍有 53,901 个订单项（¥389.12 万）未归一，不属于 P1 范围；人工历史成本按既定口径不补录，因此人工毛利当前是“收入已归商品、成本仅新单有”的状态。 -> 分支事实：以上实现已快进合并到 `dev`；迁移 `103–112` **未推送远端、未部署生产**。生产口径仍以 `main` 为准。 +> 分支事实：以上实现已快进合并到 `dev`；迁移 `103`–`107` **未推送远端、未部署生产**。生产口径仍以 `main` 为准。 --- diff --git a/docs/财务系统集成方案.md b/docs/财务系统集成方案.md index ed9864ad..9b33d44f 100644 --- a/docs/财务系统集成方案.md +++ b/docs/财务系统集成方案.md @@ -2,7 +2,7 @@ > 状态：**现行方案（总账层未实施）**。本文只描述 `finance_*` 总账层；当前总账表尚未建立，现有财务页仍是 `UNION ALL` 业务事件拼装。 > 最后校准：2026-10-23 -> 代码基线：`dev @ 43f402cf + 迁移 103–109`（已合并到 `dev`，**未推送、未部署生产**） +> 代码基线：`dev @ 43f402cf + 迁移 `103`–`107`（已合并到 `dev`，**未推送、未部署生产**） > **履约方式、成本模型、人工全覆盖口径以 [财务与履约口径总纲-2026-10-23.md](财务与履约口径总纲-2026-10-23.md) 为准**；本文不重复分类设计。 > 目标：在**不破坏现有抢单、押金、结算、寄卖、提现链路**的前提下，增加可对账、可关账、可追溯的复式记账底座。 > 结论先说：**不要直接在 `worker_wallets` / `worker_wallet_ledgers` 上继续加字段。** 现有表是业务钱包与流水，不是会计总账；正确做法是新增复式记账底座，让现有钱包成为它的“余额投影”。 @@ -18,8 +18,8 @@ | 客服备用金台账（`fund_*` / 备用金 `manual_expenses`） | **已实施 P0**；账户编号 `FA-<用户名>`；客服只能使用本人账户 | | 商品主数据 / 渠道 SKU 映射 / 成本中心 | **已实施 P0（`dev` 分支）**，迁移 `103/104`；标准商品 745 个，只覆盖自动发货 38 + 接单平台 707 | | `sales_daily_facts` / 订单级毛利 | **已实施 P0（`dev` 分支）**，迁移 `105`；94 天收入 ¥2,650.87 万、成本 ¥950.27 万 | -| 人工成本录入（确认履约 → 扣积分/备用金 → 写快照） | **已实施 P0（`dev` 分支）**，迁移 `106/108`；2026-10-24 人工履约页下线、入口收敛到订单页；**无登记单、无审批、无报销** | -| 履约方式统一 `fulfillment_mode` | **已实施 P0（`dev` 分支）**；迁移 `107`，316,585 项已回填；订单页、成本快照、销售事实统一读该字段 | +| 人工成本录入（确认履约 → 扣积分/备用金 → 写快照） | **已实施 P0（`dev` 分支）**，迁移 `104/107`；2026-10-24 人工履约页下线、入口收敛到订单页；**无登记单、无审批、无报销** | +| 履约方式统一 `fulfillment_mode` | **已实施 P0（`dev` 分支）**；迁移 `105`，316,585 项已回填；订单页、成本快照、销售事实统一读该字段 | | `finance_accounts` / `finance_business_events` / `finance_journal_*` | 未实施 | | `finance_settlements` / `finance_reconciliations` | 未实施 | | 现有 `admin-finance-service.ts` | 仍是业务事件 `UNION ALL`，不是总账 |