# 公海池模块迁移方案 — 05 特殊场景

---

## 定时任务

### 任务 1：保护期到期检查

| 项目 | 内容 |
|------|------|
| 触发频率 | 每天凌晨 1 点 |
| 说明 | 检查保护期到期的客户，跟进次数未达标的自动退回公海 |
| Java 源码 | `CrmCustomerPoolTask.checkProtectPeriodExpired` |

**业务逻辑**：

1. 查询 `protect_time <= 今天` 且 `status='normal'` 且有负责人的客户
2. 检查每个客户的 `follow_count`：
   - `follow_count < 3` → 自动退回公海
     - 更新 `crm_customer.status='pool'`, `into_pool_time`=now, `into_pool_by`=系统
     - 清空 `owner_user_id`
     - 写入 `crm_customer_pool` 记录（operation_type='recycle'）
   - `follow_count >= 3` → 达标，清除保护期（`protect_time=NULL`）
3. 记录日志

**Python 实现位置**：`backend/app/tasks/customer_pool.py` → `check_customer_protect_time`

---

### 任务 2：保护期到期提醒

| 项目 | 内容 |
|------|------|
| 触发频率 | 每天凌晨 1 点（与任务 1 同步执行） |
| 说明 | 提前 3 天提醒保护期即将到期的客户 |
| Java 源码 | `CrmCustomerPoolTask.remindProtectExpiring` |

**业务逻辑**：

1. 查询 `protect_time` 在 3 天内的客户
2. 如果 `follow_count < 3`，发送提醒（当前仅 log，后续接入消息系统）

**Python 实现位置**：`backend/app/tasks/customer_pool.py` → `remind_customer_recycle`

---

### 任务 3：自动回收规则执行

| 项目 | 内容 |
|------|------|
| 触发频率 | 每天凌晨 2 点 |
| 说明 | 根据公海池规则自动回收超时客户 |
| Java 源码 | `CrmCustomerPoolRuleServiceImpl.executePoolRules` |

**业务逻辑**：

1. 查询所有 `status='enable'` 的 `crm_customer_pool_rule`
2. 对每条规则：
   - `rule_type='no_follow'`：查找 `last_time < (now - timeout_days)` 或 `last_time IS NULL` 的正常客户
   - `rule_type='no_deal'`：查找 `claim_time < (now - timeout_days)` 且 `deal_status='not_deal'` 的正常客户
3. 将匹配客户放入公海：
   - 更新 `crm_customer.status='pool'`
   - 记录原负责人信息
   - 写入操作记录（operation_type='recycle'）
4. 排除已成交客户（`deal_status='dealed'`）

**Python 实现位置**：`backend/app/tasks/customer_pool.py` → `execute_pool_rules`

---

## 状态机 / 业务流程

### 流程 1：客户 ↔ 公海池流转

```
normal(正常) → (手动放入/规则回收) → pool(公海) → (领取/分配) → normal(正常) → ...
```

| 转换 | 触发条件 | 伴随操作 |
|------|---------|---------|
| normal→pool | 手动放入 | 写入操作记录(into)，更新 into_pool_time/by/reason，清空 owner |
| normal→pool | 规则自动回收 | 写入操作记录(recycle)，更新 into_pool_time，清空 owner |
| normal→pool | 保护期到期回收 | 写入操作记录(recycle)，更新 into_pool_time，清空 owner |
| pool→normal | 领取 | 写入操作记录(claim)，设置 owner=当前用户，设置 claim_time |
| pool→normal | 管理员分配 | 写入操作记录(assign)，设置 owner=目标用户，设置 assign_time/by |

### 流程 2：保护期机制

```
领取/分配 → 设置保护期(protect_days天) → 到期检查 → 跟进≥3次 → 清除保护期
                                                        → 跟进<3次 → 退回公海
```

| 步骤 | 触发条件 | 伴随操作 |
|------|---------|---------|
| 设置保护期 | 领取/分配时，如果规则有 protect_days | `protect_time = now + protect_days` |
| 保护期到期 | 定时任务检查 `protect_time <= today` | 跟进达标→清除；未达标→退回公海 |
| 提前提醒 | protect_time 在 3 天内 | 记录提醒日志 |

---

## 校验规则

### 规则管理校验

| 场景 | 校验规则 |
|------|---------|
| 新增规则 | poolName 必填；ruleType 必填(no_follow/no_deal)；timeoutDays ≥ 1；protectDays ≥ 0 |
| 删除规则 | status='enable' 的规则禁止删除，须先禁用 |
| 执行规则 | 只执行 status='enable' 的规则；排除 deal_status='dealed' 的客户 |

### 操作校验

| 场景 | 校验规则 |
|------|---------|
| 领取 | 客户 status 必须为 pool |
| 分配 | 客户 status 必须为 pool；ownerUserId 对应有效用户 |
| 放入公海 | 客户 status 必须为 normal；reason 必填 |