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.
1 Commit
1 Branch
0 Tags
405 MiB
Tree: 6329a6ba74
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '6329a6ba74'
${ noResults }
crm-backend-matt/.qoder/repowiki/zh/content/项目概览/模块说明/认证服务模块(crm-auth)/认证服务模块(crm-auth).md

600 lines
35 KiB
Raw Normal View History

first-commit
1 month ago
# 认证服务模块(crm-auth)
<cite>
**本文引用的文件**
- [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)
- [AuthProperties.java](file://crm-auth/src/main/java/com/crm/auth/config/AuthProperties.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)
- [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)
- [AuthLoginUser.java](file://crm-auth/src/main/java/com/crm/auth/security/AuthLoginUser.java)
- [DataScopeInterceptor.java](file://crm-auth/src/main/java/com/crm/auth/security/DataScopeInterceptor.java)
- [DataScopeTables.java](file://crm-auth/src/main/java/com/crm/auth/security/DataScopeTables.java)
- [SecurityExceptionHandlers.java](file://crm-auth/src/main/java/com/crm/auth/security/SecurityExceptionHandlers.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)
- [IAuthUserService.java](file://crm-auth/src/main/java/com/crm/auth/service/IAuthUserService.java)
- [AuthUserServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/AuthUserServiceImpl.java)
- [IAuthIdentityService.java](file://crm-auth/src/main/java/com/crm/auth/service/IAuthIdentityService.java)
- [AuthIdentityServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/AuthIdentityServiceImpl.java)
- [ISysRoleService.java](file://crm-auth/src/main/java/com/crm/auth/service/ISysRoleService.java)
- [SysRoleServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/SysRoleServiceImpl.java)
- [ISysMenuService.java](file://crm-auth/src/main/java/com/crm/auth/service/ISysMenuService.java)
- [SysMenuServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/SysMenuServiceImpl.java)
- [ISysDeptService.java](file://crm-auth/src/main/java/com/crm/auth/service/ISysDeptService.java)
- [SysDeptServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/SysDeptServiceImpl.java)
- [DingTalkAuthClient.java](file://crm-auth/src/main/java/com/crm/auth/service/client/DingTalkAuthClient.java)
- [ThirdPartyAuthClient.java](file://crm-auth/src/main/java/com/crm/auth/service/client/ThirdPartyAuthClient.java)
- [ThirdPartyAuthClientFactory.java](file://crm-auth/src/main/java/com/crm/auth/service/client/ThirdPartyAuthClientFactory.java)
- [ThirdPartyUserInfo.java](file://crm-auth/src/main/java/com/crm/auth/service/client/ThirdPartyUserInfo.java)
- [LoginParam.java](file://crm-auth/src/main/java/com/crm/auth/domain/param/LoginParam.java)
- [LoginResultDTO.java](file://crm-auth/src/main/java/com/crm/auth/domain/dto/LoginResultDTO.java)
- [UserInfoDTO.java](file://crm-auth/src/main/java/com/crm/auth/domain/dto/UserInfoDTO.java)
- [AuthUser.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/AuthUser.java)
- [AuthIdentity.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/AuthIdentity.java)
- [SysRole.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysRole.java)
- [SysMenu.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysMenu.java)
- [SysDept.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysDept.java)
- [SysUserRole.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysUserRole.java)
- [SysRoleMenu.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysRoleMenu.java)
- [SysUserDept.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysUserDept.java)
- [DataScopeEnum.java](file://crm-auth/src/main/java/com/crm/auth/domain/enums/DataScopeEnum.java)
- [IdentityTypeEnum.java](file://crm-auth/src/main/java/com/crm/auth/domain/enums/IdentityTypeEnum.java)
- [MenuTypeEnum.java](file://crm-auth/src/main/java/com/crm/auth/domain/enums/MenuTypeEnum.java)
- [AuthConstants.java](file://crm-auth/src/main/java/com/crm/auth/constant/AuthConstants.java)
- [application.yml](file://crm-auth/src/main/resources/application.yml)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考虑](#性能考虑)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)
## 简介
本模块为 CRM 后端的认证与授权中心，提供用户登录、JWT 令牌签发与校验、角色权限控制、数据权限（部门/范围）过滤、第三方登录集成（如钉钉）等能力。通过安全配置、过滤器链与拦截器协同工作，实现从请求入口到业务方法的全链路鉴权与数据可见性控制。
## 项目结构
认证模块采用分层架构：
- 配置层：安全策略、权限开关、第三方登录参数、初始化数据等
- 控制器层：登录、登出、用户信息、系统信息等接口
- 安全层：JWT 过滤器、令牌服务、登录用户上下文、异常处理、数据权限拦截器
- 服务层：认证、用户、身份、角色、菜单、部门等业务逻辑
- 领域模型：实体、枚举、DTO、入参
- 客户端：第三方登录客户端及工厂
```mermaid
graph TB
subgraph "配置"
SC["SecurityConfig"]
PC["PermissionConfig"]
AP["AuthProperties"]
DI["DataInitializer"]
end
subgraph "控制器"
AC["AuthController"]
SYSC["SystemController"]
end
subgraph "安全"
JF["JwtAuthenticationFilter"]
TS["TokenService"]
ALU["AuthLoginUser"]
DSI["DataScopeInterceptor"]
SEH["SecurityExceptionHandlers"]
end
subgraph "服务"
IAS["IAuthService"]
AS["AuthServiceImpl"]
IAUS["IAuthUserService"]
AUS["AuthUserServiceImpl"]
IIDS["IAuthIdentityService"]
AIS["AuthIdentityServiceImpl"]
IRS["ISysRoleService"]
SRS["SysRoleServiceImpl"]
IMS["ISysMenuService"]
SMS["SysMenuServiceImpl"]
IDS["ISysDeptService"]
SDS["SysDeptServiceImpl"]
end
subgraph "第三方"
DTAC["DingTalkAuthClient"]
TPAC["ThirdPartyAuthClient"]
TPACF["ThirdPartyAuthClientFactory"]
TPI["ThirdPartyUserInfo"]
end
subgraph "领域模型"
LPM["LoginParam"]
LRDTO["LoginResultDTO"]
UIDTO["UserInfoDTO"]
AU["AuthUser"]
AI["AuthIdentity"]
SR["SysRole"]
SM["SysMenu"]
SD["SysDept"]
SUR["SysUserRole"]
SRM["SysRoleMenu"]
SUD["SysUserDept"]
end
AC --> IAS
AC --> IAUS
AC --> IIDS
SYSC --> IMS
SYSC --> IRS
SYSC --> IDS
JF --> TS
JF --> ALU
DSI --> ALU
AS --> IAUS
AS --> IIDS
AS --> IRS
AS --> IMS
AS --> IDS
AUS --> IIDS
AIS --> IAUS
SRS --> IRS
SMS --> IMS
SDS --> IDS
DTAC --> TPAC
TPACF --> DTAC
```
图表来源
- [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)
- [AuthProperties.java](file://crm-auth/src/main/java/com/crm/auth/config/AuthProperties.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)
- [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)
- [AuthLoginUser.java](file://crm-auth/src/main/java/com/crm/auth/security/AuthLoginUser.java)
- [DataScopeInterceptor.java](file://crm-auth/src/main/java/com/crm/auth/security/DataScopeInterceptor.java)
- [SecurityExceptionHandlers.java](file://crm-auth/src/main/java/com/crm/auth/security/SecurityExceptionHandlers.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)
- [IAuthUserService.java](file://crm-auth/src/main/java/com/crm/auth/service/IAuthUserService.java)
- [AuthUserServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/AuthUserServiceImpl.java)
- [IAuthIdentityService.java](file://crm-auth/src/main/java/com/crm/auth/service/IAuthIdentityService.java)
- [AuthIdentityServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/AuthIdentityServiceImpl.java)
- [ISysRoleService.java](file://crm-auth/src/main/java/com/crm/auth/service/ISysRoleService.java)
- [SysRoleServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/SysRoleServiceImpl.java)
- [ISysMenuService.java](file://crm-auth/src/main/java/com/crm/auth/service/ISysMenuService.java)
- [SysMenuServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/SysMenuServiceImpl.java)
- [ISysDeptService.java](file://crm-auth/src/main/java/com/crm/auth/service/ISysDeptService.java)
- [SysDeptServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/SysDeptServiceImpl.java)
- [DingTalkAuthClient.java](file://crm-auth/src/main/java/com/crm/auth/service/client/DingTalkAuthClient.java)
- [ThirdPartyAuthClient.java](file://crm-auth/src/main/java/com/crm/auth/service/client/ThirdPartyAuthClient.java)
- [ThirdPartyAuthClientFactory.java](file://crm-auth/src/main/java/com/crm/auth/service/client/ThirdPartyAuthClientFactory.java)
- [ThirdPartyUserInfo.java](file://crm-auth/src/main/java/com/crm/auth/service/client/ThirdPartyUserInfo.java)
- [LoginParam.java](file://crm-auth/src/main/java/com/crm/auth/domain/param/LoginParam.java)
- [LoginResultDTO.java](file://crm-auth/src/main/java/com/crm/auth/domain/dto/LoginResultDTO.java)
- [UserInfoDTO.java](file://crm-auth/src/main/java/com/crm/auth/domain/dto/UserInfoDTO.java)
- [AuthUser.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/AuthUser.java)
- [AuthIdentity.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/AuthIdentity.java)
- [SysRole.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysRole.java)
- [SysMenu.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysMenu.java)
- [SysDept.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysDept.java)
- [SysUserRole.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysUserRole.java)
- [SysRoleMenu.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysRoleMenu.java)
- [SysUserDept.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysUserDept.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：定义全局安全策略、放行路径、跨域、会话策略、异常处理器注册等
- JwtAuthenticationFilter：解析请求头中的 JWT，构建并设置认证上下文
- TokenService：JWT 的签发、解析、刷新、黑名单/过期管理（如有）
- AuthLoginUser：封装当前登录用户及其角色、权限、数据权限范围
- DataScopeInterceptor：在业务查询前注入数据权限 SQL 片段，限制数据可见范围
- SecurityExceptionHandlers：统一安全相关异常处理与响应
- 认证与授权服务
- IAuthService/AuthServiceImpl：登录、登出、密码校验、第三方登录流程编排
- IAuthUserService/AuthUserServiceImpl：用户信息查询、状态校验、缓存（可选）
- IAuthIdentityService/AuthIdentityServiceImpl：多身份源绑定与校验（手机号、邮箱、第三方）
- ISysRoleService/SysRoleServiceImpl：角色查询、角色-权限映射
- ISysMenuService/SysMenuServiceImpl：菜单树、按钮级权限标识
- ISysDeptService/SysDeptServiceImpl：部门树、用户-部门关联
- 第三方登录
- ThirdPartyAuthClient：第三方登录抽象接口
- DingTalkAuthClient：钉钉登录实现
- ThirdPartyAuthClientFactory：按类型创建对应第三方客户端
- ThirdPartyUserInfo：第三方返回的用户信息标准化
- 领域模型与常量
- LoginParam/LoginResultDTO/UserInfoDTO：登录入参与结果
- AuthUser/AuthIdentity/SysRole/SysMenu/SysDept 等实体
- DataScopeEnum/IdentityTypeEnum/MenuTypeEnum：数据权限、身份类型、菜单类型
- AuthConstants：认证相关常量
章节来源
- [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)
- [AuthLoginUser.java](file://crm-auth/src/main/java/com/crm/auth/security/AuthLoginUser.java)
- [DataScopeInterceptor.java](file://crm-auth/src/main/java/com/crm/auth/security/DataScopeInterceptor.java)
- [SecurityExceptionHandlers.java](file://crm-auth/src/main/java/com/crm/auth/security/SecurityExceptionHandlers.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)
- [IAuthUserService.java](file://crm-auth/src/main/java/com/crm/auth/service/IAuthUserService.java)
- [AuthUserServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/AuthUserServiceImpl.java)
- [IAuthIdentityService.java](file://crm-auth/src/main/java/com/crm/auth/service/IAuthIdentityService.java)
- [AuthIdentityServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/AuthIdentityServiceImpl.java)
- [ISysRoleService.java](file://crm-auth/src/main/java/com/crm/auth/service/ISysRoleService.java)
- [SysRoleServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/SysRoleServiceImpl.java)
- [ISysMenuService.java](file://crm-auth/src/main/java/com/crm/auth/service/ISysMenuService.java)
- [SysMenuServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/SysMenuServiceImpl.java)
- [ISysDeptService.java](file://crm-auth/src/main/java/com/crm/auth/service/ISysDeptService.java)
- [SysDeptServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/SysDeptServiceImpl.java)
- [ThirdPartyAuthClient.java](file://crm-auth/src/main/java/com/crm/auth/service/client/ThirdPartyAuthClient.java)
- [DingTalkAuthClient.java](file://crm-auth/src/main/java/com/crm/auth/service/client/DingTalkAuthClient.java)
- [ThirdPartyAuthClientFactory.java](file://crm-auth/src/main/java/com/crm/auth/service/client/ThirdPartyAuthClientFactory.java)
- [ThirdPartyUserInfo.java](file://crm-auth/src/main/java/com/crm/auth/service/client/ThirdPartyUserInfo.java)
- [LoginParam.java](file://crm-auth/src/main/java/com/crm/auth/domain/param/LoginParam.java)
- [LoginResultDTO.java](file://crm-auth/src/main/java/com/crm/auth/domain/dto/LoginResultDTO.java)
- [UserInfoDTO.java](file://crm-auth/src/main/java/com/crm/auth/domain/dto/UserInfoDTO.java)
- [AuthUser.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/AuthUser.java)
- [AuthIdentity.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/AuthIdentity.java)
- [SysRole.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysRole.java)
- [SysMenu.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysMenu.java)
- [SysDept.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysDept.java)
- [SysUserRole.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysUserRole.java)
- [SysRoleMenu.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysRoleMenu.java)
- [SysUserDept.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysUserDept.java)
- [DataScopeEnum.java](file://crm-auth/src/main/java/com/crm/auth/domain/enums/DataScopeEnum.java)
- [IdentityTypeEnum.java](file://crm-auth/src/main/java/com/crm/auth/domain/enums/IdentityTypeEnum.java)
- [MenuTypeEnum.java](file://crm-auth/src/main/java/com/crm/auth/domain/enums/MenuTypeEnum.java)
- [AuthConstants.java](file://crm-auth/src/main/java/com/crm/auth/constant/AuthConstants.java)
## 架构总览
认证服务以“控制器 -> 服务 -> 安全上下文”为主线，配合 JWT 过滤器与数据权限拦截器完成全链路鉴权。
```mermaid
sequenceDiagram
participant C as "客户端"
participant AC as "AuthController"
participant AS as "AuthServiceImpl"
participant AUS as "AuthUserServiceImpl"
participant AIS as "AuthIdentityServiceImpl"
participant TS as "TokenService"
participant JF as "JwtAuthenticationFilter"
participant DSI as "DataScopeInterceptor"
C->>AC : "POST /auth/login"
AC->>AS : "login(LoginParam)"
AS->>AUS : "校验用户状态/密码"
AS->>AIS : "校验身份绑定(手机/邮箱/第三方)"
AS-->>AC : "认证成功"
AC->>TS : "签发JWT(含用户ID/角色/权限/数据范围)"
TS-->>AC : "返回Token"
AC-->>C : "LoginResultDTO{token,...}"
C->>AC : "带Authorization的请求"
AC->>JF : "解析JWT并构建认证上下文"
JF->>DSI : "设置数据权限范围"
DSI-->>AC : "注入SQL数据范围片段"
AC-->>C : "受保护资源"
```
图表来源
- [AuthController.java](file://crm-auth/src/main/java/com/crm/auth/controller/AuthController.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)
- [AuthIdentityServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/AuthIdentityServiceImpl.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)
- [DataScopeInterceptor.java](file://crm-auth/src/main/java/com/crm/auth/security/DataScopeInterceptor.java)
## 详细组件分析
### 安全配置与过滤器链
- SecurityConfig：集中配置白名单、跨域、会话策略、异常处理器；将 JwtAuthenticationFilter 加入过滤器链；可配置是否启用基于注解的权限控制。
- JwtAuthenticationFilter：从请求头提取 Token，调用 TokenService 解析并填充认证上下文，供后续控制器与拦截器使用。
- DataScopeInterceptor：根据当前用户的 DataScopeEnum 与部门关系，动态拼接 SQL 条件，确保只返回允许的数据行。
- SecurityExceptionHandlers：捕获未认证、无权限、参数错误等异常，统一返回标准响应。
```mermaid
flowchart TD
Start(["请求进入"]) --> CheckPath["匹配白名单/静态资源"]
CheckPath --> |放行| Next["继续业务处理"]
CheckPath --> |需认证| Extract["提取Authorization头"]
Extract --> Parse["TokenService解析JWT"]
Parse --> Valid{"Token有效?"}
Valid --> |否| Deny["拒绝访问(401/403)"]
Valid --> |是| SetCtx["设置认证上下文(AuthLoginUser)"]
SetCtx --> Scope["DataScopeInterceptor注入数据范围"]
Scope --> Next
Next --> End(["返回响应"])
```
图表来源
- [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)
- [SecurityExceptionHandlers.java](file://crm-auth/src/main/java/com/crm/auth/security/SecurityExceptionHandlers.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)
- [SecurityExceptionHandlers.java](file://crm-auth/src/main/java/com/crm/auth/security/SecurityExceptionHandlers.java)
### 认证流程与令牌处理
- 登录流程：AuthController 接收 LoginParam，AuthServiceImpl 调用用户与身份服务进行校验，成功后由 TokenService 签发 JWT，返回 LoginResultDTO。
- 令牌处理：TokenService 负责生成、解析、刷新、失效策略；JwtAuthenticationFilter 在每个请求中解析并设置认证上下文。
- 会话管理：建议无状态化（JWT），如需限流或黑名单可在 TokenService 中扩展 Redis 存储。
```mermaid
sequenceDiagram
participant Client as "客户端"
participant AC as "AuthController"
participant AS as "AuthServiceImpl"
participant AUS as "AuthUserServiceImpl"
participant AIS as "AuthIdentityServiceImpl"
participant TS as "TokenService"
Client->>AC : "POST /auth/login"
AC->>AS : "login(LoginParam)"
AS->>AUS : "查询用户/校验状态"
AS->>AIS : "校验身份绑定"
AS-->>AC : "成功"
AC->>TS : "createToken(user, roles, dataScope)"
TS-->>AC : "token"
AC-->>Client : "LoginResultDTO(token, userInfo)"
```
图表来源
- [AuthController.java](file://crm-auth/src/main/java/com/crm/auth/controller/AuthController.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)
- [AuthIdentityServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/AuthIdentityServiceImpl.java)
- [TokenService.java](file://crm-auth/src/main/java/com/crm/auth/security/TokenService.java)
- [LoginParam.java](file://crm-auth/src/main/java/com/crm/auth/domain/param/LoginParam.java)
- [LoginResultDTO.java](file://crm-auth/src/main/java/com/crm/auth/domain/dto/LoginResultDTO.java)
章节来源
- [AuthController.java](file://crm-auth/src/main/java/com/crm/auth/controller/AuthController.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)
- [AuthIdentityServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/AuthIdentityServiceImpl.java)
- [TokenService.java](file://crm-auth/src/main/java/com/crm/auth/security/TokenService.java)
- [LoginParam.java](file://crm-auth/src/main/java/com/crm/auth/domain/param/LoginParam.java)
- [LoginResultDTO.java](file://crm-auth/src/main/java/com/crm/auth/domain/dto/LoginResultDTO.java)
### 权限管理与数据权限控制
- 角色与菜单：SysRole 与 SysMenu 建立 RBAC 模型，支持菜单与按钮级权限标识。
- 用户-角色-部门：SysUserRole、SysUserDept 维护用户与角色、部门的关联。
- 数据权限：DataScopeEnum 定义数据可见范围（全部、本部门、本部门及以下、本人等），DataScopeInterceptor 根据当前用户范围注入 SQL 片段。
- 权限检查：可通过注解或拦截器对接口进行权限校验，结合菜单标识与角色集合判断。
```mermaid
classDiagram
class AuthUser {
+id
+username
+status
}
class SysRole {
+id
+name
+code
}
class SysMenu {
+id
+name
+type
+permission
}
class SysUserRole {
+userId
+roleId
}
class SysRoleMenu {
+roleId
+menuId
}
class SysDept {
+id
+name
+parentId
}
class SysUserDept {
+userId
+deptId
}
class DataScopeEnum {
+ALL
+DEPT
+DEPT_AND_BELOW
+SELF
}
AuthUser ||--o{ SysUserRole : "拥有"
SysRole ||--o{ SysUserRole : "分配给"
SysRole ||--o{ SysRoleMenu : "包含"
SysMenu ||--o{ SysRoleMenu : "被包含"
AuthUser ||--o{ SysUserDept : "属于"
SysDept ||--o{ SysUserDept : "包含"
```
图表来源
- [AuthUser.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/AuthUser.java)
- [SysRole.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysRole.java)
- [SysMenu.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysMenu.java)
- [SysUserRole.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysUserRole.java)
- [SysRoleMenu.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysRoleMenu.java)
- [SysDept.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysDept.java)
- [SysUserDept.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysUserDept.java)
- [DataScopeEnum.java](file://crm-auth/src/main/java/com/crm/auth/domain/enums/DataScopeEnum.java)
章节来源
- [ISysRoleService.java](file://crm-auth/src/main/java/com/crm/auth/service/ISysRoleService.java)
- [SysRoleServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/SysRoleServiceImpl.java)
- [ISysMenuService.java](file://crm-auth/src/main/java/com/crm/auth/service/ISysMenuService.java)
- [SysMenuServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/SysMenuServiceImpl.java)
- [ISysDeptService.java](file://crm-auth/src/main/java/com/crm/auth/service/ISysDeptService.java)
- [SysDeptServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/SysDeptServiceImpl.java)
- [DataScopeInterceptor.java](file://crm-auth/src/main/java/com/crm/auth/security/DataScopeInterceptor.java)
- [DataScopeTables.java](file://crm-auth/src/main/java/com/crm/auth/security/DataScopeTables.java)
- [DataScopeEnum.java](file://crm-auth/src/main/java/com/crm/auth/domain/enums/DataScopeEnum.java)
### 第三方登录集成（钉钉）
- 抽象与工厂：ThirdPartyAuthClient 定义统一接口，ThirdPartyAuthClientFactory 根据类型创建具体客户端。
- 钉钉实现：DingTalkAuthClient 对接钉钉 API，获取用户信息并转换为 ThirdPartyUserInfo。
- 集成流程：前端跳转钉钉授权 -> 回调携带 code -> 服务端换取 access_token -> 拉取用户信息 -> 本地用户绑定/自动注册 -> 签发 JWT。
```mermaid
sequenceDiagram
participant Client as "客户端"
participant AC as "AuthController"
participant AS as "AuthServiceImpl"
participant DTAC as "DingTalkAuthClient"
participant TS as "TokenService"
Client->>AC : "GET /auth/thirdparty/dingtalk/callback?code=..."
AC->>AS : "thirdPartyLogin(type, code)"
AS->>DTAC : "getAccessToken(code)"
DTAC-->>AS : "accessToken"
AS->>DTAC : "getUserInfo(accessToken)"
DTAC-->>AS : "ThirdPartyUserInfo"
AS->>AS : "查找/绑定本地用户"
AS->>TS : "createToken(user, roles, dataScope)"
TS-->>AC : "token"
AC-->>Client : "LoginResultDTO(token)"
```
图表来源
- [AuthController.java](file://crm-auth/src/main/java/com/crm/auth/controller/AuthController.java)
- [AuthServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/AuthServiceImpl.java)
- [DingTalkAuthClient.java](file://crm-auth/src/main/java/com/crm/auth/service/client/DingTalkAuthClient.java)
- [ThirdPartyAuthClient.java](file://crm-auth/src/main/java/com/crm/auth/service/client/ThirdPartyAuthClient.java)
- [ThirdPartyAuthClientFactory.java](file://crm-auth/src/main/java/com/crm/auth/service/client/ThirdPartyAuthClientFactory.java)
- [ThirdPartyUserInfo.java](file://crm-auth/src/main/java/com/crm/auth/service/client/ThirdPartyUserInfo.java)
- [TokenService.java](file://crm-auth/src/main/java/com/crm/auth/security/TokenService.java)
章节来源
- [DingTalkAuthClient.java](file://crm-auth/src/main/java/com/crm/auth/service/client/DingTalkAuthClient.java)
- [ThirdPartyAuthClient.java](file://crm-auth/src/main/java/com/crm/auth/service/client/ThirdPartyAuthClient.java)
- [ThirdPartyAuthClientFactory.java](file://crm-auth/src/main/java/com/crm/auth/service/client/ThirdPartyAuthClientFactory.java)
- [ThirdPartyUserInfo.java](file://crm-auth/src/main/java/com/crm/auth/service/client/ThirdPartyUserInfo.java)
- [AuthServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/AuthServiceImpl.java)
- [AuthController.java](file://crm-auth/src/main/java/com/crm/auth/controller/AuthController.java)
### 用户与会话管理
- 用户上下文：AuthLoginUser 封装用户基本信息、角色、权限、数据权限范围，便于全链路使用。
- 会话策略：推荐无状态 JWT；如需在线用户统计、强制下线等，可在 TokenService 中引入 Redis 做黑名单或在线列表。
- 初始化数据：DataInitializer 用于启动时预置基础角色、菜单、部门等数据。
章节来源
- [AuthLoginUser.java](file://crm-auth/src/main/java/com/crm/auth/security/AuthLoginUser.java)
- [TokenService.java](file://crm-auth/src/main/java/com/crm/auth/security/TokenService.java)
- [DataInitializer.java](file://crm-auth/src/main/java/com/crm/auth/config/DataInitializer.java)
## 依赖关系分析
- 控制器依赖服务层，服务层依赖领域模型与枚举，安全组件贯穿请求生命周期。
- 第三方登录通过工厂解耦不同平台实现，便于扩展。
- 数据权限通过拦截器与表名映射（DataScopeTables）组合，降低对业务代码侵入。
```mermaid
graph LR
AC["AuthController"] --> AS["AuthServiceImpl"]
AC --> AUS["AuthUserServiceImpl"]
AC --> AIS["AuthIdentityServiceImpl"]
SYSC["SystemController"] --> SRS["SysRoleServiceImpl"]
SYSC --> SMS["SysMenuServiceImpl"]
SYSC --> SDS["SysDeptServiceImpl"]
JF["JwtAuthenticationFilter"] --> TS["TokenService"]
DSI["DataScopeInterceptor"] --> ALU["AuthLoginUser"]
DTAC["DingTalkAuthClient"] --> TPACF["ThirdPartyAuthClientFactory"]
```
图表来源
- [AuthController.java](file://crm-auth/src/main/java/com/crm/auth/controller/AuthController.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)
- [AuthIdentityServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/AuthIdentityServiceImpl.java)
- [SystemController.java](file://crm-auth/src/main/java/com/crm/auth/controller/SystemController.java)
- [SysRoleServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/SysRoleServiceImpl.java)
- [SysMenuServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/SysMenuServiceImpl.java)
- [SysDeptServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/SysDeptServiceImpl.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)
- [AuthLoginUser.java](file://crm-auth/src/main/java/com/crm/auth/security/AuthLoginUser.java)
- [DingTalkAuthClient.java](file://crm-auth/src/main/java/com/crm/auth/service/client/DingTalkAuthClient.java)
- [ThirdPartyAuthClientFactory.java](file://crm-auth/src/main/java/com/crm/auth/service/client/ThirdPartyAuthClientFactory.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)
- [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)
- [AuthIdentityServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/AuthIdentityServiceImpl.java)
- [SysRoleServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/SysRoleServiceImpl.java)
- [SysMenuServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/SysMenuServiceImpl.java)
- [SysDeptServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/SysDeptServiceImpl.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)
- [AuthLoginUser.java](file://crm-auth/src/main/java/com/crm/auth/security/AuthLoginUser.java)
- [DingTalkAuthClient.java](file://crm-auth/src/main/java/com/crm/auth/service/client/DingTalkAuthClient.java)
- [ThirdPartyAuthClientFactory.java](file://crm-auth/src/main/java/com/crm/auth/service/client/ThirdPartyAuthClientFactory.java)
## 性能考虑
- JWT 解析开销：避免在 TokenService 中进行重型计算；必要时缓存用户角色/权限集合。
- 数据权限 SQL 注入：尽量复用 MyBatis 分页插件与条件构造器，减少字符串拼接带来的性能损耗。
- 第三方登录：对钉钉等外部 API 调用增加超时与重试策略，避免阻塞主线程。
- 缓存策略：对菜单树、角色-权限映射、部门树等热点数据引入缓存（如 Redis）。
- 无状态会话：避免服务端 Session 存储，提升水平扩展能力。
[本节为通用指导，不直接分析具体文件]
## 故障排查指南
- 常见错误
- 401 未认证：检查 Authorization 头格式、Token 是否过期、过滤器链是否生效
- 403 无权限：检查用户角色与接口权限标识是否匹配，菜单权限是否正确配置
- 数据越权：确认 DataScopeEnum 与用户-部门关系是否正确，拦截器是否注入成功
- 第三方登录失败：核对 AppKey/AppSecret、回调地址、网络连通性与签名校验
- 定位手段
- 开启调试日志，查看 JwtAuthenticationFilter 解析过程
- 打印 DataScopeInterceptor 注入的 SQL 片段，验证数据范围
- 检查 SecurityExceptionHandlers 返回的错误码与消息
- 修复建议
- 修正白名单配置，避免误放行敏感接口
- 完善用户-角色-部门关联数据
- 优化第三方客户端超时与重试配置
章节来源
- [JwtAuthenticationFilter.java](file://crm-auth/src/main/java/com/crm/auth/security/JwtAuthenticationFilter.java)
- [SecurityExceptionHandlers.java](file://crm-auth/src/main/java/com/crm/auth/security/SecurityExceptionHandlers.java)
- [DataScopeInterceptor.java](file://crm-auth/src/main/java/com/crm/auth/security/DataScopeInterceptor.java)
- [DingTalkAuthClient.java](file://crm-auth/src/main/java/com/crm/auth/service/client/DingTalkAuthClient.java)
## 结论
认证服务模块通过清晰的分层设计与安全组件协作，实现了完整的认证、授权与数据权限控制能力。JWT 无状态化提升了可扩展性，RBAC 与数据权限满足企业级权限需求，第三方登录框架便于快速接入新平台。建议在部署时关注安全配置、缓存策略与外部依赖稳定性，以获得更好的性能与可靠性。
[本节为总结，不直接分析具体文件]
## 附录
- 安全最佳实践
- 最小权限原则：仅授予必要角色与菜单权限
- 强口令策略与登录失败锁定
- HTTPS 传输与 Token 短期有效期
- 定期审计角色与权限变更
- 自定义扩展方法
- 新增第三方平台：实现 ThirdPartyAuthClient 接口并在工厂中注册
- 扩展数据权限：在 DataScopeInterceptor 中增加新的 DataScopeEnum 分支
- 增强权限校验：在 PermissionConfig 中启用注解式权限控制
[本节为补充说明，不直接分析具体文件]