# 整体架构模式

<cite>
**本文引用的文件**   
- [pom.xml](file://pom.xml)
- [CrmAppApplication.java](file://crm-app/src/main/java/com/crm/app/CrmAppApplication.java)
- [application.yml](file://crm-app/src/main/resources/application.yml)
- [AuthApplication.java](file://crm-auth/src/main/java/com/crm/auth/AuthApplication.java)
- [application.yml](file://crm-auth/src/main/resources/application.yml)
- [SecurityConfig.java](file://crm-auth/src/main/java/com/crm/auth/config/SecurityConfig.java)
- [PermissionConfig.java](file://crm-auth/src/main/java/com/crm/auth/config/PermissionConfig.java)
- [DataInitializer.java](file://crm-auth/src/main/java/com/crm/auth/config/DataInitializer.java)
- [AuthController.java](file://crm-auth/src/main/java/com/crm/auth/controller/AuthController.java)
- [SystemController.java](file://crm-auth/src/main/java/com/crm/auth/controller/SystemController.java)
- [TokenService.java](file://crm-auth/src/main/java/com/crm/auth/security/TokenService.java)
- [JwtAuthenticationFilter.java](file://crm-auth/src/main/java/com/crm/auth/security/JwtAuthenticationFilter.java)
- [AuthService.java](file://crm-auth/src/main/java/com/crm/auth/service/IAuthService.java)
- [AuthServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/AuthServiceImpl.java)
- [ThirdPartyAuthClientFactory.java](file://crm-auth/src/main/java/com/crm/auth/service/client/ThirdPartyAuthClientFactory.java)
- [DingTalkAuthClient.java](file://crm-auth/src/main/java/com/crm/auth/service/client/DingTalkAuthClient.java)
- [BaseServiceImpl.java](file://crm-base/src/main/java/com/crm/base/service/impl/BaseServiceImpl.java)
- [MybatisPlusConfig.java](file://crm-base/src/main/java/com/crm/base/config/MybatisPlusConfig.java)
- [RedisConfig.java](file://crm-base/src/main/java/com/crm/base/config/RedisConfig.java)
- [JacksonConfig.java](file://crm-base/src/main/java/com/crm/base/config/JacksonConfig.java)
- [GlobalExceptionHandlerAdvice.java](file://crm-base/src/main/java/com/crm/base/advice/GlobalExceptionHandlerAdvice.java)
- [TraceIdFilter.java](file://crm-base/src/main/java/com/crm/base/filter/TraceIdFilter.java)
- [SnowflakeIdWorker.java](file://crm-base/src/main/java/com/crm/base/config/SnowflakeIdWorker.java)
- [FileApi.java](file://crm-file/src/main/java/com/crm/file/api/FileApi.java)
- [FileController.java](file://crm-file/src/main/java/com/crm/file/controller/FileController.java)
- [FileInfoServiceImpl.java](file://crm-file/src/main/java/com/crm/file/service/impl/FileInfoServiceImpl.java)
- [KkFileViewClient.java](file://crm-file/src/main/java/com/crm/file/service/KkFileViewClient.java)
- [MinioConfig.java](file://crm-file/src/main/java/com/crm/file/config/MinioConfig.java)
- [SchedulingConfig.java](file://crm-file/src/main/java/com/crm/file/config/SchedulingConfig.java)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考虑](#性能考虑)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本文件面向CRM系统的开发者与架构师，系统性阐述微服务架构设计、模块划分原则、服务间通信机制，以及Maven多模块组织方式。重点覆盖以下模块：
- crm-app：应用入口与聚合启动
- crm-auth：认证与授权服务（含第三方登录、权限控制、数据范围）
- crm-base：基础框架（通用配置、异常处理、序列化、分布式ID、分页等）
- crm-file：文件服务（上传、分片、预览、清理任务）

文档同时解释Spring Boot应用的启动流程、组件扫描机制与服务发现模式，并提供架构图展示各模块间的调用关系和数据流向，帮助读者建立系统级理解与技术选型依据。

## 项目结构
本项目采用Maven多模块工程组织，顶层pom.xml定义统一依赖管理与版本策略，子模块按职责拆分：
- crm-app：聚合模块，负责引导启动与外部暴露的API网关或聚合层
- crm-auth：认证授权领域服务，提供登录、鉴权、用户角色菜单、数据权限等能力
- crm-base：公共基础库，提供通用配置、异常处理、工具类、持久化与缓存配置等
- crm-file：文件服务，提供文件上传、分片、预览、元数据存储与定时清理

```mermaid
graph TB
subgraph "Maven 多模块"
ROOT["根 POM<br/>统一依赖管理"]
APP["crm-app<br/>应用入口"]
AUTH["crm-auth<br/>认证授权服务"]
BASE["crm-base<br/>基础框架"]
FILE["crm-file<br/>文件服务"]
end
ROOT --> APP
ROOT --> AUTH
ROOT --> BASE
ROOT --> FILE
APP --> AUTH
APP --> FILE
AUTH --> BASE
FILE --> BASE
```

**图表来源** 
- [pom.xml](file://pom.xml)

**章节来源**
- [pom.xml](file://pom.xml)

## 核心组件
- 应用入口（crm-app）
  - 通过Spring Boot主类启动应用，加载聚合配置，对外暴露统一接口或转发到下游服务
- 认证服务（crm-auth）
  - 提供登录、令牌签发与校验、权限与数据范围控制、第三方登录集成
- 基础框架（crm-base）
  - 提供全局异常处理、跨域、序列化、数据库与缓存配置、分布式ID、分页转换等
- 文件服务（crm-file）
  - 提供文件上传（支持分片）、元数据持久化、在线预览、临时分片清理任务

**章节来源**
- [CrmAppApplication.java](file://crm-app/src/main/java/com/crm/app/CrmAppApplication.java)
- [AuthApplication.java](file://crm-auth/src/main/java/com/crm/auth/AuthApplication.java)
- [MybatisPlusConfig.java](file://crm-base/src/main/java/com/crm/base/config/MybatisPlusConfig.java)
- [RedisConfig.java](file://crm-base/src/main/java/com/crm/base/config/RedisConfig.java)
- [JacksonConfig.java](file://crm-base/src/main/java/com/crm/base/config/JacksonConfig.java)
- [GlobalExceptionHandlerAdvice.java](file://crm-base/src/main/java/com/crm/base/advice/GlobalExceptionHandlerAdvice.java)
- [TraceIdFilter.java](file://crm-base/src/main/java/com/crm/base/filter/TraceIdFilter.java)
- [SnowflakeIdWorker.java](file://crm-base/src/main/java/com/crm/base/config/SnowflakeIdWorker.java)
- [FileController.java](file://crm-file/src/main/java/com/crm/file/controller/FileController.java)
- [FileInfoServiceImpl.java](file://crm-file/src/main/java/com/crm/file/service/impl/FileInfoServiceImpl.java)
- [KkFileViewClient.java](file://crm-file/src/main/java/com/crm/file/service/KkFileViewClient.java)
- [MinioConfig.java](file://crm-file/src/main/java/com/crm/file/config/MinioConfig.java)
- [SchedulingConfig.java](file://crm-file/src/main/java/com/crm/file/config/SchedulingConfig.java)

## 架构总览
下图展示了CRM系统的微服务架构与模块间调用关系。crm-app作为聚合入口，将请求路由至crm-auth与crm-file；crm-auth依赖crm-base提供的通用能力；crm-file同样依赖crm-base；认证服务内部通过工厂模式扩展第三方登录客户端；文件服务通过对象存储与在线预览服务完成文件生命周期管理。

```mermaid
graph TB
Client["客户端"]
App["crm-app<br/>应用入口"]
Auth["crm-auth<br/>认证授权服务"]
File["crm-file<br/>文件服务"]
Base["crm-base<br/>基础框架"]
DB["数据库"]
Redis["缓存"]
MinIO["对象存储"]
Preview["在线预览服务"]
Client --> App
App --> Auth
App --> File
Auth --> Base
File --> Base
Auth --> DB
Auth --> Redis
File --> DB
File --> MinIO
File --> Preview
```

**图表来源** 
- [CrmAppApplication.java](file://crm-app/src/main/java/com/crm/app/CrmAppApplication.java)
- [AuthApplication.java](file://crm-auth/src/main/java/com/crm/auth/AuthApplication.java)
- [SecurityConfig.java](file://crm-auth/src/main/java/com/crm/auth/config/SecurityConfig.java)
- [PermissionConfig.java](file://crm-auth/src/main/java/com/crm/auth/config/PermissionConfig.java)
- [MybatisPlusConfig.java](file://crm-base/src/main/java/com/crm/base/config/MybatisPlusConfig.java)
- [RedisConfig.java](file://crm-base/src/main/java/com/crm/base/config/RedisConfig.java)
- [MinioConfig.java](file://crm-file/src/main/java/com/crm/file/config/MinioConfig.java)
- [KkFileViewClient.java](file://crm-file/src/main/java/com/crm/file/service/KkFileViewClient.java)

**章节来源**
- [CrmAppApplication.java](file://crm-app/src/main/java/com/crm/app/CrmAppApplication.java)
- [AuthApplication.java](file://crm-auth/src/main/java/com/crm/auth/AuthApplication.java)
- [SecurityConfig.java](file://crm-auth/src/main/java/com/crm/auth/config/SecurityConfig.java)
- [PermissionConfig.java](file://crm-auth/src/main/java/com/crm/auth/config/PermissionConfig.java)
- [MybatisPlusConfig.java](file://crm-base/src/main/java/com/crm/base/config/MybatisPlusConfig.java)
- [RedisConfig.java](file://crm-base/src/main/java/com/crm/base/config/RedisConfig.java)
- [MinioConfig.java](file://crm-file/src/main/java/com/crm/file/config/MinioConfig.java)
- [KkFileViewClient.java](file://crm-file/src/main/java/com/crm/file/service/KkFileViewClient.java)

## 详细组件分析

### 应用入口（crm-app）
- 职责
  - 聚合启动Spring Boot应用，加载应用配置，对外暴露统一接口或转发到下游服务
- 启动流程
  - 主类启动后，Spring容器初始化，读取application.yml配置，注册Web服务器与过滤器
- 组件扫描
  - 默认扫描主类所在包及其子包，确保控制器、配置类、过滤器等被自动装配

```mermaid
sequenceDiagram
participant CLI as "命令行"
participant Main as "CrmAppApplication"
participant Ctx as "Spring上下文"
participant Web as "Web服务器"
CLI->>Main : 启动应用
Main->>Ctx : 初始化容器
Ctx->>Ctx : 扫描组件并装配
Ctx->>Web : 启动HTTP服务器
Web-->>CLI : 服务就绪
```

**图表来源** 
- [CrmAppApplication.java](file://crm-app/src/main/java/com/crm/app/CrmAppApplication.java)
- [application.yml](file://crm-app/src/main/resources/application.yml)

**章节来源**
- [CrmAppApplication.java](file://crm-app/src/main/java/com/crm/app/CrmAppApplication.java)
- [application.yml](file://crm-app/src/main/resources/application.yml)

### 认证服务（crm-auth）
- 职责
  - 提供用户登录、令牌签发与校验、权限与数据范围控制、第三方登录集成
- 关键组件
  - SecurityConfig：安全配置，拦截器链、访问控制规则
  - PermissionConfig：权限相关配置
  - TokenService：令牌生成与解析
  - JwtAuthenticationFilter：JWT过滤与身份注入
  - DataInitializer：初始数据准备
  - ThirdPartyAuthClientFactory：第三方登录客户端工厂
  - DingTalkAuthClient：钉钉登录客户端实现
- 启动流程
  - 主类启动后，加载security与permission配置，注册JWT过滤器，初始化权限与数据范围拦截器

```mermaid
sequenceDiagram
participant Client as "客户端"
participant AuthCtrl as "AuthController"
participant SecCfg as "SecurityConfig"
participant JwtFilt as "JwtAuthenticationFilter"
participant TokSvc as "TokenService"
participant Svc as "IAuthService"
participant Impl as "AuthServiceImpl"
Client->>AuthCtrl : POST /login
AuthCtrl->>Svc : 验证用户名密码
Svc->>Impl : 业务逻辑
Impl-->>Svc : 用户信息
Svc-->>AuthCtrl : 返回用户上下文
AuthCtrl->>TokSvc : 签发JWT
TokSvc-->>AuthCtrl : 返回令牌
AuthCtrl-->>Client : {token, userInfo}
Note over Client,JwtFilt : 后续请求携带JWT由过滤器校验
```

**图表来源** 
- [AuthController.java](file://crm-auth/src/main/java/com/crm/auth/controller/AuthController.java)
- [SecurityConfig.java](file://crm-auth/src/main/java/com/crm/auth/config/SecurityConfig.java)
- [JwtAuthenticationFilter.java](file://crm-auth/src/main/java/com/crm/auth/security/JwtAuthenticationFilter.java)
- [TokenService.java](file://crm-auth/src/main/java/com/crm/auth/security/TokenService.java)
- [IAuthService.java](file://crm-auth/src/main/java/com/crm/auth/service/IAuthService.java)
- [AuthServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/AuthServiceImpl.java)

**章节来源**
- [AuthApplication.java](file://crm-auth/src/main/java/com/crm/auth/AuthApplication.java)
- [application.yml](file://crm-auth/src/main/resources/application.yml)
- [SecurityConfig.java](file://crm-auth/src/main/java/com/crm/auth/config/SecurityConfig.java)
- [PermissionConfig.java](file://crm-auth/src/main/java/com/crm/auth/config/PermissionConfig.java)
- [DataInitializer.java](file://crm-auth/src/main/java/com/crm/auth/config/DataInitializer.java)
- [AuthController.java](file://crm-auth/src/main/java/com/crm/auth/controller/AuthController.java)
- [SystemController.java](file://crm-auth/src/main/java/com/crm/auth/controller/SystemController.java)
- [TokenService.java](file://crm-auth/src/main/java/com/crm/auth/security/TokenService.java)
- [JwtAuthenticationFilter.java](file://crm-auth/src/main/java/com/crm/auth/security/JwtAuthenticationFilter.java)
- [IAuthService.java](file://crm-auth/src/main/java/com/crm/auth/service/IAuthService.java)
- [AuthServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/AuthServiceImpl.java)
- [ThirdPartyAuthClientFactory.java](file://crm-auth/src/main/java/com/crm/auth/service/client/ThirdPartyAuthClientFactory.java)
- [DingTalkAuthClient.java](file://crm-auth/src/main/java/com/crm/auth/service/client/DingTalkAuthClient.java)

### 基础框架（crm-base）
- 职责
  - 提供全局异常处理、跨域、序列化、数据库与缓存配置、分布式ID、分页转换、审计字段填充等
- 关键组件
  - GlobalExceptionHandlerAdvice：统一异常处理
  - MybatisPlusConfig：MyBatis Plus配置与SQL注入器
  - RedisConfig：Redis连接与序列化配置
  - JacksonConfig：JSON序列化策略
  - TraceIdFilter：链路追踪ID过滤器
  - SnowflakeIdWorker：分布式雪花ID生成
  - BaseServiceImpl：通用服务基类

```mermaid
classDiagram
class GlobalExceptionHandlerAdvice {
+处理异常()
}
class MybatisPlusConfig {
+配置分页()
+配置SQL注入器()
}
class RedisConfig {
+配置连接()
+配置序列化()
}
class JacksonConfig {
+配置序列化策略()
}
class TraceIdFilter {
+注入链路ID()
}
class SnowflakeIdWorker {
+生成ID()
}
class BaseServiceImpl {
+通用CRUD()
}
GlobalExceptionHandlerAdvice <.. BaseServiceImpl : "异常处理"
MybatisPlusConfig <.. BaseServiceImpl : "持久化"
RedisConfig <.. BaseServiceImpl : "缓存"
JacksonConfig <.. BaseServiceImpl : "序列化"
TraceIdFilter <.. BaseServiceImpl : "链路追踪"
SnowflakeIdWorker <.. BaseServiceImpl : "ID生成"
```

**图表来源** 
- [GlobalExceptionHandlerAdvice.java](file://crm-base/src/main/java/com/crm/base/advice/GlobalExceptionHandlerAdvice.java)
- [MybatisPlusConfig.java](file://crm-base/src/main/java/com/crm/base/config/MybatisPlusConfig.java)
- [RedisConfig.java](file://crm-base/src/main/java/com/crm/base/config/RedisConfig.java)
- [JacksonConfig.java](file://crm-base/src/main/java/com/crm/base/config/JacksonConfig.java)
- [TraceIdFilter.java](file://crm-base/src/main/java/com/crm/base/filter/TraceIdFilter.java)
- [SnowflakeIdWorker.java](file://crm-base/src/main/java/com/crm/base/config/SnowflakeIdWorker.java)
- [BaseServiceImpl.java](file://crm-base/src/main/java/com/crm/base/service/impl/BaseServiceImpl.java)

**章节来源**
- [GlobalExceptionHandlerAdvice.java](file://crm-base/src/main/java/com/crm/base/advice/GlobalExceptionHandlerAdvice.java)
- [MybatisPlusConfig.java](file://crm-base/src/main/java/com/crm/base/config/MybatisPlusConfig.java)
- [RedisConfig.java](file://crm-base/src/main/java/com/crm/base/config/RedisConfig.java)
- [JacksonConfig.java](file://crm-base/src/main/java/com/crm/base/config/JacksonConfig.java)
- [TraceIdFilter.java](file://crm-base/src/main/java/com/crm/base/filter/TraceIdFilter.java)
- [SnowflakeIdWorker.java](file://crm-base/src/main/java/com/crm/base/config/SnowflakeIdWorker.java)
- [BaseServiceImpl.java](file://crm-base/src/main/java/com/crm/base/service/impl/BaseServiceImpl.java)

### 文件服务（crm-file）
- 职责
  - 提供文件上传（支持分片）、元数据持久化、在线预览、临时分片清理任务
- 关键组件
  - FileController：文件上传与下载接口
  - FileInfoServiceImpl：文件元数据服务实现
  - KkFileViewClient：在线预览客户端
  - MinioConfig：对象存储配置
  - SchedulingConfig：定时任务配置
  - OrphanChunkCleanupTask：孤立分片清理任务
- 上传流程（分片）

```mermaid
flowchart TD
Start(["开始"]) --> Init["初始化上传会话"]
Init --> UploadChunks["分片上传"]
UploadChunks --> Merge{"所有分片上传完成?"}
Merge --> |否| UploadChunks
Merge --> |是| SaveMeta["保存文件元数据"]
SaveMeta --> Preview["生成预览链接"]
Preview --> End(["结束"])
```

**图表来源** 
- [FileController.java](file://crm-file/src/main/java/com/crm/file/controller/FileController.java)
- [FileInfoServiceImpl.java](file://crm-file/src/main/java/com/crm/file/service/impl/FileInfoServiceImpl.java)
- [KkFileViewClient.java](file://crm-file/src/main/java/com/crm/file/service/KkFileViewClient.java)
- [MinioConfig.java](file://crm-file/src/main/java/com/crm/file/config/MinioConfig.java)
- [SchedulingConfig.java](file://crm-file/src/main/java/com/crm/file/config/SchedulingConfig.java)

**章节来源**
- [FileApi.java](file://crm-file/src/main/java/com/crm/file/api/FileApi.java)
- [FileController.java](file://crm-file/src/main/java/com/crm/file/controller/FileController.java)
- [FileInfoServiceImpl.java](file://crm-file/src/main/java/com/crm/file/service/impl/FileInfoServiceImpl.java)
- [KkFileViewClient.java](file://crm-file/src/main/java/com/crm/file/service/KkFileViewClient.java)
- [MinioConfig.java](file://crm-file/src/main/java/com/crm/file/config/MinioConfig.java)
- [SchedulingConfig.java](file://crm-file/src/main/java/com/crm/file/config/SchedulingConfig.java)

## 依赖关系分析
- Maven依赖
  - 根POM统一管理版本与依赖，子模块按需引入
- 运行时依赖
  - crm-app依赖crm-auth与crm-file（聚合或网关转发）
  - crm-auth依赖crm-base（通用配置、异常、序列化、持久化、缓存）
  - crm-file依赖crm-base（同上）
- 外部依赖
  - 数据库、Redis、对象存储、在线预览服务

```mermaid
graph LR
Root["根POM"] --> App["crm-app"]
Root --> Auth["crm-auth"]
Root --> Base["crm-base"]
Root --> File["crm-file"]
App --> Auth
App --> File
Auth --> Base
File --> Base
```

**图表来源** 
- [pom.xml](file://pom.xml)

**章节来源**
- [pom.xml](file://pom.xml)

## 性能考虑
- 序列化与反序列化
  - 使用Jackson优化JSON处理，避免不必要的字段序列化
- 数据库访问
  - 使用MyBatis Plus分页插件减少全量查询，合理索引与批量操作
- 缓存
  - 使用Redis缓存热点数据（如权限、字典、用户信息），降低DB压力
- 分布式ID
  - 使用雪花算法避免自增ID冲突，提升写入性能
- 文件上传
  - 分片上传与断点续传提升大文件稳定性与吞吐
- 链路追踪
  - 通过TraceIdFilter记录请求链路，便于定位性能瓶颈

[本节为通用指导，不直接分析具体文件]

## 故障排查指南
- 统一异常处理
  - 通过GlobalExceptionHandlerAdvice捕获并标准化错误响应
- 认证与授权问题
  - 检查SecurityConfig与JwtAuthenticationFilter配置是否正确
  - 确认TokenService的密钥与过期时间设置
- 第三方登录失败
  - 核对ThirdPartyAuthClientFactory与DingTalkAuthClient的配置与网络连通性
- 文件上传失败
  - 检查MinioConfig的对象存储配置与权限
  - 查看OrphanChunkCleanupTask是否清理了孤立分片
- 缓存与数据库
  - 确认Redis与数据库连接配置正确
  - 检查MybatisPlusConfig的分页与SQL注入器配置

**章节来源**
- [GlobalExceptionHandlerAdvice.java](file://crm-base/src/main/java/com/crm/base/advice/GlobalExceptionHandlerAdvice.java)
- [SecurityConfig.java](file://crm-auth/src/main/java/com/crm/auth/config/SecurityConfig.java)
- [JwtAuthenticationFilter.java](file://crm-auth/src/main/java/com/crm/auth/security/JwtAuthenticationFilter.java)
- [TokenService.java](file://crm-auth/src/main/java/com/crm/auth/security/TokenService.java)
- [ThirdPartyAuthClientFactory.java](file://crm-auth/src/main/java/com/crm/auth/service/client/ThirdPartyAuthClientFactory.java)
- [DingTalkAuthClient.java](file://crm-auth/src/main/java/com/crm/auth/service/client/DingTalkAuthClient.java)
- [MinioConfig.java](file://crm-file/src/main/java/com/crm/file/config/MinioConfig.java)
- [SchedulingConfig.java](file://crm-file/src/main/java/com/crm/file/config/SchedulingConfig.java)
- [MybatisPlusConfig.java](file://crm-base/src/main/java/com/crm/base/config/MybatisPlusConfig.java)
- [RedisConfig.java](file://crm-base/src/main/java/com/crm/base/config/RedisConfig.java)

## 结论
本CRM系统采用清晰的Maven多模块与微服务架构，crm-app作为聚合入口，crm-auth与crm-file分别承担认证授权与文件管理能力，crm-base提供统一的横切能力。通过Spring Boot的组件扫描与自动装配，结合JWT、Redis、对象存储与在线预览服务，构建了可扩展、可维护且高性能的企业级平台。建议在生产环境完善服务发现与配置中心，进一步提升弹性与运维效率。

[本节为总结，不直接分析具体文件]

## 附录
- Spring Boot启动流程要点
  - 主类启动，创建ApplicationContext，扫描组件，加载配置文件，启动Web服务器
- 组件扫描机制
  - 默认扫描主类所在包及子包，可通过自定义注解或配置调整
- 服务发现模式
  - 当前为单体聚合模式，未来可引入注册中心（如Nacos/Eureka）进行服务治理

[本节为概念性内容，不直接分析具体文件]