菜单清单发布契约说明

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

查看文档来源信息

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

## 适用范围 - `system_menu` - `app_menu` - 菜单版本上传、提交版本、发布、切换当前生效版本、运行态查看

当前文档版本

• 文档更新时间：2026-06-23

正式口径

1. 菜单清单类型固定为 system_menu 与 app_menu，不再使用旧命名。
2. 版本治理的正式动作口径统一为：
   • 选择文件并预校验清单
   • 保存草稿
   • 提交版本
   • 发布
   • 当前生效版本
   • 切换为当前版本
3. 当前生效版本以“当前范围下最新成功发布记录对应的版本”为准。
4. 版本详情与运行态详情必须优先展示结构化菜单结果和差异摘要，原始 JSON 只作为辅助出口。
5. 菜单清单根字段必须使用正式字段名，菜单承载节点固定为 menuSeeds，不能使用 seeds 代替。

关键字段

字段	说明
catalogType	清单类型，固定为 system_menu 或 app_menu
versionUuid	菜单版本唯一标识
catalogVersion	菜单版本号
appScope	应用范围
menuSeeds	菜单承载节点清单
currentPublished	当前生效版本对应的成功发布记录
publishStatus	发布记录结果，成功时为 success
validation.summary.hasBlocking	是否存在阻断项

正式流程契约

1. 正式主流程固定为“选择清单 -> 服务端预校验 -> 程序解析 -> 与当前生效版本做差异对比 -> 保存草稿 -> 提交版本 -> 发布 -> 查看运行态”。
2. uploaded 状态只代表草稿，不代表可直接切换为当前版本。
3. submitted 状态代表已进入待发布队列，可以继续发布，也可以切换为当前版本。
4. published 状态代表该版本曾经发布成功；如果不是最新成功发布记录，则属于历史已发布版本。
5. blocked 状态代表版本存在阻断项，不能继续发布，也不能切换为当前版本。
6. 选择文件后必须调用 /sys_base/platform/manifest/validateMenuCatalog 完成服务端预校验；存在 blocking 阻断项时，前端必须展示字段和修复建议，并禁用保存草稿。
7. /sys_base/platform/manifest/uploadMenuCatalog 会在落库前二次校验；只要存在 blocking 阻断项，就返回阻断详情且不创建、不更新版本记录。
8. 预校验接口不落库，返回 code=0 只代表接口调用成功；是否允许保存草稿必须以 validation.summary.hasBlocking=false 为准。

当前生效版本契约

1. 版本列表中必须能识别当前生效版本。
2. 历史已提交版本与历史已发布版本都允许执行“切换为当前版本”。
3. 切换当前版本会追加一条新的成功发布记录，并立即刷新当前生效结果。
4. system_menu 切换后会同步刷新系统菜单承载；app_menu 切换后会按最新成功发布记录立即生效。

权限契约

1. 查看菜单治理首页需要对应页面权限。
2. 执行上传、提交版本、发布、切换当前版本等操作时，还需要对应动作权限。
3. 超级管理员在正式页面权限链下直接放行；普通角色仍按页面权限与动作权限双重校验。