shanxia2.0/docs/crm-migration/plans/clue/06-steps.md

线索管理模块迁移方案 — 06 分步实施计划（28 步）

For agentic workers: 按序执行，每步完成后勾选。必须先通过 01~05 方案审核。
关联： docs/crm-migration/step-02-frontend-copy.md、step-03-frontend-adapt.md、step-04-backend.md

---

Phase 0：准备与清理（步骤 1~3）

步骤 1：确认方案审核通过

• 阅读 01-overview.md ~ 05-special.md
• 与产品确认：统计页是否 Phase B
• 完成标准：评审记录或口头确认可进入编码

步骤 2：清理门户已有线索前端

• 确认 web-admin/src/views/crm/clue/ 为空或不存在
• 删除 web-admin/src/api/crm/clue.ts（门户适配版）
• 从 sqxp.ts 移除线索路由（若已加回则再删）
• 文件：web-admin/src/router/modules/sqxp.ts

步骤 3：标记后端「待对照 Java 重写」

• 在 module-status.md 将线索标为「前端重做 / 后端待核验」
• 不删除现有 Python（可选）；开发时以 04-api-spec 缺口表为准
• 完成标准：团队知晓勿直接信任现后端行为

---

Phase 1：原版拷贝（步骤 4~6）

步骤 4：拷贝 Vue 页面

从 shanxia/crm/web/src/views/crm/clue/ 拷贝至 web-admin/src/views/crm/clue/（含 statistics/）。

• 9 个 vue + README 就位
• 禁止：改 UI、改 API

步骤 5：拷贝 API 与类型

• api/crm/clue/index.ts → web-admin/src/api/crm/clue.ts 或拆 clue/index.ts
• api/crm/clue/types.ts → web-admin/src/api/crm/clue/types.ts

步骤 6：本地编译冒烟

• pnpm dev 可启动（允许路由未注册时报错仅来自菜单点击）
• 完成标准：无「模块找不到」类错误（拷贝完整性）

---

Phase 2：前端 UI 适配（步骤 7~14）

每步：先读原 script 逻辑，再改 template/style。参照 ref-ui-standards.md。

步骤 7：适配 index.vue — 骨架与筛选

• filter-block / list-toolbar / list-body 类名
• 梳理本页 API 调用清单写入 PR 说明
• 文件：views/crm/clue/index.vue

步骤 8：适配 index.vue — 表格与分页

• 状态列 el-tag；操作列 fixed="right"
• 分页入 list-pager-bar

步骤 9：适配 index.vue — 工具栏与 v-auth

• 按钮图标；唯一 primary
• Tab 切换调用的 list/mine/toFollow API 记下参数

步骤 10：适配 form.vue

• dialog-form-layout、form-grid-2
• 字典、fetchUserOptions

步骤 11：适配 assignForm.vue + invalidForm.vue

• 用户列表 @/api/admin
• 弹窗底栏 Close/Check 图标

步骤 12：适配 followForm.vue + convertForm.vue

• 附件上传组件门户化
• 转化原因校验与 Java 一致

步骤 13：适配 detail.vue

• 布局与 tag；跟进列表分页
• 路由 /#/crm/clue/detail/:id

步骤 14：注册路由与菜单 SQL

• sqxp.ts 增加 CrmClue、CrmClueDetail
• 执行/编写 sys_menu 线索菜单增量 SQL
• 角色授权勾选测试账号

---

Phase 3：后端业务梳理（步骤 15~17）— 先于补全代码

步骤 15：精读 Java CrmClueServiceImpl

• 逐方法做 checklist（转化/分配/导入/统计）
• 更新 05-special.md 若发现遗漏规则

步骤 16：精读 Java CrmClueFollowServiceImpl

• 确认跟进级联四字段
• 确认删除跟进是否递减 count

步骤 17：输出 Postman/接口用例表

• 每条 API 至少 1 正常 + 1 拒绝用例（如已转化不可删）
• 产出：07-verify.md 草稿或 Apifox 集合

---

Phase 4：后端对齐与缺口（步骤 18~25）

步骤 18：核验 DDL 已执行

• 执行 incremental_crm_clue.sql
• 字典数据齐全

步骤 19：对齐 CRUD _row_to_dict 与 Schema

• 对照 Java Vo 字段
• check_field_consistency.py

步骤 20：核验已有 15 个核心路由

• list/detail/add/update/delete/assign/convert/...
• 修正与 Java 不一致处（invalid 批量等）

步骤 21：实现跟进 detail + update

• follow/detail、follow/update
• CRUD + Schema + 路由

步骤 22：实现 export + importTemplate + import

• 参考 crm.py 产品/客户导出实现 openpyxl
• 移植 importClues 校验逻辑

步骤 23：实现 checkDuplicate

• 手机号+公司模糊查重

步骤 24：前端 API 层改 POST 路径

• clue.ts 全部 /web/crm/clue/*
• 响应解包与 customer 模块一致

步骤 25：前后端联调 MVP

• 列表五 Tab
• 新增→跟进→转化→客户详情可查
• 分配、无效、删除边界

---

Phase 5：统计与验收（步骤 26~28）

步骤 26：（可选 Phase B）statistics 五接口 + 统计页

• 后端 5 路由
• statistics/index.vue UI 适配

步骤 27：整体验证

• 执行 07-verify.md 全清单
• pnpm lint / 手测核心路径

步骤 28：更新状态与图谱

• module-status.md 标为已验证
• ./scripts/update-graph.sh frontend（若改大量文件）

---

预估工时（参考）

Phase	步数	人天（1 人）
0~1 拷贝	6	0.5
2 前端	8	2~3
3 梳理	3	1
4 后端	8	2~3
5 验收	3	1
合计	28	6~8