# CRM客户关系管理API

<cite>
**本文档引用的文件**
- [CrmCustomerController.java](file://viewsh-module-crm/viewsh-module-crm-server/src/main/java/com/viewsh/module/crm/controller/admin/customer/CrmCustomerController.java)
- [CrmBusinessController.java](file://viewsh-module-crm/viewsh-module-crm-server/src/main/java/com/viewsh/module/crm/controller/admin/business/CrmBusinessController.java)
- [CrmContractController.java](file://viewsh-module-crm/viewsh-module-crm-server/src/main/java/com/viewsh/module/crm/controller/admin/contract/CrmContractController.java)
- [CrmContactController.java](file://viewsh-module-crm/viewsh-module-crm-server/src/main/java/com/viewsh/module/crm/controller/admin/contact/CrmContactController.java)
- [CrmCustomerService.java](file://viewsh-module-crm/viewsh-module-crm-server/src/main/java/com/viewsh/module/crm/service/customer/CrmCustomerService.java)
- [CrmContractService.java](file://viewsh-module-crm/viewsh-module-crm-server/src/main/java/com/viewsh/module/crm/service/contract/CrmContractService.java)
- [CrmCustomerLevelEnum.java](file://viewsh-module-crm/viewsh-module-crm-api/src/main/java/com/viewsh/module/crm/enums/customer/CrmCustomerLevelEnum.java)
- [CrmPermissionLevelEnum.java](file://viewsh-module-crm/viewsh-module-crm-api/src/main/java/com/viewsh/module/crm/enums/permission/CrmPermissionLevelEnum.java)
- [ApiConstants.java](file://viewsh-module-crm/viewsh-module-crm-api/src/main/java/com/viewsh/module/crm/enums/ApiConstants.java)
- [CrmCustomerSaveReqVO.java](file://viewsh-module-crm/viewsh-module-crm-server/src/main/java/com/viewsh/module/crm/controller/admin/customer/vo/customer/CrmCustomerSaveReqVO.java)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概览](#架构概览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)

## 简介

本文件为AIOT平台云项目的CRM客户关系管理模块提供详细的API接口文档。该模块实现了完整的客户关系管理功能，包括客户管理、商机管理、合同管理、联系人管理等核心业务功能。

CRM模块采用Spring Boot微服务架构，通过RESTful API提供统一的服务接口。系统支持多租户、数据权限控制、操作日志记录等企业级特性。所有API接口均遵循统一的命名规范和响应格式，确保了系统的可维护性和扩展性。

## 项目结构

CRM模块在整体项目中的位置和组织结构如下：

```mermaid
graph TB
subgraph "AIOT平台云项目"
subgraph "视图科技框架层"
Framework[viewsh-framework]
end
subgraph "CRM模块"
CRM_API[viewsh-module-crm-api]
CRM_SERVER[viewsh-module-crm-server]
end
subgraph "其他模块"
SYSTEM[viewsh-module-system]
BPM[viewsh-module-bpm]
INFRA[viewsh-module-infra]
end
end
Framework --> CRM_API
Framework --> CRM_SERVER
CRM_SERVER --> SYSTEM
CRM_SERVER --> BPM
CRM_SERVER --> INFRA
```

**图表来源**
- [CrmCustomerController.java](file://viewsh-module-crm/viewsh-module-crm-server/src/main/java/com/viewsh/module/crm/controller/admin/customer/CrmCustomerController.java#L1-L50)
- [CrmBusinessController.java](file://viewsh-module-crm/viewsh-module-crm-server/src/main/java/com/viewsh/module/crm/controller/admin/business/CrmBusinessController.java#L1-L50)

**章节来源**
- [CrmCustomerController.java](file://viewsh-module-crm/viewsh-module-crm-server/src/main/java/com/viewsh/module/crm/controller/admin/customer/CrmCustomerController.java#L1-L50)
- [CrmBusinessController.java](file://viewsh-module-crm/viewsh-module-crm-server/src/main/java/com/viewsh/module/crm/controller/admin/business/CrmBusinessController.java#L1-L50)

## 核心组件

CRM模块由以下核心组件构成：

### 1. 控制器层 (Controller Layer)
- **客户控制器**: 处理客户相关的HTTP请求
- **商机控制器**: 管理商机生命周期
- **合同控制器**: 维护合同状态和流程
- **联系人控制器**: 管理客户联系信息

### 2. 服务层 (Service Layer)
- **客户管理服务**: 实现客户CRUD操作和业务逻辑
- **合同管理服务**: 处理合同创建、更新、审批流程
- **商机管理服务**: 管理商机状态转换和产品关联
- **联系人管理服务**: 维护联系人信息和业务关联

### 3. 数据访问层 (DAO Layer)
- **数据对象映射**: 客户、商机、合同、联系人实体
- **数据库操作**: 基于MyBatis的SQL映射
- **Redis缓存**: 性能优化和热点数据缓存

### 4. 枚举和常量
- **客户等级枚举**: 客户重要程度分类
- **权限级别枚举**: 数据访问权限控制
- **API常量**: 统一的API前缀和服务标识

**章节来源**
- [CrmCustomerService.java](file://viewsh-module-crm/viewsh-module-crm-server/src/main/java/com/viewsh/module/crm/service/customer/CrmCustomerService.java#L1-L50)
- [CrmContractService.java](file://viewsh-module-crm/viewsh-module-crm-server/src/main/java/com/viewsh/module/crm/service/contract/CrmContractService.java#L1-L50)

## 架构概览

CRM模块采用分层架构设计，确保关注点分离和代码复用：

```mermaid
graph TB
subgraph "表现层"
API[RESTful API]
VO[值对象]
end
subgraph "业务逻辑层"
Controller[控制器]
Service[服务接口]
BO[业务对象]
end
subgraph "数据访问层"
DAO[数据访问对象]
DO[数据对象]
Mapper[MyBatis映射器]
end
subgraph "基础设施层"
Redis[Redis缓存]
DB[(MySQL数据库)]
Log[操作日志]
Security[安全框架]
end
API --> Controller
Controller --> Service
Service --> BO
Service --> DAO
DAO --> Mapper
Mapper --> DB
Service --> Redis
Controller --> VO
Service --> Log
Controller --> Security
```

**图表来源**
- [CrmCustomerController.java](file://viewsh-module-crm/viewsh-module-crm-server/src/main/java/com/viewsh/module/crm/controller/admin/customer/CrmCustomerController.java#L50-L100)
- [CrmBusinessController.java](file://viewsh-module-crm/viewsh-module-crm-server/src/main/java/com/viewsh/module/crm/controller/admin/business/CrmBusinessController.java#L50-L100)

## 详细组件分析

### 客户管理API

#### 基础CRUD操作

**创建客户**
- **URL**: `POST /crm/customer/create`
- **权限**: `crm:customer:create`
- **功能**: 创建新的客户记录，支持批量导入
- **参数**: 客户基本信息（名称、联系方式、地址等）
- **响应**: 客户ID

**更新客户**
- **URL**: `PUT /crm/customer/update`
- **权限**: `crm:customer:update`
- **功能**: 修改现有客户信息
- **参数**: 客户更新信息
- **响应**: 操作成功标志

**删除客户**
- **URL**: `DELETE /crm/customer/delete?id={id}`
- **权限**: `crm:customer:delete`
- **功能**: 删除指定客户记录
- **参数**: 客户ID
- **响应**: 操作成功标志

**获取客户详情**
- **URL**: `GET /crm/customer/get?id={id}`
- **权限**: `crm:customer:query`
- **功能**: 获取单个客户完整信息
- **参数**: 客户ID
- **响应**: 客户详情VO

**分页查询客户**
- **URL**: `GET /crm/customer/page`
- **权限**: `crm:customer:query`
- **功能**: 支持条件筛选的客户分页查询
- **参数**: 分页参数和查询条件
- **响应**: 客户分页结果

#### 高级功能

**客户转移**
- **URL**: `PUT /crm/customer/transfer`
- **权限**: `crm:customer:update`
- **功能**: 将客户从一个负责人转移到另一个负责人
- **参数**: 转移请求信息
- **响应**: 操作成功标志

**客户锁定/解锁**
- **URL**: `PUT /crm/customer/lock`
- **权限**: `crm:customer:update`
- **功能**: 锁定或解锁客户，防止被其他用户操作
- **参数**: 锁定请求信息
- **响应**: 操作成功标志

**公海管理**
- **放入公海**: `PUT /crm/customer/put-pool?id={id}`
- **领取公海客户**: `PUT /crm/customer/receive`
- **分配公海客户**: `PUT /crm/customer/distribute`
- **权限**: `crm:customer:update`、`crm:customer:receive`、`crm:customer:distribute`

**数据导入导出**
- **导入模板**: `GET /crm/customer/get-import-template`
- **批量导入**: `POST /crm/customer/import`
- **导出Excel**: `GET /crm/customer/export-excel`

**统计查询**
- **待进入公海客户**: `GET /crm/customer/put-pool-remind-page`
- **今日需联系客户**: `GET /crm/customer/today-contact-count`
- **待跟进客户**: `GET /crm/customer/follow-count`

**章节来源**
- [CrmCustomerController.java](file://viewsh-module-crm/viewsh-module-crm-server/src/main/java/com/viewsh/module/crm/controller/admin/customer/CrmCustomerController.java#L65-L317)
- [CrmCustomerService.java](file://viewsh-module-crm/viewsh-module-crm-server/src/main/java/com/viewsh/module/crm/service/customer/CrmCustomerService.java#L21-L199)

#### 客户管理API序列图

```mermaid
sequenceDiagram
participant Client as 客户端
participant Controller as 客户控制器
participant Service as 客户服务
participant DB as 数据库
participant Cache as 缓存
Client->>Controller : POST /crm/customer/create
Controller->>Controller : 参数验证
Controller->>Service : createCustomer()
Service->>DB : 插入客户记录
DB-->>Service : 返回客户ID
Service->>Cache : 更新缓存
Cache-->>Service : 缓存成功
Service-->>Controller : 客户ID
Controller-->>Client : 成功响应
Note over Client,DB : 客户创建流程完成
```

**图表来源**
- [CrmCustomerController.java](file://viewsh-module-crm/viewsh-module-crm-server/src/main/java/com/viewsh/module/crm/controller/admin/customer/CrmCustomerController.java#L65-L70)
- [CrmCustomerService.java](file://viewsh-module-crm/viewsh-module-crm-server/src/main/java/com/viewsh/module/crm/service/customer/CrmCustomerService.java#L30-L31)

### 商机管理API

#### 商机生命周期管理

**创建商机**
- **URL**: `POST /crm/business/create`
- **权限**: `crm:business:create`
- **功能**: 建立新的商业机会
- **参数**: 商机基本信息和产品明细
- **响应**: 商机ID

**更新商机状态**
- **URL**: `PUT /crm/business/update-status`
- **权限**: `crm:business:update`
- **功能**: 更新商机所处阶段或状态
- **参数**: 状态更新信息
- **响应**: 操作成功标志

**商机转移**
- **URL**: `PUT /crm/business/transfer`
- **权限**: `crm:business:update`
- **功能**: 调整商机负责人
- **参数**: 转移请求信息
- **响应**: 操作成功标志

**分页查询**
- **按客户查询**: `GET /crm/business/page-by-customer`
- **按联系人查询**: `GET /crm/business/page-by-contact`
- **权限**: `crm:business:query`

#### 商机流程接口

**商机状态管理**
- **状态类型**: 支持自定义状态类型配置
- **状态转换**: 基于业务规则的状态流转
- **状态统计**: 不同状态下商机数量统计

**产品关联**
- **产品明细**: 支持多个产品的关联
- **价格计算**: 基于产品单价和数量计算总价
- **库存检查**: 自动检查产品可用库存

**章节来源**
- [CrmBusinessController.java](file://viewsh-module-crm/viewsh-module-crm-server/src/main/java/com/viewsh/module/crm/controller/admin/business/CrmBusinessController.java#L72-L223)

#### 商机管理流程图

```mermaid
flowchart TD
Start([商机创建]) --> Init[初始化商机信息]
Init --> Validate[验证输入参数]
Validate --> Valid{参数有效?}
Valid --> |否| Error[返回错误信息]
Valid --> |是| Save[保存商机记录]
Save --> Status[设置初始状态]
Status --> Notify[通知相关人员]
Notify --> End([流程结束])
Error --> End
subgraph "状态流转"
New[新建] --> Negotiation[谈判中]
Negotiation --> Won[赢单]
Negotiation --> Lost[输单]
end
```

**图表来源**
- [CrmBusinessController.java](file://viewsh-module-crm/viewsh-module-crm-server/src/main/java/com/viewsh/module/crm/controller/admin/business/CrmBusinessController.java#L72-L93)

### 合同管理API

#### 合同生命周期管理

**创建合同**
- **URL**: `POST /crm/contract/create`
- **权限**: `crm:contract:create`
- **功能**: 基于商机生成正式合同
- **参数**: 合同基本信息和产品明细
- **响应**: 合同ID

**合同审批**
- **发起审批**: `PUT /crm/contract/submit?id={id}`
- **权限**: `crm:contract:update`
- **功能**: 触发BPM审批流程
- **响应**: 操作成功标志

**合同转移**
- **URL**: `PUT /crm/contract/transfer`
- **权限**: `crm:contract:update`
- **功能**: 调整合同负责人
- **参数**: 转移请求信息
- **响应**: 操作成功标志

**分页查询**
- **按客户查询**: `GET /crm/contract/page-by-customer`
- **按商机查询**: `GET /crm/contract/page-by-business`
- **权限**: `crm:contract:query`

#### 回款管理集成

**回款统计**
- **已回款金额**: 自动计算合同已回收款项
- **未回款金额**: 总金额减去已回款
- **回款计划**: 支持分期回款计划管理

**到期提醒**
- **即将到期**: 基于合同到期日期的提醒
- **逾期管理**: 超过期限的合同跟踪

**章节来源**
- [CrmContractController.java](file://viewsh-module-crm/viewsh-module-crm-server/src/main/java/com/viewsh/module/crm/controller/admin/contract/CrmContractController.java#L81-L257)
- [CrmContractService.java](file://viewsh-module-crm/viewsh-module-crm-server/src/main/java/com/viewsh/module/crm/service/contract/CrmContractService.java#L25-L206)

#### 合同管理序列图

```mermaid
sequenceDiagram
participant Client as 客户端
participant Controller as 合同控制器
participant Service as 合同服务
participant BPM as BPM引擎
participant DB as 数据库
participant Receivable as 回款服务
Client->>Controller : POST /crm/contract/create
Controller->>Service : createContract()
Service->>DB : 保存合同记录
DB-->>Service : 合同ID
Service-->>Controller : 合同ID
Controller-->>Client : 合同ID
Client->>Controller : PUT /crm/contract/submit
Controller->>Service : submitContract()
Service->>BPM : 发起审批流程
BPM-->>Service : 流程实例ID
Service->>DB : 更新审批状态
Service-->>Controller : 完成
Controller-->>Client : 成功响应
Note over Client,DB : 合同审批流程完成
```

**图表来源**
- [CrmContractController.java](file://viewsh-module-crm/viewsh-module-crm-server/src/main/java/com/viewsh/module/crm/controller/admin/contract/CrmContractController.java#L174-L180)
- [CrmContractService.java](file://viewsh-module-crm/viewsh-module-crm-server/src/main/java/com/viewsh/module/crm/service/contract/CrmContractService.java#L73-L82)

### 联系人管理API

#### 联系人维护

**创建联系人**
- **URL**: `POST /crm/contact/create`
- **权限**: `crm:contact:create`
- **功能**: 为客户提供联系人信息
- **参数**: 联系人基本信息
- **响应**: 联系人ID

**更新联系人**
- **URL**: `PUT /crm/contact/update`
- **权限**: `crm:contact:update`
- **功能**: 修改联系人信息
- **参数**: 更新后的联系人信息
- **响应**: 操作成功标志

**删除联系人**
- **URL**: `DELETE /crm/contact/delete?id={id}`
- **权限**: `crm:contact:delete`
- **功能**: 移除联系人记录
- **参数**: 联系人ID
- **响应**: 操作成功标志

**分页查询**
- **按客户查询**: `GET /crm/contact/page-by-customer`
- **按商机查询**: `GET /crm/contact/page-by-business`
- **权限**: `crm:contact:query`

#### 商机关联管理

**建立关联**
- **URL**: `POST /crm/contact/create-business-list`
- **权限**: `crm:contact:create-business`
- **功能**: 将联系人与商机建立关联关系
- **参数**: 关联信息
- **响应**: 操作成功标志

**解除关联**
- **URL**: `DELETE /crm/contact/delete-business-list`
- **权限**: `crm:contact:delete-business`
- **功能**: 移除联系人与商机的关联
- **参数**: 解关联信息
- **响应**: 操作成功标志

**章节来源**
- [CrmContactController.java](file://viewsh-module-crm/viewsh-module-crm-server/src/main/java/com/viewsh/module/crm/controller/admin/contact/CrmContactController.java#L67-L227)

#### 联系人管理流程图

```mermaid
flowchart TD
Create[创建联系人] --> Verify[验证联系信息]
Verify --> Valid{信息有效?}
Valid --> |否| Error[返回验证错误]
Valid --> |是| Save[保存到数据库]
Save --> Customer[关联客户]
Customer --> Business[关联商机]
Business --> Complete[完成]
subgraph "信息验证"
Phone[手机号验证]
Email[邮箱格式验证]
Required[必填字段检查]
end
Verify --> Phone
Verify --> Email
Verify --> Required
```

**图表来源**
- [CrmContactController.java](file://viewsh-module-crm/viewsh-module-crm-server/src/main/java/com/viewsh/module/crm/controller/admin/contact/CrmContactController.java#L67-L98)

### 客户等级管理API

#### 等级配置

**等级枚举定义**
- **A级客户**: 重点客户，最高优先级
- **B级客户**: 普通客户，标准服务
- **C级客户**: 非优先客户，基础服务

**等级应用**
- **服务优先级**: 影响客户服务响应时间
- **资源分配**: 决定客户经理分配策略
- **营销活动**: 基于等级的差异化营销

**章节来源**
- [CrmCustomerLevelEnum.java](file://viewsh-module-crm/viewsh-module-crm-api/src/main/java/com/viewsh/module/crm/enums/customer/CrmCustomerLevelEnum.java#L16-L38)

### 权限控制机制

#### 数据权限级别

**权限枚举**
- **负责人 (OWNER)**: 完全控制权，可读写删改
- **读写 (WRITE)**: 可读写，不可删除
- **只读 (READ)**: 仅可查看

**权限验证流程**
```mermaid
flowchart TD
Request[API请求] --> Get[获取用户信息]
Get --> Check[检查数据权限]
Check --> Level{权限级别}
Level --> |OWNER| Allow[允许操作]
Level --> |WRITE| WriteOnly[仅写操作]
Level --> |READ| Deny[拒绝访问]
Allow --> Process[处理业务逻辑]
WriteOnly --> Process
Deny --> Error[返回权限错误]
Process --> Response[返回响应]
```

**图表来源**
- [CrmPermissionLevelEnum.java](file://viewsh-module-crm/viewsh-module-crm-api/src/main/java/com/viewsh/module/crm/enums/permission/CrmPermissionLevelEnum.java#L20-L60)

**章节来源**
- [CrmPermissionLevelEnum.java](file://viewsh-module-crm/viewsh-module-crm-api/src/main/java/com/viewsh/module/crm/enums/permission/CrmPermissionLevelEnum.java#L18-L60)

## 依赖关系分析

CRM模块的内部依赖关系如下：

```mermaid
graph TB
subgraph "控制器层"
CustomerController[客户控制器]
BusinessController[商机控制器]
ContractController[合同控制器]
ContactController[联系人控制器]
end
subgraph "服务层"
CustomerService[客户服务]
BusinessService[商机服务]
ContractService[合同服务]
ContactService[联系人服务]
end
subgraph "数据访问层"
CustomerDAO[客户DAO]
BusinessDAO[商机DAO]
ContractDAO[合同DAO]
ContactDAO[联系人DAO]
end
subgraph "外部服务"
SystemAPI[系统服务API]
BPMService[BPM服务]
ExcelService[Excel服务]
end
CustomerController --> CustomerService
BusinessController --> BusinessService
ContractController --> ContractService
ContactController --> ContactService
CustomerService --> CustomerDAO
BusinessService --> BusinessDAO
ContractService --> ContractDAO
ContactService --> ContactDAO
CustomerService --> SystemAPI
BusinessService --> SystemAPI
ContractService --> SystemAPI
ContactService --> SystemAPI
ContractService --> BPMService
CustomerController --> ExcelService
BusinessController --> ExcelService
ContractController --> ExcelService
ContactController --> ExcelService
```

**图表来源**
- [CrmCustomerController.java](file://viewsh-module-crm/viewsh-module-crm-server/src/main/java/com/viewsh/module/crm/controller/admin/customer/CrmCustomerController.java#L55-L64)
- [CrmBusinessController.java](file://viewsh-module-crm/viewsh-module-crm-server/src/main/java/com/viewsh/module/crm/controller/admin/business/CrmBusinessController.java#L56-L71)

**章节来源**
- [CrmCustomerController.java](file://viewsh-module-crm/viewsh-module-crm-server/src/main/java/com/viewsh/module/crm/controller/admin/customer/CrmCustomerController.java#L1-L50)
- [CrmBusinessController.java](file://viewsh-module-crm/viewsh-module-crm-server/src/main/java/com/viewsh/module/crm/controller/admin/business/CrmBusinessController.java#L1-L50)

## 性能考虑

### 缓存策略
- **热点数据缓存**: 客户等级、状态类型等静态配置
- **查询结果缓存**: 常用查询结果的短期缓存
- **分布式缓存**: Redis集群支持高并发访问

### 数据库优化
- **索引优化**: 关键查询字段建立适当索引
- **分页查询**: 大数据量场景使用分页避免全表扫描
- **批量操作**: 支持批量导入导出提升效率

### 异步处理
- **报表生成**: 大数据量导出采用异步任务
- **通知推送**: 重要事件通过消息队列异步通知
- **数据同步**: 跨模块数据变更采用事件驱动

## 故障排除指南

### 常见错误类型

**权限相关错误**
- **错误码**: 403 Forbidden
- **原因**: 用户缺少相应权限
- **解决方案**: 检查用户权限配置和角色分配

**参数验证错误**
- **错误码**: 400 Bad Request
- **原因**: 请求参数不符合业务规则
- **解决方案**: 检查参数格式和必填字段

**业务逻辑错误**
- **错误码**: 500 Internal Server Error
- **原因**: 业务规则违反或数据不一致
- **解决方案**: 查看系统日志定位具体问题

### 调试建议

**启用调试模式**
- 在application.yaml中设置日志级别
- 使用API客户端工具进行测试
- 监控系统性能指标

**常见问题排查**
- 检查数据库连接状态
- 验证缓存服务可用性
- 确认外部服务接口连通性

**章节来源**
- [ApiConstants.java](file://viewsh-module-crm/viewsh-module-crm-api/src/main/java/com/viewsh/module/crm/enums/ApiConstants.java#L10-L24)

## 结论

CRM客户关系管理模块提供了完整的企业级客户关系管理解决方案。通过清晰的分层架构、完善的权限控制和丰富的业务功能，该模块能够满足不同规模企业的客户管理需求。

模块的主要优势包括：
- **功能完整性**: 覆盖客户关系管理的全生命周期
- **扩展性强**: 基于接口的设计便于功能扩展
- **安全性高**: 多层次权限控制和数据保护
- **易用性好**: 统一的API设计和详细的文档支持

未来可以考虑的功能增强方向：
- 集成更多第三方服务
- 增强数据分析和报表功能
- 优化移动端用户体验
- 扩展自动化工作流能力