# 步骤一：模块分析 + 编写迁移方案

> 移植新模块时首先加载此文档。完成后进入 step-02。
> **前置条件**：通用指南已阅读，理解强制要求。

---

## 目标

产出该模块的完整迁移方案（7 个小文档），作为后续所有实施步骤的依据。

## 强制要求

> ⚠️ 不写方案直接编码是**禁止行为**。方案必须审核通过后才能进入 step-02。

## 操作流程

### 1. 分析原 CRM 模块

在 `shanxia/crm/web/` 和 `shanxia/crm/backend/` 中全面搜索该模块相关文件，输出：

| 分析维度 | 操作 | 输出 |
|---------|------|------|
| 前端页面 | 搜索 `crm/{module}/` 下所有 .vue 文件 | 文件映射表 |
| 数据库表 | 从 `docs/sql/sx.sql` 找 `crm_*` 表 | 表清单 + DDL |
| API 接口 | 阅读前端 API 调用 + Java Controller | API 清单 |
| 特殊场景 | 搜索定时任务/监听器/批量操作 | 场景清单 |
| 字典数据 | 从 sx.sql 找 `crm_%` 字典 | 字典清单 |

### 2. 清理 shanxia2.0 中已有代码

如果该模块之前有部分移植代码，先删除避免干扰：

```
删除范围：
- web-admin/src/views/crm/{module}/ 目录
- web-admin/src/api/crm/{module}.ts
- backend/app/crud/crm/{module}.py
- backend/app/schemas/crm/{module}.py
- backend/app/models/crm_models.py 中该模块的 Model 类
- backend/app/api/crm.py 中该模块的路由
```

### 3. 按模板编写迁移方案

在 `docs/crm-migration/plans/{module}/` 目录下，按以下模板逐个创建方案文档：

| 文件 | 模板 | 内容 | 填写指引 |
|------|------|------|---------|
| `01-overview.md` | [模板](plan-template/01-overview.md) | 迁移范围、涉及表、文件映射、策略 | 从 sx.sql 和 Java 源码提取 |
| `02-database.md` | [模板](plan-template/02-database.md) | 原始DDL、迁移后DDL、字段对照表 | 每张表一节，字段逐个对照 |
| `03-frontend-spec.md` | [模板](plan-template/03-frontend-spec.md) | 每个页面的字段/按钮/交互流程 | 从原 CRM Vue 组件提取 |
| `04-api-spec.md` | [模板](plan-template/04-api-spec.md) | URL、参数、响应、业务逻辑 | 从 Java Controller/Service 提取 |
| `05-special.md` | [模板](plan-template/05-special.md) | 定时任务、导入导出、状态机 | 从 Java Task/Listener 提取 |
| `06-steps.md` | [模板](plan-template/06-steps.md) | 10~20个分步实施计划 | 每步有目标+文件+完成标准 |
| `07-verify.md` | [模板](plan-template/07-verify.md) | 功能验证清单、UI合规检查、测试用例 | 对照原 CRM 功能逐条编写 |

### 4. 方案审核

方案编写完成后，逐文档检查：

- [ ] 每个文档聚焦单一主题，内容多时已拆分为子文档（如 04a/04b）
- [ ] 数据库表与 sx.sql 核对一致
- [ ] API 清单中每个 URL 有 Java 源码位置
- [ ] 前端功能完整性对照表无遗漏
- [ ] 字段对照表中 dict_value 与原 CRM 一致

## 参考资源

| 资源 | 用途 |
|------|------|
| `docs/客户管理及公海池迁移方案.md` | 内容参考（4291行完整方案，但不要照搬格式） |
| `docs/crm-migration/plan-template/` | 模板文件（按此结构拆分） |
| `docs/crm-migration/ref-database-rules.md` | 数据库适配规则 |
| `docs/sql/sx.sql` | 原 CRM 数据库快照 |
| `shanxia/crm/web/` | 原 CRM 前端源码 |
| `shanxia/crm/backend/` | 原 CRM Java 后端源码 |

## 完成标准

- [ ] `docs/crm-migration/plans/{module}/` 下所有文档已创建
- [ ] 每个文档信息完整，未压缩或精简
- [ ] 方案审核通过

## 下一步

方案审核通过后加载 [step-02-frontend-copy.md](step-02-frontend-copy.md)。