CL 正式文档平台

角色授权与默认页契约说明 ​

构建时间2026-06-26 20:10:33（Asia/Shanghai）来源项目中间件文档 / 中间件后端来源仓../cl-midserver-2026来源提交号69b951a07311e75887b57e0400d888f89dd72cac
查看文档来源信息
  • 来源目录：addons/sys_base/docs
  • 来源文件：契约说明/角色授权与默认页契约说明.md
## 契约用途 - 适用范围：角色管理页、角色授权抽屉、登录后运行时权限初始化、头部身份切换后的权限重建。 - 当前正式版本：2026-06-10。

当前正式口径 ​

  1. 超级管理员是用户级身份，不是 sys_authorities 中的一条普通角色记录。
  2. 当前正式运行上下文只有两种：role 和 super_admin。
  3. selectedAuthorityId=0 只在 super_admin 上下文下合法。
  4. 角色授权正式以页面码、动作码、菜单标识和默认页页面码为准，不再以历史菜单树字段作为正式口径。
  5. 下游业务菜单授权必须基于当前模块已发布 system_menu，不再使用代码动作清单接口保存业务页面授权。
  6. 移动端/应用端菜单授权必须基于当前模块和当前应用范围已发布的 app_menu，并与 PCWEB system_menu 授权相互独立。

关键字段口径 ​

字段含义
authorityId普通角色主键 ID
accessMode当前运行上下文类型，正式取值为 role 或 super_admin
selectedAuthorityId当前生效角色 ID；super_admin 上下文下固定为 0
pageCodes目标角色正式页面码列表
actionCodes目标角色正式动作码列表
menuFlags目标角色正式菜单标识列表，仅在已发布菜单授权中使用
defaultPageCode目标角色正式默认页页面码
defaultPage当前上下文默认页；PCWEB 默认页来自已发布 system_menu，应用菜单默认页来自已发布 app_menu
appMenuDefaultPage当前 app-id 下命中 app_menu 授权后的应用端默认首页摘要
manageableAuthorityIds当前角色可管理角色范围
appScopeapp_menu 生效应用范围，支持 all_apps、app_model_uuids、app_uuids、app_ids
appScopeKey后端归一化后的 app_menu 应用范围键

运行规则 ​

  1. GET /sys_base/platform/manifest/getAuthorityCodeActionStatus 由控制器内按当前上下文和可管理角色范围校验，不依赖外层 Casbin 先命中。
  2. 当前会话读取自己当前生效角色的授权状态属于正式允许场景。
  3. 超级管理员用户可以读取任意普通角色授权状态，也可以读取 super_admin 上下文状态。
  4. 普通角色读取其他角色授权状态时，目标角色必须落在自己可管理角色范围内。
  5. GET /sys_base/platform/manifest/getPublishedMenuAuthorityStatus 是下游业务菜单授权状态读取入口，数据源只来自当前模块已发布 system_menu。
  6. POST /sys_base/platform/manifest/savePublishedMenuAuthority 是下游业务菜单授权保存入口，保存前校验目标角色模块、已发布页面/菜单/动作存在性、默认页范围和操作者可下发范围。
  7. POST /sys_base/platform/manifest/saveAuthorityCodeActions 只服务代码动作清单授权；调用方传入不属于代码动作清单的业务页面码时，必须提示改用 savePublishedMenuAuthority。
  8. 超级管理员上下文保存普通角色授权时，可以使用当前模块已发布菜单中的全部可见节点；没有发布菜单时不能生成兜底授权树。
  9. 普通角色保存目标角色授权时，选中的页面、菜单和动作必须仍落在自己当前角色已放行的菜单承载范围内。
  10. defaultPageCode 必须属于本次保存后的页面授权集合；保存完成后由后端同步修正目标角色默认页。
  11. POST /sys_base/platform/authority/copyAuthority 复制角色时，仍按当前上下文对源角色、可管理角色范围、已发布菜单授权和默认页进行同口径校验，不能通过复制绕开正式授权边界。
  12. POST /sys_base/platform/manifest/getAppMenuAuthorityStatus 是角色应用菜单授权状态读取入口，数据源只来自当前模块、当前应用范围已发布的 app_menu。
  13. POST /sys_base/platform/manifest/saveAppMenuAuthority 是角色应用菜单授权保存入口，保存结果写入 sys_app_menu_authority_grants，不写入 sys_authority_menus，不修改 PCWEB 默认页；保存后会重建该角色运行态 Casbin，把 system_menu 与 app_menu 已授权 grantApis 合并为统一接口权限。
  14. POST /sys_base/public/auth/getAppMenuAuthority 是移动端/应用端运行态读取入口，按当前 app-id 匹配已发布 app_menu 后只返回当前上下文已授权的应用菜单结果。
  15. GET /sys_base/platform/user/getUserInfo 在返回当前上下文时会附带 appMenuDefaultPage，用于让调用方确认当前应用菜单默认首页是否已配置并授权；该字段不替代完整应用菜单权限接口。
  16. 当 getUserInfo 的 PCWEB system_menu 默认页未解析，而当前应用菜单默认页已经明确解析成功时，defaultPage 可返回同一个应用菜单默认页以兼容登录态默认页消费；该行为不构成从 app_menu 回退到 system_menu，也不允许在未发布、未授权或未配置时生成默认页。

上下游约定 ​

  • PCWEB 登录和切换身份必须以 getUserInfo、asyncMenu、运行时权限状态和 defaultPage 为准。
  • PCWEB 角色授权抽屉在 sys_base 或明确代码动作清单场景下使用 getAuthorityCodeActionStatus、saveAuthorityCodeActions。
  • PCWEB 角色授权抽屉在下游业务模块下使用 getPublishedMenuAuthorityStatus、savePublishedMenuAuthority。
  • PCWEB 角色授权抽屉的“应用菜单授权”页签使用 getAppMenuAuthorityStatus、saveAppMenuAuthority，用于配置移动端/应用端权限。
  • 调用方可通过 getUserInfo.currentContext.appMenuDefaultPage 或 getUserInfo.appMenuDefaultPage 判断当前应用菜单首页是否已配置；需要渲染应用端菜单和做页面/动作校验时必须继续使用 getAppMenuAuthority。
  • 移动端/应用端只消费 getAppMenuAuthority 返回的 pageCodes、actionCodes、menuFlags、tree 和 defaultPage，不能用 PCWEB 菜单权限推导应用菜单权限。
  • 下游后端接口权限检查统一调用 checkPermission 或 SDK 封装；授权来源可以是 system_menu 或 app_menu，运行时放行结果只看当前角色 Casbin。
  • 普通角色被正式拒绝时，应直接展示后端权限结果；不得把拒绝伪装成“前端不再请求”。
  • 超级管理员被正式放行时，不得因外层 Casbin 预拦截而阻断页面初始化。
  • 下游模块需要公共治理入口时，必须把入口随本模块 system_menu 发布后再授权。

不允许的做法 ​

  • 不允许新增“超级管理员角色”替代超级管理员用户身份。
  • 不允许用伪造 authorityId 或伪造角色记录模拟 super_admin。
  • 不允许把超级管理员正式放行问题归因成“前端不要请求这个接口”后结束整改。
  • 不允许让普通角色拿到超管能力，也不允许超管和普通角色一起被挡住。
  • 不允许用 saveAuthorityCodeActions 保存下游业务页面授权。
  • 不允许无发布菜单时回退展示共享治理菜单或默认公共治理菜单。
  • 不允许用 system_menu 或 sys_authority_menus 结果代替移动端 app_menu 授权。
  • 不允许 app_menu 未发布、未匹配或未授权时回退到代码清单、历史 app_model_menu 或 PCWEB 系统菜单授权。

2026-04-24 联调补充口径 ​

  1. getAuthorityCodeActionStatus 在 super_admin 模式下只允许超级管理员上下文读取；普通角色上下文即使账号本身是超管用户，也不得读取 super_admin 授权状态。
  2. 角色授权页读取目标角色授权状态时，普通角色只能查看自身或可管理角色范围内的目标角色；超级管理员上下文可查看任意普通角色与 super_admin 状态。
  3. 角色授权结果保存后，普通角色继续按正式页面码、动作码、默认页和可管理角色范围生效；超级管理员上下文不再受普通角色当前菜单承载范围误拦截。

2026-05-07 已发布菜单授权补充口径 ​

  1. 下游模块角色授权页展示“已发布菜单授权”，授权树来自当前模块已发布 system_menu。
  2. 未发布 system_menu 时，授权状态接口返回空树，前端展示“当前模块尚未发布菜单”。
  3. saveAuthorityCodeActions 的边界收窄为代码动作清单授权，不再承担下游业务菜单授权职责。
  4. 默认页解析只接受已发布菜单中的已授权页面；无发布菜单、未授权或失效页面均按未配置处理。

2026-06-10 应用菜单授权补充口径 ​

  1. system_menu 授权服务 PCWEB/后台导航、动作和默认页；app_menu 授权服务移动端/应用端页面、动作和菜单树。
  2. 两套菜单授权可以不同，保存、读取、菜单运行态消费和持久化表互相独立；但接口权限统一落到同一角色 Casbin 中。
  3. app_menu 授权必须带明确 appScope，不同应用范围下同一角色的应用菜单权限互相隔离。
  4. 移动端运行态按当前 app-id 在已发布 app_menu 中匹配具体范围：具体应用 UUID、具体接入 AppID、应用模型、全部应用。
  5. 没有正式发布、没有命中应用范围或没有正式授权时，移动端返回空权限；不得回退到历史表或系统菜单权限。
  6. 接口运行态鉴权以 token 中当前 authorityId 为准，checkPermission 在 token、应用和上下文合法后只查角色 Casbin，不在每次请求时再查询 sys_app_menu_authority_grants。

2026-06-24 用户资料接口应用菜单首页补充口径 ​

  1. getUserInfo 返回的上下文列表会按当前 app-id + addons-type + accessMode + authorityId 解析应用菜单默认首页，并放入 appMenuDefaultPage。
  2. appMenuDefaultPage.source=app_menu_authority_grant 表示普通角色命中 sys_app_menu_authority_grants 中的默认页授权；source=super_admin_app_menu 表示超级管理员上下文命中已发布 app_menu 默认页。
  3. appMenuDefaultPage 只在已发布、已命中、已授权或超级管理员上下文可见时返回；否则为空，不返回 default_page_unconfigured 伪结果。
  4. defaultPage 仍优先服务 PCWEB 登录与后台默认页；只有 PCWEB 默认页未解析且 appMenuDefaultPage 已解析时，才会复用应用菜单默认页，便于应用端当前上下文直接读取。

CL 正式文档平台

统一发布开发规范、中间件接口契约与功能说明