Web 接入与运行态调用

可信外部应用应在业务页面初始化前完成平台应用启动。推荐把授权、token 兑换和请求代理封装成一个统一的 bootstrap 层，业务组件不要各自实现授权跳转。

启动状态机

读取 installId
  -> 有有效 token：进入应用
  -> 有 code：校验 state 并兑换 token
  -> 都没有：创建 PKCE 请求并跳转网页授权页

appClientToken 是不透明的 App Gateway token，绑定 workspaceId + runtimeAppId + installId + userId。token 缓存必须至少按 workspaceId + runtimeAppId + installId 隔离，并保存过期时间。不能让同一浏览器中的 不同工作区或不同 Runtime 安装共用一个 token。

调用模块方法

页面调用 Bundle 中已安装的模块能力时，通过 app-gateway 的 service/method 路径发送请求，请求体直接使用模块方法参数。完整的 URL、字段对应、 响应和错误处理规范见 调用模块方法。

POST https://api.baijimu.com/app-gateway/api/workspace-runtime/apps/{installId}/services/{service}/methods/{method}
Authorization: Bearer {appClientToken}
Content-Type: application/json

{"name":"示例"}

App Gateway 会校验 token、安装、默认 Runtime 绑定、当前平台应用版本的方法声明和 Runtime 权限，并按当前安装的 interfaceBindings 把 logicalService 解析成具体 Runtime businessId，再把调用交给安装在该 Runtime 中的模块。前端不选择后端实例， 也不持有模块服务凭证。

await fetch(
  `${appGatewayBase}/workspace-runtime/apps/${encodeURIComponent(installId)}` +
    `/services/${encodeURIComponent(logicalService)}/methods/${encodeURIComponent(method)}`,
  {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${appClientToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(params),
  },
);

平台应用没有独立的 PLATFORM_APPLICATION token，也不通过通用 HTTP 代理访问 bundle-service、project-service、workflow-engine 等平台内部 API。需要新增能力时， 应先把能力定义为 Runtime 模块方法，发布模块不可变版本，再把该方法加入平台应用版本的 methodDefinitions。

会话失效

以下情况应终止当前应用会话并重新授权：

• token 已到期或被撤销。
• 安装已经停用、卸载或升级后要求重新授权。
• 返回的 token 与当前 workspaceId、runtimeAppId、installId 不一致。
• 平台返回明确的未授权结果。

不要在所有业务错误上盲目跳转授权页。参数错误、目标服务异常和能力未声明应分别展示真实错误，避免形成授权循环。

本地开发

本地回跳地址必须与平台应用入口模板同源。若入口是生产域名，本地 localhost 回跳不会通过同源校验。开发时应发布专用开发入口版本或使用平台认可的预览域名，并保证：

• 页面可以从入口参数取得真实 installId。
• HTTPS、端口和域名与登记入口一致。
• Hash Router 和普通查询参数都能正确读取回跳字段。
• 浏览器刷新后不会丢失 PKCE 会话。