This commit is contained in:
zlwu committed 2026-07-13 20:26:43 +08:00
1 parent 3520f9ce90
commit 0e60b88cba
104 files changed
+344311 -250708

No files matched your search

+83
View File
@@ -0,0 +1,83 @@
# 数据移植过程留痕规范
> **编写日期**:2026-07-12
> **目的**:后续会再次全量/增量移植,所有步骤必须可追溯、可复现、可对比。
---
## 1. 三层文档结构
| 层级 | 路径 | 用途 |
|------|------|------|
| 总体规划 | `00-master-plan.md`、`04-execution-order.md` | 阶段划分、依赖、全局原则 |
| 步骤操作手册 | `phase-*/step-*.md` | 单步前置条件、命令、验收、日志模板 |
| 执行批次日志 | `phase-*/logs/YYYY-MM-DD-HHMM-*.md` | **每次真实执行**的留痕(只追加,禁止覆盖) |
Superpowers 设计与实施计划(字段映射、脚本结构、风险)放在:
- `docs/superpowers/specs/*-data-migration-design.md`
- `docs/superpowers/plans/*-data-migration.md`
---
## 2. 每步必须产出的映射与脚本
| 产物 | 说明 |
|------|------|
| `mappings/*_id_mapping.csv` | 源 ID → 目标 ID;业务表多为 **恒等映射**(`str(源id)`);用户表见 `user_mapping` |
| `backend/scripts/migrate_*.py` | 支持 `--dry-run`、`--mapping-out` |
| `phase-*/logs/*.md` | 执行前后行数、抽样 SQL、问题处理 |
---
## 3. 执行批次日志模板(强制字段)
```markdown
## 批次:YYYY-MM-DD HH:MM
### 环境
- 目标库:(host/db,脱敏)
- 源库:
- 操作人:
- Git 分支 / 提交:
### 执行前备份
- mysqldump 路径或快照名:
### 执行命令
(完整命令,密码脱敏)
### 行数对比
| 表 | 源库 del_flag=0 | 执行前目标库 | 执行后目标库 | 预期 |
### 映射产物
- 文件路径、行数、未映射条数
### 抽样校验 SQL
(粘贴 2~3 条 SELECT 及结果摘要)
### 界面验收
- 页面路径、账号、结果
### 问题与处理
```
---
## 4. 幂等与二次移植
1. **首次移植**:生成 mapping CSV。业务主键 **原样保留**(见 [05-id-preservation-policy.md](./05-id-preservation-policy.md));`sys_user` 例外。
2. **二次移植**(同环境重跑):
- 脚本按 `source_id` 查 mapping,已存在则 **UPDATE 或 SKIP**(步骤文档中写明策略)。
- 日志新批次追加,注明 `re-run` / `incremental`。
3. **清空重灌**(仅测试库):步骤文档单独写 `TRUNCATE` 范围与顺序,生产禁止随意清空。
---
## 5. 当前进度索引
| 阶段 | 步骤文档 | 设计/计划 | 脚本 | 状态 |
|------|----------|-----------|------|------|
| P0-1 字典 | [step-01-dict.md](./phase-0-foundation/step-01-dict.md) | — | `compare_dict_snapshots.py` | 已分析,无需批量导入 |
| P0-4 用户 | [step-04-users.md](./phase-0-foundation/step-04-users.md) | — | `migrate_users.py` | 已执行,见 mappings |
| P1-1 产品分类 | [step-01-product-category.md](./phase-1-crm/step-01-product-category.md) | [design](../superpowers/specs/2026-07-12-crm-product-category-data-migration-design.md) / [plan](../superpowers/plans/2026-07-12-crm-product-category-data-migration.md) | `migrate_crm_product_category.py` | ✅ 2026-07-12 已执行 |