@d2m/plugin-frontend-sdk

@d2m/plugin-frontend-sdk 是 D2M 前端插件作者使用的稳定类型包。它定义 active frontend manifest、插件入口模块、运行上下文、路由、前端资源、诊断、兼容性结果和宿主 capability 契约，不暴露宿主内部 router、全局状态、权限审批或后端授权实现。

快速开始

前端插件默认导出 D2MFrontendPluginModule。D2M Web 在加载受控 ESM 后，会先调用 register(context)，再通过 createPages(context) 读取页面注册表。

import type {
  D2MFrontendPluginModule,
  PluginPageRegistry
} from "@d2m/plugin-frontend-sdk";

function WorkOrdersPage() {
  return "示例工单页面";
}

const plugin: D2MFrontendPluginModule = {
  register(context) {
    context.registerRoutes([
      {
        routePath: "work-orders",
        moduleKey: "work-orders-page",
        title: "示例工单",
        requiredPermissionCodes: ["plugins.sample.minimal.work-order.read"]
      }
    ]);
  },
  createPages(): PluginPageRegistry {
    return {
      "work-orders-page": WorkOrdersPage
    };
  }
};

export default plugin;

运行上下文

• register(context)：插件注册前端能力的唯一入口。
• createPages(context)：返回页面注册表，key 必须和路由里的 moduleKey 一致。
• apiBaseUrl：当前插件调用自身后端运行 API 的基址，例如 /api/plugin-runtime/sample.minimal/v1。插件只能基于该值拼接相对路径。
• assetBaseUrl：当前插件读取受控前端静态资产的基址。
• theme：宿主当前主题快照，包含 themeId、mode、density 和稳定 tokens。
• locale：宿主当前语言环境快照，包含 language、textDirection、timeZone 等字段。
• permissions：当前用户对该插件可见的权限快照，只用于体验过滤。
• config：宿主投影后的前端安全配置快照。
• compatibility：当前插件与宿主之间的协议兼容性协商结果。
• host：受控宿主 capability 集合，首期基线包含 navigation、dialog、notification、clipboard、download。
• registerRoutes：注册当前插件 routeBase 下的页面路由。
• hasPermission / hasAnyPermission / hasAllPermissions：读取当前前端权限投影，只用于体验过滤，后端 API 仍必须授权。
• getConfigValue：读取安全配置快照里的单个 key。
• resolveAssetUrl：解析当前插件已声明资源的受控 URL。
• reportDiagnostic：上报脱敏后的前端运行诊断。
• getOverlayContainer：获取宿主浮层容器，插件弹窗和下拉应挂载到这里。
• onThemeChanged / onLocaleChanged：订阅主题和语言环境变化。

API 调用

插件调用自身后端能力时必须使用 context.apiBaseUrl：

async function loadCurrentWorkOrder(context: { apiBaseUrl: string }) {
  const response = await fetch(`${context.apiBaseUrl}/work-orders/current`, {
    credentials: "include"
  });
  return response.json();
}

页面

• routePath 必须是相对路径，不能以 / 开头。
• moduleKey 必须能在 createPages(context) 返回的注册表里找到。

边界

插件不得引用 D2M Web apps 内部路径，不得直接操作宿主 router，不得把浮层默认挂到 document.body，也不得调用 ReactDOM.render。诊断内容必须脱敏，不能包含 token、secret、连接字符串或完整用户输入。