hzhub/docs/CRM销售模块详细设计说明书V2.md

CRM销售自动化（渠道版）执行级详细设计说明书 V2

1. 文档说明

1.1 文档目标

本文档用于指导HZHub项目中CRM销售自动化（渠道版）系统的：

• 数据库设计（适配 MySQL 8 + MyBatis-Plus）
• 后端接口开发（适配 hzhub-system 服务）
• 前端页面开发（适配 hzhub-admin Vben Admin）
• AI能力集成（适配 LangChain4j + Weaviate）
• 企业微信集成
• 自动化流程配置（适配 warm-flow）
• 权限与组织体系建设（适配 Sa-Token）

本文档属于"开发执行版设计文档 V2"，针对HZHub项目架构进行定制化适配。

---

1.2 与 V1 版本的主要差异

方面	V1 版本	V2 版本（HZHub 适配）
前端技术栈	Vue3 + Element Plus	Vben Admin + Ant Design Vue
后端框架	Java Spring Boot（通用）	Spring Boot 3.5.8 + MyBatis-Plus
API路径	/api/**	/crm/**（通过 Gateway 路由）
权限框架	JWT（自定义）	Sa-Token（已集成）
工作流引擎	Flowable	warm-flow 1.8.2（已集成）
AI服务	Python FastAPI	LangChain4j（Java）
向量数据库	未指定	Weaviate 1.25.0（已部署）
搜索引擎	Elasticsearch	暂不集成（可选）
消息队列	RabbitMQ	暂不集成（可选）
文件存储	MinIO	MinIO（已部署）
实体设计	通用字段规范	TenantEntity（多租户）

---

2. 系统总体架构

2.1 HZHub 集成架构

服务归属

CRM模块归属于 hzhub-system 服务（端口 8083），通过 Gateway 路由对外提供服务。

┌─────────────────────────────────────────┐
│   hzhub-admin (管理后台)                 │
│   Vue3 + Vben Admin + Ant Design Vue    │
│   Port: 5666                             │
└────────────┬────────────────────────────┘
             │
    ┌────────┴────────┐
    │  hzhub-gateway  │  (API Gateway, port 8080)
    │  Spring Cloud   │  JWT auth, routing
    └───┬──────┬──────┘
        │      │
    ┌───▼──────────┐
    │ hzhub-system │  CRM 模块归属服务
    │   8083       │  (Users, Roles, CRM)
    └─────────────┘

Gateway 路由配置

在 hzhub-gateway/src/main/resources/application.yml 中添加 CRM 路由：

spring:
  cloud:
    gateway:
      routes:
        # CRM 路由（新增）
        - id: hzhub-crm
          uri: lb://hzhub-system
          predicates:
            - Path=/crm/**
          filters:
            - StripPrefix=1  # 去除 /crm 前缀

注意： CRM 路由需要添加到现有路由列表中，位置在 hzhub-system 路由之后。

---

2.2 技术栈适配

层级	HZHub 技术栈	说明
前端Web	Vue3 + Vben Admin + Ant Design Vue	已在 hzhub-admin 中部署
移动端	企业微信H5 + UniApp	集成企业微信侧边栏
后端	Spring Boot 3.5.8 + MyBatis-Plus	hzhub-system 服务
数据库	MySQL 8.0	已部署
缓存	Redis 7	已部署，用于缓存与限流
向量数据库	Weaviate 1.25.0	已部署，用于知识检索
AI服务	LangChain4j + LangGraph4j	hzhub-ai 服务集成
文件存储	MinIO	已部署，用于合同/录音文件存储
工作流	warm-flow 1.8.2	已集成在 hzhub-system
权限	Sa-Token	已集成，JWT-based
BI	FineBI / Superset	可选（暂不集成）

---

3. 数据库设计规范（HZHub 适配）

3.1 通用字段规范

所有CRM业务表继承 TenantEntity，包含以下字段：

字段	类型	注解	说明
tenant_id	varchar(20)	无注解（继承）	租户ID（多租户）
create_dept	bigint	@TableField(fill = INSERT)	创建部门
create_by	bigint	@TableField(fill = INSERT)	创建人
create_time	datetime	@TableField(fill = INSERT)	创建时间
update_by	bigint	@TableField(fill = INSERT_UPDATE)	更新人
update_time	datetime	@TableField(fill = INSERT_UPDATE)	更新时间

注意： 不需要手动添加 id 字段，使用 MyBatis-Plus 的 @TableId 注解。

---

3.2 Entity 实体类规范

基类继承

@Data
@NoArgsConstructor
@EqualsAndHashCode(callSuper = true)
@TableName("crm_lead")
public class CrmLead extends TenantEntity {

    @TableId(value = "lead_id", type = IdType.ASSIGN_ID)
    private Long leadId;

    // 业务字段...

    /**
     * 删除标志（0代表存在 1代表删除）
     */
    @TableLogic
    private Integer delFlag;
}

Bo 业务对象

@Data
@NoArgsConstructor
@EqualsAndHashCode(callSuper = true)
@AutoMapper(target = CrmLead.class)
public class CrmLeadBo extends BaseEntity {

    private Long leadId;

    // 业务字段...
}

Vo 视图对象

@Data
@AutoMapper(target = CrmLead.class)
public class CrmLeadVo implements Serializable {

    @Serial
    private static final long serialVersionUID = 1L;

    private Long leadId;

    /**
     * 租户ID（翻译）
     */
    @Translation(type = TransConstant.TENANT_ID_TO_NAME, mapper = "tenantId")
    private String tenantId;

    /**
     * 创建人（翻译）
     */
    @Translation(type = TransConstant.USER_ID_TO_NAME, mapper = "createBy")
    private String createByName;

    // 业务字段...
}

---

3.3 Controller 接口规范

@Validated
@RequiredArgsConstructor
@RestController
@RequestMapping("/crm/lead")
public class CrmLeadController extends BaseController {

    private final ICrmLeadService leadService;

    /**
     * 获取线索列表
     */
    @SaCheckPermission("crm:lead:list")
    @GetMapping("/list")
    public TableDataInfo<CrmLeadVo> list(CrmLeadBo lead, PageQuery pageQuery) {
        return leadService.selectPageLeadList(lead, pageQuery);
    }

    /**
     * 新增线索
     */
    @Log(title = "线索管理", businessType = BusinessType.INSERT)
    @SaCheckPermission("crm:lead:add")
    @RepeatSubmit()
    @PostMapping()
    public R<Void> add(@Validated @RequestBody CrmLeadBo lead) {
        return R.ok(leadService.insertLead(lead));
    }
}

---

4. 线索中心模块设计

4.1 模块目标

用于管理潜在经销商，支持：

• 多渠道线索接入
• AI意向识别（LangChain4j）
• AI风险分析
• 自动分配销售
• 商机转化

---

4.2 数据表设计

4.2.1 crm_lead（线索表）

字段	类型	注解	说明
lead_id	bigint	@TableId(ASSIGN_ID)	主键
company_name	varchar(200)	-	公司名称
contact_name	varchar(100)	-	联系人
mobile	varchar(50)	-	手机号
wechat	varchar(100)	-	微信号
province	varchar(50)	-	省
city	varchar(50)	-	市
region_id	bigint	-	区域ID（关联 sys_dept）
source_type	varchar(50)	-	来源类型（字典：crm_lead_source）
activity_name	varchar(100)	-	活动名称
referrer_name	varchar(100)	-	推荐人
industry	varchar(100)	-	行业（字典：crm_industry）
company_scale	varchar(100)	-	公司规模（字典：crm_scale）
store_count	int	-	门店数
intent_level	varchar(20)	-	AI意向等级（字典：crm_intent_level）
ai_score	decimal(5,2)	-	AI评分
risk_level	varchar(20)	-	风险等级（字典：crm_risk_level）
owner_user_id	bigint	-	负责人（关联 sys_user）
lead_status	varchar(50)	-	状态（字典：crm_lead_status）
converted_dealer_id	bigint	-	转化经销商ID
del_flag	int	@TableLogic	删除标志

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

---

4.2.2 crm_lead_follow（线索跟进记录）

字段	类型	说明
follow_id	bigint	主键
lead_id	bigint	线索ID
follow_type	varchar(50)	跟进方式（字典：crm_follow_type）
content	text	跟进内容
ai_summary	text	AI摘要
next_follow_time	datetime	下次跟进时间
follow_user_id	bigint	跟进人（关联 sys_user）
del_flag	int	删除标志

---

4.3 接口设计

4.3.1 创建线索

API： POST /crm/lead

请求参数：

{
  "companyName": "XX贸易有限公司",
  "contactName": "张三",
  "mobile": "13800000000",
  "wechat": "zhangsan",
  "province": "广东省",
  "city": "深圳市",
  "industry": "食品",
  "storeCount": 20
}

业务逻辑：

1. 校验手机号是否重复（同租户内）
2. 调用 LangChain4j AI服务分析意向等级（hzhub-ai:6039/ai/analyze/intent）
3. 自动生成AI评分
4. 根据区域规则（sys_dept）分配销售（owner_user_id）
5. 创建自动跟进任务（warm-flow）

---

4.3.2 线索转经销商

API： POST /crm/lead/convert

请求参数：

{
  "leadId": 12345,
  "dealerName": "XX贸易",
  "dealerCode": "DL20260001"
}

逻辑：

1. 创建 crm_dealer 数据
2. 迁移历史跟进记录到 crm_dealer_follow
3. 创建初始商机（crm_opportunity）
4. 更新线索状态为"已转化"
5. 触发 warm-flow 工作流（经销商审批）

---

4.4 前端页面设计（Vben Admin）

4.4.1 线索列表页

路径： apps/web-antd/src/views/crm/lead/index.vue

页面布局：

-------------------------------------------------
顶部：搜索栏 + 高级筛选（Ant Design Form）
-------------------------------------------------
左侧：区域树（Ant Design Tree）
右侧：线索列表（Ant Design Table）
-------------------------------------------------
底部：分页（Ant Design Pagination）

筛选项：

• 区域（区域树选择）
• 来源（字典下拉：crm_lead_source）
• AI意向等级（字典下拉：crm_intent_level）
• 风险等级（字典下拉：crm_risk_level）
• 销售负责人（用户选择器）
• 创建时间（日期范围）

表格字段：

字段	Ant Design 组件
公司名称	Tag（高意向标红）
联系人	-
手机	脱敏展示
区域	翻译展示
AI评分	Progress（进度条）
意向等级	Badge（高/中/低）
风险等级	Tag（高风险标红）
当前负责人	Avatar（头像）
跟进状态	Badge
下次跟进时间	DatePicker

操作按钮：

• 查看（Drawer 侧边栏）
• 分配（Modal 弹窗）
• 跟进（Drawer）
• 转经销商（Modal）
• 作废（Popconfirm 确认）

---

4.4.2 AI分析侧边栏

右侧固定展示（Ant Design Drawer）：

┌────────────────────────┐
│ AI意向评分（Progress）  │
│ AI风险提示（Alert）     │
│ 推荐动作（Steps）       │
│ 推荐销售话术（Collapse）│
│ 推荐拜访时间（DatePicker）│
└────────────────────────┘

AI服务调用： 通过 Gateway 调用 hzhub-ai:6039/ai/chat/analyze

---

5. 经销商中心模块设计

5.1 数据表设计

5.1.1 crm_dealer（经销商表）

字段	类型	说明
dealer_id	bigint	主键
dealer_name	varchar(200)	经销商名称
dealer_code	varchar(100)	编码
contact_name	varchar(100)	联系人
mobile	varchar(50)	手机
province	varchar(50)	省
city	varchar(50)	市
level	varchar(50)	等级（字典：crm_dealer_level）
lifecycle	varchar(50)	生命周期（字典：crm_lifecycle）
signed_at	datetime	签约时间
store_count	int	门店数
team_size	int	团队规模
total_order_amount	decimal(18,2)	累计订单金额
total_payment_amount	decimal(18,2)	累计回款金额
activity_score	decimal(5,2)	活跃评分
risk_score	decimal(5,2)	飆险评分
owner_user_id	bigint	负责人（关联 sys_user）
del_flag	int	删除标志

---

5.1.2 crm_dealer_tag（经销商标签表）

字段	类型	说明
tag_id	bigint	主键
dealer_id	bigint	经销商ID
tag_name	varchar(100)	标签名称
tag_type	varchar(50)	标签类型（字典：crm_tag_type）
score	decimal(5,2)	标签评分
del_flag	int	删除标志

---

5.2 接口设计

5.2.1 获取经销商画像

API： GET /crm/dealer/{dealerId}/profile

返回内容：

{
  "code": 200,
  "data": {
    "dealerName": "XX贸易",
    "activityLevel": "高活跃",
    "riskLevel": "低风险",
    "growthTrend": "高增长",
    "lastVisitTime": "2026-05-10",
    "nextVisitTime": "2026-05-20",
    "aiRecommendActions": [
      "建议本周拜访",
      "关注库存周转"
    ]
  }
}

---

5.3 前端页面设计

5.3.1 经销商详情页

路径： apps/web-antd/src/views/crm/dealer/detail.vue

页面布局：

顶部：基础信息卡片（Ant Design Card）
-------------------------------------------------
Tab页（Ant Design Tabs）：
1. 基础档案（Descriptions）
2. 商机（Table + Kanban）
3. 拜访记录（Timeline）
4. 订单（Table）
5. 回款（Table）
6. AI画像（Progress + Chart）
7. 会话记录（Timeline）
-------------------------------------------------
右侧：AI经营分析面板（Affix 固定）

AI经营分析面板：

使用 Ant Design Charts 展示：

• 活跃度趋势（LineChart）
• 近90天订单趋势（AreaChart）
• 流失风险（Gauge）
• 推荐动作（Steps）
• 竞品风险（Alert）

---

6. 拜访管理模块设计

6.1 数据表设计

6.1.1 crm_visit_plan（拜访计划表）

字段	类型	说明
plan_id	bigint	主键
dealer_id	bigint	经销商ID
visit_type	varchar(50)	拜访类型（字典：crm_visit_type）
planned_time	datetime	计划时间
visit_user_id	bigint	销售人员（关联 sys_user）
status	varchar(50)	状态（字典：crm_visit_plan_status）
del_flag	int	删除标志

---

6.1.2 crm_visit_record（拜访记录表）

字段	类型	说明
record_id	bigint	主键
dealer_id	bigint	经销商ID
plan_id	bigint	拜访计划ID
visit_time	datetime	拜访时间
participants	varchar(500)	参与人员
voice_file_url	varchar(500)	录音文件（MinIO）
ai_summary	text	AI摘要
ai_requirements	text	AI提取需求
ai_risk	text	AI风险
next_action	text	下一步动作
latitude	decimal(10,6)	纬度
longitude	decimal(10,6)	经度
sign_photo_url	varchar(500)	签到照片（MinIO）
del_flag	int	删除标志

---

6.2 AI语音处理流程

语音上传（MinIO）
-> 调用 hzhub-ai:6039/ai/voice/transcribe
-> LangChain4j ASR识别
-> NLP结构化提取
-> AI摘要生成
-> 风险分析
-> 推荐下一步动作
-> 写入 CRM

技术栈： LangChain4j + OpenAI Whisper / 本地 ASR 模型

---

6.3 移动端页面设计

6.3.1 企业微信H5拜访页面

路径： hzhub-portal-employee/src/pages/crm/visit.vue（员工门户）

页面模块（Element Plus）：

• 地图签到（腾讯地图）
• 语音录入按钮（Recorder）
• 拍照上传（Upload）
• AI实时摘要（Card）
• 下一步动作建议（Steps）

AI辅助区域：

自动生成（调用 hzhub-ai）：

• 客户关注点（Tag）
• 异议问题（Alert）
• 竞品信息（Collapse）
• 推荐招商话术（Collapse）

---

7. 商机管理模块设计

7.1 数据表设计

7.1.1 crm_opportunity（商机表）

字段	类型	说明
opportunity_id	bigint	主键
dealer_id	bigint	经销商ID
opportunity_name	varchar(200)	商机名称
stage	varchar(50)	商机阶段（字典：crm_opportunity_stage）
estimated_amount	decimal(18,2)	预计金额
success_rate	decimal(5,2)	成交概率
expected_sign_date	date	预计签约时间
owner_user_id	bigint	销售负责人（关联 sys_user）
ai_next_stage	varchar(50)	AI建议阶段
ai_probability	decimal(5,2)	AI成交预测
del_flag	int	删除标志

---

7.1.2 crm_opportunity_stage_log（阶段日志表）

字段	类型	说明
log_id	bigint	主键
opportunity_id	bigint	商机ID
old_stage	varchar(50)	原阶段
new_stage	varchar(50)	新阶段
change_reason	text	变更原因
changed_by	bigint	变更人（关联 sys_user）
change_time	datetime	变更时间

---

7.2 商机阶段规则

阶段（字典：crm_opportunity_stage）	条件
初步接触	创建商机
需求沟通	已记录需求
招商政策沟通	已发送政策
样品测试	已寄样
商务谈判	已讨论返点
签约中	已提交合同
已签约	合同生效

---

7.3 AI自动推进逻辑

规则示例：

如果AI识别（LangChain4j分析会话记录）：
- 已询价
- 已谈返点
- 已谈库存

则自动建议推进至"商务谈判"阶段。

实现方式： 定时任务调用 hzhub-ai:6039/ai/opportunity/predict

---

7.4 前端页面设计

7.4.1 商机看板页

路径： apps/web-antd/src/views/crm/opportunity/kanban.vue

视图模式（Ant Design Segmented）：

• Kanban阶段看板
• 列表模式
• 销售漏斗模式

看板列（Ant Design Card）：

初步接触
需求沟通
招商政策沟通
样品测试
商务谈判
签约中
已签约

卡片展示：

• 经销商名称
• 金额（Statistic）
• AI成交概率（Progress）
• 最近跟进时间
• 风险提示（Tag）

---

8. 合同管理模块设计

8.1 数据表设计

8.1.1 crm_contract（合同表）

字段	类型	说明
contract_id	bigint	主键
contract_no	varchar(100)	合同编号
dealer_id	bigint	经销商ID
opportunity_id	bigint	商机ID
contract_amount	decimal(18,2)	合同金额
sign_date	date	签约日期
expire_date	date	到期日期
contract_status	varchar(50)	状态（字典：crm_contract_status）
approval_status	varchar(50)	审批状态（字典：crm_approval_status）
sign_file_url	varchar(500)	合同文件（MinIO）
ai_risk_summary	text	AI风险摘要
del_flag	int	删除标志

---

8.2 AI合同分析

AI识别（LangChain4j）：

• 高风险条款
• 超标准返点
• 区域冲突
• 超长账期

实现： 调用 hzhub-ai:6039/ai/contract/analyze

---

8.3 审批流设计（warm-flow）

销售提交
-> 区域经理审批（warm-flow节点）
-> 财务审批
-> 法务审批
-> 总部审批
-> 电子签章（可选）

实现：

1. 在 hzhub-system 中定义 warm-flow 流程定义（workflow_definition）
2. 合同提交触发流程实例（workflow_instance）
3. 审批节点与 sys_role 关联

---

9. 订单管理模块设计

9.1 数据表设计

9.1.1 crm_order（订单表）

字段	类型	说明
order_id	bigint	主键
order_no	varchar(100)	订单编号
dealer_id	bigint	经销商ID
contract_id	bigint	合同ID
order_amount	decimal(18,2)	订单金额
order_status	varchar(50)	订单状态（字典：crm_order_status）
shipment_status	varchar(50)	发货状态（字典：crm_shipment_status）
payment_status	varchar(50)	回款状态（字典：crm_payment_status）
logistics_status	varchar(50)	物流状态（字典：crm_logistics_status）
erp_sync_status	varchar(50)	ERP同步状态（字典：crm_erp_sync_status）
del_flag	int	删除标志

---

9.2 ERP同步逻辑

同步内容

• 订单数据（从 hzhub-erp:8082 拉取）
• 发货数据
• 库存数据
• 回款数据
• 物流数据

同步方式

1. 定时拉取： 使用 XXL-Job（hzhub-extend 中已集成）定时任务
2. Webhook回调： ERP 主动推送（可选）
3. MQ异步同步： 暂不集成（可选）

实现：

@Scheduled(cron = "0 0 2 * * ?")  // 每天凌晨2点
public void syncErpOrders() {
    // 调用 hzhub-erp:8082/erp/order/sync
    // 使用 dynamic-datasource 切换到 erp 数据源
}

---

9.3 前端页面设计

9.3.1 订单中心

路径： apps/web-antd/src/views/crm/order/index.vue

页面布局：

顶部：订单筛选（Form）
-------------------------------------------------
中部：订单表格（Table）
-------------------------------------------------
右侧：订单风险分析（Affix）

风险分析：

• 延迟发货风险（Alert）
• 超账期风险（Alert）
• 异常退货风险（Alert）

---

10. 回款管理模块设计

10.1 数据表设计

10.1.1 crm_payment（回款表）

字段	类型	说明
payment_id	bigint	主键
dealer_id	bigint	经销商ID
order_id	bigint	订单ID
payment_amount	decimal(18,2)	回款金额
payment_date	date	回款日期
receivable_due_date	date	应收截止日
overdue_days	int	超期天数
payment_status	varchar(50)	状态（字典：crm_payment_status）
del_flag	int	删除标志

---

10.2 AI预警规则

条件	预警	Redis 缓存键
超过30天未回款	高风险	crm:payment:risk:{dealer_id}
连续2次延迟	中风险	-
回款金额下降	流失风险	-

实现： 定时任务扫描 crm_payment 表，更新 Redis 缓存，前端实时查询。

---

11. 企业微信协同模块设计

11.1 集成能力

企业微信侧边栏

展示内容：

• 经销商画像（从 crm_dealer 查询）
• 最近订单（从 crm_order 查询）
• 最近拜访（从 crm_visit_record 查询）
• 商机阶段（从 crm_opportunity 查询）
• AI风险（Redis 缓存）

实现：

1. 企业微信应用配置（应用ID、Secret）
2. 后端接口：GET /crm/wecom/sidebar/{externalUserId}
3. 前端嵌入企业微信侧边栏（H5页面）

---

会话存档同步

同步内容：

• 文本
• 图片
• 文件
• 语音

数据表： crm_wecom_chat_record

字段	类型	说明
record_id	bigint	主键
external_user_id	varchar(100)	外部联系人
dealer_id	bigint	经销商ID
sender_id	bigint	发送人（关联 sys_user）
message_type	varchar(50)	消息类型
message_content	text	内容
send_time	datetime	发送时间
ai_analysis_result	text	AI分析结果
del_flag	int	删除标志

---

11.2 AI会话分析

识别内容：

• 采购意向
• 价格异议
• 投诉风险
• 竞品信息

实现： 调用 hzhub-ai:6039/ai/chat/analyze

---

12. AI分析中心设计

12.1 AI标签体系

标签类型（字典：crm_tag_type）	示例
活跃标签	高频沟通
风险标签	流失风险
经营标签	高增长
敏感标签	价格敏感

---

12.2 AI预测模型

模型	输入	调用服务
成交预测	商机数据	hzhub-ai:6039/ai/opportunity/predict
回款预测	订单与历史回款	hzhub-ai:6039/ai/payment/predict
流失预测	活跃度与订单	hzhub-ai:6039/ai/churn/predict
补货预测	销量趋势	hzhub-ai:6039/ai/replenish/predict

向量检索： 使用 Weaviate 存储历史案例，LangChain4j 进行相似度检索。

---

13. 自动化工作流设计

13.1 自动提醒规则

规则	动作	实现方式
7天未跟进	创建跟进提醒	XXL-Job 定时任务 + Redis 缓存
30天未下单	创建经营风险提醒	-
合同即将到期	通知销售与经理	-
回款超期	通知财务与销售	-

---

13.2 自动任务规则

条件	自动任务	warm-flow 流程
高意向线索	自动创建拜访	crm_auto_visit_flow
商机推进	自动创建回访	crm_auto_follow_flow
合同签约	自动创建首单跟进	crm_auto_order_flow

---

14. BI分析设计（可选）

14.1 BI指标体系

销售指标

• 销售额
• 回款率
• 转化率
• 客单价
• 区域增长率

AI经营指标

• 高风险经销商数
• 高潜经销商数
• AI成交预测准确率
• AI流失预测准确率

---

14.2 仪表盘设计（Ant Design Charts）

总部仪表盘

路径： apps/web-antd/src/views/crm/dashboard/index.vue

展示内容：

• 全国销售地图（ChinaMap）
• 区域排名（BarChart）
• 经销商增长趋势（LineChart）
• AI风险预警（Alert）
• 商机漏斗（FunnelChart）

---

销售个人仪表盘

展示内容：

• 今日待跟进（Statistic）
• 今日拜访（Statistic）
• 本月成交（Statistic）
• AI推荐客户（List）
• AI销售建议（Collapse）

---

15. 权限与组织设计（Sa-Token）

15.1 RBAC模型

数据权限层级

总部（sys_dept: root）
-> 大区（sys_dept: level 1）
-> 区域（sys_dept: level 2）
-> 城市（sys_dept: level 3）
-> 销售（sys_user）

实现： 使用 sys_dept 表的树形结构，通过 DataPermissionHelper 实现数据隔离。

---

15.2 权限控制点

模块	权限标识	Sa-Token 注解
线索	crm:lead:list, crm:lead:add, crm:lead:edit, crm:lead:remove	@SaCheckPermission
经销商	crm:dealer:list, crm:dealer:edit	-
合同	crm:contract:approve, crm:contract:amount-edit	-
回款	crm:payment:list, crm:payment:verify	-
BI	crm:bi:view（区域数据隔离）	-

菜单配置： 在 sys_menu 表中添加 CRM 模块菜单树。

---

16. 移动端设计

16.1 企业微信H5页面

归属项目： hzhub-portal-employee（员工门户，Element Plus）

必须支持：

• 快速拜访
• AI语音录入
• 地图签到（腾讯地图）
• 拍照上传（MinIO）
• 快速订单查询
• AI风险提醒

---

16.2 移动端交互要求

要求	说明	技术实现
单手操作	核心按钮底部固定	Element Plus Affix
弱网容错	本地缓存	IndexedDB / LocalStorage
快速录入	支持语音	Recorder + LangChain4j ASR
离线能力	支持草稿	IndexedDB

---

17. 性能与安全设计

17.1 性能目标

指标	目标	实现方式
页面响应	<2秒	Redis 缓存 + 分页查询
AI分析响应	<5秒	LangChain4j 异步调用
ERP同步延迟	<1分钟	XXL-Job 定时任务
并发支持	5000用户	Gateway 限流 + Redis 缓存

---

17.2 安全设计（HZHub 已有）

安全要求

• HTTPS加密（Gateway 配置）
• Sa-Token JWT鉴权（已集成）
• 数据权限隔离（TenantEntity + DataPermissionHelper）
• 敏感字段脱敏（@Sensitive 注解）
• 操作日志审计（@Log 注解）
• 企业微信身份校验（wecom_userid）

---

18. AI能力优先级实施建议

P0（第一阶段必须上线）

• 企业微信集成（侧边栏）
• 客户画像（基础字段）
• AI语音拜访（LangChain4j ASR）
• 会话分析（LangChain4j NLP）
• 订单查询（ERP同步）

---

P1（第二阶段）

• AI标签（LangChain4j + Weaviate）
• AI摘要（LangChain4j）
• AI意向识别
• 自动提醒（XXL-Job）

---

P2（第三阶段）

• AI Copilot（LangGraph4j）
• AI销售建议
• AI预测模型
• AI自动推进商机

---

19. 项目实施计划

第一阶段（1-2个月）

建设内容：

• 基础CRM（线索、经销商、商机）
• 企业微信侧边栏集成
• 拜访管理（移动端）
• warm-flow 审批流程
• 订单查询（ERP同步）

技术栈：

• 后端：Spring Boot + MyBatis-Plus + Sa-Token
• 前端：Vben Admin + Ant Design Vue
• 移动端：Element Plus + 企业微信H5
• 工作流：warm-flow

---

第二阶段（2-3个月）

建设内容：

• AI标签体系（Weaviate）
• AI会话分析（LangChain4j）
• AI语音拜访（ASR + NLP）
• 自动化工作流（XXL-Job）
• 合同管理

技术栈：

• AI：LangChain4j + hzhub-ai 服务
• 向量：Weaviate
• 定时任务：XXL-Job

---

第三阶段（3-4个月）

建设内容：

• AI预测模型（成交预测、流失预测）
• AI Copilot（LangGraph4j）
• AI经营分析面板
• 智能决策支持
• BI仪表盘

技术栈：

• AI：LangGraph4j + hzhub-ai 服务
• 图表：Ant Design Charts

---

20. 数据字典定义

20.1 线索相关字典

crm_lead_source（线索来源）

字典值	字典标签
activity	活动
referral	推荐
website	网站
exhibition	展会

crm_lead_status（线索状态）

字典值	字典标签
new	新线索
following	跟进中
converted	已转化
invalid	已作废

crm_intent_level（AI意向等级）

字典值	字典标签
high	高意向
medium	中意向
low	低意向

---

20.2 经销商相关字典

crm_dealer_level（经销商等级）

字典值	字典标签
A	A级经销商
B	B级经销商
C	C级经销商

crm_lifecycle（生命周期）

字典值	字典标签
active	活跃期
stable	稳定期
decline	衰退期
churn	流失期

---

20.3 商机相关字典

crm_opportunity_stage（商机阶段）

字典值	字典标签
initial_contact	初步接触
requirement	需求沟通
policy	招商政策沟通
sample	样品测试
negotiation	商务谈判
signing	签约中
signed	已签约

---

20.4 审批状态字典

crm_approval_status（审批状态）

字典值	字典标签
pending	待审批
approved	已审批
rejected	已拒绝

---

21. 最终产品定位

系统最终定位：

"AI驱动的渠道销售经营平台"

区别于传统CRM：

传统CRM：记录客户

本系统：

• AI驱动增长（LangChain4j + Weaviate）
• AI驱动招商（意向识别 + 风险分析）
• AI驱动销售动作（语音拜访 + 会话分析）
• AI驱动经营分析（预测模型 + Copilot）
• AI驱动渠道运营（自动化工作流）

---

22. 与 HZHub 项目的集成要点

22.1 Gateway 路由配置

位置： hzhub-gateway/src/main/resources/application.yml

spring:
  cloud:
    gateway:
      routes:
        # CRM 路由（添加到现有路由列表）
        - id: hzhub-crm
          uri: lb://hzhub-system
          predicates:
            - Path=/crm/**
          filters:
            - StripPrefix=1

---

22.2 hzhub-system 依赖

位置： hzhub-system/pom.xml

<dependencies>
    <!-- 已有依赖 -->
    <dependency>
        <groupId>org.hzhub</groupId>
        <artifactId>hzhub-common-core</artifactId>
    </dependency>

    <!-- 新增 CRM 依赖（可选） -->
    <dependency>
        <groupId>org.hzhub</groupId>
        <artifactId>hzhub-common-chat</artifactId>
        <version>${project.version}</version>
    </dependency>
</dependencies>

---

22.3 前端路由配置

位置： hzhub-admin/apps/web-antd/src/router/routes/modules/crm.ts

export default {
  path: '/crm',
  name: 'CRM',
  component: Layout,
  redirect: '/crm/dashboard',
  meta: {
    title: 'CRM管理',
    icon: 'ant-design:team-outlined',
  },
  children: [
    {
      path: 'dashboard',
      name: 'CrmDashboard',
      component: () => import('@/views/crm/dashboard/index.vue'),
      meta: { title: 'CRM仪表盘' },
    },
    {
      path: 'lead',
      name: 'CrmLead',
      component: () => import('@/views/crm/lead/index.vue'),
      meta: { title: '线索管理' },
    },
    // ...
  ],
};

---

22.4 菜单配置（sys_menu）

在 sys_menu 表中添加 CRM 模块菜单树：

-- CRM 模块根菜单
INSERT INTO sys_menu (menu_id, menu_name, parent_id, order_num, path, component, menu_type, visible, status, perms, icon, create_by, create_time)
VALUES (5000, 'CRM管理', 0, 5, '/crm', NULL, 'M', '0', '0', '', 'ant-design:team-outlined', 1, NOW());

-- 线索管理菜单
INSERT INTO sys_menu (menu_id, menu_name, parent_id, order_num, path, component, menu_type, visible, status, perms, icon, create_by, create_time)
VALUES (5001, '线索管理', 5000, 1, 'lead', 'crm/lead/index', 'C', '0', '0', 'crm:lead:list', 'ant-design:user-outlined', 1, NOW());

-- ... 其他菜单

---

23. 开发规范建议

23.1 包结构

hzhub-system/src/main/java/org/hzhub/
├── crm/
│   ├── controller/        # CRM 控制器
│   │   ├── CrmLeadController.java
│   │   ├── CrmDealerController.java
│   │   └── ...
│   ├── domain/            # 实体类
│   │   ├── CrmLead.java
│   │   ├── bo/
│   │   │   ├── CrmLeadBo.java
│   │   └── vo/
│   │   │   ├── CrmLeadVo.java
│   ├── service/           # 服务接口
│   │   ├── ICrmLeadService.java
│   │   └── impl/
│   │   │   ├── CrmLeadServiceImpl.java
│   └── mapper/            # MyBatis Mapper
│   │   ├── CrmLeadMapper.java

---

23.2 前端目录结构

hzhub-admin/apps/web-antd/src/
├── api/
│   └── crm/
│   │   ├── lead.ts        # 线索 API
│   │   ├── dealer.ts      # 经销商 API
│   │   └── types.ts       # 类型定义
├── views/
│   └── crm/
│   │   ├── dashboard/     # CRM 仪表盘
│   │   ├── lead/          # 线索管理
│   │   ├── dealer/        # 经销商管理
│   │   ├── opportunity/   # 商机管理
│   │   └── ...

---

24. 部署建议

24.1 Docker Compose 配置

CRM 模块不需要新增容器，使用现有 hzhub-system 容器。

位置： hzhub-deploy/docker-compose.yml

services:
  # 现有服务（无需修改）
  hzhub-system:
    build: ../hzhub-system
    container_name: hzhub-system
    ports:
      - "8083:8083"
    environment:
      - SPRING_PROFILES_ACTIVE=prod
    depends_on:
      - mysql
      - redis
    networks:
      - hzhub-network

---

24.2 数据库初始化

SQL 文件： hzhub-system/src/main/resources/db/crm_init.sql

包含：

• CRM 表结构（crm_lead, crm_dealer, ...）
• 数据字典（crm_lead_source, crm_opportunity_stage, ...）
• 菜单配置（sys_menu）

---

25. 后续优化方向

25.1 性能优化

• Redis 缓存经销商画像、AI评分
• Weaviate 向量检索优化（相似案例推荐）
• MyBatis-Plus 分页优化（避免全表扫描）

25.2 AI能力扩展

• LangGraph4j 集成（复杂 AI 工作流）
• 多模型支持（OpenAI、Claude、本地模型）
• AI Copilot 智能助手

25.3 移动端增强

• UniApp 跨平台支持（iOS/Android）
• 离线数据同步（IndexedDB）
• 企业微信深度集成

---

附录：技术栈对比表

功能模块	V1 版本技术栈	V2 版本（HZHub）技术栈	优势
前端框架	Vue3 + Element Plus	Vben Admin + Ant Design Vue	企业级UI，更丰富的组件
后端框架	Spring Boot（通用）	Spring Boot 3.5.8 + MyBatis-Plus	更强的ORM能力，多租户支持
权限框架	JWT（自定义）	Sa-Token	已集成，成熟稳定
工作流引擎	Flowable	warm-flow 1.8.2	已集成，轻量级
AI服务	Python FastAPI	LangChain4j（Java）	与后端同语言，更易集成
向量数据库	未指定	Weaviate 1.25.0	已部署，用于知识检索
文件存储	MinIO	MinIO（已部署）	无需额外部署
数据权限	自定义实现	TenantEntity + DataPermissionHelper	已有实现，支持多租户

---

总结

本文档将 CRM 销售自动化系统完全适配到 HZHub 项目架构中，充分利用项目已有的基础设施（Gateway、Sa-Token、warm-flow、MinIO、Weaviate、LangChain4j），避免重复开发，提高实施效率。

核心改动：

1. 服务归属：CRM 模块归属于 hzhub-system 服务
2. API路径：统一使用 /crm/**，通过 Gateway 路由
3. 数据模型：继承 TenantEntity，支持多租户与自动填充
4. 前端UI：使用 Vben Admin + Ant Design Vue
5. AI集成：调用 hzhub-ai 服务的 LangChain4j API
6. 权限控制：使用 Sa-Token + 数据权限隔离

后续实施时，严格按照本文档执行，确保与 HZHub 项目架构的一致性。