# 线索管理模块迁移方案 — 04 API 规格

> 原 CRM：REST + `GET/POST/PUT/DELETE`，前缀 `/crm/clue`  
> 门户：统一 `POST /web/crm/clue/*`，JSON body，响应 `{ code, message, data }`

---

## 线索主接口对照表

| # | 原 CRM（Java） | 门户目标 | Python 现状 | 备注 |
|---|----------------|----------|-------------|------|
| 1 | GET `/list` | POST `/web/crm/clue/list` | ✅ | + `viewType` |
| 2 | GET `/{id}` | POST `/web/crm/clue/detail` | ✅ | body `{ id }` |
| 3 | POST `/` | POST `/web/crm/clue/add` | ✅ | |
| 4 | PUT `/` | POST `/web/crm/clue/update` | ✅ | |
| 5 | DELETE `/{ids}` | POST `/web/crm/clue/delete` | ✅ | `{ ids: string[] }` |
| 6 | PUT `/assign` | POST `/web/crm/clue/assign` | ✅ | |
| 7 | POST `/convert` | POST `/web/crm/clue/convert` | ✅ | 事务 |
| 8 | GET `/checkConvert/{id}` | POST `/web/crm/clue/checkConvert` | ✅ | |
| 9 | PUT `/status` | POST `/web/crm/clue/updateStatus` | ✅ | |
| 10 | PUT `/invalid` | POST `/web/crm/clue/invalid` | ✅ | Java 支持批量 ids |
| 11 | PUT `/level` | POST `/web/crm/clue/updateLevel` | ✅ | |
| 12 | POST `/export` | POST `/web/crm/clue/export` | ✅ | 返回 blob |
| 13 | POST `/importTemplate` | POST `/web/crm/clue/importTemplate` | ✅ | |
| 14 | POST `/import` | POST `/web/crm/clue/import` | ✅ | multipart |
| 15 | GET `/mine` | POST `/web/crm/clue/mine` | ✅ | |
| 16 | GET `/toFollow` | POST `/web/crm/clue/toFollow` | ✅ | |
| 17 | GET `/parkAreaList` | POST `/web/crm/clue/parkAreaList` | ✅ | 建议改字典 |
| 18 | GET `/todayNew` | POST `/web/crm/clue/todayNew` | ✅ | |
| 19 | POST `/checkDuplicate` | POST `/web/crm/clue/checkDuplicate` | ✅ | |
| 20 | GET `/statistics/overview` | POST `/web/crm/clue/statistics/overview` | ✅ | 统计页菜单隐藏 |
| 21 | GET `/statistics/source` | POST `/web/crm/clue/statistics/source` | ✅ | |
| 22 | GET `/statistics/level` | POST `/web/crm/clue/statistics/level` | ✅ | |
| 23 | GET `/statistics/trend` | POST `/web/crm/clue/statistics/trend` | ✅ | |
| 24 | GET `/statistics/owner` | POST `/web/crm/clue/statistics/owner` | ✅ | |

## 跟进记录接口

| # | 原 CRM | 门户目标 | Python 现状 |
|---|--------|----------|-------------|
| 1 | GET `/follow/list` | POST `.../follow/list` | ✅ |
| 2 | GET `/follow/{id}` | POST `.../follow/detail` | ✅ |
| 3 | POST `/follow` | POST `.../follow/add` | ✅ |
| 4 | PUT `/follow` | POST `.../follow/update` | ✅ |
| 5 | DELETE `/follow/{ids}` | POST `.../follow/delete` | ✅ |
| 6 | GET `/follow/clue/{clueId}` | 可合并进 list | — |
| 7 | POST `/follow/export` | POST `.../follow/export` | ❌ |
| 8 | GET `/follow/statistics/{clueId}` | POST `.../follow/statistics` | ✅ |

## 列表响应约定（门户）

```json
{
  "code": 200,
  "data": {
    "list": [],
    "total": 0,
    "page": 1,
    "pageSize": 10,
    "totalPages": 0
  }
}
```

字段命名：CRUD `_row_to_dict` 输出 camelCase（`clueName`、`ownerUserId` …）。

## 关键业务逻辑索引（开发前必读 Java）

| API | Java 方法 |
|-----|-----------|
| 新增 | `CrmClueServiceImpl.insertByBo` |
| 转化 | `convertToCustomer` |
| 分配 | `assignClues` |
| 跟进新增 | `CrmClueFollowServiceImpl.insertByBo` |
| 列表待跟进 | `queryToFollowClues` |
| 导入 | `importClues` |

详见 `05-special.md`。

## 前端 API 文件结构建议

```
web-admin/src/api/crm/
  clue.ts          # 方法（post 封装）
  clue/types.ts    # ClueQuery, ClueForm, ClueVO, ...
```

拷贝后第一步仅改 `request` 路径与 method，不改组件逻辑。