unis_crm/docs/crm.md

# 紫光汇智 CRM 技术系统规划与技术文档

## 1. 文档定位

本文档面向研发、架构、测试、运维与交付团队，说明紫光汇智 CRM 系统的技术现状、目标架构、模块规划、关键设计原则、实施路线与交付边界。

文档目标如下：

- 为当前系统提供统一的技术说明基线
- 为后续迭代提供可落地的技术规划
- 为环境部署、模块扩展、接口治理和性能治理提供参考
- 为研发协作、测试设计和运维交接提供统一口径

本文档基于当前仓库代码、SQL 初始化脚本与现有项目文档整理，整理日期为 `2026-04-03`。

## 2. 系统概述

紫光汇智 CRM 是一个围绕销售过程管理建设的轻量 CRM 系统，当前主要覆盖以下业务域：

- 首页工作台聚合
- 销售拓展与渠道拓展
- 商机储备与推进
- 外勤打卡
- 销售日报
- 个人资料与账号安全

系统当前采用前后端分离模式：

- 前端：`frontend/`，基于 `Vite + React + TypeScript`
- 后端：`backend/`，基于 `Spring Boot + MyBatis Plus + PostgreSQL + Redis`
- 数据：通过 `sql/init_full_pg17.sql` 初始化业务表

## 3. 当前技术现状

### 3.1 前端现状

前端目录位于 `frontend/src/`，核心结构如下：

```text
frontend/src/
├── App.tsx
├── components/
├── hooks/
├── lib/
└── pages/
```

当前页面模块包括：

- `Login.tsx`：登录页
- `Dashboard.tsx`：首页工作台
- `Expansion.tsx`：销售拓展、渠道拓展
- `Opportunities.tsx`：商机管理
- `Work.tsx`：打卡、日报、历史记录
- `Profile.tsx`：个人中心

当前前端特点：

- 使用 `react-router-dom` 管理路由
- 通过 `lib/auth.ts` 封装统一 API 调用
- 已适配 PC 与移动端
- 页面交互完整，具备较强的可交付性
- 复杂页面采用单文件实现，后续存在进一步拆分空间

### 3.2 后端现状

后端目录位于 `backend/src/main/java/com/unis/crm/`，当前结构包括：

```text
backend/src/main/java/com/unis/crm/
├── common/
├── config/
├── controller/
├── dto/
├── mapper/
├── service/
└── service/impl/
```

当前已实现的控制器包括：

- `DashboardController`
- `ExpansionController`
- `OpportunityController`
- `WorkController`
- `ProfileController`
- `OpportunityIntegrationController`
- `WecomSsoController`

当前后端特点：

- 采用 Spring Boot 单体模式
- 基于 MyBatis Plus 组织数据访问
- DTO 分包清晰，按业务域拆分
- 已具备基础异常处理、统一响应和安全配置
- 业务仍集中在服务实现层，后续可继续增强领域边界和可测试性

### 3.3 数据层现状

当前项目已将业务初始化入口收敛为：

- `sql/init_full_pg17.sql`

脚本中已覆盖以下核心表：

- `crm_customer`
- `crm_opportunity`
- `crm_opportunity_followup`
- `crm_sales_expansion`
- `crm_channel_expansion`
- `crm_channel_expansion_contact`
- `crm_expansion_followup`
- `work_checkin`
- `work_daily_report`
- `work_daily_report_comment`
- `work_todo`
- `sys_activity_log`

当前数据层特点：

- 业务主表与过程表已较完整
- 初始化脚本已能作为统一部署入口
- 仍依赖基础平台表与基础数据
- 后续需继续收敛索引策略、归档策略和审计策略

## 4. 技术建设目标

未来技术建设建议围绕以下五个目标推进：

1. 稳定性目标：保证主链路功能可持续发布与回归验证。
2. 可维护性目标：降低单文件复杂度，提升模块边界清晰度。
3. 可扩展性目标：为后续客户管理、审批流、分析报表等能力预留扩展空间。
4. 可运维性目标：完善日志、监控、配置治理和部署标准。
5. 安全性目标：提升鉴权、配置、上传、接口访问和数据变更可控性。

## 5. 总体技术架构规划

建议系统继续保持“前后端分离 + 单体业务后端”的建设模式，在当前阶段不急于拆分微服务，以降低复杂度与运维成本。

推荐总体架构如下：

```mermaid
flowchart TD
  U["用户端<br/>PC / Mobile"] --> FE["前端应用<br/>React + Vite"]
  FE --> GW["应用接入层<br/>Nginx / HTTPS"]
  GW --> BE["CRM 后端单体服务<br/>Spring Boot"]
  BE --> PG["PostgreSQL"]
  BE --> RD["Redis"]
  BE --> BASE["基础平台能力<br/>用户/组织/参数/鉴权"]
  BE --> OMS["外部系统集成<br/>OMS / 其他业务系统"]
  BE --> FILE["文件存储目录<br/>上传附件 / 打卡照片"]
```

规划原则：

- 业务复杂度未达到微服务拆分必要性前，优先优化单体结构
- 前端优先按业务域拆分组件和状态
- 后端优先按业务模块做清晰分层，而不是过早做技术拆分
- 数据库优先保障一致性与查询性能
- 接口治理、日志治理、异常治理要优先于功能外延扩张

## 6. 模块规划

### 6.1 首页工作台模块

职责：

- 聚合展示欢迎语、统计指标、待办事项、最新动态
- 提供工作入口跳转

技术规划：

- 统计接口与待办接口继续保留聚合型接口风格
- 增加缓存策略，减少重复统计计算
- 动态与待办建议做统一事件源或统一日志源治理

### 6.2 拓展管理模块

职责：

- 管理销售拓展与渠道拓展主数据
- 支撑后续商机关联、日报关联和项目推进

技术规划：

- 拓展列表查询支持分页、筛选、导出、关键词搜索
- 跟进记录数据结构统一化
- 重复校验规则集中到服务层或领域规则层
- 前端表单组件逐步抽象，降低 `Expansion.tsx` 单文件复杂度

### 6.3 商机管理模块

职责：

- 管理商机主数据、推进阶段、竞争态势、售前协同和系统推送

技术规划：

- 商机状态机建议标准化
- 推送外部系统逻辑与本地业务保存逻辑解耦
- 推送记录、失败原因、重试机制单独建模
- 回写字段、自动跟进字段需进一步规范来源

### 6.4 工作管理模块

职责：

- 支撑打卡、日报、历史记录和过程数据留痕

技术规划：

- 打卡上传、定位、逆地理解析可进一步隔离为基础服务组件
- 日报行项目结构建议形成稳定 DTO 契约
- 历史记录建议增加分页游标和时间维度索引优化
- 主管点评能力后续可进一步显式建模为评审子域

### 6.5 个人中心模块

职责：

- 查看与修改个人资料
- 密码修改
- 展示个人月度工作概览

技术规划：

- 用户资料更新与基础平台用户数据同步策略需要明确
- 密码修改链路需与统一安全策略对齐

## 7. 分层设计规划

建议后端逐步收敛为以下分层：

### 7.1 Controller 层

职责：

- 接收 HTTP 请求
- 做基础参数校验
- 调用应用服务
- 返回统一响应体

约束：

- 不直接承载复杂业务规则
- 不直接拼接复杂数据库逻辑

### 7.2 Application Service 层

职责：

- 编排业务流程
- 协调多个领域对象、外部系统、事务边界
- 对接 Mapper/Repository

建议：

- 当前 `service/impl` 可逐步向“应用服务 + 领域服务”演进

### 7.3 Domain Rule 层

职责：

- 放置核心业务规则
- 例如：重复校验、状态切换、编辑权限判定、推送条件判断

建议：

- 先从复杂模块开始，例如商机推送、日报回写、拓展重复校验

### 7.4 Repository / Mapper 层

职责：

- 承接数据库查询和持久化
- 隔离 SQL 与业务逻辑

建议：

- 查询 SQL 与写入 SQL 适当拆分
- 对复杂列表查询建立专门 Mapper 方法，不在服务层拼装

## 8. 前端技术规划

### 8.1 路由与页面拆分

建议维持当前路由结构，但将复杂页面拆成子模块：

- `Expansion.tsx` 拆为列表区、表单区、详情区、导出逻辑
- `Opportunities.tsx` 拆为列表、详情、推送弹窗、编辑弹窗
- `Work.tsx` 拆为打卡面板、日报面板、历史面板、对象选择器

### 8.2 API 层治理

建议继续以 `lib/auth.ts` 作为 API 网关入口，但逐步按域拆文件：

- `api/dashboard.ts`
- `api/expansion.ts`
- `api/opportunity.ts`
- `api/work.ts`
- `api/profile.ts`

收益：

- 便于维护
- 更清晰的类型边界
- 更方便单元测试和 mock

### 8.3 组件规划

建议将高复用部分抽出：

- 弹窗容器
- 列表卡片
- 表单字段组件
- 状态标签组件
- 导出按钮组件
- 历史记录详情组件

### 8.4 前端质量治理

建议补齐以下内容：

- ESLint 与 Prettier 统一规范
- 类型检查纳入 CI
- 关键页面冒烟测试
- API mock 机制沉淀为正式脚本

## 9. 后端技术规划

### 9.1 单体后端演进路线

当前推荐继续使用单体服务，建议按模块增强而不是拆服务。

演进方向：

- 强化模块边界
- 减少跨模块直接访问
- 将外部系统集成收敛到独立适配层
- 增加服务层测试与接口测试

### 9.2 DTO 与接口契约

当前 DTO 已按业务域拆包，建议继续坚持：

- 输入 DTO 与输出 DTO 分离
- 复杂聚合返回专门建模
- 避免前端直接依赖数据库字段命名

### 9.3 事务与一致性

重点关注场景：

- 商机保存与外部系统推送
- 日报提交与商机回写
- 拓展编辑与关联信息刷新
- 打卡上传文件与数据库记录保存

建议：

- 本地事务和外部调用解耦
- 外部系统调用失败时保留本地状态与失败日志
- 对推送行为增加状态记录表或审计表

## 10. 数据库规划

### 10.1 设计原则

- 主表负责业务主状态
- 过程表负责轨迹沉淀
- 审计字段默认标准化
- 删除操作优先逻辑删除或状态化
- 高频查询字段提前建索引

### 10.2 索引规划建议

建议重点优化以下查询：

- 首页待办查询
- 首页动态查询
- 商机列表按负责人、阶段、归档状态查询
- 拓展列表按负责人、姓名、渠道名查询
- 打卡/日报历史按用户、日期倒序查询

### 10.3 归档与清理规划

建议对以下数据建立归档策略：

- 已签单商机
- 早期历史动态日志
- 历史打卡照片
- 大体量日报附件或冗余快照

## 11. 接口治理规划

### 11.1 接口规范

建议保持统一 API 风格：

- URL 使用业务域前缀
- GET 用于查询
- POST 用于新增或业务动作
- PUT 用于更新
- 统一返回结构 `code / msg / data`

### 11.2 错误处理

建议错误分层：

- 参数错误
- 业务规则错误
- 鉴权错误
- 外部系统错误
- 系统内部错误

并在日志中保留：

- traceId
- userId
- requestPath
- requestParams
- errorCode
- rootCause

### 11.3 版本治理

当前系统体量不大，可暂不引入 `/v1` 路径版本。

但建议提前约定：

- 外部开放接口预留版本化策略
- 集成接口变更必须同步更新文档
- 高风险字段变更必须保持向后兼容

## 12. 安全规划

### 12.1 鉴权

当前系统基于 JWT 鉴权，建议继续强化：

- Access Token 有效期控制
- Refresh Token 生命周期管理
- 登录失败次数控制
- 敏感操作二次确认

### 12.2 数据权限

建议明确至少三类权限边界：

- 仅本人可编辑
- 本部门可查看
- 管理员可全局查看

### 12.3 配置安全

建议将敏感配置从默认配置文件中进一步外置：

- 数据库密码
- Redis 密码
- JWT Secret
- 内部系统 Secret
- 外部系统 API Key

### 12.4 上传安全

打卡照片上传需重点关注：

- 文件类型限制
- 文件大小限制
- 文件名安全
- 存储目录隔离
- 访问权限控制

## 13. 日志、监控与可观测性规划

建议建立以下可观测能力：

### 13.1 日志

- 应用日志
- 接口访问日志
- 外部系统调用日志
- 业务动作日志
- 失败日志

### 13.2 监控指标

- 接口响应时间
- 错误率
- 慢 SQL
- PostgreSQL 连接数
- Redis 可用性
- 文件上传失败率
- 外部系统推送成功率

### 13.3 告警建议

- 登录异常激增
- 商机推送失败率异常
- 文件上传失败率异常
- 数据库连接异常
- 首页聚合接口超时

## 14. 测试规划

建议建立三层测试体系：

### 14.1 单元测试

覆盖重点：

- 业务规则判断
- 状态切换
- 参数转换
- 重复校验

### 14.2 接口测试

覆盖重点：

- 登录
- 首页接口
- 拓展新增/编辑
- 商机新增/编辑/推送
- 打卡与日报提交流程

### 14.3 前端冒烟测试

覆盖重点：

- 登录页
- 首页
- 拓展页
- 商机页
- 打卡页
- 日报页
- 个人中心页

## 15. 部署与环境规划

### 15.1 环境分层建议

建议至少分为：

- 本地开发环境
- 测试环境
- 预发布环境
- 生产环境

### 15.2 部署建议

前端建议：

- 使用 Nginx 托管静态资源
- 区分环境配置
- 启用 gzip 与缓存策略

后端建议：

- 使用独立配置文件或环境变量
- 使用进程守护或容器部署
- 按环境区分日志目录、上传目录和外部地址

数据库建议：

- 定期备份
- 版本化执行 SQL
- 升级前回滚预案

## 16. 迭代路线建议

### 第一阶段：稳态交付

目标：

- 完成现有主链路稳定交付
- 收敛环境配置
- 完成基础测试清单

建议事项：

- 修正高复杂度页面拆分
- 完善日志与异常信息
- 固化部署手册与回归手册

### 第二阶段：治理增强

目标：

- 增强可维护性与可观测性

建议事项：

- 引入 CI 检查
- 完成 API 分层拆分
- 增加推送日志和审计机制
- 增强权限模型

### 第三阶段：业务扩展

目标：

- 支撑更大规模的 CRM 业务演进

建议事项：

- 引入客户主档视图
- 引入审批/流程节点
- 引入经营分析与管理报表
- 引入更标准的数据字典中心

## 17. 当前主要技术风险

建议重点关注以下风险：

1. 前端复杂页面单文件过大，维护成本上升。
2. 外部系统集成失败场景的状态闭环仍需增强。
3. 当前配置文件中存在敏感参数，生产治理需加强。
4. 数据权限与角色权限模型还需要形成正式方案。
5. 自动化测试和持续集成能力仍有较大提升空间。

## 18. 技术文档交付建议

建议后续完整技术文档体系至少包括：

- 技术系统规划与技术文档
- 部署手册
- 数据库设计说明
- 接口文档
- 测试方案与回归清单
- 运维巡检与故障处理手册

## 19. 相关文件

- `docs/system-construction.md`
- `docs/business-schema-design.md`
- `docs/deployment-guide.md`
- `docs/opportunity-integration-api.md`
- `backend/README.md`
- `frontend/README.md`