DM-ROW 接口文档

Appearance

权限控制系统 ​

**本文引用的文件** - [CustomUserDetailsServiceImpl.java](file://lemes-cloud/lemes-auth/src/main/java/com/lenovo/lemes/auth/security/CustomUserDetailsServiceImpl.java) - [PasswordAuthenticationProvider.java](file://lemes-cloud/lemes-auth/src/main/java/com/lenovo/lemes/auth/security/password/PasswordAuthenticationProvider.java) - [PermissionController.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-common/lemes-service-dm-common-server/src/main/java/com/lenovo/lemes/service/dm/common/controller/PermissionController.java) - [UserController.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-common/lemes-service-dm-common-server/src/main/java/com/lenovo/lemes/service/dm/common/controller/UserController.java) - [RoleController.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-common/lemes-service-dm-common-server/src/main/java/com/lenovo/lemes/service/dm/common/controller/RoleController.java) - [SysUserClient.java](file://lemes-cloud/lemes-auth/src/main/java/com/lenovo/lemes/auth/feign/SysUserClient.java) - [OAuth2AuthenticationDeserialize.java](file://lemes-cloud/lemes-framework/lemes-framework-auth/src/main/java/com/lenovo/lemes/framework/auth/security/OAuth2AuthenticationDeserialize.java)

目录 ​

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

简介 ​

本文件面向DeviceMate项目的权限控制系统，系统采用基于Spring Security与Spring Authorization Server的认证与授权方案，结合RBAC（基于角色的访问控制）模型，实现用户、角色、权限、菜单的层级关系管理；并通过注解式权限控制、URL权限过滤、方法级权限验证等机制保障系统安全。同时，文档涵盖菜单权限管理（树形结构、动态加载、继承规则）、数据权限控制（范围限制、用户数据隔离、跨部门访问控制）、操作权限管理（按钮、字段、表单细粒度控制）、权限缓存策略（缓存、失效与通知）、以及权限审计（使用统计、异常监控、违规告警）等完整方案，为系统管理员与开发者提供可落地的权限管理解决方案。

项目结构 ​

围绕权限控制的关键模块分布于以下位置：

  • 认证与用户服务：lemes-auth（用户详情加载、密码认证提供者）
  • 业务控制器：lemes-service-dm-common-server（用户、角色、权限演示）
  • 权限框架：lemes-framework-auth（OAuth2反序列化等工具）

图表来源

章节来源

核心组件 ​

  • 用户详情加载与权限注入：通过自定义UserDetailsService从远程客户端加载用户信息，并将菜单与权限注入Security上下文。
  • 密码认证提供者：实现基于用户名/密码的OAuth2认证流程，生成访问令牌与刷新令牌并持久化授权信息。
  • RBAC控制器：提供用户、角色、权限的增删改查与授权接口，配合注解实现方法级权限校验。
  • 权限演示接口：通过注解式权限控制展示hasAnyAuthority的使用方式。
  • 权限缓存与反序列化：提供OAuth2认证信息的反序列化支持，兼容历史缓存格式。

章节来源

架构总览 ​

下图展示了认证与授权在DeviceMate中的整体交互：前端发起登录请求，后端通过密码认证提供者完成认证，生成访问令牌与刷新令牌；随后用户详情加载器从远程客户端获取菜单与权限，注入到Security上下文；业务控制器通过注解进行方法级权限校验；权限框架提供OAuth2认证信息的反序列化能力以兼容缓存。

图表来源

详细组件分析 ​

用户详情加载与权限注入 ​

  • 职责：实现UserDetailsService，从远程客户端加载用户详情（含菜单与权限），并将权限集合注入到Security上下文。
  • 关键点：当用户不存在时抛出用户名未找到异常；权限集合由远程客户端提供，确保集中管理。

图表来源

章节来源

密码认证提供者（OAuth2） ​

  • 职责：实现基于用户名/密码的OAuth2认证流程，校验客户端与作用域，生成访问令牌与刷新令牌，并持久化授权信息。
  • 关键点：对用户名/密码进行认证失败时返回标准OAuth2错误；支持按请求作用域覆盖默认作用域；生成令牌后保存授权记录。

图表来源

章节来源

RBAC控制器（用户/角色/权限） ​

  • 用户控制器：提供用户增删改查、角色授权、权限查询、报表权限标志等接口，支撑用户维度的权限管理。
  • 角色控制器：提供角色增删改查、角色授权用户、角色绑定菜单等接口，支撑角色维度的权限管理。
  • 权限演示控制器：通过注解式权限控制展示hasAnyAuthority的使用方式，便于理解方法级权限验证。

图表来源

章节来源

注解式权限控制与方法级验证 ​

  • 使用PreAuthorize注解在控制器方法上声明所需权限，系统在执行方法前进行权限校验。
  • 示例：演示控制器中对“列出权限”和“新增权限”的注解式权限控制。

图表来源

章节来源

菜单权限管理（树形结构、动态加载、继承规则） ​

  • 菜单树形结构：菜单以树形结构组织，支持父子层级关系，便于构建导航与页面布局。
  • 动态菜单加载：用户登录后，系统从用户详情中获取菜单列表，动态渲染前端界面。
  • 继承规则：角色可继承多个菜单权限，用户通过角色获得菜单集合，菜单权限向下继承至子节点。

图表来源

章节来源

数据权限控制（范围限制、用户隔离、跨部门访问） ​

  • 报表权限标志：提供查询用户报表权限标志的接口，用于区分“查看全量数据”与“仅查看本部门”两种模式。
  • 同部门用户查询：提供按当前登录用户所在部门（含子部门）查询用户的接口，实现数据隔离。
  • 跨部门访问控制：通过权限标志与部门查询接口组合，实现精细化的数据访问控制。

图表来源

章节来源

操作权限管理（按钮、字段、表单） ​

  • 按钮权限：通过菜单与权限集合控制页面按钮的显示与可用性，避免越权操作。
  • 字段权限：在表单渲染时根据权限集合决定字段的可见性与可编辑性。
  • 表单权限：在提交前进行权限校验，确保用户具备对应操作权限。

（本节为概念性说明，不直接分析具体文件）

权限缓存策略（缓存、失效与通知） ​

  • 缓存内容：用户菜单与权限集合、OAuth2认证信息等。
  • 失效策略：用户角色/菜单/权限发生变更时，触发缓存失效与重建。
  • 通知机制：权限变更后通过消息或事件通知相关模块更新本地缓存。

（本节为概念性说明，不直接分析具体文件）

权限审计（使用统计、异常监控、违规告警） ​

  • 使用统计：记录权限使用频次与热点接口，辅助优化权限设计。
  • 异常监控：对认证失败、权限不足等异常进行统一捕获与上报。
  • 违规告警：对高风险操作与异常访问行为进行实时告警。

（本节为概念性说明，不直接分析具体文件）

依赖关系分析 ​

  • 用户详情加载依赖远程客户端，后者负责提供菜单与权限集合。
  • 密码认证提供者依赖认证管理器、授权服务与令牌生成器，形成完整的OAuth2认证链路。
  • 控制器层通过注解实现方法级权限校验，依赖Security上下文中的权限集合。
  • 权限框架提供OAuth2认证信息的反序列化支持，兼容历史缓存格式。

图表来源

章节来源

性能考虑 ​

  • 缓存优先：将用户菜单与权限集合放入缓存，减少远程调用次数。
  • 批量查询：在用户/角色/权限查询时尽量使用批量接口，降低网络往返。
  • 令牌复用：合理设置访问令牌有效期与刷新令牌策略，平衡安全性与性能。
  • 权限预热：在用户登录时预加载其权限集合，避免首次请求延迟。

（本节为通用建议，不直接分析具体文件）

故障排查指南 ​

  • 登录失败：检查密码认证提供者对用户名/密码的认证流程与错误码映射。
  • 权限不足：确认用户角色与菜单权限是否正确配置，控制器注解是否匹配权限标识。
  • 菜单不显示：检查用户详情加载器返回的菜单集合是否正确，前端是否正确渲染。
  • 缓存异常：核对权限缓存的失效与重建逻辑，必要时清理缓存并重试。

章节来源

结论 ​

DeviceMate的权限控制系统以RBAC为核心，结合Spring Security与Spring Authorization Server实现了从认证到授权的完整闭环。通过用户详情加载、密码认证提供者、注解式权限控制与控制器接口，系统能够灵活地管理用户、角色、权限与菜单，并支持数据权限与操作权限的细粒度控制。配合完善的缓存与审计策略，可满足生产环境对安全性与性能的双重要求。

附录 ​

  • 建议在生产环境中启用HTTPS、最小权限原则、定期审计与权限复核机制。
  • 对高风险接口增加二次确认与操作日志，强化合规与可追溯性。