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**

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

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

```bash
# 检查表创建
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：重启服务

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

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

**验证服务状态**：

```bash
./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：自动创建商机验证

**后端验证**：

```sql
-- 查询刚转化的线索对应的商机
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）：

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

**成功响应**：

```json
{
  "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. 查看后端日志：
   ```bash
   tail -f /data/hzhub/hzhub-system/logs/hzhub-system.log
   ```

---

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

**排查步骤**：
1. 查询crm_opportunity表：
   ```sql
   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并开始测试！**