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脚本**：

```bash
# 登录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. 启动基础设施

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

# 检查服务状态
docker-compose ps
```

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

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

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

#### 3. 启动 hzhub-system（必须）

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

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

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

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

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

#### 5. 启动 hzhub-gateway（必须）

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

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

---

### 步骤3：启动前端服务

```bash
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

**后端验证**：
```sql
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摘要字段可能为空（第二阶段实现）

**后端验证**：
```sql
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":"删除成功"}
- 线索从列表消失（逻辑删除）

**后端验证**：
```sql
select * from crm_lead where lead_id = 1;  -- del_flag = 1
```

---

## 🔧 配置检查清单

### 1. 数据库配置

**检查MySQL连接**：

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

**检查CRM表创建**：

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

---

### 2. 数据字典配置

**检查字典类型**：

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

**检查路由配置**：

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

**预期结果**：
```yaml
- id: hzhub-crm
  uri: http://${SYSTEM_HOST:localhost}:${SYSTEM_PORT:8083}
  predicates:
    - Path=/crm/**
  filters:
    - StripPrefix=1
```

---

### 4. ERP服务配置

**检查ERP配置**：

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

**预期结果**：
```yaml
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测试**：

```bash
# 线索列表查询
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. {问题描述}

---

## ✅ 完成确认

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