# 开发指南

<cite>
**本文档引用的文件**   
- [CrmAppApplication.java](file://crm-app/src/main/java/com/crm/app/CrmAppApplication.java)
- [application.yml](file://crm-app/src/main/resources/application.yml)
- [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)
- [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)
- [AuthUserServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/AuthUserServiceImpl.java)
- [SysDeptServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/SysDeptServiceImpl.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)
- [DataScopeInterceptor.java](file://crm-auth/src/main/java/com/crm/auth/security/DataScopeInterceptor.java)
- [BaseEntity.java](file://crm-base/src/main/java/com/crm/base/domain/entity/BaseEntity.java)
- [OwnedEntity.java](file://crm-base/src/main/java/com/crm/base/domain/entity/OwnedEntity.java)
- [Result.java](file://crm-base/src/main/java/com/crm/base/domain/result/Result.java)
- [PageResult.java](file://crm-base/src/main/java/com/crm/base/domain/result/PageResult.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)
- [SnowflakeIdWorker.java](file://crm-base/src/main/java/com/crm/base/config/SnowflakeIdWorker.java)
- [MetaObjectFillHandler.java](file://crm-base/src/main/java/com/crm/base/config/MetaObjectFillHandler.java)
- [DataScope.java](file://crm-base/src/main/java/com/crm/base/annotation/DataScope.java)
- [BaseServiceImpl.java](file://crm-base/src/main/java/com/crm/base/service/impl/BaseServiceImpl.java)
- [IBaseService.java](file://crm-base/src/main/java/com/crm/base/service/IBaseService.java)
- [FileApiImpl.java](file://crm-file/src/main/java/com/crm/file/service/impl/FileApiImpl.java)
- [FileInfoServiceImpl.java](file://crm-file/src/main/java/com/crm/file/service/impl/FileInfoServiceImpl.java)
- [FileController.java](file://crm-file/src/main/java/com/crm/file/controller/FileController.java)
- [OrphanChunkCleanupTask.java](file://crm-file/src/main/java/com/crm/file/task/OrphanChunkCleanupTask.java)
</cite>

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

## 简介
本指南面向新加入的开发者，提供从环境搭建到业务模块快速落地的完整路径。内容涵盖：
- 项目开发规范、代码风格与命名约定
- Git 工作流与协作流程
- 基于基础框架（Base 层）快速实现实体、Service、Controller、数据访问层
- 高级特性：自定义注解、AOP 切面、消息队列集成、定时任务
- 代码审查清单、性能优化建议与安全编码规范

目标是确保代码质量与团队协作效率，帮助开发者在统一规范下高效交付。

## 项目结构
本项目采用多模块 Maven 工程，按领域与职责划分：
- crm-app：应用启动入口与全局配置
- crm-base：通用能力（基础实体、结果封装、异常处理、安全上下文、MyBatis Plus、Redis、雪花ID等）
- crm-auth：认证授权与系统管理（用户、角色、菜单、部门、权限、数据范围）
- crm-file：文件服务（上传、分片、预览、清理任务）

```mermaid
graph TB
subgraph "应用层"
APP["crm-app<br/>启动入口"]
end
subgraph "基础能力"
BASE["crm-base<br/>通用组件"]
end
subgraph "业务域"
AUTH["crm-auth<br/>认证与系统管理"]
FILE["crm-file<br/>文件服务"]
end
APP --> AUTH
APP --> FILE
AUTH --> BASE
FILE --> BASE
```

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

## 核心组件
- 基础实体与分页结果
  - BaseEntity：公共字段（如创建时间、更新时间等）
  - OwnedEntity：数据所有权扩展（用于数据范围控制）
  - Result/PageResult：统一响应体与分页封装
- 异常与全局处理
  - GlobalExceptionHandlerAdvice：统一异常捕获与错误码返回
- MyBatis Plus 与数据库
  - MybatisPlusConfig：分页插件、元对象填充处理器等
  - MetaObjectFillHandler：自动填充审计字段
  - SnowflakeIdWorker：分布式主键生成
- Redis 缓存
  - RedisConfig：序列化策略与连接配置
- 安全上下文与数据范围
  - DataScope 注解与拦截器：实现数据可见性控制
  - SecurityUtils：获取当前登录用户信息

**章节来源**
- [BaseEntity.java](file://crm-base/src/main/java/com/crm/base/domain/entity/BaseEntity.java)
- [OwnedEntity.java](file://crm-base/src/main/java/com/crm/base/domain/entity/OwnedEntity.java)
- [Result.java](file://crm-base/src/main/java/com/crm/base/domain/result/Result.java)
- [PageResult.java](file://crm-base/src/main/java/com/crm/base/domain/result/PageResult.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)
- [MetaObjectFillHandler.java](file://crm-base/src/main/java/com/crm/base/config/MetaObjectFillHandler.java)
- [SnowflakeIdWorker.java](file://crm-base/src/main/java/com/crm/base/config/SnowflakeIdWorker.java)
- [RedisConfig.java](file://crm-base/src/main/java/com/crm/base/config/RedisConfig.java)
- [DataScope.java](file://crm-base/src/main/java/com/crm/base/annotation/DataScope.java)

## 架构总览
整体分层清晰：Controller -> Service -> Mapper -> DB，辅以安全、缓存、分页、审计等横切能力。

```mermaid
sequenceDiagram
participant Client as "客户端"
participant Controller as "控制器(Controller)"
participant Service as "服务层(Service)"
participant Mapper as "数据访问(Mapper)"
participant DB as "数据库"
participant Cache as "缓存(Redis)"
Client->>Controller : "HTTP 请求"
Controller->>Service : "调用业务方法"
Service->>Cache : "可选：读取/写入缓存"
Service->>Mapper : "CRUD/查询"
Mapper->>DB : "SQL 执行"
DB-->>Mapper : "结果集"
Mapper-->>Service : "实体/DTO"
Service-->>Controller : "业务结果"
Controller-->>Client : "统一响应(Result)"
```

**图表来源** 
- [AuthController.java](file://crm-auth/src/main/java/com/crm/auth/controller/AuthController.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)
- [BaseServiceImpl.java](file://crm-base/src/main/java/com/crm/base/service/impl/BaseServiceImpl.java)

## 详细组件分析

### 认证与鉴权（Auth）
- 控制器
  - AuthController：登录、登出、用户信息等接口
  - SystemController：系统级接口（如字典、配置等）
- 安全配置
  - SecurityConfig：Spring Security 配置、放行路径、过滤器链
  - JwtAuthenticationFilter：JWT 解析与认证上下文设置
  - TokenService：令牌签发、校验、刷新
  - DataScopeInterceptor：数据范围拦截，结合 @DataScope 注解
- 服务层
  - IAuthService / AuthServiceImpl：登录逻辑、第三方登录、权限加载
  - IAuthUserService / AuthUserServiceImpl：用户信息查询、密码校验
  - ISysDeptService / SysDeptServiceImpl：部门树构建与缓存

```mermaid
classDiagram
class AuthController {
+登录()
+登出()
+获取用户信息()
}
class AuthService {
+登录(参数)
+第三方登录(类型, 参数)
+加载权限(用户)
}
class AuthUserServiceImpl {
+校验密码()
+查询用户()
}
class SecurityConfig {
+配置过滤器链()
+配置授权规则()
}
class JwtAuthenticationFilter {
+解析JWT()
+设置认证上下文()
}
class TokenService {
+签发()
+校验()
+刷新()
}
class DataScopeInterceptor {
+拦截请求()
+注入数据范围条件()
}
AuthController --> AuthService : "调用"
AuthService --> AuthUserServiceImpl : "使用"
SecurityConfig --> JwtAuthenticationFilter : "注册"
SecurityConfig --> DataScopeInterceptor : "注册"
```

**图表来源** 
- [AuthController.java](file://crm-auth/src/main/java/com/crm/auth/controller/AuthController.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)
- [AuthUserServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/AuthUserServiceImpl.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)
- [DataScopeInterceptor.java](file://crm-auth/src/main/java/com/crm/auth/security/DataScopeInterceptor.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)
- [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)
- [DataScopeInterceptor.java](file://crm-auth/src/main/java/com/crm/auth/security/DataScopeInterceptor.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)
- [AuthUserServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/AuthUserServiceImpl.java)
- [SysDeptServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/SysDeptServiceImpl.java)

### 文件服务（File）
- 控制器
  - FileController：上传、下载、分片初始化、断点续传、预览
- 服务层
  - FileApiImpl：对外文件 API 实现（对接 MinIO/本地存储）
  - FileInfoServiceImpl：文件元信息管理、状态流转
- 定时任务
  - OrphanChunkCleanupTask：清理孤儿分片，避免磁盘膨胀

```mermaid
flowchart TD
Start(["开始"]) --> Init["初始化分片会话"]
Init --> Upload["上传分片"]
Upload --> Merge{"是否全部上传完成?"}
Merge --> |否| Upload
Merge --> |是| SaveMeta["保存文件元信息"]
SaveMeta --> Preview["生成预览链接"]
Preview --> Done(["结束"])
```

**图表来源** 
- [FileController.java](file://crm-file/src/main/java/com/crm/file/controller/FileController.java)
- [FileApiImpl.java](file://crm-file/src/main/java/com/crm/file/service/impl/FileApiImpl.java)
- [FileInfoServiceImpl.java](file://crm-file/src/main/java/com/crm/file/service/impl/FileInfoServiceImpl.java)
- [OrphanChunkCleanupTask.java](file://crm-file/src/main/java/com/crm/file/task/OrphanChunkCleanupTask.java)

**章节来源**
- [FileController.java](file://crm-file/src/main/java/com/crm/file/controller/FileController.java)
- [FileApiImpl.java](file://crm-file/src/main/java/com/crm/file/service/impl/FileApiImpl.java)
- [FileInfoServiceImpl.java](file://crm-file/src/main/java/com/crm/file/service/impl/FileInfoServiceImpl.java)
- [OrphanChunkCleanupTask.java](file://crm-file/src/main/java/com/crm/file/task/OrphanChunkCleanupTask.java)

### 基础服务与通用能力（Base）
- BaseServiceImpl：通用 CRUD、分页、批量操作封装
- IBaseService：通用接口定义
- 元对象填充：MetaObjectFillHandler 自动填充创建人、创建时间等
- 雪花ID：SnowflakeIdWorker 分布式主键
- Redis：RedisConfig 统一序列化与过期策略
- 数据范围：@DataScope 注解配合拦截器实现行级数据隔离

```mermaid
classDiagram
class BaseServiceImpl {
+新增()
+更新()
+删除()
+分页查询()
+批量操作()
}
class IBaseService {
<<interface>>
}
class MetaObjectFillHandler {
+填充审计字段()
}
class SnowflakeIdWorker {
+生成ID()
}
class RedisConfig {
+序列化配置()
+连接配置()
}
class DataScope {
<<annotation>>
}
BaseServiceImpl ..|> IBaseService
BaseServiceImpl --> MetaObjectFillHandler : "使用"
BaseServiceImpl --> SnowflakeIdWorker : "使用"
BaseServiceImpl --> RedisConfig : "使用"
```

**图表来源** 
- [BaseServiceImpl.java](file://crm-base/src/main/java/com/crm/base/service/impl/BaseServiceImpl.java)
- [IBaseService.java](file://crm-base/src/main/java/com/crm/base/service/IBaseService.java)
- [MetaObjectFillHandler.java](file://crm-base/src/main/java/com/crm/base/config/MetaObjectFillHandler.java)
- [SnowflakeIdWorker.java](file://crm-base/src/main/java/com/crm/base/config/SnowflakeIdWorker.java)
- [RedisConfig.java](file://crm-base/src/main/java/com/crm/base/config/RedisConfig.java)
- [DataScope.java](file://crm-base/src/main/java/com/crm/base/annotation/DataScope.java)

**章节来源**
- [BaseServiceImpl.java](file://crm-base/src/main/java/com/crm/base/service/impl/BaseServiceImpl.java)
- [IBaseService.java](file://crm-base/src/main/java/com/crm/base/service/IBaseService.java)
- [MetaObjectFillHandler.java](file://crm-base/src/main/java/com/crm/base/config/MetaObjectFillHandler.java)
- [SnowflakeIdWorker.java](file://crm-base/src/main/java/com/crm/base/config/SnowflakeIdWorker.java)
- [RedisConfig.java](file://crm-base/src/main/java/com/crm/base/config/RedisConfig.java)
- [DataScope.java](file://crm-base/src/main/java/com/crm/base/annotation/DataScope.java)

## 依赖关系分析
- 模块依赖
  - crm-app 依赖 crm-auth、crm-file
  - crm-auth、crm-file 依赖 crm-base
- 运行时依赖
  - Spring Security、JWT、MyBatis Plus、Redis、MinIO（文件服务）
- 关键耦合点
  - 安全上下文与数据范围贯穿各模块
  - 统一异常处理与结果封装在 base 层

```mermaid
graph LR
APP["crm-app"] --> AUTH["crm-auth"]
APP --> FILE["crm-file"]
AUTH --> BASE["crm-base"]
FILE --> BASE
```

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

## 性能考虑
- 数据库
  - 合理使用索引，避免全表扫描；分页查询限制返回字段
  - 批量操作优先使用批量插入/更新，减少往返次数
- 缓存
  - 热点数据入缓存（如部门树、字典），注意一致性策略与过期时间
  - 避免大对象缓存，合理序列化
- 异步与任务
  - 耗时操作异步化（如文件处理、通知发送）
  - 定时任务幂等设计，失败重试与告警
- 连接与线程池
  - 合理配置线程池大小与超时时间，避免阻塞
  - 监控慢 SQL，定期优化

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

## 故障排查指南
- 统一异常
  - GlobalExceptionHandlerAdvice 捕获并返回标准错误码与消息
- 常见错误
  - 认证失败：检查 JWT 配置、过滤器链顺序、TokenService 签名密钥
  - 数据范围异常：确认 @DataScope 注解与拦截器生效，上下文用户信息正确
  - 文件上传失败：检查 MinIO 配置、分片大小、临时目录权限
- 日志与追踪
  - 开启必要日志级别，定位问题链路
  - 使用 TraceId 贯穿请求链路

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

## 结论
通过统一的 Base 能力与清晰的模块边界，团队可以快速扩展业务功能。遵循本指南中的规范与实践，可显著提升代码质量、可维护性与协作效率。建议在迭代中持续完善监控、测试与文档，保障系统稳定演进。

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

## 附录

### 开发规范与命名约定
- 包与类
  - 包名小写，按模块划分；类名大驼峰，动词+名词表示行为
  - 接口以 I 开头，实现类以 Impl 结尾
- 方法与变量
  - 方法名动宾结构，布尔方法用 is/has/can 前缀
  - 常量全大写加下划线，枚举值全大写
- 注释与文档
  - 复杂逻辑添加行内注释；接口使用 Swagger/Knife4j 注解描述

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

### Git 工作流
- 分支模型
  - main：生产分支；develop：开发主干；feature/*：功能分支；hotfix/*：热修复
- 提交规范
  - 类型：feat/fix/docs/style/refactor/test/chore
  - 格式：type(scope): subject
- 合并流程
  - 功能分支合并至 develop，PR 需至少一名 Reviewer 批准
  - 发布前打 tag，main 分支仅允许受保护合并

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

### 快速上手：从零到一开发业务模块
- 创建实体
  - 继承 BaseEntity/OwnedEntity，标注表映射与字段属性
- 创建 Mapper
  - 继承 CrmBaseMapper，定义必要方法或沿用默认 CRUD
- 创建 Service
  - 继承 BaseServiceImpl，实现业务逻辑，必要时注入缓存
- 创建 Controller
  - 定义 REST 接口，统一返回 Result/PageResult
- 数据范围与权限
  - 需要数据隔离的方法上添加 @DataScope，并在拦截器中生效
- 示例参考
  - 认证模块的 Controller/Service/Mapper 组织方式

**章节来源**
- [BaseEntity.java](file://crm-base/src/main/java/com/crm/base/domain/entity/BaseEntity.java)
- [OwnedEntity.java](file://crm-base/src/main/java/com/crm/base/domain/entity/OwnedEntity.java)
- [BaseServiceImpl.java](file://crm-base/src/main/java/com/crm/base/service/impl/BaseServiceImpl.java)
- [AuthController.java](file://crm-auth/src/main/java/com/crm/auth/controller/AuthController.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)

### 高级特性
- 自定义注解
  - 使用 @DataScope 实现数据范围控制；可扩展审计、限流等注解
- AOP 切面
  - 基于注解的切面实现日志、性能统计、权限校验等横切逻辑
- 消息队列集成
  - 引入 MQ 客户端，封装生产者/消费者模板，保证可靠投递与幂等消费
- 定时任务
  - 使用 @Scheduled 或任务调度框架，实现幂等与失败重试

**章节来源**
- [DataScope.java](file://crm-base/src/main/java/com/crm/base/annotation/DataScope.java)
- [OrphanChunkCleanupTask.java](file://crm-file/src/main/java/com/crm/file/task/OrphanChunkCleanupTask.java)

### 代码审查清单
- 结构与可读性
  - 包结构清晰，类职责单一，方法长度适中
- 安全性
  - 输入校验、越权防护、敏感信息脱敏、SQL 防注入
- 健壮性
  - 异常处理完备，空值与边界条件覆盖
- 性能
  - 避免 N+1 查询，合理使用缓存与索引
- 可测试性
  - 单元测试覆盖核心逻辑，Mock 外部依赖

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

### 安全编码规范
- 认证与授权
  - 最小权限原则，接口级鉴权，敏感操作二次确认
- 数据安全
  - 传输加密（HTTPS）、存储加密（敏感字段）、日志脱敏
- 依赖安全
  - 定期升级依赖，扫描漏洞，禁用不安全算法

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