hzhub/docs/crm-convert-testing-guide.md

# CRM线索转经销商功能 - 测试指引

## ✅ 后端开发完成状态

**创建文件统计**：
- 数据库SQL：1个（`crm_dealer_init.sql`）
- Entity实体类：1个（`CrmDealer.java`）
- Bo业务对象：2个（`CrmDealerBo.java`, `CrmLeadConvertBo.java`）
- Vo视图对象：1个（`CrmDealerVo.java`）
- Mapper接口：1个（`CrmDealerMapper.java`）
- Service实现：修改1个（`CrmLeadServiceImpl.java`，添加`convertToDealer`方法）
- Controller：修改1个（`CrmLeadController.java`，添加`POST /lead/convert`接口）

**总计**：6个新代码文件 + 1个SQL文件 + 2个现有文件修改

---

## ✅ 前端开发完成状态

**修改文件统计**：
- 页面扩展：1个（`/crm/index.vue`，添加转经销商Dialog和转化逻辑）
- API类型定义：1个修改（`types.ts`，添加`LeadConvertRequest`类型）
- API调用方法：1个修改（`index.ts`，添加`convertLeadToDealer`函数）

**总计**：3个文件修改

---

## 🚀 测试步骤

### 步骤1：数据库初始化

**⚠️ 重要：必须先执行数据库SQL**

执行SQL脚本创建`crm_dealer`表和数据字典：

```bash
# 方式1：使用Docker MySQL容器（推荐）
cd /data/hzhub/hzhub-deploy
docker compose exec -T mysql mysql -u root -pHzhub@2024 hzhub < /data/hzhub/hzhub-system/src/main/resources/db/crm_dealer_init.sql

# 方式2：手动在数据库客户端执行
# 打开数据库客户端（如Navicat、DBeaver），连接到hzhub数据库
# 执行SQL文件：/data/hzhub/hzhub-system/src/main/resources/db/crm_dealer_init.sql
```

**验证SQL执行成功**：

```sql
-- 检查表创建
SHOW TABLES LIKE 'crm_dealer';
DESC crm_dealer;

-- 检查数据字典
SELECT dict_type, dict_name FROM sys_dict_type WHERE dict_type IN ('crm_dealer_level', 'crm_lifecycle');
SELECT dict_value, dict_label FROM sys_dict_data WHERE dict_type = 'crm_dealer_level';
SELECT dict_value, dict_label FROM sys_dict_data WHERE dict_type = 'crm_lifecycle';
```

**预期结果**：
- `crm_dealer`表存在，包含所有字段
- 数据字典类型：`crm_dealer_level`（经销商等级）、`crm_lifecycle`（生命周期）
- 经销商等级数据：A、B、C
- 生命周期数据：active、stable、decline、churn

---

### 步骤2：重启后端服务

所有服务已通过`restart-all.sh`重启完成，无需额外操作。

**验证服务状态**：

```bash
cd /data/hzhub
./status-all.sh
```

**预期结果**：
- hzhub-system: Running (PID: 1771446)
- hzhub-gateway: Running (PID: 1771913)
- hzhub-portal-employee: Running (PID: 1772306)

---

### 步骤3：测试线索转化功能

#### 测试准备：创建测试线索

1. 登录员工门户：http://localhost:5137
2. 导航到"销售CRM" → "线索管理"Tab
3. 点击"新建线索"，填写以下信息：
   - 公司名称：测试贸易有限公司
   - 联系人：张三
   - 手机号：13800138000
   - 线索来源：活动
   - 活动名称：春季招商会

4. 点击"创建线索"，确认创建成功

---

#### 测试转化流程

**测试步骤**：

1. 在线索列表中，找到刚创建的测试线索
2. 点击该线索行的"转化"按钮
3. 查看转经销商Dialog弹出

**Dialog字段检查**：
- 经销商名称：默认填充线索公司名称（可修改）
- 经销商编码：输入框（必填）
- ERP客户编码：输入框（可选）
- 签约时间：日期选择器（可选）
- 经销商等级：下拉选择（默认C，可选：A/B/C）

4. 填写转化表单：
   - 经销商名称：保持默认"测试贸易有限公司"
   - 经销商编码：DL20260001
   - 签约时间：选择今天或任意日期
   - 经销商等级：选择C级经销商

5. 点击"确认转化"按钮

**预期结果**：
- 显示"转化成功"提示
- Dialog自动关闭
- 线索列表刷新，该线索状态变为"已转化"
- 线索行的"转化"按钮消失或变为禁用状态

---

#### 后端数据验证

**验证线索状态更新**：

```sql
-- 查询线索状态
SELECT lead_id, company_name, lead_status, converted_dealer_id
FROM crm_lead
WHERE company_name = '测试贸易有限公司';
```

**预期结果**：
- `lead_status` = 'converted'
- `converted_dealer_id` 有值（指向新创建的经销商ID）

---

**验证经销商创建**：

```sql
-- 查询经销商数据
SELECT dealer_id, dealer_name, dealer_code, contact_name, mobile, level, lifecycle, source_lead_id
FROM crm_dealer
WHERE dealer_code = 'DL20260001';
```

**预期结果**：
- `dealer_name` = '测试贸易有限公司'
- `dealer_code` = 'DL20260001'
- `contact_name` = '张三'（从线索复制）
- `mobile` = '13800138000'（从线索复制）
- `level` = 'C'
- `lifecycle` = 'active'
- `source_lead_id` = 线索ID（关联）

---

#### 测试重复转化（负面测试）

**测试步骤**：

1. 尝试再次转化已转化的线索
2. 点击已转化线索的"转化"按钮

**预期结果**：
- 后端返回错误："线索已转化，不能重复转化"
- Dialog显示错误提示

---

#### 测试经销商编码唯一性（负面测试）

**测试步骤**：

1. 创建另一个新线索（不同手机号）：
   - 公司名称：另一个测试公司
   - 联系人：李四
   - 手机号：13900139000

2. 点击"转化"，填写表单：
   - 经销商编码：DL20260001（重复编码）

3. 点击"确认转化"

**预期结果**：
- 后端返回错误："经销商编码已存在"
- Dialog显示错误提示

---

## 🔧 后端接口验证

### API调用测试（使用Postman或curl）

**转化接口**：

```bash
POST http://localhost:8080/crm/lead/convert
Headers:
  Authorization: Bearer {token}
  ClientID: employee-portal
Body:
{
  "leadId": 1,
  "dealerName": "测试贸易有限公司",
  "dealerCode": "DL20260001",
  "signedAt": "2026-05-20",
  "level": "C"
}
```

**成功响应**：

```json
{
  "code": 200,
  "msg": "操作成功"
}
```

**错误响应示例**：

```json
{
  "code": 500,
  "msg": "线索已转化，不能重复转化"
}
```

---

## 📊 完整功能测试清单

| 测试项 | 预期结果 | 实际结果 | 备注 |
|---|---|---|---|
| 数据库SQL执行 | 表和数据字典创建成功 | ✅/❌ | |
| 服务重启 | 所有服务正常运行 | ✅/❌ | |
| 创建测试线索 | 线索创建成功 | ✅/❌ | |
| 转化Dialog显示 | Dialog正常弹出，字段完整 | ✅/❌ | |
| 默认值填充 | 公司名称自动填充 | ✅/❌ | |
| 经销商等级下拉 | 显示A/B/C选项，默认C | ✅/❌ | |
| 正常转化流程 | 转化成功，提示显示 | ✅/❌ | |
| 线索状态更新 | lead_status = converted | ✅/❌ | |
| 经销商数据创建 | 所有字段正确复制 | ✅/❌ | |
| 重复转化拦截 | 错误提示显示 | ✅/❌ | |
| 编码唯一性校验 | 错误提示显示 | ✅/❌ | |

---

## 🐛 常见问题排查

### 问题1：转化按钮点击无响应

**排查步骤**：
1. 检查浏览器Console是否有错误日志
2. 检查前端代码中`submitConvert`函数是否正确实现
3. 检查`convertLeadToDealer` API调用是否正常

---

### 问题2：转化成功但经销商数据未创建

**排查步骤**：
1. 检查数据库中`crm_dealer`表是否创建成功
2. 检查数据字典是否存在
3. 查看hzhub-system日志：
   ```bash
   tail -f /data/hzhub/hzhub-system/logs/hzhub-system.log
   ```
4. 确认`CrmDealerMapper`是否正确注入到`CrmLeadServiceImpl`

---

### 问题3：转化成功但线索状态未更新

**排查步骤**：
1. 查询线索数据：
   ```sql
   SELECT lead_id, lead_status, converted_dealer_id FROM crm_lead WHERE lead_id = {线索ID};
   ```
2. 检查`CrmLeadServiceImpl.convertToDealer`方法中是否执行了线索更新
3. 检查事务是否正确提交（方法有`@Transactional`注解）

---

### 问题4：Gateway路由失败

**排查步骤**：
1. 检查Gateway服务是否启动
2. 检查Gateway路由配置：
   ```bash
   cat /data/hzhub/hzhub-gateway/src/main/resources/application.yml | grep -A 10 "hzhub-crm"
   ```
3. 测试Gateway健康：http://localhost:8080/actuator/health

---

## ✅ 测试完成确认

**请按照以上步骤进行测试，完成后告知测试结果。**

**测试报告格式**：

```
测试日期：{填写日期}
测试人员：{填写姓名}

测试结果：
- 数据库初始化：✅/❌
- 转化功能：✅/❌
- 数据验证：✅/❌
- 异常处理：✅/❌

问题记录：
1. {问题描述}
2. {问题描述}

下一步建议：
{填写内容}
```

---

## 📝 开发总结

### 实现的功能

1. **数据库层**：
   - 创建`crm_dealer`表，包含经销商完整字段
   - 初始化经销商等级和生命周期数据字典
   - 建立线索与经销商的关联（`converted_dealer_id`, `source_lead_id`）

2. **业务逻辑层**：
   - 线索状态校验（防止重复转化）
   - 经销商编码唯一性校验
   - 从线索复制基础信息到经销商
   - 线索状态更新为"已转化"
   - 关联线索和经销商ID
   - 事务保证数据一致性

3. **前端交互层**：
   - 转经销商Dialog UI
   - 表单字段默认值填充（公司名称）
   - 经销商等级下拉选择
   - 转化成功提示和列表刷新
   - 错误提示显示

### 待实现功能（后续阶段）

1. **跟进记录迁移**：
   - 将线索跟进记录迁移到经销商跟进记录表（需要创建`crm_dealer_follow`表）

2. **初始商机创建**：
   - 转化时自动创建初始商机（需要创建`crm_opportunity`表）

3. **ERP数据关联**：
   - 如果提供了ERP客户编码，在经销商详情中可查看ERP数据

4. **用户选择器集成**：
   - 分配线索时使用真实的用户选择组件

5. **线索删除功能**：
   - 完整的线索删除功能实现

---

## 🎯 下一阶段功能预告

根据"方案A：实用优先"，后续开发顺序：

**第2项功能**：用户选择器组件
- 替换线索分配中的硬编码用户ID输入
- 实现真实的用户选择下拉组件

**第3项功能**：线索删除功能
- 完善删除按钮和确认逻辑

**Week 2-3**：AI功能（AI意向分析、AI跟进摘要、AI风险分析）

**Week 4+**：企业微信集成、移动H5页面

---

**当前任务完成，请开始测试！**