shanxia2.0/docs/data-migration/05-id-preservation-policy.md

主键 ID 保留策略（全局）

决策日期：2026-07-12
适用范围：docs/data-migration/ 下全部生产数据同步（CRM、报销、地磅）
原则：原系统业务主键 原样迁入 门户库，仅做类型适配（bigint/int → 同值 VARCHAR），不重新生成 UUID。

---

1. 核心规则

项	规则
业务表主键 id	target.id = str(source.id)（十进制字符串，与源数值一致）
业务外键 *_id	指向业务实体时：str(source_*_id)；指向用户时：见 §3
parent_id 等树字段	0 → '0'；非 0 → str(source_parent_id)
映射文件	仍生成 *_id_mapping.csv，多为 恒等映射（source_id = new_id），用于审计与二次移植对账
脚本实现	统一使用 legacy_id_to_str()（参考 migrate_dibang_data.py、migrate_crm_product_category.py）

示例

源 crm_product.id           = 42        → 目标 "42"
源 crm_product.category_id  = 1975766458781167617 → 目标 "1975766458781167617"
源地磅 plan.id              = 12        → 目标 "12"

---

2. 好处

1. 下游表免查 mapping：产品、客户、报价、合同等子表外键可直接 str(源值) 写入。
2. 二次移植简单：按 id 幂等 SKIP/UPDATE，mapping 即对账表。
3. 与地磅策略一致：三系统同一套心智模型。
4. 问题排查：门户与旧库对照时 ID 一一对应。

---

3. 例外（不保留源 id 或需额外映射）

场景	处理方式	说明
sys_user（P0 已执行）	已生成门户 UUID	以 mappings/user_mapping_result.csv 为准；create_by / owner_user_id / approver_id 等 必须经用户映射转换
字典 sys_dict_data.id	按门户既有主键	字典项以 dict_type + dict_value 对齐，不按 sx 的 dict_code 保留 id（见 step-01-dict）
门户已手工录入且 id 冲突	步骤文档写明	测试库可用 --truncate；生产需人工合并，禁止静默覆盖
源 id 非纯数字	原样字符串写入	若超长则按目标列宽截断并记 WARNING

---

4. 各阶段适用表（摘要）

阶段	表 / 实体	主键策略
P0	sys_user	❌ 例外：门户 UUID + user_mapping
P0	sys_dept、sys_role	✅ 若从 sx 导入，优先保留源 id 字符串
P1 CRM	crm_product_category	✅ 已按本策略实现脚本
P1 CRM	crm_product、crm_customer、crm_clue、商机/报价/合同等	✅ 全部 str(source.id)
P1 CRM	sys_oss（附件）	✅ str(oss_id)
P2 报销	bx_* 业务表	✅ str(source.id)
P3 地磅	db_*	✅ 已有脚本，int → 同值字符串

---

5. 脚本约定

每个 migrate_*.py 应：

1. 支持 --dry-run
2. 默认：目标已存在同 id → SKIP；--update 可覆盖非主键字段
3. --mapping-out 写出恒等或例外映射 CSV
4. 日志与 phase-*/logs/ 记录「ID 策略：原样保留」

共享工具函数（可复制到各脚本或后续抽到 scripts/migration_utils.py）：

def legacy_id_to_str(legacy_id) -> str:
    if legacy_id is None:
        return "0"
    return str(int(legacy_id))

---

6. 与旧文档的关系

• 代码移植 spec docs/superpowers/specs/2026-05-30-crm-migration-design.md §7.1 曾写「bigint → UUID」；生产数据同步以本文档为准。
• OpenSpec / 公共字段 仍要求目标列类型为 VARCHAR(64)；保留源 id 字符串满足类型要求，不要求必须是 UUID 格式。

---

7. 相关文档

• 00-master-plan.md §2 已确认决策
• 03-process-logging.md 映射产物说明
• phase-1-crm/step-01-product-category.md 首版落地示例