luoweijian
/
crm-backend-matt
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
146 Commits
1 Branch
0 Tags
403 MiB
Branch: master
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from 'master'
${ noResults }
crm-backend-matt/.qoder/repowiki/zh/content/快速开始.md

420 lines
29 KiB
Raw Permalink Normal View History

first-commit
1 month ago
# 快速开始
<cite>
**本文引用的文件**
- [pom.xml](file://pom.xml)
- [crm-app/pom.xml](file://crm-app/pom.xml)
- [crm-auth/pom.xml](file://crm-auth/pom.xml)
- [crm-base/pom.xml](file://crm-base/pom.xml)
- [crm-file/pom.xml](file://crm-file/pom.xml)
- [crm-app/src/main/java/com/crm/app/CrmAppApplication.java](file://crm-app/src/main/java/com/crm/app/CrmAppApplication.java)
- [crm-app/src/main/resources/application.yml](file://crm-app/src/main/resources/application.yml)
- [crm-auth/src/main/java/com/crm/auth/AuthApplication.java](file://crm-auth/src/main/java/com/crm/auth/AuthApplication.java)
- [crm-auth/src/main/resources/application.yml](file://crm-auth/src/main/resources/application.yml)
- [crm-base/src/main/java/com/crm/base/config/RedisConfig.java](file://crm-base/src/main/java/com/crm/base/config/RedisConfig.java)
- [crm-base/src/main/java/com/crm/base/config/MybatisPlusConfig.java](file://crm-base/src/main/java/com/crm/base/config/MybatisPlusConfig.java)
- [crm-base/src/main/java/com/crm/base/config/JacksonConfig.java](file://crm-base/src/main/java/com/crm/base/config/JacksonConfig.java)
- [crm-base/src/main/java/com/crm/base/config/Knife4jConfig.java](file://crm-base/src/main/java/com/crm/base/config/Knife4jConfig.java)
- [crm-base/src/main/java/com/crm/base/config/CorsConfig.java](file://crm-base/src/main/java/com/crm/base/config/CorsConfig.java)
- [crm-base/src/main/java/com/crm/base/config/MetaObjectFillHandler.java](file://crm-base/src/main/java/com/crm/base/config/MetaObjectFillHandler.java)
- [crm-base/src/main/java/com/crm/base/config/SnowflakeIdWorker.java](file://crm-base/src/main/java/com/crm/base/config/SnowflakeIdWorker.java)
- [crm-base/src/main/java/com/crm/base/config/SnowflakeProperties.java](file://crm-base/src/main/java/com/crm/base/config/SnowflakeProperties.java)
- [crm-base/src/main/java/com/crm/base/config/CustomIdGenerator.java](file://crm-base/src/main/java/com/crm/base/config/CustomIdGenerator.java)
- [crm-base/src/main/java/com/crm/base/config/InsertBatchOnDuplicateKeyUpdate.java](file://crm-base/src/main/java/com/crm/base/config/InsertBatchOnDuplicateKeyUpdate.java)
- [crm-base/src/main/java/com/crm/base/config/CrmSqlInjector.java](file://crm-base/src/main/java/com/crm/base/config/CrmSqlInjector.java)
- [crm-base/src/main/java/com/crm/base/config/ScheduledTaskProperties.java](file://crm-base/src/main/java/com/crm/base/config/ScheduledTaskProperties.java)
- [crm-base/src/main/java/com/crm/base/advice/GlobalExceptionHandlerAdvice.java](file://crm-base/src/main/java/com/crm/base/advice/GlobalExceptionHandlerAdvice.java)
- [crm-base/src/main/java/com/crm/base/filter/TraceIdFilter.java](file://crm-base/src/main/java/com/crm/base/filter/TraceIdFilter.java)
- [crm-base/src/main/java/com/crm/base/security/DataScopeHelper.java](file://crm-base/src/main/java/com/crm/base/security/DataScopeHelper.java)
- [crm-base/src/main/java/com/crm/base/security/LoginUser.java](file://crm-base/src/main/java/com/crm/base/security/LoginUser.java)
- [crm-base/src/main/java/com/crm/base/domain/entity/BaseEntity.java](file://crm-base/src/main/java/com/crm/base/domain/entity/BaseEntity.java)
- [crm-base/src/main/java/com/crm/base/service/impl/BaseServiceImpl.java](file://crm-base/src/main/java/com/crm/base/service/impl/BaseServiceImpl.java)
- [crm-base/src/main/java/com/crm/base/mapper/CrmBaseMapper.java](file://crm-base/src/main/java/com/crm/base/mapper/CrmBaseMapper.java)
- [crm-auth/src/main/java/com/crm/auth/config/SecurityConfig.java](file://crm-auth/src/main/java/com/crm/auth/config/SecurityConfig.java)
- [crm-auth/src/main/java/com/crm/auth/config/AuthProperties.java](file://crm-auth/src/main/java/com/crm/auth/config/AuthProperties.java)
- [crm-auth/src/main/java/com/crm/auth/config/DataInitializer.java](file://crm-auth/src/main/java/com/crm/auth/config/DataInitializer.java)
- [crm-auth/src/main/java/com/crm/auth/config/PermissionConfig.java](file://crm-auth/src/main/java/com/crm/auth/config/PermissionConfig.java)
- [crm-auth/src/main/java/com/crm/auth/security/JwtAuthenticationFilter.java](file://crm-auth/src/main/java/com/crm/auth/security/JwtAuthenticationFilter.java)
- [crm-auth/src/main/java/com/crm/auth/security/TokenService.java](file://crm-auth/src/main/java/com/crm/auth/security/TokenService.java)
- [crm-auth/src/main/java/com/crm/auth/controller/AuthController.java](file://crm-auth/src/main/java/com/crm/auth/controller/AuthController.java)
- [crm-auth/src/main/java/com/crm/auth/service/impl/AuthServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/AuthServiceImpl.java)
- [crm-auth/src/main/java/com/crm/auth/service/IAuthService.java](file://crm-auth/src/main/java/com/crm/auth/service/IAuthService.java)
- [crm-auth/src/main/java/com/crm/auth/mapper/AuthUserMapper.java](file://crm-auth/src/main/java/com/crm/auth/mapper/AuthUserMapper.java)
- [crm-auth/src/main/java/com/crm/auth/domain/entity/AuthUser.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/AuthUser.java)
- [crm-file/src/main/java/com/crm/file/config/FileProperties.java](file://crm-file/src/main/java/com/crm/file/config/FileProperties.java)
- [crm-file/src/main/java/com/crm/file/config/MinioConfig.java](file://crm-file/src/main/java/com/crm/file/config/MinioConfig.java)
- [crm-file/src/main/java/com/crm/file/config/SchedulingConfig.java](file://crm-file/src/main/java/com/crm/file/config/SchedulingConfig.java)
- [crm-file/src/main/java/com/crm/file/controller/FileController.java](file://crm-file/src/main/java/com/crm/file/controller/FileController.java)
- [crm-file/src/main/java/com/crm/file/service/impl/FileApiImpl.java](file://crm-file/src/main/java/com/crm/file/service/impl/FileApiImpl.java)
- [crm-file/src/main/java/com/crm/file/task/OrphanChunkCleanupTask.java](file://crm-file/src/main/java/com/crm/file/task/OrphanChunk清理任务.java)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)
10. [附录](#附录)
## 简介
本快速开始指南面向首次接触该 CRM 系统的开发者，目标是帮助你在最短时间内完成环境准备、克隆与构建、配置初始化、数据库初始化与服务启动，并掌握基本开发流程。系统采用多模块 Maven 工程，包含认证授权（crm-auth）、基础能力（crm-base）、文件服务（crm-file）与应用入口（crm-app）。
## 项目结构
- 多模块 Maven 工程，根 pom.xml 聚合各子模块：
- crm-app：应用启动入口与全局配置
- crm-auth：认证授权、权限控制、用户角色菜单等
- crm-base：通用配置、异常处理、安全上下文、工具类、基础实体与 MyBatis-Plus 集成
- crm-file：文件上传下载、分片、预览与清理任务
- 关键配置文件位于各模块 resources/application.yml；Spring Boot 启动类位于各模块的 Application 类中。
```mermaid
graph TB
subgraph "Maven 多模块"
Root["根 POM"] --> App["crm-app"]
Root --> Auth["crm-auth"]
Root --> Base["crm-base"]
Root --> File["crm-file"]
end
subgraph "运行时"
App --> Auth
App --> File
Auth --> Base
File --> Base
end
```
图表来源
- [pom.xml:1-200](file://pom.xml#L1-L200)
- [crm-app/pom.xml:1-100](file://crm-app/pom.xml#L1-L100)
- [crm-auth/pom.xml:1-100](file://crm-auth/pom.xml#L1-L100)
- [crm-base/pom.xml:1-100](file://crm-base/pom.xml#L1-L100)
- [crm-file/pom.xml:1-100](file://crm-file/pom.xml#L1-L100)
章节来源
- [pom.xml:1-200](file://pom.xml#L1-L200)
## 核心组件
- 应用入口
- CrmAppApplication：Spring Boot 主启动类，负责加载应用配置与模块扫描
- 认证授权
- SecurityConfig：Spring Security 配置，注册 JWT 过滤器与访问控制规则
- JwtAuthenticationFilter：请求级 JWT 校验与上下文注入
- TokenService：令牌签发、刷新与解析
- DataInitializer：启动时数据初始化（如默认租户、角色、菜单等）
- 基础能力
- RedisConfig：Redis 连接与序列化配置
- MybatisPlusConfig：分页、自动填充、SQL 注入器、雪花 ID 生成器
- JacksonConfig：JSON 序列化策略
- Knife4jConfig：API 文档与调试界面
- CorsConfig：跨域配置
- GlobalExceptionHandlerAdvice：统一异常处理
- TraceIdFilter：链路追踪 ID 注入
- 文件服务
- MinioConfig：对象存储客户端配置
- FileController：文件上传、下载、分片接口
- FileApiImpl：文件业务实现
- OrphanChunkCleanupTask：分片残留清理定时任务
章节来源
- [crm-app/src/main/java/com/crm/app/CrmAppApplication.java:1-200](file://crm-app/src/main/java/com/crm/app/CrmAppApplication.java#L1-L200)
- [crm-auth/src/main/java/com/crm/auth/config/SecurityConfig.java:1-200](file://crm-auth/src/main/java/com/crm/auth/config/SecurityConfig.java#L1-L200)
- [crm-auth/src/main/java/com/crm/auth/security/JwtAuthenticationFilter.java:1-200](file://crm-auth/src/main/java/com/crm/auth/security/JwtAuthenticationFilter.java#L1-L200)
- [crm-auth/src/main/java/com/crm/auth/security/TokenService.java:1-200](file://crm-auth/src/main/java/com/crm/auth/security/TokenService.java#L1-L200)
- [crm-auth/src/main/java/com/crm/auth/config/DataInitializer.java:1-200](file://crm-auth/src/main/java/com/crm/auth/config/DataInitializer.java#L1-L200)
- [crm-base/src/main/java/com/crm/base/config/RedisConfig.java:1-200](file://crm-base/src/main/java/com/crm/base/config/RedisConfig.java#L1-L200)
- [crm-base/src/main/java/com/crm/base/config/MybatisPlusConfig.java:1-200](file://crm-base/src/main/java/com/crm/base/config/MybatisPlusConfig.java#L1-L200)
- [crm-base/src/main/java/com/crm/base/config/JacksonConfig.java:1-200](file://crm-base/src/main/java/com/crm/base/config/JacksonConfig.java#L1-L200)
- [crm-base/src/main/java/com/crm/base/config/Knife4jConfig.java:1-200](file://crm-base/src/main/java/com/crm/base/config/Knife4jConfig.java#L1-L200)
- [crm-base/src/main/java/com/crm/base/config/CorsConfig.java:1-200](file://crm-base/src/main/java/com/crm/base/config/CorsConfig.java#L1-L200)
- [crm-base/src/main/java/com/crm/base/advice/GlobalExceptionHandlerAdvice.java:1-200](file://crm-base/src/main/java/com/crm/base/advice/GlobalExceptionHandlerAdvice.java#L1-L200)
- [crm-base/src/main/java/com/crm/base/filter/TraceIdFilter.java:1-200](file://crm-base/src/main/java/com/crm/base/filter/TraceIdFilter.java#L1-L200)
- [crm-file/src/main/java/com/crm/file/config/MinioConfig.java:1-200](file://crm-file/src/main/java/com/crm/file/config/MinioConfig.java#L1-L200)
- [crm-file/src/main/java/com/crm/file/controller/FileController.java:1-200](file://crm-file/src/main/java/com/crm/file/controller/FileController.java#L1-L200)
- [crm-file/src/main/java/com/crm/file/service/impl/FileApiImpl.java:1-200](file://crm-file/src/main/java/com/crm/file/service/impl/FileApiImpl.java#L1-L200)
- [crm-file/src/main/java/com/crm/file/task/OrphanChunkCleanupTask.java:1-200](file://crm-file/src/main/java/com/crm/file/task/OrphanChunk清理任务.java#L1-L200)
## 架构总览
下图展示了应用启动后，HTTP 请求进入认证过滤器的典型调用链，以及后续的业务服务与数据层交互。
```mermaid
sequenceDiagram
participant Client as "客户端"
participant App as "CrmAppApplication"
participant Auth as "AuthController"
participant Sec as "JwtAuthenticationFilter"
participant Tok as "TokenService"
participant Svc as "IAuthService"
participant DB as "AuthUserMapper"
Client->>App : "启动应用"
App-->>Client : "服务就绪"
Client->>Sec : "携带JWT访问受保护接口"
Sec->>Tok : "解析并校验令牌"
Tok-->>Sec : "返回用户上下文"
Sec->>Auth : "放行至控制器"
Auth->>Svc : "调用认证/鉴权服务"
Svc->>DB : "查询用户/权限信息"
DB-->>Svc : "返回数据"
Svc-->>Auth : "返回结果"
Auth-->>Client : "响应数据"
```
图表来源
- [crm-app/src/main/java/com/crm/app/CrmAppApplication.java:1-200](file://crm-app/src/main/java/com/crm/app/CrmAppApplication.java#L1-L200)
- [crm-auth/src/main/java/com/crm/auth/security/JwtAuthenticationFilter.java:1-200](file://crm-auth/src/main/java/com/crm/auth/security/JwtAuthenticationFilter.java#L1-L200)
- [crm-auth/src/main/java/com/crm/auth/security/TokenService.java:1-200](file://crm-auth/src/main/java/com/crm/auth/security/TokenService.java#L1-L200)
- [crm-auth/src/main/java/com/crm/auth/controller/AuthController.java:1-200](file://crm-auth/src/main/java/com/crm/auth/controller/AuthController.java#L1-L200)
- [crm-auth/src/main/java/com/crm/auth/service/IAuthService.java:1-200](file://crm-auth/src/main/java/com/crm/auth/service/IAuthService.java#L1-L200)
- [crm-auth/src/main/java/com/crm/auth/mapper/AuthUserMapper.java:1-200](file://crm-auth/src/main/java/com/crm/auth/mapper/AuthUserMapper.java#L1-L200)
## 详细组件分析
### 应用启动与模块装配
- 启动类：CrmAppApplication 作为 Spring Boot 入口，加载 application.yml 配置并启用模块包扫描
- 全局配置：application.yml 定义端口、日志、外部依赖（数据库、Redis、对象存储等）
- 模块装配：通过 Maven 聚合与 Spring 包扫描，将 auth、base、file 模块组件装配到应用上下文
章节来源
- [crm-app/src/main/java/com/crm/app/CrmAppApplication.java:1-200](file://crm-app/src/main/java/com/crm/app/CrmAppApplication.java#L1-L200)
- [crm-app/src/main/resources/application.yml:1-200](file://crm-app/src/main/resources/application.yml#L1-L200)
### 认证与授权（crm-auth）
- 安全配置：SecurityConfig 定义白名单、拦截器与角色权限策略
- 认证流程：AuthController 提供登录接口，TokenService 负责令牌签发与校验，JwtAuthenticationFilter 在请求链路中解析令牌并注入上下文
- 数据初始化：DataInitializer 在启动时创建默认组织、角色、菜单等基础数据
- 权限控制：PermissionConfig 与数据范围（DataScope）配合实现细粒度访问控制
```mermaid
flowchart TD
Start(["登录请求"]) --> Validate["参数校验"]
Validate --> CheckUser["查询用户"]
CheckUser --> UserFound{"用户存在?"}
UserFound --> |否| Error["返回错误"]
UserFound --> |是| VerifyPwd["密码校验"]
VerifyPwd --> PwdOk{"密码正确?"}
PwdOk --> |否| Error
PwdOk --> |是| GenToken["生成JWT令牌"]
GenToken --> SaveCache["写入缓存(可选)"]
SaveCache --> Return["返回令牌与用户信息"]
```
图表来源
- [crm-auth/src/main/java/com/crm/auth/controller/AuthController.java:1-200](file://crm-auth/src/main/java/com/crm/auth/controller/AuthController.java#L1-L200)
- [crm-auth/src/main/java/com/crm/auth/security/TokenService.java:1-200](file://crm-auth/src/main/java/com/crm/auth/security/TokenService.java#L1-L200)
- [crm-auth/src/main/java/com/crm/auth/service/impl/AuthServiceImpl.java:1-200](file://crm-auth/src/main/java/com/crm/auth/service/impl/AuthServiceImpl.java#L1-L200)
- [crm-auth/src/main/java/com/crm/auth/mapper/AuthUserMapper.java:1-200](file://crm-auth/src/main/java/com/crm/auth/mapper/AuthUserMapper.java#L1-L200)
章节来源
- [crm-auth/src/main/java/com/crm/auth/config/SecurityConfig.java:1-200](file://crm-auth/src/main/java/com/crm/auth/config/SecurityConfig.java#L1-L200)
- [crm-auth/src/main/java/com/crm/auth/config/AuthProperties.java:1-200](file://crm-auth/src/main/java/com/crm/auth/config/AuthProperties.java#L1-L200)
- [crm-auth/src/main/java/com/crm/auth/config/DataInitializer.java:1-200](file://crm-auth/src/main/java/com/crm/auth/config/DataInitializer.java#L1-L200)
- [crm-auth/src/main/java/com/crm/auth/config/PermissionConfig.java:1-200](file://crm-auth/src/main/java/com/crm/auth/config/PermissionConfig.java#L1-L200)
- [crm-auth/src/main/java/com/crm/auth/security/JwtAuthenticationFilter.java:1-200](file://crm-auth/src/main/java/com/crm/auth/security/JwtAuthenticationFilter.java#L1-L200)
- [crm-auth/src/main/java/com/crm/auth/security/TokenService.java:1-200](file://crm-auth/src/main/java/com/crm/auth/security/TokenService.java#L1-L200)
- [crm-auth/src/main/java/com/crm/auth/controller/AuthController.java:1-200](file://crm-auth/src/main/java/com/crm/auth/controller/AuthController.java#L1-L200)
- [crm-auth/src/main/java/com/crm/auth/service/IAuthService.java:1-200](file://crm-auth/src/main/java/com/crm/auth/service/IAuthService.java#L1-L200)
- [crm-auth/src/main/java/com/crm/auth/service/impl/AuthServiceImpl.java:1-200](file://crm-auth/src/main/java/com/crm/auth/service/impl/AuthServiceImpl.java#L1-L200)
- [crm-auth/src/main/java/com/crm/auth/mapper/AuthUserMapper.java:1-200](file://crm-auth/src/main/java/com/crm/auth/mapper/AuthUserMapper.java#L1-L200)
- [crm-auth/src/main/java/com/crm/auth/domain/entity/AuthUser.java:1-200](file://crm-auth/src/main/java/com/crm/auth/domain/entity/AuthUser.java#L1-L200)
### 基础能力（crm-base）
- 数据访问：MybatisPlusConfig 配置分页、自动填充、SQL 注入器与自定义 ID 生成器（雪花算法）
- 缓存：RedisConfig 配置连接池、序列化策略与过期策略
- JSON：JacksonConfig 统一时间格式、空值处理等
- API 文档：Knife4jConfig 暴露 Swagger/Knife4j 界面
- 跨域：CorsConfig 允许前端跨域访问
- 异常：GlobalExceptionHandlerAdvice 统一捕获并返回标准错误码
- 追踪：TraceIdFilter 为每个请求注入唯一追踪 ID
- 安全上下文：LoginUser、DataScopeHelper 提供当前用户与数据范围能力
章节来源
- [crm-base/src/main/java/com/crm/base/config/MybatisPlusConfig.java:1-200](file://crm-base/src/main/java/com/crm/base/config/MybatisPlusConfig.java#L1-L200)
- [crm-base/src/main/java/com/crm/base/config/RedisConfig.java:1-200](file://crm-base/src/main/java/com/crm/base/config/RedisConfig.java#L1-L200)
- [crm-base/src/main/java/com/crm/base/config/JacksonConfig.java:1-200](file://crm-base/src/main/java/com/crm/base/config/JacksonConfig.java#L1-L200)
- [crm-base/src/main/java/com/crm/base/config/Knife4jConfig.java:1-200](file://crm-base/src/main/java/com/crm/base/config/Knife4jConfig.java#L1-L200)
- [crm-base/src/main/java/com/crm/base/config/CorsConfig.java:1-200](file://crm-base/src/main/java/com/crm/base/config/CorsConfig.java#L1-L200)
- [crm-base/src/main/java/com/crm/base/advice/GlobalExceptionHandlerAdvice.java:1-200](file://crm-base/src/main/java/com/crm/base/advice/GlobalExceptionHandlerAdvice.java#L1-L200)
- [crm-base/src/main/java/com/crm/base/filter/TraceIdFilter.java:1-200](file://crm-base/src/main/java/com/crm/base/filter/TraceIdFilter.java#L1-L200)
- [crm-base/src/main/java/com/crm/base/security/LoginUser.java:1-200](file://crm-base/src/main/java/com/crm/base/security/LoginUser.java#L1-L200)
- [crm-base/src/main/java/com/crm/base/security/DataScopeHelper.java:1-200](file://crm-base/src/main/java/com/crm/base/security/DataScopeHelper.java#L1-L200)
- [crm-base/src/main/java/com/crm/base/config/SnowflakeIdWorker.java:1-200](file://crm-base/src/main/java/com/crm/base/config/SnowflakeIdWorker.java#L1-L200)
- [crm-base/src/main/java/com/crm/base/config/SnowflakeProperties.java:1-200](file://crm-base/src/main/java/com/crm/base/config/SnowflakeProperties.java#L1-L200)
- [crm-base/src/main/java/com/crm/base/config/CustomIdGenerator.java:1-200](file://crm-base/src/main/java/com/crm/base/config/CustomIdGenerator.java#L1-L200)
- [crm-base/src/main/java/com/crm/base/config/InsertBatchOnDuplicateKeyUpdate.java:1-200](file://crm-base/src/main/java/com/crm/base/config/InsertBatchOnDuplicateKeyUpdate.java#L1-L200)
- [crm-base/src/main/java/com/crm/base/config/CrmSqlInjector.java:1-200](file://crm-base/src/main/java/com/crm/base/config/CrmSqlInjector.java#L1-L200)
- [crm-base/src/main/java/com/crm/base/config/ScheduledTaskProperties.java:1-200](file://crm-base/src/main/java/com/crm/base/config/ScheduledTaskProperties.java#L1-L200)
- [crm-base/src/main/java/com/crm/base/domain/entity/BaseEntity.java:1-200](file://crm-base/src/main/java/com/crm/base/domain/entity/BaseEntity.java#L1-L200)
- [crm-base/src/main/java/com/crm/base/service/impl/BaseServiceImpl.java:1-200](file://crm-base/src/main/java/com/crm/base/service/impl/BaseServiceImpl.java#L1-L200)
- [crm-base/src/main/java/com/crm/base/mapper/CrmBaseMapper.java:1-200](file://crm-base/src/main/java/com/crm/base/mapper/CrmBaseMapper.java#L1-L200)
### 文件服务（crm-file）
- 对象存储：MinioConfig 配置端点、密钥桶名等
- 接口：FileController 提供上传、下载、分片断点续传、预览等接口
- 业务：FileApiImpl 封装文件元数据管理与分片合并逻辑
- 任务：OrphanChunkCleanupTask 定期清理未完成的分片文件
章节来源
- [crm-file/src/main/java/com/crm/file/config/MinioConfig.java:1-200](file://crm-file/src/main/java/com/crm/file/config/MinioConfig.java#L1-L200)
- [crm-file/src/main/java/com/crm/file/controller/FileController.java:1-200](file://crm-file/src/main/java/com/crm/file/controller/FileController.java#L1-L200)
- [crm-file/src/main/java/com/crm/file/service/impl/FileApiImpl.java:1-200](file://crm-file/src/main/java/com/crm/file/service/impl/FileApiImpl.java#L1-L200)
- [crm-file/src/main/java/com/crm/file/task/OrphanChunkCleanupTask.java:1-200](file://crm-file/src/main/java/com/crm/file/task/OrphanChunk清理任务.java#L1-L200)
- [crm-file/src/main/java/com/crm/file/config/FileProperties.java:1-200](file://crm-file/src/main/java/com/crm/file/config/FileProperties.java#L1-L200)
- [crm-file/src/main/java/com/crm/file/config/SchedulingConfig.java:1-200](file://crm-file/src/main/java/com/crm/file/config/SchedulingConfig.java#L1-L200)
## 依赖分析
- Maven 依赖关系
- 根 pom.xml 管理版本与聚合模块
- crm-app 依赖 crm-auth、crm-file、crm-base
- crm-auth 依赖 crm-base
- crm-file 依赖 crm-base
- 运行时依赖
- 数据库：MySQL（通过 MyBatis-Plus）
- 缓存：Redis（会话、令牌、字典缓存等）
- 对象存储：MinIO（文件存储）
- API 文档：Knife4j（Swagger）
```mermaid
graph LR
App["crm-app"] --> Auth["crm-auth"]
App --> File["crm-file"]
Auth --> Base["crm-base"]
File --> Base
Base --> DB["MySQL"]
Base --> Redis["Redis"]
File --> Minio["MinIO"]
```
图表来源
- [pom.xml:1-200](file://pom.xml#L1-L200)
- [crm-app/pom.xml:1-100](file://crm-app/pom.xml#L1-L100)
- [crm-auth/pom.xml:1-100](file://crm-auth/pom.xml#L1-L100)
- [crm-base/pom.xml:1-100](file://crm-base/pom.xml#L1-L100)
- [crm-file/pom.xml:1-100](file://crm-file/pom.xml#L1-L100)
章节来源
- [pom.xml:1-200](file://pom.xml#L1-L200)
## 性能考虑
- 数据库
- 使用 MyBatis-Plus 分页插件，避免全表扫描
- 合理索引设计，关注高频查询字段
- 批量操作使用 InsertBatchOnDuplicateKeyUpdate 提升写入效率
- 缓存
- 热点数据（如字典、权限树）放入 Redis，降低数据库压力
- 设置合理的过期策略与缓存穿透防护
- 文件服务
- 大文件分片上传，减少内存占用与网络失败影响
- 清理任务定期回收未完成分片，释放存储空间
- 序列化
- Jackson 统一时间与时区处理，避免反序列化开销
- 监控与追踪
- TraceIdFilter 为全链路添加追踪 ID，便于问题定位
[本节为通用指导，不直接分析具体文件]
## 故障排除指南
- 启动失败
- 检查 JDK 版本是否满足要求（建议 11+），Maven 版本 3.6+
- 确认 application.yml 中数据库、Redis、MinIO 地址、账号、密码正确
- 查看控制台日志中的 Bean 冲突或包扫描路径错误
- 数据库连接失败
- 验证 MySQL 服务状态、端口、用户名、密码与字符集
- 确保已执行数据库初始化脚本（若项目提供）
- 检查防火墙与安全组策略
- Redis 连接失败
- 检查 Redis 服务状态、端口、密码与网络连通性
- 确认 RedisConfig 序列化与超时配置合理
- 文件上传失败
- 检查 MinIO 服务可达性与桶是否存在
- 确认 FileProperties 与 MinioConfig 配置一致
- 观察分片清理任务是否正常运行
- 权限或登录异常
- 确认 DataInitializer 是否成功执行，基础数据是否完整
- 检查 JWT 密钥与过期时间配置
- 查看 SecurityConfig 白名单与拦截规则是否符合预期
- 常见问题排查步骤
- 开启 DEBUG 日志，定位具体异常堆栈
- 使用 Knife4j 调试接口，验证入参与返回值
- 通过 TraceId 在日志系统中检索全链路日志
章节来源
- [crm-base/src/main/java/com/crm/base/advice/GlobalExceptionHandlerAdvice.java:1-200](file://crm-base/src/main/java/com/crm/base/advice/GlobalExceptionHandlerAdvice.java#L1-L200)
- [crm-base/src/main/java/com/crm/base/filter/TraceIdFilter.java:1-200](file://crm-base/src/main/java/com/crm/base/filter/TraceIdFilter.java#L1-L200)
- [crm-auth/src/main/java/com/crm/auth/config/DataInitializer.java:1-200](file://crm-auth/src/main/java/com/crm/auth/config/DataInitializer.java#L1-L200)
- [crm-auth/src/main/java/com/crm/auth/config/SecurityConfig.java:1-200](file://crm-auth/src/main/java/com/crm/auth/config/SecurityConfig.java#L1-L200)
- [crm-base/src/main/java/com/crm/base/config/RedisConfig.java:1-200](file://crm-base/src/main/java/com/crm/base/config/RedisConfig.java#L1-L200)
- [crm-file/src/main/java/com/crm/file/config/MinioConfig.java:1-200](file://crm-file/src/main/java/com/crm/file/config/MinioConfig.java#L1-L200)
- [crm-file/src/main/java/com/crm/file/task/OrphanChunkCleanupTask.java:1-200](file://crm-file/src/main/java/com/crm/file/task/OrphanChunk清理任务.java#L1-L200)
## 结论
通过以上步骤，你可以在本地快速搭建并运行 CRM 系统。建议在熟悉基础流程后，逐步扩展业务模块，结合 Knife4j 进行接口调试，利用 TraceId 与日志系统进行问题定位，并根据实际场景优化数据库与缓存策略。
[本节为总结性内容，不直接分析具体文件]
## 附录
### 环境要求
- JDK：建议使用 11 或以上版本
- Maven：3.6 或以上版本
- 数据库：MySQL 5.7 或 8.0（根据驱动与方言选择）
- 缓存：Redis 5.0 或以上版本
- 对象存储：MinIO（用于文件存储）
[本节为通用指导，不直接分析具体文件]
### 项目克隆与构建
- 克隆仓库到本地
- 在根目录执行 Maven 构建命令，编译所有模块
- 若遇到依赖下载失败，检查网络与镜像源配置
[本节为通用指导，不直接分析具体文件]
### 配置文件设置
- 修改各模块 application.yml 中的数据库、Redis、MinIO 等连接信息
- 如需调整端口、日志级别、跨域策略，请在对应配置文件中更新
- 认证相关参数（如 JWT 密钥、过期时间）在认证模块配置中设置
章节来源
- [crm-app/src/main/resources/application.yml:1-200](file://crm-app/src/main/resources/application.yml#L1-L200)
- [crm-auth/src/main/resources/application.yml:1-200](file://crm-auth/src/main/resources/application.yml#L1-L200)
- [crm-base/src/main/java/com/crm/base/config/RedisConfig.java:1-200](file://crm-base/src/main/java/com/crm/base/config/RedisConfig.java#L1-L200)
- [crm-base/src/main/java/com/crm/base/config/MybatisPlusConfig.java:1-200](file://crm-base/src/main/java/com/crm/base/config/MybatisPlusConfig.java#L1-L200)
- [crm-base/src/main/java/com/crm/base/config/JacksonConfig.java:1-200](file://crm-base/src/main/java/com/crm/base/config/JacksonConfig.java#L1-L200)
- [crm-base/src/main/java/com/crm/base/config/Knife4jConfig.java:1-200](file://crm-base/src/main/java/com/crm/base/config/Knife4jConfig.java#L1-L200)
- [crm-base/src/main/java/com/crm/base/config/CorsConfig.java:1-200](file://crm-base/src/main/java/com/crm/base/config/CorsConfig.java#L1-L200)
- [crm-file/src/main/java/com/crm/file/config/FileProperties.java:1-200](file://crm-file/src/main/java/com/crm/file/config/FileProperties.java#L1-L200)
- [crm-file/src/main/java/com/crm/file/config/MinioConfig.java:1-200](file://crm-file/src/main/java/com/crm/file/config/MinioConfig.java#L1-L200)
### 数据库初始化
- 若项目提供 SQL 脚本，请先在 MySQL 中执行以创建表结构与基础数据
- 若无脚本，可参考 DataInitializer 的逻辑，在启动时由应用创建必要的基础数据（如角色、菜单、部门等）
- 确认数据库字符集与排序规则符合中文支持要求
章节来源
- [crm-auth/src/main/java/com/crm/auth/config/DataInitializer.java:1-200](file://crm-auth/src/main/java/com/crm/auth/config/DataInitializer.java#L1-L200)
### 服务启动流程
- 启动 crm-app 模块的主类 CrmAppApplication
- 应用加载配置并装配各模块组件
- 等待数据库、Redis、MinIO 就绪后，服务对外暴露接口
- 可通过 Knife4j 页面验证接口可用性
章节来源
- [crm-app/src/main/java/com/crm/app/CrmAppApplication.java:1-200](file://crm-app/src/main/java/com/crm/app/CrmAppApplication.java#L1-L200)
- [crm-app/src/main/resources/application.yml:1-200](file://crm-app/src/main/resources/application.yml#L1-L200)
### 基本开发工作流程
- 新增业务模块：在相应模块下创建 Controller、Service、Mapper 与 Entity
- 使用 BaseServiceImpl 与 CrmBaseMapper 简化 CRUD 操作
- 通过 Knife4j 调试接口，结合 TraceId 定位问题
- 提交前执行单元测试与静态检查，保证代码质量
章节来源
- [crm-base/src/main/java/com/crm/base/service/impl/BaseServiceImpl.java:1-200](file://crm-base/src/main/java/com/crm/base/service/impl/BaseServiceImpl.java#L1-L200)
- [crm-base/src/main/java/com/crm/base/mapper/CrmBaseMapper.java:1-200](file://crm-base/src/main/java/com/crm/base/mapper/CrmBaseMapper.java#L1-L200)
- [crm-base/src/main/java/com/crm/base/config/Knife4jConfig.java:1-200](file://crm-base/src/main/java/com/crm/base/config/Knife4jConfig.java#L1-L200)
- [crm-base/src/main/java/com/crm/base/filter/TraceIdFilter.java:1-200](file://crm-base/src/main/java/com/crm/base/filter/TraceIdFilter.java#L1-L200)