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 路由：

```yaml
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 实体类规范

### 基类继承

```java
@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 业务对象

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

    private Long leadId;

    // 业务字段...
}
```

### Vo 视图对象

```java
@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 接口规范

```java
@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`

**请求参数：**

```json
{
  "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`

**请求参数：**

```json
{
  "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`

**页面布局：**

```text
-------------------------------------------------
顶部：搜索栏 + 高级筛选（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）：

```text
┌────────────────────────┐
│ 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`

**返回内容：**

```json
{
  "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`

**页面布局：**

```text
顶部：基础信息卡片（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语音处理流程

```text
语音上传（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自动推进逻辑

**规则示例：**

```text
如果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）：**

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

**卡片展示：**

- 经销商名称
- 金额（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）

```text
销售提交
-> 区域经理审批（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异步同步：** 暂不集成（可选）

**实现：**

```java
@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`

**页面布局：**

```text
顶部：订单筛选（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模型

### 数据权限层级

```text
总部（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`

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

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

```typescript
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 模块菜单树：

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

```yaml
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 项目架构的一致性。