# 公海池模块迁移方案 — 01 概述

> **编写日期**：2026-05-31
> **状态**：待审核

---

## 迁移范围

本次迁移涉及 CRM 系统中的 **3 个子模块**：

| 模块 | 功能概述 | 涉及表 |
|------|----------|--------|
| **公海池客户列表** | 公海池中客户的查看、领取、分配、查看详情 | `crm_customer`（status=pool） |
| **公海池操作记录** | 记录放入/领取/分配/回收等操作的流水 | `crm_customer_pool` |
| **公海池规则管理** | 自动回收规则的 CRUD + 定时执行 | `crm_customer_pool_rule` |

> **注意**：公海池统计（`CrmCustomerPoolStatisticsController`）本次 **不迁移**，作为后续独立任务。

## 涉及的数据库表

共 **2** 张业务表（公海池客户复用 `crm_customer` 主表的 `status` 字段）：

| 序号 | 表名 | 说明 | 原始 DDL 位置 |
|------|------|------|---------------|
| 1 | `crm_customer_pool` | 公海池操作记录表 | `docs/sql/sx.sql` 第 859 行 |
| 2 | `crm_customer_pool_rule` | 公海池自动回收规则表 | `docs/sql/sx.sql` 第 892 行 |

`crm_customer` 主表中的公海池相关字段（`status`, `into_pool_time`, `into_pool_by`, `into_pool_reason`, `claim_time`, `assign_time`, `assign_by`, `protect_time`）已在客户管理模块迁移时处理。

## 现有 shanxia2.0 代码存在的问题

> ⚠️ 现有公海池代码存在多处违反迁移指南的问题，需全部修正。

| # | 问题 | 影响 |
|---|------|------|
| 1 | `crm_customer_pool` 字段名被改（`from_user_id`→`before_owner_user_id` 等） | 数据语义违反原 CRM |
| 2 | `crm_customer_pool_rule` 字段名被改（`pool_name`→`rule_name` 等） | 数据语义违反原 CRM |
| 3 | `crm_customer_pool_rule.rule_type` 值被改（`no_follow`→`follow_time`） | 字典值违反原 CRM |
| 4 | `crm_customer_pool_rule.status` 类型+值被改（varchar→smallint） | 字典值违反原 CRM |
| 5 | 缺少公海池规则管理前端页面 | 功能缩减 |
| 6 | 缺少公海池操作记录查看页面 | 功能缩减 |
| 7 | `poolRule.ts` API URL 与后端路由不匹配 | Bug |
| 8 | 原有"公海池"页面位于 `customer/pool/` 子目录 | 应为独立路由 |

## 迁移策略

### 方法论

采用「先清理旧代码，再从原 CRM 拷贝，然后逐段适配」：

1. **清理**：删除现有 shanxia2.0 中不符合规范的公海池代码
2. **拷贝**：从 CRM 前端源码拷贝 Vue 组件到 shanxia2.0
3. **适配**：逐行阅读后按需修改，适配门户 UI 规范（Fresh Mint）
4. **后端**：DDL 回归 sx.sql 原始设计，Model/Schema/CRUD/API 全部重写

### 数据库适配规则

按 `docs/crm-migration/ref-database-rules.md` 执行 7 项公共字段适配，业务字段与 `sx.sql` 完全一致。

**本次核心修正**：
- `crm_customer_pool` 字段名回归：`from_user_id`, `to_user_id`, `reason`, `create_by_name`
- `crm_customer_pool_rule` 字段名回归：`pool_name`, `timeout_days`, `sort`
- `rule_type` 值回归：`no_follow` / `no_deal`
- `status` 值回归：`enable` / `disable`（varchar）

### 字典数据一致性

| 字典类型 | 字典值（与 sx.sql 一致） |
|---------|------------------------|
| `crm_pool_operation_type` | into / claim / assign / recycle |
| `crm_pool_rule_type` | no_follow / no_deal |
| `crm_pool_rule_status` | enable / disable |

## 前端文件映射

| 原 CRM 文件 | shanxia2.0 目标文件 | 功能说明 |
|-------------|---------------------|---------|
| `crm/pool/index.vue` | `views/crm/customer/pool/index.vue` | 公海池客户列表 |
| `crm/pool/components/claimDialog.vue` | `views/crm/customer/pool/components/ClaimDialog.vue` | 领取弹窗 |
| `crm/pool/components/assignDialog.vue` | `views/crm/customer/pool/components/AssignDialog.vue` | 分配弹窗 |
| — | `views/crm/customer/pool/components/RuleDialog.vue` | 规则新增/编辑弹窗（新页面） |
| — | `api/crm/pool.ts` | 公海池 API（统一文件） |

## 后端文件清单

| 文件 | 路径 | 说明 |
|------|------|------|
| Model | `backend/app/models/crm_models.py` | 修正 CrmCustomerPool 和 CrmCustomerPoolRule |
| Schema | `backend/app/schemas/crm/customer_pool.py` | 重写，字段名回归 |
| Schema | `backend/app/schemas/crm/pool_rule.py` | 重写，字段名回归 |
| CRUD | `backend/app/crud/crm/customer_pool.py` | 重写 |
| CRUD | `backend/app/crud/crm/pool_rule.py` | 重写 |
| API | `backend/app/api/crm.py` | 修正路由 |
| Task | `backend/app/tasks/customer_pool.py` | 修正定时任务 |
| DDL | `docs/sql/incremental_crm_customer_pool.sql` | 增量 SQL 脚本 |