应用菜单使用说明
查看文档来源信息
- 来源目录：
addons/sys_base/docs - 来源文件：
功能说明/应用菜单使用说明.md
app_menu 还作为移动端/应用端角色授权的数据源。发布完成后，需要在角色授权抽屉的“应用菜单授权”页签为角色配置对应应用范围下的页面和动作权限。
入口位置
- PCWEB
应用菜单
使用前提
- 当前模块已经接入正式菜单清单治理链路。
- 打开应用菜单页需要页面权限
app.menu.publish。 - 执行上传、提交版本、发布、切换当前版本等管理操作，需要动作权限
app.menu.publish.manage。 - 配置角色应用菜单授权前，目标应用范围必须已经存在成功发布的
app_menu。
页面结构
- 首页默认展示当前模块、当前应用范围下的当前生效应用菜单；当只选择单个具体应用或单个接入 AppID 时，首页按该应用实际运行态匹配已发布版本，匹配顺序与移动端一致。
- 页面会明确展示当前模块、清单类型和生效范围，避免误读当前查看对象。
- 发布工作台负责处理版本操作，首页不再混入上传治理入口。
正式操作流程
- 进入应用菜单页，先确认当前应用范围。
- 首页会读取当前应用范围下的当前生效版本及结构化菜单结果；如果按 AppID 查看但实际命中按应用 UUID 发布的版本，摘要区会显示实际命中的发布范围。
- 如需调整，进入发布工作台，选择 JSON 清单后立即执行本地结构检查和服务端预校验。
- 如果存在阻断项，页面展示字段、原因和修复建议，保存草稿按钮保持不可用；例如根字段写成
seeds时，应改为正式字段menuSeeds后重新选择文件。 - 预校验通过后，页面展示程序解析结果和与当前生效版本的差异，再允许保存草稿。
- 按“保存草稿 -> 提交版本 -> 发布”完成正式发布。
- 如需让历史版本重新生效，可在版本列表中执行“切换为当前版本”。
- 切换成功后，该应用范围的运行态菜单会立即按目标版本生效。
- 发布完成后，进入角色管理页，打开目标角色授权抽屉。
- 在“应用菜单授权”页签选择与发布一致的应用范围，勾选移动端页面和动作后保存。
- 移动端调用
/sys_base/public/auth/getAppMenuAuthority获取当前用户已授权的应用菜单结果。
下游与应用端接入流程
- 下游先在本模块
app_menu清单中声明移动端或应用端页面、动作、菜单树和默认页。 - 如果清单只对部分应用生效，必须使用
appScope.scopeMode=app_uuids、app_ids或app_model_uuids明确范围；不要把只给单个应用使用的菜单发布成all_apps。 - 管理员在 PCWEB 应用菜单页按同一
appScope上传、提交并发布app_menu。 - 管理员在角色管理页打开目标角色，在“应用菜单授权”页签选择同一
appScope，保存该角色在移动端或应用端可见的页面和动作。 - 应用端登录后先持有当前用户系统 token；服务端或应用端安全层再使用当前应用 permanent key 调用
/sys_base/public/auth/exchangeTempKey换取 tempKey。 - 应用端可以通过
/sys_base/platform/user/getUserInfo的appMenuDefaultPage判断当前上下文是否已经配置应用菜单首页。 - 应用端调用
/sys_base/public/auth/getAppMenuAuthority时，请求体传token，Header 传X-App-Key: <tempKey>、app-id: <当前应用UUID>、addons-type: <当前模块标识>。 - 应用端只根据返回的
tree渲染菜单，根据pageCodes判断页面进入权限，根据actionCodes或menuFlags控制按钮、入口和业务动作；真正的后端接口访问仍由当前 token 对应角色的 Casbin 权限决定。 - 当返回
published=false或权限数组为空时，应用端应按“当前无可用菜单或无权限”处理，不显示未授权入口，也不回退到 PCWEB 菜单、代码清单或历史本地菜单。
清单编写要求
pageCode必须是移动端或应用端稳定页面编码，不能直接复用 PCWEB 后台页面码表达另一类页面。routeName和routePath面向应用端路由注册表使用；中间件只保存和返回，不负责下发具体页面组件实现。actionCode必须覆盖页面内需要独立授权的按钮、操作入口或业务动作；只配置页面可见不代表页面内所有动作都可用。menuFlag用于菜单树节点和动作授权标识归集，同一清单内应保持唯一、稳定、可读。defaultPage必须指向同一app_menu内存在的页面；应用端拿到默认页后仍要确认该页面在当前返回权限中可见。- 菜单承载节点根字段固定为
menuSeeds，不能写成seeds或其他临时字段名。
应用端消费规则
tree是已经按当前角色授权过滤后的菜单树，应用端优先用它渲染导航。pageCodes是当前用户可进入的页面集合，应用端路由守卫应以它为准。actionCodes是当前用户可执行的动作集合，应用端按钮和业务操作应以它为准。menuFlags包含已授权菜单标识和动作授权标识，可用于兼容需要按菜单标识判断的应用端实现。defaultPage表示命中清单声明的应用端默认页；如果该默认页没有出现在当前授权结果中，应用端应进入无权限页或让用户选择其他已授权页面。
联调检查清单
- 确认当前应用已在模块应用信息中登记，
app-id使用应用 UUID。 - 确认发布
app_menu时的appScope与角色授权页选择的appScope一致。 - 确认角色已绑定当前模块和当前应用，否则用户登录上下文可能无法进入该应用范围。
- 确认调用运行态接口前已经用 permanent key 换取 tempKey，不能把 permanent key 直接作为
X-App-Key。 - 确认应用端使用的是
/sys_base/public/auth/getAppMenuAuthority获取完整应用菜单授权；getUserInfo.appMenuDefaultPage只用于读取当前上下文首页摘要，不返回完整菜单树、页面码或动作码。
版本列表说明
- 版本列表按“当前生效”“待发布”“历史已发布”“草稿”“已阻断”展示状态。
- 当前生效版本会在摘要区和版本列表中明确标识。
- 版本详情优先展示程序解释后的菜单结构和差异摘要，原始 JSON 只保留为辅助导出入口。
运行规则
- 应用菜单继续按“模块 + 应用范围”隔离读取与发布。
- 切换当前版本本质上会追加一条新的成功发布记录，并立即影响该范围的运行态读取结果。
- 普通角色缺少页面权限或动作权限时，由后端正式拒绝访问。
- 应用菜单授权结果与 PCWEB 系统菜单授权结果在菜单树、默认页和持久化表上相互独立，同一角色可以拥有不同的后台权限和移动端权限；但两类清单中的
grantApis都会在授权保存或菜单发布后合并进该角色运行态 Casbin。 - 移动端运行态和应用菜单首页的单应用查看，均按当前应用匹配已发布应用菜单范围，顺序为具体应用 UUID、具体接入 AppID、应用模型、全部应用。
- 未发布、未匹配或未授权时，移动端返回空权限，不回退到系统菜单、代码清单或历史应用菜单表。
- 下游服务用当前角色 token 访问业务接口时，权限检查应走统一 Casbin；不要在业务接口中按请求临时查询应用菜单授权表。
- 保存草稿前后端都会校验菜单清单；存在
blocking阻断项时不会创建新的草稿版本。
维护提示
- 如果当前范围没有菜单，先确认该范围是否已有成功发布记录。
- 如果版本无法切换为当前版本，先确认该版本是否为已提交或历史已发布版本。
- 如果当前范围看起来不对，先核对页面顶部选择的查看范围、摘要区显示的实际命中范围，再核对版本详情中的
appScope。 - 如果移动端用户看不到菜单，先核对角色“应用菜单授权”页签选择的
appScope是否与发布范围一致。