kangwj
/
unis_crm
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
unis_crm/docs/crm.md

14 KiB
Raw Blame History

紫光汇智 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/，核心结构如下：

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/，当前结构包括：

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. 总体技术架构规划

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

推荐总体架构如下：

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