261 lines
7.5 KiB
Markdown
261 lines
7.5 KiB
Markdown
# 公海池模块迁移方案 — 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 |
|