shanxia2.0/docs/data-migration/03-process-logging.md

数据移植过程留痕规范

编写日期：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. 执行批次日志模板（强制字段）

## 批次：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）；sys_user 例外。
2. 二次移植（同环境重跑）：
   • 脚本按 source_id 查 mapping，已存在则 UPDATE 或 SKIP（步骤文档中写明策略）。
   • 日志新批次追加，注明 re-run / incremental。
3. 清空重灌（仅测试库）：步骤文档单独写 TRUNCATE 范围与顺序，生产禁止随意清空。

---

5. 当前进度索引

阶段	步骤文档	设计/计划	脚本	状态
P0-1 字典	step-01-dict.md	—	compare_dict_snapshots.py	已分析，无需批量导入
P0-4 用户	step-04-users.md	—	migrate_users.py	已执行，见 mappings
P1-1 产品分类	step-01-product-category.md	design / plan	migrate_crm_product_category.py	✅ 2026-07-12 已执行