# 线索管理模块迁移方案 — 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** |