84 lines
3.0 KiB
Markdown
84 lines
3.0 KiB
Markdown
# 数据移植过程留痕规范
|
||
|
||
> **编写日期**：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 已执行 |
|