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)

调用逻辑

// 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）

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 中添加：

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 记录

---

开发完成

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