641 lines
14 KiB
Markdown
641 lines
14 KiB
Markdown
# 紫光汇智 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`
|