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表和数据字典：

# 方式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执行成功：

-- 检查表创建
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重启完成，无需额外操作。

验证服务状态：

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自动关闭
• 线索列表刷新，该线索状态变为"已转化"
• 线索行的"转化"按钮消失或变为禁用状态

---

后端数据验证

验证线索状态更新：

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

预期结果：

• lead_status = 'converted'
• converted_dealer_id 有值（指向新创建的经销商ID）

---

验证经销商创建：

-- 查询经销商数据
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）

转化接口：

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"
}

成功响应：

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

错误响应示例：

{
  "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日志：

   tail -f /data/hzhub/hzhub-system/logs/hzhub-system.log
   

4. 确认CrmDealerMapper是否正确注入到CrmLeadServiceImpl

---

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

排查步骤：

1. 查询线索数据：

   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路由配置：

   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页面

---

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