Files

lzh b71558ae07 feat(ops): update cleaner status and assignment logic

2026-01-19 14:56:31 +08:00

22 KiB

Raw Blame History

CRM客户关系管理API

**本文档引用的文件** - [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)

简介

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

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

项目结构

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

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

图表来源

章节来源

核心组件

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

1. 控制器层 (Controller Layer)

客户控制器: 处理客户相关的HTTP请求
商机控制器: 管理商机生命周期
合同控制器: 维护合同状态和流程
联系人控制器: 管理客户联系信息

2. 服务层 (Service Layer)

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

3. 数据访问层 (DAO Layer)

数据对象映射: 客户、商机、合同、联系人实体
数据库操作: 基于MyBatis的SQL映射
Redis缓存: 性能优化和热点数据缓存

4. 枚举和常量

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

章节来源

架构概览

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

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

图表来源

详细组件分析

客户管理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

章节来源

客户管理API序列图

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 : 客户创建流程完成

图表来源

商机管理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

商机管理流程图

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

合同管理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

回款管理集成

回款统计

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

到期提醒

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

章节来源

合同管理序列图

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 : 合同审批流程完成

图表来源

联系人管理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

联系人管理流程图

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

客户等级管理API

等级配置

等级枚举定义

A级客户: 重点客户，最高优先级
B级客户: 普通客户，标准服务
C级客户: 非优先客户，基础服务

等级应用

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

章节来源

CrmCustomerLevelEnum.java

权限控制机制

数据权限级别

权限枚举

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

权限验证流程

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

章节来源

CrmPermissionLevelEnum.java

依赖关系分析

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

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

图表来源

章节来源

性能考虑

缓存策略

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

数据库优化

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

异步处理

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

故障排除指南

常见错误类型

权限相关错误

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

参数验证错误

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

业务逻辑错误

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

调试建议

启用调试模式

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

常见问题排查

检查数据库连接状态
验证缓存服务可用性
确认外部服务接口连通性

章节来源

ApiConstants.java

结论

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

模块的主要优势包括：

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

未来可以考虑的功能增强方向：

集成更多第三方服务
增强数据分析和报表功能
优化移动端用户体验
扩展自动化工作流能力

22 KiB Raw Blame History Unescape Escape

CRM客户关系管理API

目录

简介

项目结构

核心组件

1. 控制器层 (Controller Layer)

2. 服务层 (Service Layer)

3. 数据访问层 (DAO Layer)

4. 枚举和常量

架构概览

详细组件分析

客户管理API

基础CRUD操作

高级功能

客户管理API序列图

商机管理API

商机生命周期管理

商机流程接口

商机管理流程图

合同管理API

合同生命周期管理

回款管理集成

合同管理序列图

联系人管理API

联系人维护

商机关联管理

联系人管理流程图

客户等级管理API

等级配置

权限控制机制

数据权限级别

依赖关系分析

性能考虑

缓存策略

数据库优化

异步处理

故障排除指南

常见错误类型

调试建议

结论

22 KiB

Raw Blame History