# 公海池模块迁移方案 — 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 |