crm-backend-matt/.qoder/repowiki/zh/content/认证服务/认证服务.md

# 认证服务

<cite>
**本文引用的文件**   
- [CrmAppApplication.java](file://crm-app/src/main/java/com/crm/app/CrmAppApplication.java)
- [application.yml](file://crm-app/src/main/resources/application.yml)
- [application-verify.yml](file://crm-app/src/main/resources/application-verify.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)
- [AuthProperties.java](file://crm-auth/src/main/java/com/crm/auth/config/AuthProperties.java)
- [AuthController.java](file://crm-auth/src/main/java/com/crm/auth/controller/AuthController.java)
- [DebugTokenController.java](file://crm-auth/src/main/java/com/crm/auth/controller/DebugTokenController.java)
- [SystemController.java](file://crm-auth/src/main/java/com/crm/auth/controller/SystemController.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)
- [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)
- [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)
- [DeptTreeCache.java](file://crm-auth/src/main/java/com/crm/auth/service/DeptTreeCache.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)
- [ThirdPartyAuthClient.java](file://crm-auth/src/main/java/com/crm/auth/service/client/ThirdPartyAuthClient.java)
- [ThirdPartyUserInfo.java](file://crm-auth/src/main/java/com/crm/auth/service/client/ThirdPartyUserInfo.java)
- [GlobalExceptionHandlerAdvice.java](file://crm-base/src/main/java/com/crm/base/advice/GlobalExceptionHandlerAdvice.java)
- [DataScope.java](file://crm-base/src/main/java/com/crm/base/annotation/DataScope.java)
- [DataOwnership.java](file://crm-base/src/main/java/com/crm/base/security/DataOwnership.java)
- [DataScopeHelper.java](file://crm-base/src/main/java/com/crm/base/security/DataScopeHelper.java)
- [DataScopeLevel.java](file://crm-base/src/main/java/com/crm/base/security/DataScopeLevel.java)
- [DataVisibilityContext.java](file://crm-base/src/main/java/com/crm/base/security/DataVisibilityContext.java)
- [LoginUser.java](file://crm-base/src/main/java/com/crm/base/security/LoginUser.java)
- [SecurityUtils.java](file://crm-base/src/main/java/com/crm/base/security/SecurityUtils.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)
- [ResultCodeEnum.java](file://crm-base/src/main/java/com/crm/base/domain/result/ResultCodeEnum.java)
- [PageResult.java](file://crm-base/src/main/java/com/crm/base/domain/result/PageResult.java)
- [BusinessErrorException.java](file://crm-base/src/main/java/com/crm/base/domain/exception/BusinessErrorException.java)
- [PermissionErrorException.java](file://crm-base/src/main/java/com/crm/base/domain/exception/PermissionErrorException.java)
- [ResourceNotExistException.java](file://crm-base/src/main/java/com/crm/base/domain/exception/ResourceNotExistException.java)
- [MissingParameterException.java](file://crm-base/src/main/java/com/crm/base/domain/exception/MissingParameterException.java)
- [TraceIdFilter.java](file://crm-base/src/main/java/com/crm/base/filter/TraceIdFilter.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)
- [SnowflakeIdWorker.java](file://crm-base/src/main/java/com/crm/base/config/SnowflakeIdWorker.java)
- [SnowflakeProperties.java](file://crm-base/src/main/java/com/crm/base/config/SnowflakeProperties.java)
- [CustomIdGenerator.java](file://crm-base/src/main/java/com/crm/base/config/CustomIdGenerator.java)
- [MetaObjectFillHandler.java](file://crm-base/src/main/java/com/crm/base/config/MetaObjectFillHandler.java)
- [InsertBatchOnDuplicateKeyUpdate.java](file://crm-base/src/main/java/com/crm/base/config/InsertBatchOnDuplicateKeyUpdate.java)
- [CrmSqlInjector.java](file://crm-base/src/main/java/com/crm/base/config/CrmSqlInjector.java)
- [CorsConfig.java](file://crm-base/src/main/java/com/crm/base/config/CorsConfig.java)
- [Knife4jConfig.java](file://crm-base/src/main/java/com/crm/base/config/Knife4jConfig.java)
- [ScheduledTaskProperties.java](file://crm-base/src/main/java/com/crm/base/config/ScheduledTaskProperties.java)
- [CommonConstants.java](file://crm-base/src/main/java/com/crm/base/constant/CommonConstants.java)
- [AssertUtils.java](file://crm-base/src/main/java/com/crm/base/utils/AssertUtils.java)
- [BeanCopyUtils.java](file://crm-base/src/main/java/com/crm/base/utils/BeanCopyUtils.java)
- [EnumUtils.java](file://crm-base/src/main/java/com/crm/base/utils/EnumUtils.java)
- [ExcelUtil.java](file://crm-base/src/main/java/com/crm/base/utils/ExcelUtil.java)
- [PageConverter.java](file://crm-base/src/main/java/com/crm/base/utils/PageConverter.java)
- [ServletUtils.java](file://crm-base/src/main/java/com/crm/base/utils/ServletUtils.java)
- [TreeUtils.java](file://crm-base/src/main/java/com/crm/base/utils/TreeUtils.java)
</cite>

## 更新摘要
**变更内容**   
- 新增调试令牌端点章节，详细介绍DebugTokenController功能
- 更新安全配置章节，说明verify profile和三层护栏机制
- 新增验证环境专用配置说明
- 更新部署指南，包含verify profile的使用说明

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

## 简介
本技术文档围绕认证服务的用户认证、授权管理、权限控制等核心能力展开，涵盖JWT令牌机制、RBAC角色权限模型、数据权限控制、第三方登录集成等特性。同时提供用户管理、角色管理、菜单权限、部门管理等业务功能的API接口说明与使用示例，并解释安全过滤器链、异常处理、会话管理等安全机制，最后给出完整的配置指南与最佳实践建议。

**重要更新**：新增了验证环境专用的调试令牌端点，用于在验证环境中快速生成JWT令牌进行接口调试，该功能通过@Profile("verify")严格限制仅在验证环境激活。

## 项目结构
认证服务由应用启动模块与认证功能模块组成：
- crm-app：应用入口与全局配置（包含verify profile专用配置）
- crm-auth：认证与权限核心实现（控制器、服务、安全、领域模型、枚举、参数与DTO）
- crm-base：通用基础能力（异常、结果封装、安全上下文、数据可见性、工具类、配置等）

```mermaid
graph TB
subgraph "应用层"
App["CrmAppApplication<br/>应用启动"]
VerifyCfg["application-verify.yml<br/>验证环境配置"]
end
subgraph "认证模块(crm-auth)"
AuthApp["AuthApplication<br/>认证应用启动"]
SecCfg["SecurityConfig<br/>安全配置"]
PermCfg["PermissionConfig<br/>权限配置"]
CtlAuth["AuthController<br/>认证接口"]
CtlDebug["DebugTokenController<br/>调试令牌接口"]
CtlSys["SystemController<br/>系统接口"]
SvcAuth["AuthServiceImpl<br/>认证服务"]
SvcUser["AuthUserServiceImpl<br/>用户服务"]
SvcRole["SysRoleServiceImpl<br/>角色服务"]
SvcMenu["SysMenuServiceImpl<br/>菜单服务"]
SvcDept["SysDeptServiceImpl<br/>部门服务"]
JwtF["JwtAuthenticationFilter<br/>JWT过滤器"]
TokS["TokenService<br/>令牌服务"]
DpIntc["DataScopeInterceptor<br/>数据范围拦截器"]
Cache["DeptTreeCache<br/>部门树缓存"]
end
subgraph "基础模块(crm-base)"
BaseEx["GlobalExceptionHandlerAdvice<br/>全局异常处理"]
SecCtx["SecurityUtils / LoginUser<br/>安全上下文"]
DataVis["DataScopeHelper / DataVisibilityContext<br/>数据可见性"]
MyBatis["MybatisPlusConfig<br/>持久化配置"]
Redis["RedisConfig<br/>缓存配置"]
Jackson["JacksonConfig<br/>序列化配置"]
Snow["SnowflakeIdWorker<br/>雪花ID生成"]
end
App --> AuthApp
App --> VerifyCfg
AuthApp --> SecCfg
SecCfg --> JwtF
JwtF --> TokS
CtlAuth --> SvcAuth
CtlDebug --> SvcUser
CtlDebug --> TokS
CtlSys --> SvcUser
CtlSys --> SvcRole
CtlSys --> SvcMenu
CtlSys --> SvcDept
SvcAuth --> TokS
SvcUser --> SvcRole
SvcRole --> SvcMenu
SvcDept --> Cache
SecCfg --> DpIntc
DpIntc --> DataVis
SvcAuth --> SecCtx
SvcUser --> SecCtx
SvcRole --> SecCtx
SvcMenu --> SecCtx
SvcDept --> SecCtx
```

**图表来源** 
- [CrmAppApplication.java](file://crm-app/src/main/java/com/crm/app/CrmAppApplication.java)
- [application-verify.yml](file://crm-app/src/main/resources/application-verify.yml)
- [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)
- [DebugTokenController.java](file://crm-auth/src/main/java/com/crm/auth/controller/DebugTokenController.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)
- [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)
- [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)
- [DeptTreeCache.java](file://crm-auth/src/main/java/com/crm/auth/service/DeptTreeCache.java)
- [DataScopeInterceptor.java](file://crm-auth/src/main/java/com/crm/auth/security/DataScopeInterceptor.java)
- [GlobalExceptionHandlerAdvice.java](file://crm-base/src/main/java/com/crm/base/advice/GlobalExceptionHandlerAdvice.java)
- [SecurityUtils.java](file://crm-base/src/main/java/com/crm/base/security/SecurityUtils.java)
- [DataScopeHelper.java](file://crm-base/src/main/java/com/crm/base/security/DataScopeHelper.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)
- [SnowflakeIdWorker.java](file://crm-base/src/main/java/com/crm/base/config/SnowflakeIdWorker.java)

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

## 核心组件
- 安全配置与安全过滤器链
  - SecurityConfig：定义请求白名单、鉴权规则、跨域、异常处理等
  - JwtAuthenticationFilter：解析请求头中的JWT，构建认证上下文
  - TokenService：JWT的签发、校验、刷新、注销等
- 认证与授权服务
  - IAuthService/AuthServiceImpl：登录、登出、密码校验、第三方登录流程编排
  - IAuthUserService/AuthUserServiceImpl：用户CRUD、密码策略、状态管理
  - ISysRoleService/SysRoleServiceImpl：角色CRUD、角色-用户关联
  - ISysMenuService/SysMenuServiceImpl：菜单树、按钮权限、角色-菜单关联
  - ISysDeptService/SysDeptServiceImpl：部门树、用户-部门关联
- **调试令牌端点**
  - DebugTokenController：验证环境专用的JWT令牌生成接口，通过@Profile("verify")严格限制
- 数据权限控制
  - DataScopeInterceptor：基于注解的数据范围注入SQL片段
  - DataScopeHelper/DataVisibilityContext：数据可见性上下文与计算
  - DataScope/@DataScope：声明式数据范围控制
- 第三方登录集成
  - ThirdPartyAuthClientFactory：按类型创建第三方客户端
  - DingTalkAuthClient：钉钉登录实现
  - ThirdPartyAuthClient/ThirdPartyUserInfo：统一抽象与用户信息模型
- 基础能力
  - GlobalExceptionHandlerAdvice：统一异常响应
  - Result/ResultCodeEnum：统一返回体与错误码
  - SecurityUtils/LoginUser：当前登录用户上下文
  - MybatisPlusConfig/RedisConfig/JacksonConfig/SnowflakeIdWorker：持久化、缓存、序列化、ID生成

**章节来源**
- [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)
- [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)
- [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)
- [DebugTokenController.java](file://crm-auth/src/main/java/com/crm/auth/controller/DebugTokenController.java)
- [DataScopeInterceptor.java](file://crm-auth/src/main/java/com/crm/auth/security/DataScopeInterceptor.java)
- [DataScopeHelper.java](file://crm-base/src/main/java/com/crm/base/security/DataScopeHelper.java)
- [DataVisibilityContext.java](file://crm-base/src/main/java/com/crm/base/security/DataVisibilityContext.java)
- [DataScope.java](file://crm-base/src/main/java/com/crm/base/annotation/DataScope.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)
- [ThirdPartyAuthClient.java](file://crm-auth/src/main/java/com/crm/auth/service/client/ThirdPartyAuthClient.java)
- [ThirdPartyUserInfo.java](file://crm-auth/src/main/java/com/crm/auth/service/client/ThirdPartyUserInfo.java)
- [GlobalExceptionHandlerAdvice.java](file://crm-base/src/main/java/com/crm/base/advice/GlobalExceptionHandlerAdvice.java)
- [Result.java](file://crm-base/src/main/java/com/crm/base/domain/result/Result.java)
- [ResultCodeEnum.java](file://crm-base/src/main/java/com/crm/base/domain/result/ResultCodeEnum.java)
- [SecurityUtils.java](file://crm-base/src/main/java/com/crm/base/security/SecurityUtils.java)
- [LoginUser.java](file://crm-base/src/main/java/com/crm/base/security/LoginUser.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)
- [SnowflakeIdWorker.java](file://crm-base/src/main/java/com/crm/base/config/SnowflakeIdWorker.java)

## 架构总览
认证服务采用分层架构与模块化设计：
- 表现层：控制器暴露REST API（包括调试令牌端点）
- 服务层：业务编排与领域逻辑
- 安全层：过滤器链、令牌服务、权限校验、数据范围拦截
- 数据层：MyBatis Plus映射与数据库交互
- 基础设施：Redis缓存、雪花ID、统一异常与结果封装

```mermaid
sequenceDiagram
participant Client as "客户端"
participant Filter as "JwtAuthenticationFilter"
participant DebugCtl as "DebugTokenController"
participant AuthCtl as "AuthController"
participant Service as "AuthServiceImpl"
participant Token as "TokenService"
participant DB as "数据库"
participant Cache as "Redis"
Client->>Filter : "携带Authorization请求"
Filter->>Filter : "解析JWT并校验签名"
Filter-->>Client : "未通过则拒绝访问"
Note over DebugCtl : verify profile激活时可用
Client->>DebugCtl : "POST /api/auth/debug/token?userId=xxx"
DebugCtl->>DB : "查询用户信息"
DB-->>DebugCtl : "用户实体"
DebugCtl->>Token : "生成JWT(复用正式登录逻辑)"
Token->>Cache : "写入会话/黑名单(可选)"
Token-->>DebugCtl : "返回token"
DebugCtl-->>Client : "200 OK {token}"
Client->>AuthCtl : "POST /auth/login"
AuthCtl->>Service : "login(LoginParam)"
Service->>DB : "查询用户与身份"
DB-->>Service : "用户实体与角色/菜单"
Service->>Token : "生成JWT(含用户、角色、权限)"
Token->>Cache : "写入会话/黑名单(可选)"
Token-->>Service : "返回token"
Service-->>AuthCtl : "LoginResultDTO"
AuthCtl-->>Client : "200 OK {token, userInfo}"
```

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

## 详细组件分析

### 安全配置与过滤器链
- SecurityConfig：集中配置放行路径、鉴权规则、跨域、异常处理器；注册数据范围拦截器
- JwtAuthenticationFilter：从请求头提取JWT，调用TokenService完成校验与上下文填充
- TokenService：负责JWT的创建、解析、续期、撤销；支持将令牌或黑名单存入Redis
- 数据范围拦截器：在方法执行前注入数据范围条件，影响后续SQL
- **verify profile配置**：通过AuthProperties.ignoreUrls配置额外放行路径，支持动态配置

**更新**：新增了verify profile专用的安全配置机制，允许在验证环境中动态添加放行路径。

```mermaid
classDiagram
class SecurityConfig {
+配置白名单()
+配置鉴权规则()
+注册异常处理器()
+注册数据范围拦截器()
}
class JwtAuthenticationFilter {
+doFilter(request,response,chain)
+parseAndValidate(token)
}
class TokenService {
+createToken(user,roles,perms)
+validate(token)
+refresh(token)
+revoke(token)
}
class DataScopeInterceptor {
+preHandle(request,response,handler)
+buildScopeCondition()
}
class AuthProperties {
+String[] ignoreUrls
+Jwt jwt
+DingTalk dingtalk
}
SecurityConfig --> JwtAuthenticationFilter : "注册"
SecurityConfig --> AuthProperties : "读取配置"
JwtAuthenticationFilter --> TokenService : "校验令牌"
SecurityConfig --> DataScopeInterceptor : "注册"
```

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

### 调试令牌端点（验证环境专用）
**新增功能**：DebugTokenController是专门为验证环境设计的调试接口，允许通过userId直接生成JWT令牌，绕过正常的登录流程。

**核心特性**：
- **严格的环境隔离**：通过@Profile("verify")确保仅在验证环境激活
- **三层安全防护**：
  1. @Profile("verify") - Bean级别的条件注册
  2. application-verify.yml中的ignore-urls配置 - URL级别的放行
  3. 启动期WARN日志 - 审计追踪
- **功能复用**：完全复用TokenService.createToken方法，生成的令牌与正常登录完全一致
- **安全警告**：启动时打印明显的警告日志，提醒开发者这是后门接口

```mermaid
flowchart TD
Start(["应用启动"]) --> CheckProfile{"verify profile激活?"}
CheckProfile --> |否| Skip["跳过DebugTokenController注册"]
CheckProfile --> |是| Register["注册DebugTokenController"]
Register --> WarnLog["打印启动警告日志"]
WarnLog --> Ready["接口就绪"]
Ready --> Request["接收POST /api/auth/debug/token?userId=xxx"]
Request --> ValidateUser["验证userId存在"]
ValidateUser --> |不存在| Error["返回错误"]
ValidateUser --> |存在| BuildUser["构建AuthLoginUser"]
BuildUser --> GenToken["调用TokenService.createToken"]
GenToken --> LogAudit["记录审计日志"]
LogAudit --> Return["返回JWT令牌"]
Error --> End(["结束"])
Return --> End
Skip --> End
```

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

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

### 认证流程与JWT令牌机制
- 登录流程：验证用户名/密码或第三方凭证，加载用户、角色、菜单权限，生成JWT并返回
- 令牌内容：包含用户标识、角色集合、权限点集合、过期时间等
- 令牌校验：过滤器自动解析并填充安全上下文，后续接口无需重复鉴权
- 令牌刷新与注销：支持刷新过期令牌、主动注销使令牌失效
- **调试令牌生成**：验证环境下可通过userId直接生成标准JWT令牌

```mermaid
flowchart TD
Start(["开始"]) --> Parse["解析登录参数"]
Parse --> Validate{"参数有效?"}
Validate --> |否| Err["返回参数错误"]
Validate --> |是| LoadUser["加载用户与身份"]
LoadUser --> CheckPwd{"密码/凭证校验"}
CheckPwd --> |失败| Fail["返回认证失败"]
CheckPwd --> |成功| BuildPerms["构建角色与权限集合"]
BuildPerms --> GenToken["生成JWT令牌"]
GenToken --> SaveSession["写入会话/黑名单(可选)"]
SaveSession --> Return["返回登录结果"]
Return --> End(["结束"])
Err --> End
Fail --> End
```

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

### RBAC权限模型与菜单权限
- 角色-用户多对多：用户可拥有多个角色
- 角色-菜单多对多：角色可访问多个菜单与按钮
- 菜单类型：目录、菜单、按钮，用于前端路由与操作权限控制
- 数据权限：通过数据范围枚举控制可见数据范围

```mermaid
erDiagram
AUTH_USER ||--o{ SYS_USER_ROLE : "拥有"
SYS_ROLE ||--o{ SYS_USER_ROLE : "分配给"
SYS_ROLE ||--o{ SYS_ROLE_MENU : "包含"
SYS_MENU ||--o{ SYS_ROLE_MENU : "被包含"
AUTH_USER ||--o{ SYS_USER_DEPT : "属于"
SYS_DEPT ||--o{ SYS_USER_DEPT : "包含"
AUTH_USER {
bigint id PK
string username
string password
int status
}
SYS_ROLE {
bigint id PK
string role_code
string role_name
}
SYS_MENU {
bigint id PK
string menu_code
string menu_name
enum type
int sort
}
SYS_DEPT {
bigint id PK
string dept_name
int parent_id
}
SYS_USER_ROLE {
bigint user_id FK
bigint role_id FK
}
SYS_ROLE_MENU {
bigint role_id FK
bigint menu_id FK
}
SYS_USER_DEPT {
bigint user_id FK
bigint dept_id FK
}
```

**图表来源** 
- [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)
- [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)
- [MenuTypeEnum.java](file://crm-auth/src/main/java/com/crm/auth/domain/enums/MenuTypeEnum.java)
- [DataScopeEnum.java](file://crm-auth/src/main/java/com/crm/auth/domain/enums/DataScopeEnum.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)
- [AuthUserServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/AuthUserServiceImpl.java)

### 数据权限控制
- 注解驱动：@DataScope声明数据范围级别（全部、本部门、本部门及子部门、仅本人等）
- 拦截器注入：DataScopeInterceptor在方法执行前根据当前用户与注解动态拼接WHERE条件
- 上下文支撑：DataVisibilityContext维护当前可见数据范围，供查询辅助方法使用

```mermaid
flowchart TD
Enter(["进入受保护方法"]) --> CheckAnno{"存在@DataScope?"}
CheckAnno --> |否| Proceed["直接执行业务逻辑"]
CheckAnno --> |是| Resolve["解析数据范围级别"]
Resolve --> BuildCond["构建SQL数据范围条件"]
BuildCond --> Inject["注入到查询上下文"]
Inject --> Proceed
Proceed --> Exit(["退出"])
```

**图表来源** 
- [DataScopeInterceptor.java](file://crm-auth/src/main/java/com/crm/auth/security/DataScopeInterceptor.java)
- [DataScope.java](file://crm-base/src/main/java/com/crm/base/annotation/DataScope.java)
- [DataScopeHelper.java](file://crm-base/src/main/java/com/crm/base/security/DataScopeHelper.java)
- [DataVisibilityContext.java](file://crm-base/src/main/java/com/crm/base/security/DataVisibilityContext.java)

**章节来源**
- [DataScopeInterceptor.java](file://crm-auth/src/main/java/com/crm/auth/security/DataScopeInterceptor.java)
- [DataScope.java](file://crm-base/src/main/java/com/crm/base/annotation/DataScope.java)
- [DataScopeHelper.java](file://crm-base/src/main/java/com/crm/base/security/DataScopeHelper.java)
- [DataVisibilityContext.java](file://crm-base/src/main/java/com/crm/base/security/DataVisibilityContext.java)

### 第三方登录集成
- 工厂模式：ThirdPartyAuthClientFactory根据类型创建对应第三方客户端
- 统一接口：ThirdPartyAuthClient定义标准方法，如获取用户信息、绑定本地账号
- 钉钉集成：DingTalkAuthClient实现钉钉OAuth流程与用户信息映射
- 用户信息模型：ThirdPartyUserInfo标准化第三方返回的用户属性

```mermaid
classDiagram
class ThirdPartyAuthClientFactory {
+getClient(type) ThirdPartyAuthClient
}
class ThirdPartyAuthClient {
+getUserInfo(code) ThirdPartyUserInfo
+bindLocalAccount(userInfo) AuthUser
}
class DingTalkAuthClient {
+getUserInfo(code) ThirdPartyUserInfo
+bindLocalAccount(userInfo) AuthUser
}
class ThirdPartyUserInfo {
+string openId
+string nickname
+string avatar
+map extra
}
ThirdPartyAuthClientFactory --> ThirdPartyAuthClient : "创建实例"
DingTalkAuthClient ..|> ThirdPartyAuthClient
```

**图表来源** 
- [ThirdPartyAuthClientFactory.java](file://crm-auth/src/main/java/com/crm/auth/service/client/ThirdPartyAuthClientFactory.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)
- [ThirdPartyUserInfo.java](file://crm-auth/src/main/java/com/crm/auth/service/client/ThirdPartyUserInfo.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)
- [ThirdPartyAuthClient.java](file://crm-auth/src/main/java/com/crm/auth/service/client/ThirdPartyAuthClient.java)
- [ThirdPartyUserInfo.java](file://crm-auth/src/main/java/com/crm/auth/service/client/ThirdPartyUserInfo.java)

### 用户、角色、菜单、部门管理API
- 用户管理
  - 新增/修改/删除/分页查询用户
  - 重置密码、启用/禁用状态
  - 绑定/解绑角色与部门
- 角色管理
  - 新增/修改/删除/分页查询角色
  - 分配/回收菜单权限
  - 查看角色拥有的菜单树
- 菜单管理
  - 新增/修改/删除/分页查询菜单
  - 构建菜单树（目录/菜单/按钮）
  - 按角色获取可用菜单
- 部门管理
  - 新增/修改/删除/分页查询部门
  - 构建部门树
  - 用户-部门关联管理

```mermaid
sequenceDiagram
participant Admin as "管理员"
participant SysCtl as "SystemController"
participant RoleSvc as "SysRoleServiceImpl"
participant MenuSvc as "SysMenuServiceImpl"
participant DeptSvc as "SysDeptServiceImpl"
Admin->>SysCtl : "GET /system/role/list"
SysCtl->>RoleSvc : "list(page,param)"
RoleSvc-->>SysCtl : "分页结果"
SysCtl-->>Admin : "Result<List<Role>>"
Admin->>SysCtl : "POST /system/menu/tree"
SysCtl->>MenuSvc : "tree(roleId?)"
MenuSvc-->>SysCtl : "菜单树"
SysCtl-->>Admin : "Result<List<Menu>>"
Admin->>SysCtl : "POST /system/dept/tree"
SysCtl->>DeptSvc : "tree()"
DeptSvc-->>SysCtl : "部门树"
SysCtl-->>Admin : "Result<List<Dept>>"
```

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

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

### 会话管理与缓存
- 会话存储：TokenService可将令牌或黑名单写入Redis，支持分布式环境下的令牌校验与注销
- 部门树缓存：DeptTreeCache缓存部门树结构，减少频繁查询数据库
- 配置项：通过AuthProperties与RedisConfig进行相关配置

**章节来源**
- [TokenService.java](file://crm-auth/src/main/java/com/crm/auth/security/TokenService.java)
- [DeptTreeCache.java](file://crm-auth/src/main/java/com/crm/auth/service/DeptTreeCache.java)
- [AuthProperties.java](file://crm-auth/src/main/java/com/crm/auth/config/AuthProperties.java)
- [RedisConfig.java](file://crm-base/src/main/java/com/crm/base/config/RedisConfig.java)

## 依赖关系分析
- 模块内依赖
  - 控制器依赖服务层，服务层依赖领域模型与Mapper
  - 安全过滤器依赖令牌服务与安全上下文
  - 数据范围拦截器依赖数据可见性上下文
  - **调试令牌端点依赖用户服务和令牌服务**
- 模块间依赖
  - crm-auth依赖crm-base提供的异常、结果、安全上下文、工具类与配置
  - crm-app作为应用入口聚合各模块

```mermaid
graph LR
Ctl["控制器层"] --> Svc["服务层"]
Svc --> Model["领域模型/枚举"]
Svc --> Mapper["数据访问层"]
Filter["安全过滤器"] --> Token["令牌服务"]
Filter --> Ctx["安全上下文"]
Intc["数据范围拦截器"] --> Vis["数据可见性"]
DebugCtl["调试令牌控制器"] --> UserSvc["用户服务"]
DebugCtl --> Token
AuthMod["crm-auth"] --> BaseMod["crm-base"]
AppMod["crm-app"] --> AuthMod
```

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

**章节来源**
- [AuthController.java](file://crm-auth/src/main/java/com/crm/auth/controller/AuthController.java)
- [DebugTokenController.java](file://crm-auth/src/main/java/com/crm/auth/controller/DebugTokenController.java)
- [AuthServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/AuthServiceImpl.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)
- [DataVisibilityContext.java](file://crm-base/src/main/java/com/crm/base/security/DataVisibilityContext.java)

## 性能考虑
- JWT无状态校验：服务端仅需校验签名与过期时间，降低会话存储压力
- 缓存优化：部门树缓存、菜单树缓存可减少数据库访问
- 批量操作：插入时使用批处理与去重更新策略提升写入性能
- 索引设计：为常用查询字段建立索引（用户名、角色编码、菜单编码、部门父级等）
- 连接池与超时：合理配置数据库连接池与Redis连接池，避免资源耗尽

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

## 故障排查指南
- 常见异常
  - 认证失败：检查用户名/密码或第三方凭证是否正确
  - 权限不足：确认用户是否具备所需角色与菜单权限
  - 数据不可见：检查@DataScope注解与用户所属部门/角色数据范围
  - 令牌无效：检查Authorization头格式、令牌是否过期或被注销
  - **调试令牌接口404**：检查verify profile是否正确激活
- 日志与追踪
  - 使用TraceIdFilter贯穿请求链路，便于定位问题
  - 全局异常处理器统一捕获并返回结构化错误信息
  - **调试令牌接口会打印WARN日志**，可用于验证profile激活状态
- 调试建议
  - 开启Knife4j接口文档，快速验证接口行为
  - 检查Redis中令牌与黑名单状态
  - 查看数据库关联表（用户-角色、角色-菜单、用户-部门）一致性
  - **验证环境检查**：确认application-verify.yml配置正确

**章节来源**
- [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)
- [SecurityExceptionHandlers.java](file://crm-auth/src/main/java/com/crm/auth/security/SecurityExceptionHandlers.java)
- [DebugTokenController.java](file://crm-auth/src/main/java/com/crm/auth/controller/DebugTokenController.java)
- [application-verify.yml](file://crm-app/src/main/resources/application-verify.yml)
- [Result.java](file://crm-base/src/main/java/com/crm/base/domain/result/Result.java)
- [ResultCodeEnum.java](file://crm-base/src/main/java/com/crm/base/domain/result/ResultCodeEnum.java)

## 结论
认证服务以JWT为核心，结合RBAC与数据权限控制，提供了完整的安全体系。通过模块化设计与清晰的分层架构，实现了用户认证、授权管理、权限控制与第三方登录集成的统一方案。配合统一的异常处理、结果封装与缓存策略，具备良好的可扩展性与可维护性。

**重要更新**：新增的调试令牌端点为验证环境提供了极大的便利性，通过严格的@Profile("verify")机制确保了生产环境的安全性。这一设计体现了在开发便利性与生产安全性之间的平衡考虑。

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

## 附录

### 配置指南
- 应用配置
  - application.yml：设置端口、数据库、Redis、JWT密钥与过期时间等
  - **application-verify.yml**：验证环境专用配置，包含调试令牌接口的放行规则
  - AuthProperties：认证相关自定义配置项
- 安全配置
  - SecurityConfig：配置白名单、鉴权规则、跨域、异常处理器
  - PermissionConfig：权限相关配置
- 基础配置
  - MybatisPlusConfig：分页、乐观锁、SQL注入器等
  - RedisConfig：连接池、序列化策略
  - JacksonConfig：日期、空值序列化策略
  - SnowflakeIdWorker：分布式ID生成策略

**更新**：新增了application-verify.yml配置文件，用于验证环境的特殊配置。

**章节来源**
- [application.yml](file://crm-app/src/main/resources/application.yml)
- [application-verify.yml](file://crm-app/src/main/resources/application-verify.yml)
- [application.yml](file://crm-auth/src/main/resources/application.yml)
- [AuthProperties.java](file://crm-auth/src/main/java/com/crm/auth/config/AuthProperties.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)
- [JacksonConfig.java](file://crm-base/src/main/java/com/crm/base/config/JacksonConfig.java)
- [SnowflakeIdWorker.java](file://crm-base/src/main/java/com/crm/base/config/SnowflakeIdWorker.java)

### 最佳实践建议
- 令牌安全
  - 使用强密钥与合理的过期时间
  - 敏感操作二次校验（如密码修改、支付）
  - **严禁在生产环境激活verify profile**
- 权限设计
  - 最小权限原则，按需分配角色与菜单
  - 数据范围粒度适中，避免过度复杂
- 缓存策略
  - 热点数据（部门树、菜单树）缓存，注意失效策略
  - 令牌黑名单与在线用户列表定期清理
- 监控与审计
  - 记录登录、登出、权限变更等关键事件
  - 使用TraceId串联日志，便于问题定位
  - **调试令牌接口使用需记录审计日志**
- **验证环境管理**
  - 确保CI/CD流程不会在生产环境激活verify profile
  - 定期检查verify profile的配置安全性
  - 使用环境变量隔离不同环境的配置

**更新**：新增了验证环境管理的相关最佳实践建议。

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

### 验证环境使用说明
**新增章节**：详细说明验证环境专用调试令牌端点的使用方法。

#### 环境准备
1. 确保docker-compose配置中包含verify profile
2. 确认application-verify.yml已正确配置
3. 验证Spring Boot应用以verify profile启动

#### 使用步骤
1. **获取用户ID**：从数据库中查询现有用户的ID
   ```bash
   docker compose exec mysql mysql -uroot -pverify123 -e "SELECT id, username FROM crm.crm_auth_user LIMIT 5;"
   ```

2. **调用调试接口**：使用userId获取JWT令牌
   ```bash
   curl -X POST 'http://localhost:8080/api/auth/debug/token?userId=<用户ID>'
   ```

3. **使用令牌**：将返回的JWT放入Authorization头进行其他接口调用
   ```bash
   curl -X GET 'http://localhost:8080/api/file/upload' \
     -H "Authorization: Bearer <JWT令牌>"
   ```

#### 安全注意事项
- **仅限验证环境使用**：该接口绝对不能在生产环境激活
- **审计日志**：每次调用都会记录WARN级别的审计日志
- **令牌有效性**：生成的JWT与正常登录产生的令牌完全一致
- **配置隔离**：通过@Profile("verify")确保端点只在验证环境可用

**章节来源**
- [DebugTokenController.java](file://crm-auth/src/main/java/com/crm/auth/controller/DebugTokenController.java)
- [application-verify.yml](file://crm-app/src/main/resources/application-verify.yml)
- [deploy-verify.md](file://docs/deploy-verify.md)
- [0014-verify-profile-debug-token-endpoint.md](file://docs/adr/0014-verify-profile-debug-token-endpoint.md)