feat: 完成CRM商机和线索管理模块开发

## 新增功能 ### 商机中心 (/opportunity) - Stats统计卡片（商机总数、金额、赢单、转化率） - Pipeline商机管道（阶段Tab：全部/线索/谈判中/方案/赢单） - 商机列表真实数据渲染（来自crm_opportunity表） - 商机卡片详情（经销商、负责人、金额、概率） - Pipeline计数实时更新 ### 线索中心 (/lead) - 线索列表完整功能（CRUD） - 线索详情Drawer（基础信息 + 跟进记录Timeline） - 新建线索（含ERP客户关联、手机号验证） - 添加跟进记录（跟进方式、内容、下次时间） - 分配负责人（用户选择器，显示真实姓名） - 线索转经销商（自动创建商机） - 删除线索（逻辑删除） ## 后端开发 ### 数据库表 - crm_lead（线索表） - crm_lead_follow（线索跟进记录表） - crm_dealer（经销商表） - crm_opportunity（商机表） - crm_opportunity_follow（商机跟进记录表） - 数据字典初始化 ### API接口 - 线索管理：CRUD、详情、跟进、分配、转化 - 商机管理：列表查询 - 用户选择器：员工门户专用API ### 核心功能 - 线索转化自动创建经销商和商机 - 负责人翻译显示真实姓名（修复） - 手机号前后端双重格式验证（修复） ## 前端开发 ### 页面架构改进 - 商机中心：保留原CRM设计风格（Stats + Pipeline） - 线索中心：独立页面（完整线索管理） - 左侧菜单：独立菜单项（商机中心、线索中心） ### API模块 - src/api/crm/：线索和商机API类型定义和调用方法 - src/api/user/：用户选择器API ### 样式设计 - 商机中心：100%保持原CRM Pipeline设计风格 - 使用CSS变量系统（var(--radius-lg), var(--shadow-sm)等） - Pipeline Tab白色圆角设计 - 商机卡片阴影和hover效果 - 头像堆叠显示 ## 配置修改 - Gateway路由：添加CRM模块路由配置 - Gateway路由：添加system模块路由配置 - Aside菜单：拆分商机中心和线索中心 ## Bug修复 - 修复负责人显示手机号问题（UserNameTranslationImpl返回昵称） - 修复手机号格式验证缺失（前后端双重验证） - 修复商机管道设计风格不一致（完整复制原CRM样式） ## 文档 - CRM销售模块详细设计说明书V3.md - CRM线索转化API契约 - CRM线索转化开发计划 - CRM线索转化测试指引 - CRM线索管理测试指引 - CRM商机管理测试指引 - CRM架构改进报告 - CRM Bug修复报告 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-20 09:46:59 +00:00
parent 6ad14b07dc
commit 3f643ef31f
59 changed files with 11876 additions and 18 deletions
--- a/docs/CRM线索中心模块开发完成总结.md
+++ b/docs/CRM线索中心模块开发完成总结.md
@@ -0,0 +1,262 @@
+# 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 记录
+
+---
+
+## 开发完成
+所有代码已创建完毕，可进行编译测试。