shanxia2.0/docs/superpowers/plans/2026-07-12-crm-product-category-data-migration.md

CRM 产品分类数据移植 Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development or superpowers:executing-plans. Steps use checkbox (- [ ]) syntax.

Goal: 将 sx 库 crm_product_category 迁入 shanxia2.0，产出 ID 映射表，并完整留痕供二次移植。

Architecture: 独立 Python 脚本；主键原样保留（bigint→同值字符串）；拓扑序保证 parent_id 有效。

Tech Stack: Python 3.9 · SQLAlchemy raw SQL · legacy_id_to_str · CSV mapping

全局 ID 策略：05-id-preservation-policy.md
设计文档: docs/superpowers/specs/2026-07-12-crm-product-category-data-migration-design.md
操作手册: docs/data-migration/phase-1-crm/step-01-product-category.md

---

File Map

文件	职责
backend/scripts/migrate_crm_product_category.py	迁移主脚本
docs/data-migration/mappings/crm_product_category_id_mapping.csv	恒等映射 source_id=new_id
docs/data-migration/mappings/crm_id_mapping.csv	汇总映射（本步追加 category 段）
docs/data-migration/phase-1-crm/logs/*.md	执行批次日志

---

Task 1: 脚本骨架与 dry-run

Files:

• Create: backend/scripts/migrate_crm_product_category.py

• 1.1 解析 CLI：--dry-run、--source-url、--user-mapping、--mapping-out、--update

• 1.2 连接源/目标库；统计源 del_flag=0 行数

• 1.3 加载 user_mapping_result.csv：crm_user_id → new_user_id；1 → admin

• 1.4 dry-run 打印 5 条字段映射预览，不写库

验证：

cd backend && source venv/bin/activate
ENV_FILE=.env.production python scripts/migrate_crm_product_category.py --dry-run

---

Task 2: 拓扑插入与 mapping 写出

Files:

• Modify: backend/scripts/migrate_crm_product_category.py

• 2.1 实现 topo_sort_categories(rows)：父 id 先于子 id

• 2.2 逐行转换字段；id/parent_id 用 str(bigint) 原样保留

• 2.3 INSERT 目标表；事务提交

• 2.4 写出 crm_product_category_id_mapping.csv

验证：

SELECT category_name, parent_id, status, order_num, level
FROM crm_product_category WHERE tenant_no='shanxia2.0' AND del_flag=0
ORDER BY order_num;
-- 预期 5 行，名称与 sx 一致

---

Task 3: 幂等与二次移植

• 3.1 若 mapping 已有 source_id 且目标行存在 → skip（默认）
• 3.2 --update：更新 category_name、order_num、status、parent_id、level
• 3.3 日志输出 inserted / skipped / warnings 统计

---

Task 4: 留痕与文档回写

Files:

• Create: docs/data-migration/phase-1-crm/logs/YYYY-MM-DD-HHMM-product-category.md

• Modify: docs/data-migration/README.md 状态表

• 4.1 按 03-process-logging.md 模板追加日志

• 4.2 更新 README「P1-1 产品分类」为「已执行 / 待执行」

• 4.3 将 category mapping 合并进 crm_id_mapping.csv（列：entity,source_id,new_id,remark）

---

Task 5: 界面验收

• 5.1 登录门户，打开产品分类树形页
• 5.2 确认 5 个节点、排序、状态 Tag
• 5.3 在 step-01 日志中记录截图路径或文字结论

---

后续步骤（本计划不包含）

• P1-1b crm_product + category_id 外键（依赖本步 mapping）
• 参考：docs/superpowers/plans/2026-05-30-crm-iteration1-product.md（代码移植；数据同步另写 step-02）

---

执行顺序提醒

P0 用户 ✅ → P1-1 产品分类（本计划）→ P1-1b 产品 → P1-2 客户 → …

字典 P0-1：无需导入（见 phase-0-foundation/step-01-dict.md）。