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

CRM商机管理功能 - 测试指引

✅ 开发完成状态

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

创建文件：

• 数据库SQL：1个（crm_opportunity_init.sql）
• Entity实体类：1个（CrmOpportunity.java）
• Bo业务对象：1个（CrmOpportunityBo.java）
• Vo视图对象：1个（CrmOpportunityVo.java）
• Mapper接口：1个（CrmOpportunityMapper.java）
• Mapper XML：1个（CrmOpportunityMapper.xml）
• Service接口：1个（ICrmOpportunityService.java）
• Service实现：1个（CrmOpportunityServiceImpl.java）
• Controller控制器：1个（CrmOpportunityController.java）

修改文件：

• CrmLeadServiceImpl.java - 在线索转化时自动创建初始商机

总计：9个新文件 + 1个SQL文件 + 1个现有文件修改

---

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

修改文件：

• API类型定义：1个修改（api/crm/types.ts，添加商机类型）
• API调用方法：1个修改（api/crm/index.ts，添加商机API）
• CRM页面：1个修改（pages/crm/index.vue，商机管道使用真实数据）

总计：3个文件修改

---

🚀 测试步骤

步骤1：数据库初始化

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

创建商机表、跟进记录表和数据字典：

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

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

验证SQL执行成功：

# 检查表创建
sudo docker compose exec mysql mysql -u root -pHzhub@2024 hzhub -e "SHOW TABLES LIKE 'crm_opportunity';"
sudo docker compose exec mysql mysql -u root -pHzhub@2024 hzhub -e "SHOW TABLES LIKE 'crm_opportunity_follow';"

# 检查数据字典
sudo docker compose exec mysql mysql -u root -pHzhub@2024 hzhub -e "SELECT dict_type, dict_name FROM sys_dict_type WHERE dict_type IN ('crm_opportunity_stage', 'crm_opportunity_status');"

预期结果：

• crm_opportunity表存在（商机表）
• crm_opportunity_follow表存在（跟进记录表）
• 数据字典类型：crm_opportunity_stage（商机阶段）、crm_opportunity_status（商机状态）
• 商机阶段数据：lead、negotiation、proposal、closing、lost
• 商机状态数据：active、won、lost、paused

---

步骤2：重启服务

由于修改了后端代码和前端代码，需要重启服务：

cd /data/hzhub
./restart-all.sh

验证服务状态：

./status-all.sh

预期结果：

• hzhub-system: Running
• hzhub-gateway: Running
• hzhub-portal-employee: Running

---

步骤3：测试商机管道功能

测试准备：转化线索创建经销商

1. 登录员工门户：http://localhost:5137
2. 导航到"销售CRM" → "线索管理"Tab
3. 选择一个线索，点击"转化"按钮
4. 填写转化表单（经销商编码、签约时间等）
5. 点击"确认转化"

预期结果：

• 线索转化成功
• 创建经销商记录
• 自动创建初始商机（商机名称="初始商机"，阶段="lead"）

---

测试1：商机管道显示真实数据

测试步骤：

1. 点击"商机管道"Tab
2. 查看Pipeline视图

预期结果：

• 商机管道显示真实数据（不再是mock数据）
• Pipeline顶部显示各阶段计数（全部、线索、谈判中、方案、赢单）
• 商机卡片显示：
  • 商机名称（如"初始商机"）
  • 经销商名称（如"测试贸易有限公司"）
  • 负责人姓名
  • 预计成交日期
  • 商机金额
  • 阶段标签（线索/赢单等）

---

测试2：商机阶段筛选

测试步骤：

1. 在商机管道顶部，点击不同阶段Tab（全部、线索、谈判中、方案、赢单）
2. 观察商机卡片的变化

预期结果：

• 点击"线索"Tab，只显示阶段为"lead"的商机
• 点击"赢单"Tab，只显示阶段为"closing"的商机
• 计数实时更新

---

测试3：自动创建商机验证

后端验证：

-- 查询刚转化的线索对应的商机
SELECT o.opportunity_id, o.opportunity_name, o.dealer_id, o.stage, o.source_lead_id,
       d.dealer_name, d.dealer_code
FROM crm_opportunity o
LEFT JOIN crm_dealer d ON o.dealer_id = d.dealer_id
WHERE o.source_lead_id = {线索ID};

预期结果：

• 商机记录存在
• opportunity_name = '初始商机'
• stage = 'lead'
• dealer_id 关联到新创建的经销商
• source_lead_id = 线索ID
• dealer_name 显示经销商名称

---

测试4：商机列表API测试

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

GET http://localhost:8080/crm/opportunity/list?pageNum=1&pageSize=10
Headers:
  Authorization: Bearer {token}
  ClientID: employee-portal

成功响应：

{
  "code": 200,
  "msg": "查询成功",
  "data": {
    "rows": [
      {
        "opportunityId": 1,
        "opportunityName": "初始商机",
        "dealerId": 1,
        "dealerName": "测试贸易有限公司",
        "stage": "lead",
        "stageName": "线索",
        "amount": 0,
        "probability": 10,
        "ownerUserId": 1,
        "ownerUserName": "管理员",
        "status": "active",
        "statusName": "进行中"
      }
    ],
    "total": 1
  }
}

---

📊 完整功能测试清单

测试项	状态	备注
数据库SQL执行	⏳ 待执行
表创建验证	⏳ 待测试
数据字典验证	⏳ 待测试
服务重启	⏳ 待执行
线索转化创建商机	⏳ 待测试
商机管道显示	⏳ 待测试
商机阶段筛选	⏳ 待测试
商机数据验证	⏳ 待测试
商机列表API	⏳ 待测试

---

🐛 常见问题排查

问题1：商机管道显示空列表

排查步骤：

1. 检查crm_opportunity表是否创建
2. 检查是否有商机数据（先转化线索创建经销商）
3. 查看浏览器Console错误日志
4. 查看后端日志：

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

---

问题2：线索转化后商机未创建

排查步骤：

1. 查询crm_opportunity表：

   SELECT * FROM crm_opportunity WHERE source_lead_id = {线索ID};
   

2. 检查CrmLeadServiceImpl.convertToDealer方法是否正确调用opportunityService
3. 查看后端日志中的商机创建记录

---

问题3：商机管道仍显示mock数据

排查步骤：

1. 检查前端代码是否正确导入getOpportunityList
2. 检查onMounted是否调用loadOpportunities
3. 检查opportunityList是否绑定到商机卡片渲染
4. 清空浏览器缓存重新加载页面

---

问题4：负责人显示为空

排查步骤：

1. 查询商机数据中的owner_user_id字段
2. 检查用户翻译是否生效（UserNameTranslationImpl）
3. 查询sys_user表确认用户数据存在

---

🎯 功能说明

商机管道设计

数据流：

线索(crm_lead)
  ↓转化
经销商(crm_dealer)
  ↓自动创建
商机(crm_opportunity) [阶段:lead]
  ↓跟进推进
  └阶段变化: lead → negotiation → proposal → closing

阶段含义：

• lead（线索）：初始商机，刚转化
• negotiation（谈判中）：正在谈判价格和条件
• proposal（方案）：已提交方案报价
• closing（赢单）：即将成交
• lost（输单）：商机失败

商机管道视图：

• 管道顶部：阶段Tab切换（全部/线索/谈判中/方案/赢单）
• 管道卡片：商机信息（名称、经销商、负责人、金额、日期）
• 实时计数：各阶段商机数量统计

---

✅ 开发总结

实现的功能

1. 数据库层：

   • 创建crm_opportunity表（商机表）
   • 创建crm_opportunity_follow表（跟进记录表）
   • 初始化商机阶段和状态数据字典

2. 业务逻辑层：

   • 商机CRUD完整功能（新增、修改、删除、查询）
   • 线索转化自动创建初始商机
   • 商机关联经销商（方案A）
   • 商机数据翻译（经销商名称、负责人姓名）

3. 前端交互层：

   • 商机管道使用真实数据渲染
   • Pipeline阶段Tab切换和筛选
   • 商机卡片动态显示
   • 实时计数统计

架构关系

确认的设计方案：

• ✅ 方案A：商机关联经销商
• ✅ 商机管道"客户" = 经销商
• ✅ ERP客户是独立对象（数据参考源）
• ✅ 创建crm_opportunity表

数据关系图：

ERP客户（独立对象，数据源）
    ↓（可选关联）
线索（crm_lead）
    ↓转化
经销商（crm_dealer）
    ↓关联
商机（crm_opportunity）[可多个]
    ↓跟进
商机跟进记录（crm_opportunity_follow）

---

📝 后续开发建议

待实现功能

1. 商机跟进功能：

   • 添加商机跟进按钮和Dialog
   • 创建跟进记录
   • AI跟进摘要

2. 商机编辑功能：

   • 商机详情查看
   • 商机信息修改
   • 阶段推进

3. 商机新建功能：

   • 直接为经销商创建新商机（不通过线索转化）

4. 商机筛选增强：

   • 经销商搜索筛选
   • 负责人筛选
   • 商机金额范围筛选

5. 商机统计分析：

   • 商机金额统计
   • 成功率分析
   • 阶段转化率分析

---

🎯 下一步开发计划

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

本周剩余时间：完善商机基础功能

• 商机跟进功能
• 商机详情查看
• 商机编辑功能

Week 2-3：AI功能

• AI意向分析
• AI跟进摘要
• AI风险分析

Week 4+：企业微信集成

---

当前任务完成，请执行SQL并开始测试！