# 数据移植过程留痕规范

> **编写日期**：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 已执行 |