角色管理与角色授权使用说明

构建时间2026-06-26 20:10:33（Asia/Shanghai）来源项目中间件文档 / 中间件后端来源仓../cl-midserver-2026来源提交号69b951a07311e75887b57e0400d888f89dd72cac

查看文档来源信息

• 来源目录：addons/sys_base/docs
• 来源文件：功能说明/角色管理与角色授权使用说明.md

## 功能用途 用于维护普通角色基础资料、应用绑定、PCWEB 系统菜单授权、移动端应用菜单授权、动作授权、默认页和可管理角色范围。

入口位置

• PCWEB 角色管理页
• 角色授权抽屉

使用前提

1. 当前模块已接入正式页面码和动作码清单。
2. 目标角色属于当前模块。
3. 当前登录用户对目标角色具备正式可管理权限。

操作方法

1. 在角色管理页新增、复制或选择目标角色。
2. 使用“复制角色”时，只会创建新的正式角色副本，不会改动源角色；复制内容按开关决定是否沿用应用绑定、可管理角色范围、正式页面/动作授权和默认页。
3. 打开“授权设置”抽屉，维护应用绑定、页面授权、动作授权和默认页。
4. 在“菜单授权”页签维护 PCWEB/后台 system_menu 权限和默认页。
5. 在“应用菜单授权”页签选择应用范围，维护移动端/应用端 app_menu 页面、动作权限和应用端默认首页。
6. 保存后重新读取角色授权状态，确认授权结果与默认页同步结果。
7. 必要时用该角色对应账号重新登录，分别验证 PCWEB 默认页、后台页面放行和移动端应用菜单结果。

规则说明

1. 超级管理员用户可以维护任意普通角色。
2. 普通角色只能维护自己可管理角色范围内的目标角色。
3. 复制角色时，普通角色也只能复制自己可管理范围内的源角色，且复制出的可管理角色范围、页面/动作授权仍会按当前上下文重新校验，不能借复制越权下发。
4. 默认页必须属于当前角色已授权页面。
5. 角色应用绑定与应用信息列表使用同一套模块归属判定口径，列表能选即允许保存。
6. 超级管理员用户在 role 上下文为其他角色授权时，不会再被当前角色菜单范围误拦。
7. PCWEB/后台菜单授权来自当前模块已发布 system_menu，保存到 sys_authority_menus 并同步 Casbin。
8. 移动端/应用端菜单授权来自当前模块、当前应用范围已发布 app_menu，保存到 sys_app_menu_authority_grants，不影响 PCWEB 菜单树和默认页；其中已授权页面和动作的 grantApis 会同步进入目标角色运行态 Casbin。
9. 应用菜单授权的默认首页按“角色 + 模块 + 应用范围”独立保存，只能从当前应用范围已授权页面中选择，不会修改 PCWEB 默认页。
10. 同一个角色在不同 appScope 下可以拥有不同的应用菜单授权和不同的应用端默认首页。
11. 未发布 app_menu 的应用范围不能保存移动端应用菜单授权。

常见结果

• 保存成功后，目标角色默认页会同步到最新正式授权结果。
• 应用菜单授权保存成功后，移动端通过 getAppMenuAuthority 获取过滤后的页面、动作、菜单树和应用端默认首页；下游后端接口通过当前角色 Casbin 判断是否放行。
• 普通角色被拒绝时，会直接收到目标角色不可管理或菜单范围不足的正式错误。
• 超级管理员用户保存成功后，重新登录普通测试角色即可看到扩容后的页面与默认页。

维护提示

• 遇到“权限不足”时，优先核对当前 claims 的 accessMode、authorityId、isSuperAdmin、isSuperAdminContext。
• 需要排查授权异常时，先看角色授权状态接口返回，再看保存接口返回和服务日志。
• 排查移动端菜单缺失时，先核对应用菜单页当前 appScope 是否已有成功发布，再核对角色抽屉“应用菜单授权”页签是否保存了同一范围。