fusion-developer-portal

Fusion 开发者门户

介绍如何开发 Fusion 门户外壳——这类宿主应用会在共享外壳（页眉、上下文选择器、导航）中加载、路由和渲染 Fusion 应用。

适用场景

• 搭建新的 Fusion 门户
• 关于 portal.manifest.ts 或 ffc portal dev 的问题
• 配置门户级模块（遥测、分析、导航、服务、应用模块）
• 构建自定义应用加载器或门户外壳
• 添加门户级路由（/apps/:appKey/*）
• 使用 Apploader 组件或 useApploader hook 嵌入应用
• 接入门户页眉、上下文选择器或书签侧边面板
• 了解门户在运行时如何加载和初始化 Fusion 应用
• 添加门户级分析或遥测
• 门户部署（ffc portal build、ffc portal upload）

不适用场景

• 应用级功能开发 → fusion-app-react-dev
• 后端服务更改 → 单独的仓库
• Fusion Help Center 集成 → fusion-help-integration
• 技能创作 → fusion-skill-authoring
• 问题创作 → fusion-issue-authoring

必需输入

必填

• 要构建的内容：搭建门户、添加功能、配置模块或了解门户架构
• 门户背景：从头新建还是修改现有门户

条件必填

• 搭建门户时提供门户名称/ID
• 配置身份验证时提供 MSAL 客户端 ID 和服务发现 URL
• 要启用的具体模块（分析、遥测、书签、功能标志、AG Grid）
• 门户是否需要自定义应用加载器，或默认的 Apploader 是否足够

说明

步骤 1 — 确定门户任务类型

判断用户的需求：

• 搭建新门户 → 步骤 2
• 配置门户模块 → 步骤 3
• 应用加载和路由 → 步骤 4
• 门户外壳（页眉、上下文、书签） → 步骤 5
• 分析和遥测 → 步骤 6
• 构建和部署 → 步骤 7

如果 Fusion MCP 可用，请优先使用 mcp_fusion_search_framework，并使用类似 "portal manifest definePortalManifest ffc portal" 或 "createFrameworkProvider PortalModuleInitiator portal configure" 的查询来获取最新 API。对于未经 MCP 确认的指导，应标注为备用信息。

步骤 2 — 搭建新门户

使用 Fusion Framework CLI：

mkdir my-fusion-portal && cd my-fusion-portal
pnpm init
pnpm add -D @equinor/fusion-framework-cli

创建必需文件：

• portal.manifest.ts — 门户元数据和配置：

import { definePortalManifest } from '@equinor/fusion-framework-cli/portal';

export default definePortalManifest((env, { base }) => ({
  name: 'my-portal',
  version: '1.0.0',
  entry: './src/index.tsx',
}));

• portal.schema.ts（可选）— 配置验证架构
• src/index.tsx — 门户入口点（参见 references/portal-architecture.md）

启动开发服务器：

pnpm fusion-framework-cli portal dev
# or: ffc portal dev

步骤 3 — 配置门户模块

门户级配置使用 FrameworkConfigurator（而非应用使用的 AppModuleInitiator）。在 configure 回调中启用模块：

import type { FrameworkConfigurator } from '@equinor/fusion-framework';
import { enableAppModule } from '@equinor/fusion-framework-module-app';
import { enableNavigation } from '@equinor/fusion-framework-module-navigation';
import { enableAnalytics } from '@equinor/fusion-framework-module-analytics';

const configure = (configurator: FrameworkConfigurator) => {
  enableAppModule(configurator);
  enableNavigation(configurator, '/');
  enableAnalytics(configurator, { /* ... */ });
};

与应用配置的主要区别：门户配置 FrameworkConfigurator，其模块会提升到所有子应用。MSAL/身份验证在门户级配置，并由应用继承。

完整的模块配置和 portal-analytics 操作指南请参见 references/portal-architecture.md。

步骤 4 — 应用加载和路由

门户会将 /apps/:appKey/* 路由到应用加载器。有两种方式：

简单嵌入 — 使用内置的 Apploader 组件：

import { Apploader } from '@equinor/fusion-framework-react-app/apploader';

<Apploader appKey="my-app" />

警告：Apploader 是一个实验性 POC。嵌入的应用可能会出现路由和上下文问题。最适合 PowerBI 或 PowerApps 视图等简单应用。

自定义应用加载器 — 完全控制加载状态、错误处理和挂载。使用 useFramework<[AppModule]>()，监听 fusion.modules.app.current$，并调用 app.initialize()。带注释的自定义 AppLoader 模式请参见 references/portal-architecture.md。

门户路由通常通过导航模块使用 react-router-dom：

const Router = () => {
  const framework = useFramework();
  const router = framework.modules.navigation.router;
  return <RouterProvider router={router} />;
};

第 5 步 — 门户界面框架

门户级 UI 通常包括：

• 页眉 — 顶部栏，包含 Fusion 徽标、上下文选择器、书签和个人设置
• 上下文选择器 — 通过 useCurrentContext 或 useContextSelector 连接到应用上下文模块
• 书签侧边栏 — 通过导航模块切换显示
• 应用导航 — 用于切换应用的侧边栏或顶层导航

应用不会自行构建页眉，而是由门户外壳提供。

第 6 步 — 分析与遥测

门户级分析会捕获应用生命周期事件。使用适配器和收集器启用：

import { enableAnalytics } from '@equinor/fusion-framework-module-analytics';
import { ConsoleAnalyticsAdapter } from '@equinor/fusion-framework-module-analytics/adapters';
import { AppLoadedCollector, AppSelectedCollector } from '@equinor/fusion-framework-module-analytics/collectors';

enableAnalytics(configurator, (builder) => {
  builder.addAdapter(new ConsoleAnalyticsAdapter());
  builder.addCollector(new AppLoadedCollector());
  builder.addCollector(new AppSelectedCollector());
});

有关遥测（OpenTelemetry / Application Insights），请参阅references/portal-architecture.md。

第 7 步 — 构建和部署

# Build the portal template
ffc portal build

# Upload to the Fusion portal service (authenticate via `az login` or FUSION_TOKEN env var)
ffc portal upload --portal-id <id>

# Tag a specific version
ffc portal tag --portal-id <id> --tag latest --version <version>

切勿将令牌直接粘贴到命令中。 交互式身份验证请使用 az login，CI 流水线请设置 FUSION_TOKEN 环境变量。

第 8 步 — 验证

1. ffc portal dev 启动时没有错误
2. 应用可在 /apps/:appKey 加载
3. 上下文选择器和页眉正常呈现
4. TypeScript 编译无错误
5. 应用加载/选择时触发分析事件（如果已启用）

预期输出

• 可正常运行的门户外壳，支持应用加载、路由和界面框架
• 门户级模块配置正确使用 FrameworkConfigurator
• 处理应用初始化的加载和错误状态
• 简要总结创建或更改的内容

辅助 Agent

与 fusion-app-react-dev 使用相同的配套基础设施：

• fusion-research — 当门户行为不明确时，提供有来源依据的 Fusion 生态系统研究
• fusion-code-conventions — 检查命名、TSDoc 和代码风格

Fusion MCP 可用时，优先使用 mcp_fusion_search_framework 查询门户相关内容。

安全与限制

• MSAL 属于门户级配置 — 切勿在应用中配置身份验证；它由门户统一提升配置
• 不要臆造门户 API — 仅引用经 MCP 确认或在参考资料中记录的 API
• Apploader 处于实验阶段 — 就应用嵌入提供建议时，务必说明其路由/上下文限制
• 源代码中不得包含机密信息 — MSAL 客户端 ID 必须来自环境变量，不得硬编码
• 不要修改生产环境中的 Fusion 门户 — 此技能仅涵盖自定义门户开发
• 所有更改均使用 Conventional Commits