crm-backend-matt/.qoder/repowiki/zh/content/认证服务/菜单权限控制.md

# 菜单权限控制

<cite>
**本文引用的文件**   
- [SysMenu.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysMenu.java)
- [SysRoleMenu.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysRoleMenu.java)
- [MenuType.java](file://crm-auth/src/main/java/com/crm/auth/domain/enums/MenuType.java)
- [ResourceNode.java](file://crm-auth/src/main/java/com/crm/auth/domain/dto/ResourceNode.java)
- [SysMenuMapper.java](file://crm-auth/src/main/java/com/crm/auth/mapper/SysMenuMapper.java)
- [SysRoleMenuMapper.java](file://crm-auth/src/main/java/com/crm/auth/mapper/SysRoleMenuMapper.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)
- [PermissionServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/PermissionServiceImpl.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)
- [RedisConfig.java](file://crm-base/src/main/java/com/crm/base/config/RedisConfig.java)
- [TreeUtils.java](file://crm-base/src/main/java/com/crm/base/utils/TreeUtils.java)
</cite>

## 更新摘要
**所做更改**   
- 新增 MenuType 枚举，支持 CATALOG、MENU、BUTTON 三种节点类型
- SysMenu 实体扩展按钮级权限字段：description、perms、denyBehavior、status、apiUrl
- 新增 ResourceNode DTO 用于统一的资源树管理
- 实现 ADR-0011 完整的权限资源树管理功能
- 更新菜单类型枚举使用场景和权限控制策略

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

## 简介
本技术文档围绕"菜单权限控制模块"展开，重点覆盖以下能力：
- 菜单树形结构设计：支持目录、菜单、按钮等多层级组织与展示。
- 菜单权限的层级控制：基于角色-菜单关联实现细粒度权限控制。
- 动态菜单生成：根据当前登录用户及其角色，动态构建可见菜单树。
- **新增** 统一资源树管理：通过 MenuType 枚举和 ResourceNode DTO 实现标准化的资源节点管理。
- **增强** 按钮级权限控制：支持描述、权限码、拒绝行为、状态管理和接口映射。
- 缓存机制：通过 Redis 缓存菜单树与权限集合，降低数据库压力。
- 前端集成方案：提供接口契约与数据模型说明，便于前端渲染与按钮级权限控制。
- 配置示例与常见问题：给出典型配置思路与排错清单。

## 项目结构
该模块位于 crm-auth 子模块中，围绕实体、枚举、映射器、服务、控制器与安全过滤器协同工作；通用能力（如 Redis 配置、工具类）位于 crm-base。

```mermaid
graph TB
subgraph "认证授权(crm-auth)"
A["SysMenu(实体)"]
B["SysRoleMenu(实体)"]
C["MenuType(枚举)"]
D["ResourceNode(DTO)"]
E["SysMenuMapper(映射)"]
F["SysRoleMenuMapper(映射)"]
G["ISysMenuService(接口)"]
H["SysMenuServiceImpl(实现)"]
I["PermissionServiceImpl(实现)"]
J["AuthController(控制器)"]
K["SystemController(控制器)"]
L["JwtAuthenticationFilter(过滤器)"]
M["TokenService(令牌服务)"]
N["AuthLoginUser(登录用户上下文)"]
end
subgraph "基础能力(crm-base)"
O["RedisConfig(Redis配置)"]
P["TreeUtils(树工具)"]
end
A --> E
B --> F
G --> H
H --> E
H --> F
I --> G
J --> G
K --> G
L --> M
M --> N
H --> O
H --> P
D --> C
A --> D
```

**图表来源**
- [SysMenu.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysMenu.java)
- [SysRoleMenu.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysRoleMenu.java)
- [MenuType.java](file://crm-auth/src/main/java/com/crm/auth/domain/enums/MenuType.java)
- [ResourceNode.java](file://crm-auth/src/main/java/com/crm/auth/domain/dto/ResourceNode.java)
- [SysMenuMapper.java](file://crm-auth/src/main/java/com/crm/auth/mapper/SysMenuMapper.java)
- [SysRoleMenuMapper.java](file://crm-auth/src/main/java/com/crm/auth/mapper/SysRoleMenuMapper.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)
- [PermissionServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/PermissionServiceImpl.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)
- [RedisConfig.java](file://crm-base/src/main/java/com/crm/base/config/RedisConfig.java)
- [TreeUtils.java](file://crm-base/src/main/java/com/crm/base/utils/TreeUtils.java)

章节来源
- [SysMenu.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysMenu.java)
- [SysRoleMenu.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysRoleMenu.java)
- [MenuType.java](file://crm-auth/src/main/java/com/crm/auth/domain/enums/MenuType.java)
- [ResourceNode.java](file://crm-auth/src/main/java/com/crm/auth/domain/dto/ResourceNode.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)
- [PermissionServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/PermissionServiceImpl.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)
- [RedisConfig.java](file://crm-base/src/main/java/com/crm/base/config/RedisConfig.java)
- [TreeUtils.java](file://crm-base/src/main/java/com/crm/base/utils/TreeUtils.java)

## 核心组件
- **菜单实体 SysMenu**：定义菜单节点的基本信息、层级关系、排序、状态及类型字段，支撑树形结构与权限标识。**新增** 按钮级权限字段包括 description（描述）、perms（权限码）、denyBehavior（拒绝行为）、status（状态）、apiUrl（接口URL）。
- **角色-菜单关联 SysRoleMenu**：维护角色与菜单的多对多关系，用于权限判定。
- **菜单类型 MenuType**：**全新枚举** 区分 CATALOG（目录）、MENU（菜单）、BUTTON（按钮）三种类型，驱动不同的权限控制策略和节点层级关系。
- **资源节点 DTO ResourceNode**：**新增** 统一的资源树管理载体，提供与 SysMenu 实体的双向转换方法。
- **映射层 SysMenuMapper / SysRoleMenuMapper**：封装菜单与角色-菜单的数据访问操作。
- **服务层 ISysMenuService / SysMenuServiceImpl**：提供菜单查询、树构建、权限计算、缓存读写等核心逻辑。
- **权限服务 PermissionServiceImpl**：聚合用户-角色-菜单权限，输出权限集合或菜单树。
- **控制器 AuthController / SystemController**：暴露获取菜单树、权限码列表等接口。
- **安全组件 JwtAuthenticationFilter / TokenService / AuthLoginUser**：解析 JWT、加载用户上下文，为权限判断提供身份依据。
- **基础设施 RedisConfig / TreeUtils**：提供缓存能力与树结构组装工具。

章节来源
- [SysMenu.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysMenu.java)
- [SysRoleMenu.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysRoleMenu.java)
- [MenuType.java](file://crm-auth/src/main/java/com/crm/auth/domain/enums/MenuType.java)
- [ResourceNode.java](file://crm-auth/src/main/java/com/crm/auth/domain/dto/ResourceNode.java)
- [SysMenuMapper.java](file://crm-auth/src/main/java/com/crm/auth/mapper/SysMenuMapper.java)
- [SysRoleMenuMapper.java](file://crm-auth/src/main/java/com/crm/auth/mapper/SysRoleMenuMapper.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)
- [PermissionServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/PermissionServiceImpl.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)
- [RedisConfig.java](file://crm-base/src/main/java/com/crm/base/config/RedisConfig.java)
- [TreeUtils.java](file://crm-base/src/main/java/com/crm/base/utils/TreeUtils.java)

## 架构总览
下图展示了从请求进入、鉴权到菜单权限计算的完整链路，包含新增的资源树管理流程。

```mermaid
sequenceDiagram
participant FE as "前端"
participant API as "SystemController/AuthController"
participant SVC as "ISysMenuService/SysMenuServiceImpl"
participant PERM as "PermissionServiceImpl"
participant MAP as "SysMenuMapper/SysRoleMenuMapper"
participant REDIS as "Redis"
participant AUTH as "JwtAuthenticationFilter/TokenService"
participant USER as "AuthLoginUser"
FE->>API : "请求获取菜单/权限"
API->>AUTH : "解析JWT并加载用户上下文"
AUTH-->>USER : "返回当前用户信息"
API->>SVC : "调用获取菜单树/权限接口"
SVC->>REDIS : "尝试读取缓存"
alt "缓存命中"
REDIS-->>SVC : "返回已缓存的菜单树/权限集"
else "缓存未命中"
SVC->>PERM : "计算用户权限集合"
PERM->>MAP : "查询角色-菜单关联"
MAP-->>PERM : "返回关联数据"
PERM-->>SVC : "返回权限集合"
SVC->>SVC : "按 MenuType 构建菜单树"
SVC->>REDIS : "写入缓存"
end
SVC-->>API : "返回菜单树/权限集"
API-->>FE : "响应结果"
```

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

## 详细组件分析

### 菜单实体与类型设计
- **SysMenu 实体**：包含菜单编码、名称、父节点ID、层级、排序、状态、类型等字段，用于表达树形结构与权限标识。**新增** 按钮级权限字段：
  - `description`：描述/备注，仅 button 类型使用
  - `perms`：权限码（如 crm:user:list），仅 button 类型使用  
  - `denyBehavior`：无权限时的前端行为（hide/disable），仅 button 类型使用
  - `status`：权限点状态（enabled/disabled），全局断路开关
  - `apiUrl`：接口 URL（按钮对应的后端 API 路径），仅 button 类型使用
- **MenuType 枚举**：**全新设计** 定义三种节点类型：
  - `CATALOG(1)`：菜单分组，收纳容器，不承载页面，只能挂 menu 子节点
  - `MENU(2)`：菜单页面，可导航的页面，只能挂 button 子节点
  - `BUTTON(3)`：按钮/权限点，叶子节点，不可再挂子节点，承载权限码和接口映射
- **ResourceNode DTO**：**新增** 统一的资源树管理载体，提供与 SysMenu 的双向转换方法，简化 API 层的输入输出处理。

```mermaid
classDiagram
class SysMenu {
+id
+parentId
+menuName
+menuType
+path
+component
+icon
+sort
+visible
+description
+perms
+denyBehavior
+status
+apiUrl
+children
}
class MenuType {
<<enumeration>>
+CATALOG(1, "catalog")
+MENU(2, "menu")
+BUTTON(3, "button")
+fromCode(code)
+isLegalChild(parentType, childType)
}
class ResourceNode {
+id
+parentId
+name
+type
+sort
+description
+route
+perms
+denyBehavior
+apiUrl
+status
+icon
+fromEntity(entity)
+toEntity()
}
class SysRoleMenu {
+id
+roleId
+menuId
}
SysMenu <.. SysRoleMenu : "被角色关联"
SysMenu --> MenuType : "使用类型"
SysMenu --> ResourceNode : "双向转换"
```

**图表来源**
- [SysMenu.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysMenu.java)
- [MenuType.java](file://crm-auth/src/main/java/com/crm/auth/domain/enums/MenuType.java)
- [ResourceNode.java](file://crm-auth/src/main/java/com/crm/auth/domain/dto/ResourceNode.java)
- [SysRoleMenu.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysRoleMenu.java)

章节来源
- [SysMenu.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysMenu.java)
- [MenuType.java](file://crm-auth/src/main/java/com/crm/auth/domain/enums/MenuType.java)
- [ResourceNode.java](file://crm-auth/src/main/java/com/crm/auth/domain/dto/ResourceNode.java)
- [SysRoleMenu.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysRoleMenu.java)

### 菜单树构建与权限计算流程
- 服务层负责从数据库查询菜单与角色-菜单关联，结合用户角色计算权限集合，再按 MenuType 过滤与排序构建树。
- 树构建过程中，CATALOG 作为容器，MENU 作为路由节点，BUTTON 作为叶子节点参与权限校验。
- **新增** 按钮级权限控制：支持权限码验证、拒绝行为配置、接口 URL 映射等功能。

```mermaid
flowchart TD
Start(["开始"]) --> LoadUser["加载当前用户与角色"]
LoadUser --> CheckCache{"是否命中缓存?"}
CheckCache --> |是| ReturnCache["返回缓存中的菜单树/权限集"]
CheckCache --> |否| QueryDB["查询菜单与角色-菜单关联"]
QueryDB --> CalcPerms["计算权限集合"]
CalcPerms --> BuildTree["按 MenuType 构建菜单树"]
BuildTree --> ApplyButtonPerms["应用按钮级权限控制"]
ApplyButtonPerms --> WriteCache["写入缓存"]
WriteCache --> ReturnResult["返回结果"]
ReturnCache --> End(["结束"])
ReturnResult --> End
```

**图表来源**
- [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)
- [PermissionServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/PermissionServiceImpl.java)
- [SysMenuMapper.java](file://crm-auth/src/main/java/com/crm/auth/mapper/SysMenuMapper.java)
- [SysRoleMenuMapper.java](file://crm-auth/src/main/java/com/crm/auth/mapper/SysRoleMenuMapper.java)
- [TreeUtils.java](file://crm-base/src/main/java/com/crm/base/utils/TreeUtils.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)
- [PermissionServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/PermissionServiceImpl.java)
- [SysMenuMapper.java](file://crm-auth/src/main/java/com/crm/auth/mapper/SysMenuMapper.java)
- [SysRoleMenuMapper.java](file://crm-auth/src/main/java/com/crm/auth/mapper/SysRoleMenuMapper.java)
- [TreeUtils.java](file://crm-base/src/main/java/com/crm/base/utils/TreeUtils.java)

### 控制器与接口契约
- SystemController 暴露获取菜单树与权限码列表的接口，供前端初始化时拉取。
- AuthController 提供登录相关接口，登录后返回用户基本信息与令牌，后续请求携带令牌以进行权限校验。
- **现有接口保持向后兼容**：新的 MenuType 和 ResourceNode 不影响现有的 `/api/system/menus/*` 端点行为。

章节来源
- [SystemController.java](file://crm-auth/src/main/java/com/crm/auth/controller/SystemController.java)
- [AuthController.java](file://crm-auth/src/main/java/com/crm/auth/controller/AuthController.java)

### 安全过滤器与用户上下文
- JwtAuthenticationFilter 在请求到达控制器前解析 JWT，提取用户身份信息。
- TokenService 负责令牌校验与刷新策略。
- AuthLoginUser 承载当前登录用户的上下文信息，包括用户ID、角色集合等，供权限计算使用。

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

### 缓存机制与工具类
- RedisConfig 提供 Redis 客户端配置，用于缓存菜单树与权限集合。
- TreeUtils 提供树结构组装工具，将扁平菜单列表转换为树形结构。

章节来源
- [RedisConfig.java](file://crm-base/src/main/java/com/crm/base/config/RedisConfig.java)
- [TreeUtils.java](file://crm-base/src/main/java/com/crm/base/utils/TreeUtils.java)

## 依赖关系分析
- 控制器依赖服务层，服务层依赖映射器与缓存，权限服务依赖用户上下文与角色-菜单映射。
- 安全过滤器依赖令牌服务，令牌服务依赖用户上下文。
- **新增依赖**：ResourceNode 依赖 MenuType 枚举和 BeanCopyUtils 工具类进行实体转换。

```mermaid
graph LR
Controller["SystemController/AuthController"] --> Service["ISysMenuService/SysMenuServiceImpl"]
Service --> Mapper["SysMenuMapper/SysRoleMenuMapper"]
Service --> Cache["Redis"]
Service --> Utils["TreeUtils"]
Service --> Perm["PermissionServiceImpl"]
Perm --> Context["AuthLoginUser"]
Filter["JwtAuthenticationFilter"] --> Token["TokenService"]
Token --> Context
ResourceNode --> MenuType
ResourceNode --> BeanCopyUtils
SysMenu --> MenuType
```

**图表来源**
- [SystemController.java](file://crm-auth/src/main/java/com/crm/auth/controller/SystemController.java)
- [AuthController.java](file://crm-auth/src/main/java/com/crm/auth/controller/AuthController.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)
- [SysMenuMapper.java](file://crm-auth/src/main/java/com/crm/auth/mapper/SysMenuMapper.java)
- [SysRoleMenuMapper.java](file://crm-auth/src/main/java/com/crm/auth/mapper/SysRoleMenuMapper.java)
- [PermissionServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/PermissionServiceImpl.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)
- [ResourceNode.java](file://crm-auth/src/main/java/com/crm/auth/domain/dto/ResourceNode.java)
- [MenuType.java](file://crm-auth/src/main/java/com/crm/auth/domain/enums/MenuType.java)

章节来源
- [SystemController.java](file://crm-auth/src/main/java/com/crm/auth/controller/SystemController.java)
- [AuthController.java](file://crm-auth/src/main/java/com/crm/auth/controller/AuthController.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)
- [SysMenuMapper.java](file://crm-auth/src/main/java/com/crm/auth/mapper/SysMenuMapper.java)
- [SysRoleMenuMapper.java](file://crm-auth/src/main/java/com/crm/auth/mapper/SysRoleMenuMapper.java)
- [PermissionServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/PermissionServiceImpl.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)
- [ResourceNode.java](file://crm-auth/src/main/java/com/crm/auth/domain/dto/ResourceNode.java)
- [MenuType.java](file://crm-auth/src/main/java/com/crm/auth/domain/enums/MenuType.java)

## 性能考虑
- 缓存优先：首次请求后缓存菜单树与权限集合，减少重复查询。
- 合理键名：按用户ID或角色维度设计缓存键，避免冲突。
- 失效策略：当菜单或角色-菜单关联变更时主动清理相关缓存。
- 分页与懒加载：对于大型菜单树，可在前端按需加载子节点。
- 索引优化：确保菜单表与角色-菜单表的关联字段有合适索引。
- **新增优化**：ResourceNode DTO 减少数据传输量，提升网络传输效率。

[本节为通用指导，无需特定文件引用]

## 故障排查指南
- 菜单树为空：检查用户是否有角色分配，确认角色-菜单关联是否存在。
- 权限不一致：核对缓存是否过期或未及时清理，确认权限计算逻辑是否包含目标菜单类型。
- **新增问题**：按钮权限无效：检查按钮类型的 perms 字段是否正确配置，确认 denyBehavior 设置是否符合预期。
- **新增问题**：节点类型错误：验证 MenuType 枚举值是否正确，检查 isLegalChild 规则是否满足。
- **新增问题**：ResourceNode 转换失败：确认 fromEntity/toEntity 方法的字段映射是否正确。
- 登录失败：检查 JWT 解析与令牌服务配置，确认用户上下文是否正确加载。
- 缓存异常：检查 Redis 连接与序列化配置，确认键名与过期时间设置。

章节来源
- [SysMenuServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/SysMenuServiceImpl.java)
- [PermissionServiceImpl.java](file://crm-auth/src/main/java/com/crm/auth/service/impl/PermissionServiceImpl.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)
- [RedisConfig.java](file://crm-base/src/main/java/com/crm/base/config/RedisConfig.java)
- [MenuType.java](file://crm-auth/src/main/java/com/crm/auth/domain/enums/MenuType.java)
- [ResourceNode.java](file://crm-auth/src/main/java/com/crm/auth/domain/dto/ResourceNode.java)

## 结论
本模块通过清晰的实体设计与分层架构，实现了灵活的菜单树形结构与细粒度的权限控制。**新增的 MenuType 枚举和 ResourceNode DTO 提供了统一的资源树管理能力**，增强了按钮级权限控制的灵活性。借助缓存与工具类，提升了性能与可维护性。配合前端集成方案，可实现完整的动态菜单与按钮级权限控制。

[本节为总结性内容，无需特定文件引用]

## 附录

### 菜单类型与权限策略对照
- **CATALOG（目录）**：控制可见性与展开行为，不直接绑定资源权限，只能包含 MENU 子节点。
- **MENU（菜单）**：控制页面路由与导航可见性，通常对应前端路由，只能包含 BUTTON 子节点。
- **BUTTON（按钮）**：控制页面内操作按钮的显示与可点击，需在后端进行接口级权限校验，支持权限码、拒绝行为和接口映射。

章节来源
- [MenuType.java](file://crm-auth/src/main/java/com/crm/auth/domain/enums/MenuType.java)
- [SysMenu.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysMenu.java)

### 前端集成要点
- 登录后拉取菜单树与权限码列表，存储至本地状态。
- 路由守卫根据菜单类型与权限码决定是否允许进入。
- **新增** 按钮级权限通过指令或条件渲染控制显示与禁用，支持 hide 和 disable 两种拒绝行为。
- 菜单变更时主动刷新缓存与前端状态。
- **新增** 使用 ResourceNode DTO 进行前后端数据交互，简化字段映射。

章节来源
- [SystemController.java](file://crm-auth/src/main/java/com/crm/auth/controller/SystemController.java)
- [AuthController.java](file://crm-auth/src/main/java/com/crm/auth/controller/AuthController.java)
- [ResourceNode.java](file://crm-auth/src/main/java/com/crm/auth/domain/dto/ResourceNode.java)

### 常见配置示例（思路）
- **菜单表字段**：父节点ID、编码、名称、类型、排序、状态、路径、组件、权限码。
- **新增按钮字段**：description（描述）、perms（权限码）、denyBehavior（拒绝行为）、status（状态）、apiUrl（接口URL）。
- **角色-菜单关联**：角色ID、菜单ID。
- **缓存键命名**：user_menu_tree:{userId}、user_perms:{userId}。
- **失效时机**：菜单增删改、角色-菜单关联变更、用户角色变更。
- **新增枚举映射**：CATALOG=1、MENU=2、BUTTON=3。

章节来源
- [SysMenu.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysMenu.java)
- [SysRoleMenu.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysRoleMenu.java)
- [MenuType.java](file://crm-auth/src/main/java/com/crm/auth/domain/enums/MenuType.java)
- [ResourceNode.java](file://crm-auth/src/main/java/com/crm/auth/domain/dto/ResourceNode.java)
- [RedisConfig.java](file://crm-base/src/main/java/com/crm/base/config/RedisConfig.java)

### ADR-0011 实施说明
- **目标**：实现完整的权限资源树管理，支持三级节点结构（目录-菜单-按钮）。
- **核心变更**：
  - 引入 MenuType 枚举替代原有的数字类型
  - 扩展 SysMenu 实体支持按钮级权限配置
  - 创建 ResourceNode DTO 统一资源树管理接口
- **兼容性**：保持现有接口的向后兼容，不影响现有 `/api/system/menus/*` 端点行为。
- **测试覆盖**：确保所有现有测试用例通过，新功能不影响现有功能。

章节来源
- [MenuType.java](file://crm-auth/src/main/java/com/crm/auth/domain/enums/MenuType.java)
- [SysMenu.java](file://crm-auth/src/main/java/com/crm/auth/domain/entity/SysMenu.java)
- [ResourceNode.java](file://crm-auth/src/main/java/com/crm/auth/domain/dto/ResourceNode.java)