hzhub/docs/crm-testing-guide.md

CRM线索中心模块 - 开发完成与测试指引

✅ 开发完成状态

后端开发（hzhub-system）- 已完成

创建文件统计：

• 数据库SQL：1个
• Entity实体类：2个
• Bo业务对象：2个
• Vo视图对象：2个
• Mapper接口：2个
• Mapper XML：2个
• Service接口与实现：4个
• Controller控制器：2个
• ERP集成服务：1个
• RestTemplate配置：1个
• application.yml配置：1个修改

总计：19个代码文件 + 1个SQL文件 + 1个配置修改

---

前端开发（hzhub-portal-employee）- 已完成

创建文件统计：

• API类型定义：1个（types.ts）
• API调用方法：1个（index.ts）
• 页面扩展：1个（/crm/index.vue，从107行扩展到779行）

总计：2个API文件 + 1个页面扩展

---

Gateway配置 - 已完成

路由配置：

• 已添加 /crm/** 路由到 hzhub-system 服务
• 配置文件：hzhub-gateway/src/main/resources/application.yml

---

🚀 启动测试步骤

步骤1：数据库初始化

执行SQL脚本：

# 登录MySQL
mysql -h localhost -u root -p

# 执行初始化SQL
source /data/hzhub/hzhub-system/src/main/resources/db/crm_lead_init.sql;

# 检查表创建和数据字典
show tables like 'crm_%';
select * from sys_dict_type where dict_type like 'crm_%';

SQL文件内容：

• 创建 crm_lead 表（线索表）
• 创建 crm_lead_follow 表（跟进记录表）
• 初始化5个数据字典：
  • crm_lead_source（线索来源）
  • crm_lead_status（线索状态）
  • crm_intent_level（AI意向等级）
  • crm_risk_level（风险等级）
  • crm_follow_type（跟进方式）

---

步骤2：启动后端服务

启动顺序（按依赖关系）：

1. 启动基础设施

cd hzhub-deploy
docker-compose up -d mysql redis weaviate

# 检查服务状态
docker-compose ps

2. 启动 hzhub-ai（可选，第一阶段不需要AI功能）

cd hzhub-ai/hzhub-admin
mvn spring-boot:run -Dspring-boot.run.profiles=dev

注意：第一阶段测试不需要启动AI服务，AI功能在第二阶段实现。

3. 启动 hzhub-system（必须）

cd hzhub-system
mvn spring-boot:run -Dspring-boot.run.profiles=dev

验证：

• 访问：http://localhost:8083/actuator/health
• 确认服务健康状态为 UP

4. 启动 hzhub-erp（可选，测试ERP关联功能）

cd hzhub-erp
mvn spring-boot:run -Dspring-boot.run.profiles=dev

注意：如果要测试ERP客户关联功能，需要启动ERP服务。

5. 启动 hzhub-gateway（必须）

cd hzhub-gateway
mvn spring-boot:run -Dspring-boot.run.profiles=dev

验证：

• 访问：http://localhost:8080/actuator/health
• 确认服务健康状态为 UP

---

步骤3：启动前端服务

cd hzhub-portal-employee
pnpm install  # 如果没有安装依赖
pnpm dev

访问：http://localhost:5137

验证：

• 登录员工门户
• 导航到"销售CRM"页面
• 确认页面正常加载

---

🧪 功能测试清单

测试1：Tab切换功能

测试步骤：

1. 登录员工门户：http://localhost:5137
2. 点击左侧菜单"销售CRM"
3. 确认默认显示"商机管道"Tab
4. 点击"线索管理"Tab
5. 确认线索列表自动加载

预期结果：

• Tab切换流畅，无卡顿
• 切换到"线索管理"时显示空列表或现有线索数据

---

测试2：新建线索功能

测试步骤：

1. 在"线索管理"Tab，点击"新建线索"按钮
2. 填写必填字段：
   • 公司名称：测试贸易有限公司
   • 联系人：张三
   • 手机号：13800138000
3. 选择来源类型：活动
4. 填写活动名称：春季招商会
5. 点击"创建线索"

预期结果：

• 显示"创建成功"提示
• 线索列表自动刷新，显示新创建的线索
• 手机号脱敏显示为：138****8000

后端验证：

select * from crm_lead order by create_time desc limit 1;

---

测试3：ERP客户关联功能（需要启动ERP服务）

测试步骤：

1. 新建线索时，不填写基础信息
2. 填写ERP客户编码：C001（需要ERP中存在的客户编码）
3. 点击"创建线索"

预期结果：

• 后端自动从ERP拉取客户信息
• 线索列表显示的公司名称、联系人、手机号来自ERP
• ERP编码显示为蓝色链接

后端验证：

• 查看后端日志，确认调用ERP API：GET /erp/dynamic/v1/customer/detail?customerCode=C001

---

测试4：线索详情查看

测试步骤：

1. 在线索列表中，点击某个线索的"详情"按钮
2. 查看详情Drawer展示
3. 确认字段完整显示

预期结果：

• Drawer右侧打开，宽度50%
• 公司名称、联系人、手机号完整显示（未脱敏）
• AI意向评分显示进度条（初始可能为空，第二阶段AI分析后填充）
• 风险等级显示标签
• ERP编码显示链接（如果有）

---

测试5：线索跟进功能

测试步骤：

1. 在线索列表中，点击某个线索的"跟进"按钮
2. 选择跟进方式：电话
3. 输入跟进内容：与客户沟通了合作意向，客户对产品感兴趣
4. 选择下次跟进时间：明天
5. 点击"保存跟进"

预期结果：

• 显示"跟进成功"提示
• Drawer关闭
• 线索列表刷新，"下次跟进时间"列更新

详情验证：

1. 打开线索详情Drawer
2. 查看跟进记录Timeline
3. 确认最新跟进记录显示在最上方
4. AI摘要字段可能为空（第二阶段实现）

后端验证：

select * from crm_lead_follow where lead_id = {线索ID} order by create_time desc;

---

测试6：线索筛选功能

测试步骤：

1. 在"线索管理"Tab的筛选栏
2. 输入关键词：测试
3. 选择AI意向等级：高意向
4. 选择线索状态：跟进中
5. 点击"搜索"

预期结果：

• 线索列表只显示符合条件的记录
• 分页总数更新
• 清空筛选条件后，列表恢复完整显示

---

测试7：线索分配功能

测试步骤：

1. 在线索列表中，点击某个线索的"分配"按钮（暂未在UI显示，需要后端接口测试）
2. 使用API工具（如Postman）测试：

   PUT http://localhost:8080/crm/lead/assign
   Headers: Authorization: Bearer {token}
   Body: {
     "leadId": 1,
     "ownerUserId": 12345
   }
   

预期结果：

• 后端返回：{"code":200,"msg":"分配成功"}
• 线索负责人更新为指定用户

---

测试8：线索删除功能

测试步骤：

1. 在线索列表中，点击某个线索的"删除"按钮（暂未在UI显示，需要后端接口测试）
2. 使用API工具测试：

   DELETE http://localhost:8080/crm/lead/1
   Headers: Authorization: Bearer {token}
   

预期结果：

• 后端返回：{"code":200,"msg":"删除成功"}
• 线索从列表消失（逻辑删除）

后端验证：

select * from crm_lead where lead_id = 1;  -- del_flag = 1

---

🔧 配置检查清单

1. 数据库配置

检查MySQL连接：

mysql -h localhost -u root -p -e "show databases like 'hzhub';"

检查CRM表创建：

use hzhub;
show tables like 'crm_%';
desc crm_lead;
desc crm_lead_follow;

---

2. 数据字典配置

检查字典类型：

select dict_type, dict_name from sys_dict_type where dict_type like 'crm_%';

预期结果：

• crm_lead_source - 线索来源
• crm_lead_status - 线索状态
• crm_intent_level - AI意向等级
• crm_risk_level - 风险等级
• crm_follow_type - 跟进方式

---

3. Gateway路由配置

检查路由配置：

cat hzhub-gateway/src/main/resources/application.yml | grep -A 10 "hzhub-crm"

预期结果：

- id: hzhub-crm
  uri: http://${SYSTEM_HOST:localhost}:${SYSTEM_PORT:8083}
  predicates:
    - Path=/crm/**
  filters:
    - StripPrefix=1

---

4. ERP服务配置

检查ERP配置：

cat hzhub-system/src/main/resources/application.yml | grep "erp.base-url"

预期结果：

erp:
  base-url: ${ERP_BASE_URL:http://localhost:8082}

---

🐛 常见问题排查

问题1：线索列表加载失败

排查步骤：

1. 检查hzhub-system服务是否启动
2. 检查Gateway路由配置
3. 检查数据库表是否创建
4. 查看浏览器Console错误日志
5. 查看后端日志：tail -f hzhub-system/logs/hzhub-system.log

---

问题2：新建线索失败

排查步骤：

1. 检查数据库连接是否正常
2. 检查数据字典是否初始化
3. 检查必填字段是否填写
4. 查看后端日志中的错误信息

---

问题3：ERP客户关联失败

排查步骤：

1. 检查hzhub-erp服务是否启动
2. 检查ERP服务健康：http://localhost:8082/erp/test/health
3. 检查customerCode是否在ERP中存在
4. 查看hzhub-system日志中的ERP调用记录

---

问题4：Gateway路由失败

排查步骤：

1. 检查Gateway服务是否启动
2. 检查Gateway日志：tail -f hzhub-gateway/logs/hzhub-gateway.log
3. 确认路由配置顺序（CRM路由在hzhub-ai-workflow之前）
4. 测试Gateway健康：http://localhost:8080/actuator/health

---

📊 性能测试建议

API响应时间测试

使用Postman或curl测试：

# 线索列表查询
curl -w "\nTime: %{time_total}s\n" \
  -H "Authorization: Bearer {token}" \
  "http://localhost:8080/crm/lead/list?pageNum=1&pageSize=10"

# 线索详情查询
curl -w "\nTime: %{time_total}s\n" \
  -H "Authorization: Bearer {token}" \
  "http://localhost:8080/crm/lead/1"

预期响应时间：

• 列表查询：< 200ms
• 详情查询：< 100ms
• 新增线索：< 300ms（含ERP调用）

---

🎯 第二阶段功能预告

待实现功能

1. AI意向分析

   • 调用hzhub-ai服务分析线索意向
   • 自动生成AI评分

2. AI跟进摘要

   • 使用LangChain4j生成跟进摘要
   • 自动提取关键信息

3. 线索转经销商

   • 完整的转化流程UI
   • 创建经销商数据

4. 用户选择器

   • 分配线索时使用真实的用户选择组件

5. 企业微信集成

   • 移动端H5页面
   • 企业微信侧边栏

---

📝 测试报告模板

测试日期：{填写日期}

测试人员：{填写姓名}

测试环境：

• MySQL版本：8.0.x
• Redis版本：7.x
• Node版本：22.x
• JDK版本：17

测试结果：

测试项	结果	备注
Tab切换	✅
新建线索	✅
ERP关联	❌
线索详情	✅
线索跟进	✅
线索筛选	✅
线索分配	✅/❌
线索删除	✅/❌

问题记录：

1. {问题描述}
2. {问题描述}

---

✅ 完成确认

请按照以上步骤进行测试，完成后告知测试结果，以便继续第二阶段开发！