Bridge 协议

Bridge 是基座对所有插件形态（脚手架 / HTML / React / iframe 外的 micro 子应用）统一暴露的能力协议。插件不实现这些能力，只调用；实现都在基座侧。

调用格式

const bridge = props.hostBridge || props.amBridge
const result = await bridge.invoke(method, params)

桥对象还提供：getCapabilities()（当前已开通的能力清单）、subscribeTheme(cb)（订阅基座主题变化，返回取消订阅函数）。

能力清单

登录与用户

await bridge.invoke('auth.getLoginState')     // { isLogin, sid, userId, username, nickname, avatar, accountType, isAdmin }
await bridge.invoke('auth.getUserProfile')    // 当前用户资料
await bridge.invoke('auth.getSession')        // { accessToken, refreshToken, user }
await bridge.invoke('auth.getAccessToken')    // 主 JWT（供插件自己请求接口带 Authorization）
await bridge.invoke('auth.logout')

sid 优先

跨模块引用主体一律用 sid（sys_ 前缀的人主体），userId（自增）仅为向后兼容保留。

字典、配置、远程数据

await bridge.invoke('data.getDict', { code: 'structure_type' })        // 不传 code 返回全部字典
await bridge.invoke('data.getConfig', { /* 配置查询参数 */ })
await bridge.invoke('data.getRemoteOptions', { code: 'xxx', params: {} })

业务选择器与表单

由基座 PluginCapabilityHost 承载，以 Promise 返回选择/填写结果，取消返回 { cancelled: true }：

await bridge.invoke('picker.structure', { type: 7, title: '选择组织' })
await bridge.invoke('picker.file', { multiple: true, type: 1, title: '选择图片' })
await bridge.invoke('form.builder', { title: '表单生成器', items: [] })   // 返回 { items }
await bridge.invoke('form.render', { title: '填写表单', items: [...], model: {} })  // 返回表单值

导航与 UI

await bridge.invoke('navigation.setTitle', { title: '页面标题' })         // 同步页签标题
await bridge.invoke('navigation.openRoute', { path: '/dashboard/console' })  // 打开基座内部路由（仅相对路径）
await bridge.invoke('navigation.openPlugin', { name: 'am_xxx' })         // 打开另一个插件（按 name，不依赖记录 id）

await bridge.invoke('ui.message', { type: 'success', message: '操作成功' })
await bridge.invoke('ui.notify', { title: '提示', message: '通知内容' })
await bridge.invoke('ui.confirm', { title: '确认', message: '确定继续？' })  // 取消返回 { cancelled: true }
await bridge.invoke('ui.alert', { title: '提示', message: '内容' })

主题

const theme = await bridge.invoke('theme.get')   // 基座当前主题快照（不含菜单布局）
const unwatch = bridge.subscribeTheme((t) => { /* 实时跟随 */ })

主题快照含 systemThemeType / systemThemeMode / systemThemeColor / menuThemeType / customRadius；菜单布局 menuType 不跟随基座，子应用保持自己的布局。

能力开通与门禁

生产按 scope 授权

• 开发模式（import.meta.env.DEV）：跳过同域校验、放开全部能力，方便本地多端口调试。
• 生产模式：只有同域（或 manifest.bridge.trust='same-origin'）才可用 Bridge；可用能力 = 一组默认能力 + manifest.json 的 bridge.scopes 映射出的方法。未开通的方法 invoke 抛"插件未开通能力"。

scopes 是能力分组声明，如 ["auth.session", "data.dict", "picker.file", "ui.feedback", "theme"]，按需最小声明。Bridge 已销毁时 invoke 抛错。

不做请求代理

基座不代理插件的业务请求。插件自己的接口由插件自己 fetch，需要 token 时先 auth.getAccessToken 取主 JWT 塞进 Authorization 头。接口前缀规范 /app/{name}/xxx 见控制器与路由。