App Gateway 接入与配置

App Gateway 是平台应用复用百积木登录用户、工作区安装态和权限体系的标准入口。 当前作者配置使用 7.3.0，浏览器使用 SDK 10.2.0。项目有独立 platformAppId、唯一归属 Bundle 与专属平台应用项目。

入口与调用链

工作区打开应用 accessUrl
  -> 网页授权和 PKCE 兑换 appClientToken
  -> SDK 向 App Gateway 发送 moduleKey、可选 propertyKey、方法、params
  -> 校验会话、工作区、安装与精确应用版本
  -> 从应用身份限定同包范围，并向 RCS 查询当前 Module 入口
  -> Runtime 校验来源身份、方法合同和当前用户权限
  -> 返回 CModel

公共 SaaS 当前前缀为 https://api.baijimu.com/app-gateway/api；其他环境以同源配置为准。 前端不得读取、缓存或提交具体 businessId，也不自行拼接 Module 后端地址或内部调用信封。

作者配置

{
  "schemaVersion": "7.3.0",
  "entry": {
    "urlTemplate": "/index.html",
    "type": "ENVIRONMENT_HOSTED_APP",
    "openMode": "WORKSPACE_TAB"
  },
  "pages": []
}

新应用不声明 targets 或方法名单。浏览器只传模块键和可选属性键，Runtime、来源环境和 Bundle 由后端从应用身份取得； 实际入口由 RCS 返回。完整调用规则见声明应用能力。

当前配置不接受 methodDefinitions、interface target 或 manifest.interfaceBindings；跨包能力经本包 Module 的 Interface 属性和 ServiceReference 绑定调用。定义安装、属性绑定和真实调用分别验证，不能以安装成功代替用户业务权限验证。

入口是版本归档内的相对根路径，不含外部域名、查询串、hash 或 {installId}。platformAppId 不在文件中重复声明。 PLATFORM_ROUTE 不能使用通用平台应用宿主地址冒充内置业务页面；完整规则见 入口类型与应用清单。

初始化与会话

pnpm add --save-exact @baijimu/platform-application-sdk@10.2.0

import { createPlatformApplicationClientFromHostedConfiguration } from "@baijimu/platform-application-sdk";

const client = await createPlatformApplicationClientFromHostedConfiguration();
await client.bootstrap();

SDK 从当前 HTTPS origin 的 /.well-known/baijimu-platform-application.json 读取应用身份、 applicationOrigin、appGatewayApiBase、授权页与管理地址。同源配置合同仍为 2.0.0。 应用归档不能覆盖配置文件；缺失或身份不匹配时失败，不从 URL 或公共 SaaS 地址补值。

SDK 校验 PKCE state 后兑换授权码：

POST {appGatewayApiBase}/workspace-runtime/apps/{installId}/token/exchange
Content-Type: application/json

{
  "code": "authorization-code",
  "codeVerifier": "original-code-verifier"
}

授权码只使用一次。token 绑定用户、工作区、Runtime 与安装，SDK 仅保存在内存；不写入 URL、日志或持久化存储。 授权流程见平台应用授权与 PKCE。

公开调用

以下路径均相对于同源配置中的 appGatewayApiBase：

除授权码兑换外，SDK 携带 Authorization: Bearer {appClientToken}。 业务组件通过 client.call({ moduleKey: "course-directory" }, "createCourse", params) 调用；SDK 将第三个参数放入外层请求的 params。 名称、参数、业务错误与会话处理见调用模块方法。

版本、安装与验收

环境托管应用从专属项目主线构建不可变版本，项目 package.json 的版本与创建版本一致。 创建应用版本后更新 Bundle 的精确引用并安装或升级，由安装或升级交付当前应用资源与来源凭据。完整流程见 创建版本并纳入 Bundle。

验收至少覆盖同源配置、PKCE 回跳、同包模块解析、真实方法成功、不存在模块拒绝、用户权限拒绝和跨安装 token 拒绝。 新应用没有应用方法白名单；目标方法存在性和权限由 Runtime 验证。页面或应用实现变化仍需新应用和 Bundle 版本；调用本包已有方法无需增加目标声明。 旧版本内容保持不可变；历史客户端适配不能作为新应用协议或自动回退。