shanxia2.0/docs/crm-migration/plans/clue/04-api-spec.md

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

列表响应约定（门户）

{
  "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，不改组件逻辑。