# 线索管理模块迁移方案 — 01 概述

> **编写日期**：2026-05-31  
> **状态**：待审核（审核通过后再执行 step-02 拷贝）

---

## 迁移目标

将原 CRM（`shanxia/crm`）的 **线索管理** 能力完整移植到 shanxia2.0（`web-admin` + `backend`），行为以 Java 实现为准，UI 对齐 Fresh Mint 规范。

## 迁移范围

| 子模块 | 原 CRM 入口 | 说明 |
|--------|-------------|------|
| 线索列表 | `crm/clue/index.vue` | 多视图 Tab、筛选、批量操作、导入导出 |
| 线索详情 | `crm/clue/detail.vue` | 独立详情页（含跟进时间线、转化入口） |
| 线索表单 | `crm/clue/form.vue` | 新增/编辑弹窗 |
| 跟进表单 | `crm/clue/followForm.vue` | 新增/编辑跟进 |
| 转化确认 | `crm/clue/convertForm.vue` | 线索 → 客户 |
| 批量分配 | `crm/clue/assignForm.vue` | 批量改负责人 |
| 标记无效 | `crm/clue/invalidForm.vue` | 无效原因 |
| 线索统计 | `crm/clue/statistics/index.vue` | 5 类统计图表（可选二期，见 06-steps） |

> 原 CRM README 还提到 `detailDrawer.vue`；以 `shanxia/crm/web` 当前目录为准（无 drawer 文件时以 `detail.vue` 为准）。

## 涉及数据库表

| 表名 | DDL 脚本 | 说明 |
|------|----------|------|
| `crm_clue` | `docs/sql/incremental_crm_clue.sql` | 线索主表（已按门户公共字段适配） |
| `crm_clue_follow` | 同上 | 跟进记录 |

字典（`shanxia2.0.sql` 已含）：`crm_clue_source`、`crm_clue_level`、`crm_clue_status`、`crm_title`、`crm_industry`、`crm_customer_park` 等。

## 当前 shanxia2.0 状态（2026-05-31）

| 层级 | 状态 | 处理策略 |
|------|------|----------|
| 前端页面 | **已删除** `web-admin/src/views/crm/clue/` | 按 step-02 从原 CRM 重新拷贝 |
| 前端路由 | sqxp 中线索路由已移除 | 适配完成后再注册 |
| 前端 API | 存在 `web-admin/src/api/crm/clue.ts`（门户 POST 风格） | step-01 删除后 step-02 拷贝原版，step-03 再改 URL |
| 后端 Python | `crud/clue*.py`、`schemas/crm/clue.py`、`api/crm.py` 路由 **已有** | **冻结**：以本方案 04/05 章对照 Java **重写或补齐**，不假定现实现正确 |
| 菜单 SQL | 曾提供 `sys_menu` 增量脚本（未入仓可另补） | 前端+后端验收后再插入菜单 |

## 原 CRM 源码位置

| 类型 | 路径 |
|------|------|
| 前端页面 | `shanxia/crm/web/src/views/crm/clue/` |
| 前端 API | `shanxia/crm/web/src/api/crm/clue/index.ts`、`types.ts` |
| Java Controller | `.../controller/CrmClueController.java`、`CrmClueFollowController.java` |
| Java Service | `.../service/impl/CrmClueServiceImpl.java`、`CrmClueFollowServiceImpl.java` |

## 前端文件映射

| 原 CRM 文件 | shanxia2.0 目标 | 备注 |
|-------------|-----------------|------|
| `views/crm/clue/index.vue` | 同路径 | 列表主页面 |
| `views/crm/clue/detail.vue` | 同路径 | 详情页 |
| `views/crm/clue/form.vue` | 同路径 | 表单弹窗 |
| `views/crm/clue/followForm.vue` | 同路径 | 跟进弹窗 |
| `views/crm/clue/convertForm.vue` | 同路径 | 转化弹窗 |
| `views/crm/clue/assignForm.vue` | 同路径 | 分配弹窗 |
| `views/crm/clue/invalidForm.vue` | 同路径 | 无效弹窗 |
| `views/crm/clue/statistics/index.vue` | 同路径 | 统计（可二期） |
| `api/crm/clue/index.ts` | `api/crm/clue.ts` + `api/crm/clue/types.ts` | 合并或分文件，与项目习惯一致 |
| `api/crm/clue/types.ts` | `api/crm/clue/types.ts` | 类型定义 |

## 方法论（六步对应关系）

| 用户步骤 | 仓库步骤文档 | 产出物 |
|----------|--------------|--------|
| 第一步：删旧 + 拷贝原版 | step-01 + step-02 | 干净的前端源码树 |
| 第二步：逐页 UI + 梳理 API | step-03 + `03-frontend-spec.md` | 每页改造清单、API 调用表 |
| 第三步：Java → Python + SQL | step-04 + `02-database.md` + `04-api-spec.md` | 增量 SQL、路由与 CRUD |
| （第四步略） | — | — |
| 第五步：20~30 细步 | `06-steps.md` | 可执行任务清单 |
| 第六步：先梳理业务再开发 | `05-special.md` + `04-api-spec.md` §业务 | 禁止跳过方案直接编码 |

## 不在本次范围

- MySQL **触发器**：原 `sx.sql` 无线索相关触发器
- **定时任务**：线索模块无独立 SnailJob/Quartz 任务（公海池规则定时任务属客户模块）
- 线索统计页：可列为 **Phase B**（后端 5 个 statistics 接口现未实现）

## 审核检查项

- [ ] 文件映射与原 CRM 目录一致
- [ ] 明确「现 Python 后端仅作参考、以 Java 为准」
- [ ] 统计/导入导出/查重接口缺口已在 04-api-spec 列出

## 关联文档

- 通用流程：`docs/crm-migration/step-01-prepare.md` … `step-05-verify.md`
- 公海池范例：`docs/crm-migration/plans/customer-pool/`
- UI：`docs/web-admin-ui-spec-fresh-mint.md`、模板页 `/#/demo/unit`、`/#/demo/order`