feat(ops): update cleaner status and assignment logic

2026-01-19 14:56:31 +08:00
parent 73bc3b299f
commit b71558ae07
169 changed files with 57972 additions and 162 deletions
--- a/.qoder/repowiki/zh/content/API接口文档/业务模块API/CRM客户关系管理API.md
+++ b/.qoder/repowiki/zh/content/API接口文档/业务模块API/CRM客户关系管理API.md
@@ -0,0 +1,626 @@
+# 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设计和详细的文档支持
+
+未来可以考虑的功能增强方向：
+- 集成更多第三方服务
+- 增强数据分析和报表功能
+- 优化移动端用户体验
+- 扩展自动化工作流能力