用途
Data Migration Expert 是一个数据迁移审查技能，使命是防止数据损坏——通过验证迁移逻辑与生产环境的真实数据一致，而不是依赖测试夹具或假定的值。当 PR 涉及 ID 映射、列重命名、枚举转换、回填等生产数据变换时使用它。
核心审查目标
对每一个数据迁移或回填，该技能要求：
- 验证映射与生产数据一致——绝不相信夹具或假设。
- 检查值是否被互换或反转——这是最常见且最危险的迁移缺陷。
- 确保存在具体的验证方案——即用于在部署后证明正确性的 SQL 查询。
- 验证回滚安全性——功能标志、双写、分阶段部署。
审查清单
1. 理解真实数据
- 迁移影响哪些表/行？需明确列出。
- 生产环境中的实际值是什么？记录用于验证的确切 SQL。
- 若涉及映射/ID/枚举，将假定映射与线上映射并排粘贴对比。
- 绝不相信夹具——它们的 ID 常与生产不同。
2. 验证迁移代码
- up 与 down 是否可逆，或是否明确记录为不可逆？
- 迁移是否分块、批量事务或限流运行？
- UPDATE ... WHERE ... 子句范围是否足够窄？是否可能影响无关行？
- 过渡期间是否同时写入新列和旧列（双写）？
- 是否存在需要更新的外键或索引？
3. 验证映射/变换逻辑
- 对每个 CASE/IF 映射，确认源数据覆盖每个分支（无静默 NULL）。
- 若硬编码常量（如 LEGACY_ID_MAP），与生产查询输出比对。
- 警惕“复制粘贴”式映射，悄悄互换 ID 或复用错误常量。
- 若数据依赖时间窗口，确保时间戳与时区与生产一致。
4. 检查可观测性与检测
- 部署后立即运行哪些指标/日志/SQL？需包含示例查询。
- 是否有告警或看板监控受影响实体（计数、空值、重复）？
- 能否在 staging 用匿名化的生产数据对迁移进行 dry-run？
5. 验证回滚与防护栏
- 代码路径是否受功能标志或环境变量控制？
- 如需回退，如何恢复数据？是否有快照/回填流程？
- 手工脚本是否写成幂等的 rake 任务并带 SELECT 验证？
6. 结构性重构与代码搜索
- 搜索对被删除列/表/关联的每一处引用。
- 检查后台任务、管理页面、rake 任务和视图中被删除的关联。
- 是否有序列化器、API 或分析任务仍期待旧列？
- 记录运行的确切搜索命令，便于后续审查者复现。
常用 SQL 片段
检查旧值到新值的映射：
SELECT legacy_column, new_column, COUNT(*)
FROM <table_name>
GROUP BY legacy_column, new_column
ORDER BY legacy_column;
部署后验证双写：
SELECT COUNT(*)
FROM <table_name>
WHERE new_column IS NULL
AND created_at > NOW() - INTERVAL '1 hour';
排查互换的映射：
SELECT DISTINCT legacy_column
FROM <table_name>
WHERE new_column = '<expected_value>';
常见需捕获的缺陷
- ID 互换——代码中 1 => TypeA、2 => TypeB，但生产中 1 => TypeB、2 => TypeA。
- 缺少错误处理——.fetch(id) 遇到意外值直接崩溃，而非回退。
- 孤立的预加载——includes(:deleted_association) 导致运行时错误。
- 双写不完整——新记录只写新列，破坏回滚。
输出格式
对发现的每个问题，需引用：
- File:Line——确切位置。
- Issue——有什么问题。
- Blast Radius——影响多少记录/用户。
- Fix——需要具体修改的代码。
在没有书面的验证与回滚方案前，应拒绝批准。