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

公海池模块迁移方案 — 04 后端 API 接口规格

后端规范：docs/crm-migration/ref-database-rules.md、docs/crm-migration/ref-lessons-learned.md

---

4.1 公海池客户列表（复用客户 CRUD）

4.1.1 公海池客户列表

项目	内容
URL	/web/crm/customer/pool/list
方法	POST
认证	require_admin_or_super_admin

请求参数：

字段	类型	必填	说明
page	int	是	页码
pageSize	int	是	每页条数
customerName	string	否	客户名称模糊搜索
customerNo	string	否	客户编号模糊搜索
level	string	否	客户级别
source	string	否	客户来源
industry	string	否	所属行业

业务逻辑：

1. 查询 crm_customer 表，status='pool' 且 del_flag=0 且当前租户
2. 支持按 customerName/customerNo 模糊搜索
3. 支持按 level/source/industry 精确筛选
4. 默认排序 create_time DESC

Java 源码：CrmCustomerController → 查询 status=pool 的客户

---

4.1.2 领取公海客户

项目	内容
URL	/web/crm/customer/claim
方法	POST

请求参数：

字段	类型	必填	说明
ids	string[]	是	客户ID列表
remark	string	否	领取说明

业务逻辑：

1. 校验客户 status 必须为 pool，否则报错
2. 更新 crm_customer：status='normal', owner_user_id=当前用户, owner_user_name=当前用户名, claim_time=now
3. 写入 crm_customer_pool 操作记录：operation_type='claim', from_user_id=null(公海无负责人), to_user_id=当前用户

Java 源码：CrmCustomerController.claimCustomer

---

4.1.3 分配公海客户

项目	内容
URL	/web/crm/customer/pool/assign
方法	POST

请求参数：

字段	类型	必填	说明
ids	string[]	是	客户ID列表
ownerUserId	string	是	目标负责人ID
ownerUserName	string	否	目标负责人姓名
remark	string	否	分配说明

业务逻辑：

1. 校验客户 status 必须为 pool
2. 校验 ownerUserId 对应用户存在且有效
3. 更新 crm_customer：status='normal', owner_user_id=目标用户, owner_user_name=目标用户名, assign_time=now, assign_by=当前用户
4. 写入 crm_customer_pool 操作记录：operation_type='assign', to_user_id=目标用户

Java 源码：CrmCustomerController.assignPoolCustomers

---

4.1.4 放入公海池（从客户管理触发）

项目	内容
URL	/web/crm/customer/intoPool
方法	POST

请求参数：

字段	类型	必填	说明
ids	string[]	是	客户ID列表
reason	string	是	放入原因

业务逻辑：

1. 校验客户 status 必须为 normal
2. 更新 crm_customer：status='pool', into_pool_time=now, into_pool_by=当前用户, into_pool_reason=reason, 清空 owner_user_id
3. 写入 crm_customer_pool 操作记录：operation_type='into', from_user_id=原负责人

Java 源码：CrmCustomerController.intoPool

---

4.2 公海池操作记录

4.2.1 操作记录列表

项目	内容
URL	/web/crm/customer/pool/record/list
方法	POST

请求参数：

字段	类型	必填	说明
page	int	是	页码
pageSize	int	是	每页条数
customerName	string	否	客户名称模糊搜索
customerId	string	否	指定客户的记录
operationType	string	否	操作类型筛选
beginTime	string	否	操作时间起
endTime	string	否	操作时间止

业务逻辑：

1. 查询 crm_customer_pool，当前租户，del_flag=0
2. 按 create_time DESC 排序

Java 源码：CrmCustomerPoolController.list

---

4.2.2 操作记录详情

项目	内容
URL	/web/crm/customer/pool/record/detail
方法	POST

请求参数：{ id: string }

Java 源码：CrmCustomerPoolController.getInfo

---

4.3 公海池规则管理

4.3.1 规则列表

URL	方法
/web/crm/customer/pool/rule/list	POST

请求参数：{ page, pageSize, poolName?, ruleType?, status? }

业务逻辑：查询 crm_customer_pool_rule，按 sort ASC, create_time DESC 排序

Java 源码：CrmCustomerPoolRuleController.list

---

4.3.2 新增规则

URL	方法
/web/crm/customer/pool/rule/add	POST

请求参数：

字段	类型	必填	校验	说明
poolName	string	是	required	规则名称
ruleType	string	是	required	no_follow / no_deal
timeoutDays	int	是	≥1	超时天数
protectDays	int	是	≥0	保护期天数
status	string	否	—	默认 enable
sort	int	否	—	默认 0
remark	string	否	—	备注

Java 源码：CrmCustomerPoolRuleController.add

---

4.3.3 编辑规则

URL	方法
/web/crm/customer/pool/rule/update	POST

请求参数：同新增，增加 id（必填）

Java 源码：CrmCustomerPoolRuleController.edit

---

4.3.4 删除规则

URL	方法
/web/crm/customer/pool/rule/delete	POST

业务逻辑：启用状态的规则禁止删除，需先禁用

Java 源码：CrmCustomerPoolRuleController.remove

---

4.3.5 启停规则

URL	方法
/web/crm/customer/pool/rule/updateStatus	POST

请求参数：{ id: string, status: string }（status: enable/disable）

Java 源码：CrmCustomerPoolRuleController.updateStatus

---

4.3.6 手动执行规则

URL	方法
/web/crm/customer/pool/rule/execute	POST

业务逻辑：遍历所有启用规则，将超时客户移入公海，写入操作记录

Java 源码：CrmCustomerPoolRuleServiceImpl.executePoolRules

---

API 清单汇总

#	URL	方法	说明	Java 源码位置
1	/web/crm/customer/pool/list	POST	公海池客户列表	CrmCustomerController
2	/web/crm/customer/claim	POST	领取公海客户	CrmCustomerController
3	/web/crm/customer/pool/assign	POST	分配公海客户	CrmCustomerController
4	/web/crm/customer/intoPool	POST	放入公海池	CrmCustomerController
5	/web/crm/customer/pool/record/list	POST	操作记录列表	CrmCustomerPoolController
6	/web/crm/customer/pool/record/detail	POST	操作记录详情	CrmCustomerPoolController
7	/web/crm/customer/pool/rule/list	POST	规则列表	CrmCustomerPoolRuleController
8	/web/crm/customer/pool/rule/detail	POST	规则详情	CrmCustomerPoolRuleController
9	/web/crm/customer/pool/rule/add	POST	新增规则	CrmCustomerPoolRuleController
10	/web/crm/customer/pool/rule/update	POST	编辑规则	CrmCustomerPoolRuleController
11	/web/crm/customer/pool/rule/delete	POST	删除规则	CrmCustomerPoolRuleController
12	/web/crm/customer/pool/rule/updateStatus	POST	启停规则	CrmCustomerPoolRuleController
13	/web/crm/customer/pool/rule/execute	POST	手动执行规则	CrmCustomerPoolRuleController