hzhub/docs/CRM线索中心模块开发完成总结.md

# CRM线索中心模块开发完成总结

## 开发日期
2026-05-19

## 项目信息
- **服务归属**: hzhub-system (端口 8083)
- **包路径**: org.hzhub.crm
- **技术栈**: Spring Boot 3.5.8 + MyBatis-Plus + Sa-Token

---

## 一、创建的文件列表

### 1. 数据库设计
- `/data/hzhub/hzhub-system/src/main/resources/db/crm_lead_init.sql`
  - 数据字典定义（5个字典类型）
  - crm_lead 表（线索表）
  - crm_lead_follow 表（跟进记录表）

### 2. Entity 实体类
- `/data/hzhub/hzhub-system/src/main/java/org/hzhub/crm/domain/CrmLead.java`
  - 继承 TenantEntity
  - 包含 customerCode 字段（ERP客户编码）
  - 使用 @TableLogic 逻辑删除
- `/data/hzhub/hzhub-system/src/main/java/org/hzhub/crm/domain/CrmLeadFollow.java`
  - 继承 TenantEntity

### 3. Bo 业务对象
- `/data/hzhub/hzhub-system/src/main/java/org/hzhub/crm/domain/bo/CrmLeadBo.java`
  - 继承 BaseEntity
  - 使用 @AutoMapper 注解
  - 包含 customerCode 字段
- `/data/hzhub/hzhub-system/src/main/java/org/hzhub/crm/domain/bo/CrmLeadFollowBo.java`

### 4. Vo 视图对象
- `/data/hzhub/hzhub-system/src/main/java/org/hzhub/crm/domain/vo/CrmLeadVo.java`
  - 使用 @Translation 字段翻译
  - mobile 字段使用 @Sensitive 脱敏
  - 包含 customerCode 字段
- `/data/hzhub/hzhub-system/src/main/java/org/hzhub/crm/domain/vo/CrmLeadFollowVo.java`

### 5. Mapper 接口
- `/data/hzhub/hzhub-system/src/main/java/org/hzhub/crm/mapper/CrmLeadMapper.java`
  - 继承 BaseMapperPlus
- `/data/hzhub/hzhub-system/src/main/java/org/hzhub/crm/mapper/CrmLeadFollowMapper.java`

### 6. Mapper XML 映射文件
- `/data/hzhub/hzhub-system/src/main/resources/mapper/crm/CrmLeadMapper.xml`
- `/data/hzhub/hzhub-system/src/main/resources/mapper/crm/CrmLeadFollowMapper.xml`

### 7. Service 接口与实现
- `/data/hzhub/hzhub-system/src/main/java/org/hzhub/crm/service/ICrmLeadService.java`
- `/data/hzhub/hzhub-system/src/main/java/org/hzhub/crm/service/ICrmLeadFollowService.java`
- `/data/hzhub/hzhub-system/src/main/java/org/hzhub/crm/service/impl/CrmLeadServiceImpl.java`
  - 实现列表查询、详情、新增、编辑、删除、分配、跟进记录查询、添加跟进
  - **关键逻辑**: 如果提供 customerCode，调用 ERP 服务拉取客户信息
- `/data/hzhub/hzhub-system/src/main/java/org/hzhub/crm/service/impl/CrmLeadFollowServiceImpl.java`

### 8. ERP 集成类
- `/data/hzhub/hzhub-system/src/main/java/org/hzhub/crm/service/ErpIntegrationService.java`
  - 封装对 hzhub-erp 的调用
  - 使用 RestTemplate 调用 http://localhost:8082/erp/dynamic/v1/customer/detail

### 9. Controller 控制器
- `/data/hzhub/hzhub-system/src/main/java/org/hzhub/crm/controller/CrmLeadController.java`
  - 遵循 API 契约接口定义
  - 无 @SaCheckPermission 注解（员工门户权限由 Gateway 控制）
  - 使用 @Log、@RepeatSubmit 注解
- `/data/hzhub/hzhub-system/src/main/java/org/hzhub/crm/controller/CrmLeadFollowController.java`

### 10. 配置类
- `/data/hzhub/hzhub-system/src/main/java/org/hzhub/system/config/RestTemplateConfig.java`
  - 配置 RestTemplate Bean
- `/data/hzhub/hzhub-system/src/main/resources/application.yml`
  - 添加 ERP 配置: erp.base-url

---

## 二、数据库表结构摘要

### crm_lead（线索表）
主要字段：
- **lead_id**: 主键（ASSIGN_ID）
- **customer_code**: ERP客户编码（varchar(100)，可选）
- **company_name**: 公司名称（必填）
- **contact_name**: 联系人（必填）
- **mobile**: 手机号（必填）
- **region_id**: 区域ID（关联 sys_dept）
- **source_type**: 来源类型（字典：crm_lead_source）
- **intent_level**: AI意向等级（字典：crm_intent_level）
- **ai_score**: AI评分（decimal(5,2)）
- **risk_level**: 风险等级（字典：crm_risk_level）
- **owner_user_id**: 负责人（关联 sys_user）
- **lead_status**: 状态（字典：crm_lead_status）
- **del_flag**: 删除标志（逻辑删除）

继承 TenantEntity 字段：
- tenant_id, create_dept, create_by, create_time, update_by, update_time

索引：
- idx_tenant_id, idx_customer_code, idx_mobile, idx_owner_user_id, idx_lead_status, idx_create_time

### crm_lead_follow（跟进记录表）
主要字段：
- **follow_id**: 主键
- **lead_id**: 线索ID（必填）
- **follow_type**: 跟进方式（字典：crm_follow_type）
- **content**: 跟进内容（必填）
- **ai_summary**: AI摘要
- **next_follow_time**: 下次跟进时间
- **follow_user_id**: 跟进人（关联 sys_user）
- **del_flag**: 删除标志

---

## 三、主要实现的接口功能

### 1. 线索列表查询 (GET /crm/lead/list)
- 支持多条件筛选：公司名称模糊、手机号、意向等级、负责人、customerCode等
- 使用 TableDataInfo 分页返回
- mobile 字段自动脱敏
- 字典字段自动翻译

### 2. 线索详情查询 (GET /crm/lead/{leadId})
- 返回线索详细信息
- 字段自动翻译（负责人姓名、区域名称、字典值等）

### 3. 新增线索 (POST /crm/lead)
- **关键逻辑**: 如果提供 customerCode，自动从 ERP 拉取客户信息填充
- 校验手机号唯一性
- 使用 @RepeatSubmit 防重复提交
- 记录操作日志

### 4. 编辑线索 (PUT /crm/lead)
- 校验线索存在性
- 校验手机号唯一性
- 记录操作日志

### 5. 删除线索 (DELETE /crm/lead/{leadIds})
- 支持批量删除（逻辑删除）
- 记录操作日志

### 6. 分配线索 (PUT /crm/lead/assign)
- 更新 owner_user_id
- 自动更新状态为 "following"

### 7. 获取跟进记录列表 (GET /crm/lead/follow/{leadId})
- 根据线索ID查询跟进记录
- 按创建时间倒序

### 8. 添加跟进记录 (POST /crm/lead/follow)
- 自动设置跟进人为当前用户
- 如果提供下次跟进时间，更新线索的 nextFollowTime
- 记录操作日志

---

## 四、ERP集成的实现方式

### 实现方式
使用 `RestTemplate` 调用 hzhub-erp 服务

### 配置
- **配置项**: `erp.base-url` (默认: http://localhost:8082)
- **配置类**: `RestTemplateConfig` (提供 RestTemplate Bean)

### 调用逻辑
```java
// CrmLeadServiceImpl.insertLead() 方法
if (StringUtils.isNotBlank(lead.getCustomerCode())) {
    // 调用 ERP 服务拉取客户详情
    Map<String, Object> customerDetail = erpIntegrationService
        .getCustomerDetail(lead.getCustomerCode());

    // 自动填充线索基础信息
    if (customerDetail != null) {
        lead.setCompanyName((String) customerDetail.get("customerName"));
        lead.setContactName((String) customerDetail.get("contactName"));
        lead.setMobile((String) customerDetail.get("phone"));
        // ... 其他字段
    }
}
```

### ERP接口
- `GET /erp/dynamic/v1/customer/detail?customerCode={code}`
- 返回客户信息（Map形式）

---

## 五、需要注意的配置项

### 1. 数据字典类型（需在数据库初始化）
- **crm_lead_source**: 线索来源（activity/referral/website/exhibition/wecom/erp/other）
- **crm_lead_status**: 线索状态（new/following/converted/invalid）
- **crm_intent_level**: AI意向等级（high/medium/low）
- **crm_risk_level**: 风险等级（high/medium/low）
- **crm_follow_type**: 跟进方式（phone/wecom/visit/email/other）

### 2. ERP配置（application.yml）
```yaml
erp:
  base-url: ${ERP_BASE_URL:http://localhost:8082}
```

可通过环境变量 `ERP_BASE_URL` 配置 ERP 服务地址。

### 3. SQL初始化顺序
执行 `/data/hzhub/hzhub-system/src/main/resources/db/crm_lead_init.sql`：
1. 先创建数据字典（sys_dict_type, sys_dict_data）
2. 再创建业务表（crm_lead, crm_lead_follow）

### 4. Gateway路由配置
需在 `hzhub-gateway/src/main/resources/application.yml` 中添加：
```yaml
spring:
  cloud:
    gateway:
      routes:
        - id: hzhub-crm
          uri: lb://hzhub-system
          predicates:
            - Path=/crm/**
          filters:
            - StripPrefix=1
```

---

## 六、后续待实现功能（第二阶段）

### 1. AI意向分析
- 调用 hzhub-ai 服务（`/ai/analyze/intent`）
- 自动生成 aiScore、intentLevel

### 2. AI跟进摘要生成
- 调用 hzhub-ai 服务（`/ai/summarize`）
- 自动生成 aiSummary

### 3. 线索转经销商 (POST /crm/lead/convert)
- 创建 crm_dealer 数据
- 迁移历史跟进记录
- 更新线索状态为 "converted"

---

## 七、关键特性总结

1. **多租户支持**: 所有实体类继承 TenantEntity，自动租户隔离
2. **ERP关联**: customerCode 字段关联 ERP 客户，自动拉取信息
3. **字段翻译**: 使用 @Translation 注解自动翻译字典值、用户名、部门名
4. **敏感字段脱敏**: mobile 字段列表查询时自动脱敏
5. **逻辑删除**: 使用 @TableLogic，删除时不物理删除
6. **员工门户适配**: 无 Sa-Token 权限注解，权限由 Gateway 控制
7. **防重复提交**: 新增操作使用 @RepeatSubmit
8. **操作日志**: 新增、编辑、删除使用 @Log 记录

---

## 开发完成
所有代码已创建完毕，可进行编译测试。