菜单发布与运行菜单契约

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

查看文档来源信息

• 来源目录：addons/sys_base/docs
• 来源文件：契约说明/菜单发布与运行菜单契约.md

## 契约用途 说明中间件在最终态下如何处理菜单发布、登录运行菜单、角色授权、默认页和公共治理入口。本文适用于中间件后端、PCWEB、下游业务 PCWEB，以及通过中间件统一登录和授权的下游模块。

当前正式口径

1. 下游模块的运行菜单只认当前模块已经正式发布的 system_menu 清单。
2. 没有发布 system_menu，登录菜单就是空菜单，不回退到代码清单、共享治理清单、演示菜单或历史兼容菜单。
3. 公共治理入口可以复用中间件页面和接口，但必须作为下游模块 system_menu 的一部分显式发布。
4. 角色授权必须基于当前模块已发布 system_menu 解析出的运行承载菜单。
5. saveAuthorityCodeActions 只用于代码动作清单授权，不用于下游业务菜单授权。
6. 超级管理员上下文也必须基于当前模块已发布菜单；没有发布菜单时，超级管理员也拿不到兜底菜单。

字段或结果口径

对象	正式来源	说明
登录菜单	当前模块已发布 system_menu + 当前上下文授权结果	由 /sys_base/platform/menu/getMenu 返回
角色菜单授权	当前模块已发布 system_menu	由 getPublishedMenuAuthorityStatus 和 savePublishedMenuAuthority 维护
代码动作授权	中间件代码动作清单	只由 getAuthorityCodeActionStatus 和 saveAuthorityCodeActions 维护
默认页	已发布菜单中的已授权页面	普通角色必须已授权；超级管理员取已发布菜单默认页或第一个可见页面
公共治理入口	下游模块发布清单中的普通菜单节点	不允许运行时偷偷注入
菜单图标	menuSeeds[].icon；当对应页面的 menuSeeds[].icon 为空时，可由 pages[].icon 回填	/sys_base/platform/menu/getMenu 返回 meta.icon，菜单发布运行视图返回 nodes[].icon

运行规则

1. /sys_base/platform/menu/getMenu 进入 manifest 运行链时，只读取当前模块已发布的 system_menu。读取不到发布记录时返回 menus=[]。
2. 超级管理员上下文在有发布菜单时可以看到当前模块已发布菜单中的全部可见节点；没有发布菜单时仍返回空菜单。
3. 普通角色只看到 sys_authority_menus 中已授权菜单节点对应的页面树；授权数据必须属于当前模块。
4. 普通角色给其他角色授权时，只能下发自己已拥有的菜单和动作承载范围，并且目标角色必须在自己可管理范围内。
5. 保存已发布菜单授权时，后端会校验 pageCode、menuFlag、actionCode 是否存在于当前模块已发布清单。
6. defaultPageCode 只能设置成目标角色本次已授权页面；已保存默认页失效时返回未配置或空默认页，不自动跳到公共治理页。
7. 已发布菜单授权保存后，后端同步写入 sys_authority_menus，并按菜单节点 api/method、已发布 system_menu.grantApis 与当前角色已有 app_menu.grantApis 重建统一角色 Casbin 权限。
8. 下游模块如果需要部门、角色、用户、系统菜单发布、应用菜单发布等公共能力，必须把这些入口放进本模块菜单清单并发布授权。
9. app_menu 的菜单树和默认页独立于 PCWEB 运行菜单，但它声明并授权的 grantApis 与 system_menu 一样进入角色 Casbin，供下游服务统一鉴权。

上下游约定

1. 下游后端和 PCWEB 不直接写运行库补 sys_authority_menus 作为正式交付。
2. 下游脚本不得继续用 saveAuthorityCodeActions 保存业务页面授权，应改用 savePublishedMenuAuthority。
3. PCWEB 角色授权页在非 sys_base 模块下展示“已发布菜单授权”，数据来自 getPublishedMenuAuthorityStatus。
4. PCWEB 登录菜单继续只通过 asyncMenu 调 /sys_base/platform/menu/getMenu 获取，不恢复 LoginNew.menus 双入口。
5. 文档平台对外发布时，应把本契约和两条已发布菜单授权接口作为下游联调依据。

不允许的做法

1. 不允许运行菜单回退到 BuildCodeManifestMenuSeeds。
2. 不允许运行菜单回退到 shared_downstream_governance_manifest。
3. 不允许在未发布菜单时显示默认公共治理菜单。
4. 不允许把 settlement_center.* 等业务页面编码硬编码进中间件代码清单。
5. 不允许前端 mock 菜单、隐藏后端错误或静默补全授权结果。
6. 不允许普通角色越权给其他角色下发自己没有的菜单或动作。
7. 不允许无效默认页自动跳转到 dashboard 或公共治理页。

验收口径

1. 未发布 system_menu 的模块调用 /sys_base/platform/menu/getMenu 返回 menus=[]。
2. 已发布 system_menu 的模块，超级管理员上下文看到该清单中的全部可见节点。
3. 普通角色登录后只看到已授权菜单。
4. 下游角色授权页读取的是已发布菜单清单，而不是代码动作清单。
5. 已发布清单中的业务页面，例如 settlement_center.workbench，可以通过 savePublishedMenuAuthority 授权。
6. 公共治理入口只有随下游模块清单发布后才出现。