dachui/order_site
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(db): 将 108–115 补丁迁移收敛为 108–111

Browse Source 
- 原 108/111/112/113/114 合并为 108_finance_cost_integrity：
  成本异常归档、人工成本完整性、影子总账、商品页/模板查询索引
- 原 115 注释迁移改为 111_work_order_share_cancel_reason_comment
- 新增 reconcile-migration-history.sql，用于已跑旧 112–115 的库
  重建 schema_migrations 顺序，不重复执行 DDL
- 已验证：001→111、101→111 两条升级路径；
  旧 115 与新 111 的 pg_dump schema 完全一致
- 测试/文档迁移编号同步到 103–111

验证：backend check 853（849 pass / 4 skip）；frontend check 172 + build。
This commit is contained in:
yml2213
2026-10-27 12:37:21 +08:00
parent e686a77a9e
commit 0de0fd7b58
19 changed files with 394 additions and 360 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/README.md
+5 -5
View File
@@ -1,7 +1,7 @@
# order_site 文档索引
> 最后校准：2026-10-26，代码基线 `dev`（合并 `dev1023` + 人工成本完整性修复，迁移到 `112`；**未推送、未部署生产**）。
> 数据基线：生产 dump `backups/postgres/order_site-20261022-092601.dump`（数据 2026-07-10 ~ 2026-10-22）；本地生产副本已升级到 112，只跑了近 30 天增量。历史全量数字仅作基线，**上线验收以 [财务上线初始化与验收-2026-10-26.md](财务上线初始化与验收-2026-10-26.md) 为准**。
> 最后校准：2026-10-26，代码基线 `dev`（合并 `dev1023` + 人工成本完整性修复，迁移基线收敛为 `103`–`111`；**未部署生产**）。
> 数据基线：生产 dump `backups/postgres/order_site-20261022-092601.dump`（数据 2026-07-10 ~ 2026-10-22）；测试/本地旧编号已到 115，生产按收敛后的 101 → 111 路径执行。历史全量数字仅作基线，**上线验收以 [财务上线初始化与验收-2026-10-26.md](财务上线初始化与验收-2026-10-26.md) 为准**。
> 本文是 `docs/` 的唯一入口。**财务与履约口径以 [财务与履约口径总纲-2026-10-23.md](财务与履约口径总纲-2026-10-23.md) 为准**；数据模型看 [成本中心与履约模型.md](成本中心与履约模型.md)，接口看 [成本中心API契约.md](成本中心API契约.md)。
> 新增文档必须在下表登记状态；过期文档不再直接改写结论，统一移入 `docs/archive/`。
@@ -91,7 +91,7 @@
| 平台对账 / 期间关账 | **已实施 P0** | 平台账单 JSON 导入匹配、差异明细、标记解决；关账/反关账；见 `/admin/finance/ledger` |
| 平台退款 API | **部分实施** | 快手行业（91）同意退款已接入；抖音/拼多多暂未接 API，仍手工登记 |
> 分支状态（2026-10-26）：`dev` 已合并 `dev1023` 与人工成本完整性修复，迁移到 `112`；本地生产副本已验证 101 → 112（109/110 索引在生产规模数据上实测 < 0.3s），临时库全量执行与重跑幂等通过。**未推送、未部署生产**；生产口径仍以 `main` 为准。上线前按 [财务上线初始化与验收-2026-10-26.md](财务上线初始化与验收-2026-10-26.md) 初始化资金与人工 SKU。
> 分支状态（2026-10-26）：`dev` 已合并 `dev1023` 与人工成本完整性修复，迁移基线收敛为 `103`–`111`（原 108–115 的财务/性能补丁合并进 108）；临时库从 001 全量执行与从 101 升级均待验收。**未推送、未部署生产**；生产口径仍以 `main` 为准。上线前按 [财务上线初始化与验收-2026-10-26.md](财务上线初始化与验收-2026-10-26.md) 初始化资金与人工 SKU。
> 财务与履约口径以 [财务与履约口径总纲-2026-10-23.md](财务与履约口径总纲-2026-10-23.md) 为准。
## 三、统一实施顺序
@@ -103,7 +103,7 @@
2.5 人工成本链路收敛（确认履约 → 扣积分/备用金 → 写快照） 已完成 P0（迁移 104/107/111）
3. 人工商品归一与上线后人工成本全覆盖 已完成代码；生产数据需上线后配置 SKU（历史不补录）
4. 退款冲减与异常队列 已完成手工退款 + 快手平台退款；人工缺成本已入队
5. 影子总账（销售事实 + 手工凭证） 已完成 P0（迁移 112）
5. 影子总账（销售事实 + 手工凭证） 已完成 P0（迁移 108）
6. 平台对账、期间关账 已完成 P0（手工账单导入）；平台自动拉单未实施
```
@@ -129,7 +129,7 @@
| 文档 | 状态 | 用途 |
| --- | --- | --- |
| [财务与履约口径总纲-2026-10-23.md](财务与履约口径总纲-2026-10-23.md) | **现行唯一口径** | 履约方式、成本模型、人工全覆盖、历史策略、实施顺序、运营日检与验收 SQL |
| [成本中心与履约模型.md](成本中心与履约模型.md) | 现行 | 商品、成本版本、快照、异常、销售事实的数据模型；迁移 `103`–`112`；履约回填；迁移基线与本地库同步；索引与性能 |
| [成本中心与履约模型.md](成本中心与履约模型.md) | 现行 | 商品、成本版本、快照、异常、销售事实的数据模型；迁移 `103`–`111`；履约回填；迁移基线与本地库同步；索引与性能 |
| [成本中心API契约.md](成本中心API契约.md) | 现行 | 成本中心接口字段替换总表、枚举、模块边界（后端 5 模块 + 前端 4 个固定 Tab） |
| [人工支出与备用金.md](人工支出与备用金.md) | 现行（P0 已实施） | 确认履约流程/权限、客服备用金台账、本人账户与编号规则 |
| [财务上线初始化与验收-2026-10-26.md](财务上线初始化与验收-2026-10-26.md) | **现行上线手册** | 迁移后资金/人工 SKU 初始化、验收 SQL、日常监控 |
docs/履约配置/多发货平台与电子凭证整体链路.md
+1 -1
View File
@@ -1,6 +1,6 @@
# 多发货平台与电子凭证整体链路
> 状态：现行。最后校准：2026-10-23（代码基线 `dev`（合并 dev1023 后）+ 迁移 `103`–`112`；履约方式已统一落库）。
> 状态：现行。最后校准：2026-10-23（代码基线 `dev`（合并 dev1023 后）+ 迁移 `103`–`111`；履约方式已统一落库）。
> 财务与履约总口径见 [财务与履约口径总纲-2026-10-23.md](../财务与履约口径总纲-2026-10-23.md)。
> 来源口径：本系统只有三个订单来源——`kuaishou-91`、`pdd`、`douyin-mashida`。**91 回调与快手 send-code 是同一个 `kuaishou-91` 来源的两条数据通道**（91=骨架权威源，快手 send-code=补全/兜底源），不是一个来源加另一个来源。
docs/影子总账说明.md
+1 -1
View File
@@ -2,7 +2,7 @@
> 状态：**现行说明（P0 已实施，2026-10-26）**
> 最后校准：2026-10-26
> 代码基线：`dev`（合并 dev1023 后）+ 迁移 `103`–`112`（已合并到 `dev`，**未推送、未部署生产**）
> 代码基线：`dev`（合并 dev1023 后）+ 迁移 `103`–`111`（已合并到 `dev`，**未推送、未部署生产**）
> 配套方案：[财务系统集成方案.md](财务系统集成方案.md)
> **总口径以 [财务与履约口径总纲-2026-10-23.md](财务与履约口径总纲-2026-10-23.md) 为准。**
> 前置：统一履约事实、商品主数据、渠道映射、成本中心与销售事实；实施顺序以总纲第六节为准。
docs/成本中心API契约.md
+1 -1
View File
@@ -2,7 +2,7 @@
> 状态：**现行**。后端服务与前端页面都必须严格按此实现，不得各自发挥。
> 最后校准：2026-10-25
> 代码基线：`dev`（合并 dev1023 后）+ 迁移 `103`–`112`（已合并到 `dev`，**未推送、未部署生产**）
> 代码基线：`dev`（合并 dev1023 后）+ 迁移 `103`–`111`（已合并到 `dev`，**未推送、未部署生产**）
> 详细业务口径见 [财务与履约口径总纲-2026-10-23.md](财务与履约口径总纲-2026-10-23.md)；数据模型见 [成本中心与履约模型.md](成本中心与履约模型.md)。
## 一、字段替换总表
docs/成本中心与履约模型.md
+15 -11
View File
@@ -2,7 +2,7 @@
> 状态：**现行**。商品主数据、成本中心、成本快照、销售事实、履约事实均已落地。
> 最后校准：2026-10-26
> 代码基线：`dev`（合并 dev1023 + 人工成本完整性修复，迁移到 `112`）
> 代码基线：`dev`（合并 dev1023 + 人工成本完整性修复，迁移基线收敛为 `103`–`111`）
> 数据基线：生产 dump `order_site-20261022-092601.dump`（2026-07-10 ~ 2026-10-22）；本地只跑了近 30 天增量，历史数字仅作基线。
> 上线初始化/验收见 [财务上线初始化与验收-2026-10-26.md](财务上线初始化与验收-2026-10-26.md)。
> **业务口径以 [财务与履约口径总纲-2026-10-23.md](财务与履约口径总纲-2026-10-23.md) 为准**；本文只负责数据模型、迁移与运维。
@@ -35,7 +35,7 @@ orders ──┬── order_items ──── fulfillment_mode (唯一履约
## 一、迁移基线：10 个收敛为 5 个
原 `dev` 分支上，商品、成本中心、人工履约用 10 个**历史编号**迁移（`103`–`112`，1,275 行）分批落地，字段反复摇摆。其中：
原 `dev` 分支上，商品、成本中心、人工履约用 10 个**历史编号**迁移（`103`–`111`，1,275 行）分批落地，字段反复摇摆。其中：
- 原 `108`（下线人工支出登记）与原 `109`（隔离历史快照主体）在「生产 102 → 当前」的唯一升级路径上是**空操作**；
- 原 `111` 是给 `104` 自身种子打的补丁（draft 占位改 active 占位）；
@@ -58,8 +58,8 @@ orders ──┬── order_items ──── fulfillment_mode (唯一履约
| `108_cost_exception_archive.sql` | 成本异常 60 天归档 |
| `109_work_order_share_participation.sql` | 拼单多次参与份额模型（与本模块无关，同批上线） |
| `110_work_order_hall_and_shop_indexes.sql` | 大厅置顶/店铺筛选索引（与本模块无关） |
| `111_manual_cost_integrity.sql` | 人工成本单事务兜底：订单项级唯一、`subject_id=order_item_id`、人工 SKU 匹配索引、`manual_cost_missing` 监控所需索引 |
| `112_finance_ledger.sql` | 财务总账（科目/凭证/期间/对账），与本模块无直接依赖，同批上线 |
| `111_work_order_share_cancel_reason_comment.sql` | 拼单取消原因注释（与本模块无关） |
| `108_finance_cost_integrity.sql` | 成本异常归档 + 人工成本单事务兜底（订单项级唯一、`subject_id=order_item_id`、SKU 索引）+ 财务总账/期间/对账 + 商品页/模板查询索引（合并原 108/111/112/113/114） |
**合并原则**：同一批上线的结构性 DDL 才合并；数据回填与业务口径注释跟着所属表走。`103` 保持独立（商品主数据是成本与销售事实的共同上游），`106` 保持独立（退款是独立业务线）。
@@ -428,18 +428,22 @@ WHERE oi.id = d.id
---
## 八、迁移基线与本地库同步（2026-10-25 更新）
## 八、迁移基线与本地库同步（2026-10-27 收敛）
生产尚未执行过 `103` 及之后的迁移。本地库与代码对齐有两条路径：
生产尚未执行过 `103` 及之后的迁移。2026-10-27 已把原来的 `108/111/112/113/114` 合并为 `108_finance_cost_integrity`，原 `115` 注释迁移改为 `111`；生产升级统一走 **101 → 111**，不再出现 108–115 的补丁链。
1. **全新升级**：从生产 dump 恢复到 `101` / `102`，直接 `npm run db:migrate` 升到 `111`；
2. **已有本地库**：清掉 `schema_migrations` 里 `103`–`112` 的记录后重跑。所有迁移都是 `IF NOT EXISTS`，数据步骤幂等：
1. **全新升级**：从生产 dump 恢复到 `101`，直接 `npm run db:migrate` 升到 `111`；
2. **已跑过旧 112–115 的本地/测试库**：schema 已等价，不要删 103–111 重跑；执行一次迁移历史校准：
```sql
DELETE FROM schema_migrations WHERE name ~ '^(10[3-9]|11[0-1])_';
```bash
docker exec -i order_site-postgres-1 psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" \
-v ON_ERROR_STOP=1 < apps/backend/scripts/reconcile-migration-history.sql
npm run db:migrate
```
2026-10-25 实测：按第 2 条路径升级后的库，与全新构建的库 **schema 完全一致**（`pg_dump --schema-only` 仅随机 token 不同），种子数据（3 个系统成本项、2 个全局占位版本、4 个人工履约档案）也一致。
脚本只把 `schema_migrations` 的旧 `108–115` 行重建为新的 `108–111`，不重复执行 DDL；若库仍停留在旧 103–107，直接正常迁移即可。
2026-10-27 实测：旧 115 库与新 111 库 `pg_dump --schema-only` **完全一致**（仅 pg_dump 随机 token/版本注释不同）；新库 001→111 与 101→111 两条路径均通过。
旧的逐列改造脚本 `scripts/rewrite-local-db-2026-10-23.sql` 已随迁移合并作废，移入 [archive/2026-10-23/](archive/2026-10-23/)；只在追溯当时 `carrier_type → cost_model` / `fulfillment_mode` 的改造矩阵时查阅，**不要在新环境执行**。
docs/接单模板匹配引擎重构设计.md
+1 -1
View File
@@ -1,6 +1,6 @@
# 接单模板匹配引擎重构设计
> 目标读者：后端 / 后台运营。状态：**P0 + P1 已实施；P2 / P3 待办**。最后校准：2026-10-23（代码基线 `dev`（合并 dev1023 后）+ 迁移 `103`–`112`；匹配业务逻辑未变）。
> 目标读者：后端 / 后台运营。状态：**P0 + P1 已实施；P2 / P3 待办**。最后校准：2026-10-23（代码基线 `dev`（合并 dev1023 后）+ 迁移 `103`–`111`；匹配业务逻辑未变）。
>
> 一句话：把「订单信息 → 接单模板（价格/拼单/要求）」的匹配，从散落的多个消费点、平台判断和"店铺必填"的绑定表里，收敛为**一个平台无关的引擎**：匹配条件完全由**订单信息**表达，**店铺只是可选条件之一**，新增来源只加一个适配器 + 一组配置。
>
docs/财务上线初始化与验收-2026-10-26.md
+3 -3
View File
@@ -1,7 +1,7 @@
# 财务/成本上线初始化与验收（2026-10-26）
> 状态：现行操作手册。适用于 `dev` 合并后的财务/成本模块上线；**历史人工成本不补录**。
> 代码基线：迁移 `103`–`112`（本手册写于人工成本完整性与配置自动匹配修复之后）。
> 代码基线：迁移 `103`–`111`（本手册写于人工成本完整性与配置自动匹配修复之后）。
> 数据基线：生产 dump `2026-10-22`（迁移 `101`）。历史人工支出找不回来，只保证**首次配置人工履约之后**的新单可记录、可监控。
---
@@ -42,7 +42,7 @@ bash deploy/ubuntu-deploy.sh --backup # 迁移前 pg_dump + OSS，
```sql
SELECT name FROM schema_migrations ORDER BY id DESC LIMIT 5;
-- 期望包含：111_manual_cost_integrity / 110_work_order_hall_and_shop_indexes / 109_work_order_share_participation
-- 期望包含：111_work_order_share_cancel_reason_comment / 110_work_order_hall_and_shop_indexes / 109_work_order_share_participation / 108_finance_cost_integrity
```
> 迁移 `109`/`110`/`111` 都是增量、幂等；`111` 会给 `orders(375k)` 建表达式索引，实测写阻塞约 200–300ms。
@@ -266,7 +266,7 @@ GROUP BY 1;
---
## 四、总账、期间关账与平台对账（迁移 112）
## 四、总账、期间关账与平台对账（迁移 108）
入口：后台「财务 → 总账与对账」（`/admin/finance/ledger`）。
docs/财务与履约口径总纲-2026-10-23.md
+2 -2
View File
@@ -2,7 +2,7 @@
> 状态：**现行唯一口径**。本文是财务、成本、履约分类的总入口；其他文档与本文件冲突时，以本文为准。
> 最后校准：2026-10-26
> 代码基线：`dev`（合并 dev1023 + 人工成本完整性修复，迁移到 `112`）
> 代码基线：`dev`（合并 dev1023 + 人工成本完整性修复，迁移到 `111`）
> 数据基线：§二/§七 的数字来自 2026-10-22 生产 dump 的**历史快照**，只用于理解历史缺口，**不再作为上线验收依据**；
> 上线初始化与验收以 [财务上线初始化与验收-2026-10-26.md](财务上线初始化与验收-2026-10-26.md) 为准。
> 适用范围：订单接入、履约判定、商品归一、成本快照、销售事实、人工录单、备用金、后续总账与对账。
@@ -181,7 +181,7 @@ P0 的具体迁移、回填、代码清单与验收 SQL 见 [成本中心与履
| 影子总账、对账、关账 | **已实施 P0** | 迁移 `112`；销售事实按日凭证 + 手工凭证 + 试算平衡 + 账单导入对账 + 关账/反关账 |
> 历史平台仍有 53,901 个订单项（¥389.12 万）未归一，不属于 P1 范围；人工历史成本按既定口径不补录，因此人工毛利当前是“收入已归商品、成本仅新单有”的状态。
> 分支事实：以上实现已合并到 `dev`；迁移 `103`–`112` **未推送远端、未部署生产**。生产口径仍以 `main` 为准；上线前按 [财务上线初始化与验收-2026-10-26.md](财务上线初始化与验收-2026-10-26.md) 初始化资金与人工 SKU。
> 分支事实：以上实现已合并到 `dev`；迁移 `103`–`111` **未推送远端、未部署生产**。生产口径仍以 `main` 为准；上线前按 [财务上线初始化与验收-2026-10-26.md](财务上线初始化与验收-2026-10-26.md) 初始化资金与人工 SKU。
---
docs/财务系统集成方案.md
+3 -3
View File
@@ -2,7 +2,7 @@
> 状态：**现行方案（影子总账 P0 已实施，2026-10-26）**。`finance_accounts / journal_entries / journal_lines / periods / reconciliations` 已建；总账不接管钱包余额；对账当前为手工账单导入，平台自动拉单待接。
> 最后校准：2026-10-26
> 代码基线：`dev`（迁移到 `112`，**未推送、未部署生产**）
> 代码基线：`dev`（迁移到 `111`，**未推送、未部署生产**）
> 说明：本文是总账/对账/关账的目标架构与分期；当前已实施 P0（销售事实凭证、手工凭证、试算平衡、期间关账、手工账单对账）与快手平台退款。初始化步骤见 [财务上线初始化与验收-2026-10-26.md](财务上线初始化与验收-2026-10-26.md)。
> **履约方式、成本模型、人工全覆盖口径以 [财务与履约口径总纲-2026-10-23.md](财务与履约口径总纲-2026-10-23.md) 为准**；本文不重复分类设计。
> 目标：在**不破坏现有抢单、押金、结算、寄卖、提现链路**的前提下，增加可对账、可关账、可追溯的复式记账底座。
@@ -21,8 +21,8 @@
| `sales_daily_facts` / 订单级毛利 | **已实施 P0（`dev` 分支）**，迁移 `105`；94 天收入 ¥2,650.87 万、成本 ¥950.27 万 |
| 人工成本录入（确认履约 → 扣积分/备用金 → 写快照） | **已实施 P0（`dev` 分支）**，迁移 `104/107`；2026-10-24 人工履约页下线、入口收敛到订单页；**无登记单、无审批、无报销** |
| 履约方式统一 `fulfillment_mode` | **已实施 P0（`dev` 分支）**；迁移 `105`，316,585 项已回填；订单页、成本快照、销售事实统一读该字段 |
| `finance_accounts` / `finance_journal_entries` / `finance_journal_lines` | **已实施 P0（迁移 112）** |
| `finance_periods` / `finance_reconciliations` / `finance_reconciliation_items` | **已实施 P0（迁移 112）** |
| `finance_accounts` / `finance_journal_entries` / `finance_journal_lines` | **已实施 P0（迁移 108）** |
| `finance_periods` / `finance_reconciliations` / `finance_reconciliation_items` | **已实施 P0（迁移 108）** |
| `finance_business_events` / `finance_settlements` | 未实施（当前用条目唯一键幂等） |
| 现有 `admin-finance-service.ts` | 仍是业务事件 `UNION ALL`，不是总账 |
docs/部署启动与数据库重建.md
+1 -1
View File
@@ -219,7 +219,7 @@ docker compose ps
docker compose logs -f backend
```
## 财务/成本上线后的初始化（迁移 102–112）
## 财务/成本上线后的初始化（迁移 102–111）
代码与迁移只负责建表；**备用金账户、积分余额、人工 SKU 配置不会自动创建**。
首次上线后按 [财务上线初始化与验收-2026-10-26.md](财务上线初始化与验收-2026-10-26.md) 执行：