模块管理与应用信息契约说明

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

查看文档来源信息

• 来源目录：addons/sys_base/docs
• 来源文件：契约说明/模块管理与应用信息契约说明.md

## 契约用途 - 适用范围：模块管理页、应用信息页、角色应用绑定、应用菜单治理页。 - 当前正式版本：2026-04-25。

当前正式口径

1. 模块管理负责维护模块定义、模块标识和正式治理模式。
2. 应用信息负责维护具体应用实例、应用 ID、应用密钥和应用可见范围。
3. 角色应用绑定与应用菜单治理统一使用应用 UUID 作为正式应用定位键。
4. 模块下可选应用实例的正式判定，必须与后端保存时的判定完全一致。

关键字段口径

字段	含义
addonsType	模块标识，例如 sys_base
appUUID / appUuids	应用实例 UUID 或 UUID 列表
appId	具体应用 ID
app_model.id	模块记录主键，用于判定应用实例归属
app_model.uuid	模块记录 UUID，用于正式模块记录定位
app_wechat_apps_info.addonsId	应用实例关联的模块 ID 集合
manifestSupported	当前模块是否接入正式清单治理
governanceMode	当前正式治理模式，正式链固定为 manifest

运行规则

1. 角色应用绑定只能绑定目标角色所在模块的正式应用实例。
2. 应用实例归属模块时，先允许 app_wechat_apps_info.addons_type == addonsType 的直接命中；若未直接命中，再按 app_wechat_apps_info.addons_id 是否命中该模块下任一 app_model.id 进行正式判定。
3. GET /sys_base/platform/wechatAppsInfo/getWechatAppsInfoList?addonsType=... 返回的列表，与 POST /sys_base/platform/authority/bindAuthorityApps 保存时可接受的应用列表使用同一套判定口径。
4. 当模块下没有任何正式应用实例时，角色应用绑定允许保存空列表，不以此阻断角色授权主链。
5. 应用信息列表只服务展示、选择和绑定，不读取密钥运行值；密钥字段存在时只返回固定掩码。真实密钥按 app_wechat_apps_info 当前保存值供运行态和服务态同步链路使用，不再依赖 APP_SECRET_KEY。

上下游约定

• 上游 PCWEB 在角色授权抽屉中展示的应用选择结果，必须直接消费应用信息列表接口返回值，不得自行扩展跨模块候选项。
• 后端保存绑定结果时必须再次校验模块归属，不能仅相信前端筛选结果。
• 应用菜单治理页读取应用范围时，必须复用正式应用 UUID 列表，不得重新发明应用标识。

不允许的做法

• 不允许只按 app_wechat_apps_info.addons_type 单字段判定应用归属。
• 不允许出现“应用信息页能查到、角色应用绑定保存时却被判跨模块”的正式行为。
• 不允许把后端本该接受的同模块应用实例改成前端不展示来规避保存错误。
• 不允许为了列表展示而返回应用密钥明文；列表消费者也不得把掩码字段当作运行密钥使用。