crm-backend-matt/.qoder/repowiki/zh/content/项目概览/快速开始.md

# 快速开始

<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/resources/application.yml](file://crm-app/src/main/resources/application.yml)
- [crm-auth/src/main/resources/application.yml](file://crm-auth/src/main/resources/application.yml)
- [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/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/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-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-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/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)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能注意事项](#性能注意事项)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录：30分钟快速上手清单](#附录30分钟快速上手清单)

## 简介
本指南面向首次接触 CRM 后端的开发者，目标是在 30 分钟内完成环境准备、项目启动与基础 API 验证。你将了解：
- 运行所需的外部依赖（JDK、MySQL、Redis、MinIO）及版本建议
- 多模块项目的结构与职责划分
- 关键配置项（数据库、Redis、文件存储）的修改要点
- 常见问题的定位方法与调试技巧
- 用户登录、文件上传等核心 API 的调用示例

## 项目结构
本项目采用 Maven 多模块架构，核心模块如下：
- crm-app：应用入口与聚合模块
- crm-base：公共基础能力（异常、通用实体、工具类、MyBatis Plus、Redis、Knife4j 等）
- crm-auth：认证授权（用户、角色、菜单、权限、JWT、数据权限）
- crm-file：文件服务（分片上传、断点续传、MinIO 集成、在线预览）

```mermaid
graph TB
subgraph "应用层"
APP["crm-app<br/>应用入口"]
end
subgraph "业务模块"
AUTH["crm-auth<br/>认证与权限"]
FILE["crm-file<br/>文件服务"]
end
subgraph "基础模块"
BASE["crm-base<br/>公共基础能力"]
end
subgraph "外部依赖"
MYSQL["MySQL"]
REDIS["Redis"]
MINIO["MinIO"]
end
APP --> AUTH
APP --> FILE
AUTH --> BASE
FILE --> BASE
AUTH --> MYSQL
AUTH --> REDIS
FILE --> MINIO
```

**图表来源** 
- [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)

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

## 核心组件
- 应用入口与装配
  - 应用主类位于应用模块中，负责启动 Spring Boot 应用并加载各模块配置。
- 认证与权限
  - 提供登录、鉴权、JWT 签发与校验、数据权限拦截等功能。
- 文件服务
  - 提供文件上传（支持分片）、下载、元信息管理与 MinIO 存储对接。
- 基础能力
  - 统一返回体、全局异常处理、MyBatis Plus 配置、Redis 配置、Knife4j 接口文档等。

**章节来源**
- [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/RedisConfig.java](file://crm-base/src/main/java/com/crm/base/config/RedisConfig.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-file/src/main/java/com/crm/file/config/MinioConfig.java](file://crm-file/src/main/java/com/crm/file/config/MinioConfig.java)

## 架构总览
下图展示了请求从客户端到后端各层的流转路径，以及对外部依赖的访问关系。

```mermaid
sequenceDiagram
participant Client as "客户端"
participant Auth as "认证模块(Auth)"
participant File as "文件模块(File)"
participant Base as "基础模块(Base)"
participant DB as "MySQL"
participant Cache as "Redis"
participant OSS as "MinIO"
Client->>Auth : "POST /auth/login"
Auth->>DB : "查询用户与角色"
DB-->>Auth : "用户信息"
Auth->>Cache : "写入会话/缓存"
Cache-->>Auth : "成功"
Auth-->>Client : "返回令牌"
Client->>File : "POST /file/upload (分片)"
File->>OSS : "上传分片"
OSS-->>File : "分片结果"
File->>DB : "记录文件元信息"
DB-->>File : "持久化成功"
File-->>Client : "返回上传进度/结果"
```

**图表来源** 
- [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-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)

## 详细组件分析

### 认证与授权（Auth）
- 功能要点
  - 登录流程：接收用户名/密码或第三方身份，校验通过后签发 JWT。
  - 安全过滤：基于过滤器链进行 Token 校验与上下文注入。
  - 数据权限：通过注解与拦截器实现数据范围控制。
- 关键类与职责
  - 控制器：暴露登录与系统相关接口
  - 服务：认证逻辑、用户信息查询、权限计算
  - 安全：过滤器、Token 生成与解析、异常处理器
- 典型调用序列（登录）

```mermaid
sequenceDiagram
participant C as "客户端"
participant AC as "AuthController"
participant AS as "AuthServiceImpl"
participant U as "用户表"
participant R as "角色/菜单表"
participant T as "TokenService"
C->>AC : "POST /auth/login"
AC->>AS : "执行登录校验"
AS->>U : "查询用户"
U-->>AS : "用户记录"
AS->>R : "加载角色与菜单"
R-->>AS : "权限集合"
AS->>T : "生成JWT"
T-->>AS : "令牌"
AS-->>AC : "登录结果"
AC-->>C : "返回令牌与用户信息"
```

**图表来源** 
- [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/security/TokenService.java](file://crm-auth/src/main/java/com/crm/auth/security/TokenService.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/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)

### 文件服务（File）
- 功能要点
  - 支持分片上传、断点续传、合并与清理孤儿分片任务
  - 与 MinIO 对象存储对接，管理文件元数据
- 关键类与职责
  - 控制器：上传、下载、查询接口
  - 服务：分片处理、合并、元数据持久化
  - 配置：MinIO 连接、文件属性
- 上传流程概览

```mermaid
flowchart TD
Start(["开始"]) --> Init["初始化上传会话"]
Init --> UploadChunk["上传分片"]
UploadChunk --> ChunkOK{"分片是否全部上传?"}
ChunkOK --> |否| UploadChunk
ChunkOK --> |是| Merge["合并分片"]
Merge --> SaveMeta["保存文件元信息"]
SaveMeta --> Done(["结束"])
```

**图表来源** 
- [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/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/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/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)

### 基础能力（Base）
- MyBatis Plus：统一分页、自动填充、SQL 注入器等
- Redis：序列化、连接池、过期策略等
- Knife4j：API 文档与调试
- 全局异常与统一返回体

**章节来源**
- [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/RedisConfig.java](file://crm-base/src/main/java/com/crm/base/config/RedisConfig.java)

## 依赖分析
- 构建与模块依赖
  - 根 pom 定义多模块与公共依赖版本
  - 各子模块声明自身依赖，如 auth 依赖 base，file 依赖 base
- 运行时依赖
  - MySQL：用于用户、角色、菜单、文件元信息等持久化
  - Redis：用于会话、缓存、分布式锁等
  - MinIO：用于文件对象存储

```mermaid
graph LR
ROOT["根POM"] --> APP["crm-app"]
ROOT --> AUTH["crm-auth"]
ROOT --> BASE["crm-base"]
ROOT --> FILE["crm-file"]
AUTH --> BASE
FILE --> BASE
AUTH --> MYSQL["MySQL"]
AUTH --> REDIS["Redis"]
FILE --> MINIO["MinIO"]
```

**图表来源** 
- [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)

**章节来源**
- [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)

## 性能注意事项
- 数据库
  - 合理设置连接池大小与超时；为常用查询字段建立索引
  - 使用分页避免全量拉取；对热点数据启用二级缓存
- Redis
  - 合理设置 key 过期时间；避免大 value 与热 key
  - 使用 pipeline 批量操作减少网络往返
- 文件上传
  - 分片大小与并发数需根据网络与磁盘 IO 调优
  - 合并阶段注意内存占用，必要时流式处理
- 安全与鉴权
  - JWT 签名算法与密钥长度需兼顾安全与性能
  - 权限校验尽量走缓存，降低数据库压力

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

## 故障排查指南
- 无法连接数据库
  - 检查 application.yml 中的数据库 URL、用户名、密码是否正确
  - 确认 MySQL 服务已启动且端口可达
  - 查看日志中是否有连接拒绝或认证失败
- Redis 连接失败
  - 检查 Redis 地址、端口、密码
  - 确认防火墙与安全组放行
  - 观察 Redis 日志是否有连接限制或 OOM
- MinIO 上传失败
  - 核对 endpoint、accessKey、secretKey、bucket 名称
  - 确认 bucket 存在且具有读写权限
  - 检查网络连通性与代理设置
- 登录失败
  - 确认用户是否存在且状态正常
  - 检查密码加密方式与盐值配置
  - 查看 Token 生成与校验日志
- 接口文档不可用
  - 确认 Knife4j 配置未禁用
  - 检查 Swagger/OpenAPI 扫描包路径

**章节来源**
- [crm-base/src/main/java/com/crm/base/config/RedisConfig.java](file://crm-base/src/main/java/com/crm/base/config/RedisConfig.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-auth/src/main/java/com/crm/auth/config/SecurityConfig.java](file://crm-auth/src/main/java/com/crm/auth/config/SecurityConfig.java)

## 结论
通过本指南，你可以在 30 分钟内完成 CRM 后端的环境搭建、项目启动与基础 API 验证。后续可在此基础上扩展业务模块，遵循现有分层与规范，确保代码质量与可维护性。

## 附录：30分钟快速上手清单
- 环境准备
  - JDK：建议使用 17（与 Spring Boot 3.x 兼容）
  - MySQL：8.0+，创建数据库与字符集 utf8mb4
  - Redis：6.2+，开启基本认证（可选）
  - MinIO：单机或集群均可，创建对应 bucket
- 克隆与构建
  - 克隆仓库至本地
  - 在根目录执行 Maven 构建与安装
- 首次启动
  - 修改各模块 application.yml 中的数据库、Redis、MinIO 配置
  - 启动应用主类
  - 访问接口文档地址进行验证
- 基础 API 示例
  - 用户登录：POST /auth/login，提交用户名与密码，获取令牌
  - 文件上传：POST /file/upload，按分片协议上传，完成后合并并返回结果
- 常见问题
  - 参考“故障排查指南”逐项检查依赖服务与配置

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