Web 接入与运行态调用

环境托管应用必须使用公共 npm 包 @baijimu/platform-application-sdk 接入平台。不要在项目中复制 sdk.js，也不要由每个平台应用分别实现授权跳转、PKCE、token 存储、CModel 解析和 Runtime URL 拼接。

安装标准 SDK

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

提交项目锁文件，保证构建和回滚使用已解析的精确依赖版本。SDK 是应用的构建时依赖，不会在目标环境 部署新服务，也不会改变 Bundle 安装内容。

通过 PLATFORM_APPLICATION 项目类型新建的项目应已经包含 SDK、bootstrap() 入口、部署配置文件和 平台应用声明。若项目中仍存在自实现的 PKCE、token 缓存或 Gateway client，不能只在旁边新增 SDK；应删除 重复实现，让授权生命周期和逐方法调用统一经过 SDK。

读取同源环境配置

环境托管应用使用 SDK 的专用初始化入口：

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

const client = await createPlatformApplicationClientFromHostedConfiguration(applicationDefinition.id);

applicationDefinition.id 是当前应用稳定的 platformAppId。SDK 只从当前 HTTPS origin 的 /.well-known/baijimu-platform-application.json 读取配置，并校验应用身份、origin 和版本目录。 该文件由平台在 Bundle 安装或升级时的托管流程自动提供，开发者无需创建静态站点或手工部署配置文件，也不能让应用构建归档覆盖它。 历史 STATIC_SPA 站点需要完成 环境托管迁移，只升级 npm 依赖不会生成同源配置。

配置字段如下：

SDK 拒绝配置重定向、缺失字段、未知字段和身份不匹配，不缓存配置，也不从 URL 参数或公共 SaaS 地址回退。 配置不包含 installId、工作区、用户、token 或密钥；真实安装选择器由启动 URL 提供，服务端负责权限校验。 只升级 SDK 不会让外部站点取得平台授权，应用还必须按环境托管方式创建新版本并升级 Bundle。

旧项目应删除 window.__APP_CONFIG__ 手工地址注入、签名启动初始化和自实现授权逻辑。 createPlatformApplicationClient(config) 仅用于显式受控集成或本机测试，不能用它绕过平台托管要求； 外部自托管应用使用自己的后台授权。

在业务页面之前启动

const session = await client.bootstrap();

bootstrap() 统一执行以下状态机：

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

SDK 会校验返回 token 的 workspaceId、runtimeAppId、installId、platformAppId 和过期时间， 并按 platformAppId + installId 隔离浏览器存储。PKCE verifier 和 state 只保存在当前浏览器会话中； 授权完成后，SDK 会从地址栏移除授权参数。 它只移除一次性的 code 和 state，会保留平台入口要求的 installId。业务代码不要再次清空整个查询串。

调用模块方法

业务组件只传平台应用版本已声明的结构化 target、method 和方法参数：

const projects = await client.call(
  {
    type: "module",
    bundleId: "project-directory",
    moduleId: "project-directory",
  },
  "listProjects",
  { offset: 0, limit: 50 },
);

SDK 使用规范调用路由，并生成包含 target、method 和 params 的请求体：

POST {appGatewayApiBase}/workspace-runtime/apps/{installId}/invoke

新应用不得提交 Runtime service；/services/{service}/methods/{method} 只服务历史 SDK 2.x 应用。 App Gateway 会校验 token、安装、默认 Runtime 绑定、平台应用版本的 方法声明和工作区权限；前端不选择后端实例、不读取具体 businessId，也不持有模块服务凭证。完整协议见 调用模块方法。

错误与会话处理

import {
  CModelFailureError,
  PlatformApplicationSdkError,
} from "@baijimu/platform-application-sdk";

try {
  await client.call(
    { type: "module", bundleId: "project-directory", moduleId: "project-directory" },
    "listProjects",
    {},
  );
} catch (error) {
  // 由 SDK 判定会话失效；不要仅凭业务 errorCode 或 HTTP 状态重登。
  if (!client.getSession()) {
    client.restartAuthorization();
    throw error;
  }
  if (error instanceof CModelFailureError) {
    console.error(error.errorCode);
  } else if (error instanceof PlatformApplicationSdkError) {
    console.error(error.code);
  }
}

SDK 5.0.0 在 App Gateway 返回 APP_GATEWAY_UNAUTHORIZED 时清除当前安装会话，也会处理网关返回的非结构化 HTTP 401。 后端业务返回合法 CModel UNAUTHORIZED 时，即使 HTTP 状态是 401，SDK 仍保留会话；应用应展示业务错误，不能重新授权。 参数错误、能力未声明、目标服务异常和网络失败同样不能触发登录循环。以 client.getSession() 是否已由 SDK 清空作为重新授权的依据， 不要维护另一份会话状态，也不要在捕获到业务 UNAUTHORIZED 时自行清理 SDK 会话或自动重放业务请求。 需要主动注销时调用 await client.revoke()；需要重新授权时调用 client.restartAuthorization()。

平台应用没有另一套 PLATFORM_APPLICATION token，也不通过通用 HTTP 代理访问平台内部 API。需要新增 能力时，应先把能力定义为 Runtime 模块方法并发布不可变模块版本，再把该方法加入平台应用版本的 methodDefinitions。

分享与管理入口

面向其他用户分享时，分享 Manager 的 /bundle-app/{bundleId}/{platformAppId} 路由，不要分享包含当前 工作区 installId 的应用启动地址。应用配置了 managementUrl 后，可以使用 client.openManagementRoute(route) 打开管理页面；未配置时 SDK 会明确失败，不会猜测 Manager 地址。

会话失效

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

• token 已到期或被撤销。
• Bundle 安装已经停用、卸载或升级后使旧 token 失效。
• 返回的 token 与当前 workspaceId、runtimeAppId、installId 不一致。
• App Gateway 明确拒绝当前会话，SDK 已将其清空。

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

本地开发

本地回跳地址必须与实际托管入口同源。若入口是已部署域名，本地 localhost 回跳不会通过同源校验。托管初始化要求真实 HTTPS 同源配置；本地页面展示可使用明确的测试配置，但完整授权联调应发布到目标测试环境并从该环境的安装入口启动，不能用外部 URL 替代环境托管。验证时保证：

• 页面可以从入口参数取得真实 installId。
• HTTPS、端口和域名与登记入口一致。
• Hash Router 和普通查询参数都能正确读取回跳字段。
• 浏览器刷新后不会丢失 PKCE 会话。
• 本地配置明确指向本次开发环境，不回退到公共 SaaS。