fusion-developer-portal

Fusion 開発者ポータル

Fusion アプリを共有のクローム（ヘッダー、コンテキストセレクター、ナビゲーション）内で読み込み、ルーティングし、レンダリングするホストアプリケーションである、Fusion ポータルシェルの開発をガイドします。

使用する場面

• 新しい Fusion ポータルをスキャフォールドする
• portal.manifest.ts または ffc portal dev に関する質問
• ポータルレベルのモジュール（テレメトリ、アナリティクス、ナビゲーション、サービス、アプリモジュール）を設定する
• カスタムアプリローダーまたはポータルシェルを構築する
• ポータルレベルのルーティング（/apps/:appKey/*）を追加する
• アプリを埋め込むための Apploader コンポーネントまたは useApploader フック
• ポータルヘッダー、コンテキストセレクター、ブックマークのサイドシートを接続する
• ポータルが実行時に Fusion アプリを読み込み、初期化する仕組みを理解する
• ポータルレベルのアナリティクスまたはテレメトリを追加する
• ポータルをデプロイする（ffc portal build、ffc portal upload）

使用しない場面

• アプリレベルの機能開発 → fusion-app-react-dev
• バックエンドサービスの変更 → 別のリポジトリ
• Fusion ヘルプセンターとの統合 → fusion-help-integration
• スキルの作成 → fusion-skill-authoring
• Issue の作成 → fusion-issue-authoring

必要な入力

必須

• 構築するもの：ポータルのスキャフォールド、機能の追加、モジュールの設定、またはポータルアーキテクチャの把握
• ポータルの状況：新規作成か、既存のポータルの変更か

条件付き

• スキャフォールド時のポータル名／ID
• 認証の設定時の MSAL クライアント ID とサービスディスカバリー URL
• 有効化する特定のモジュール（アナリティクス、テレメトリ、ブックマーク、フィーチャーフラグ、AG Grid）
• カスタムアプリローダーが必要か、デフォルトの Apploader で十分か

手順

ステップ 1 — ポータルタスクを分類する

ユーザーが必要としている内容を判断します。

• 新しいポータルをスキャフォールドする → ステップ 2
• ポータルモジュールを設定する → ステップ 3
• アプリの読み込みとルーティング → ステップ 4
• ポータルのクローム（ヘッダー、コンテキスト、ブックマーク） → ステップ 5
• アナリティクスとテレメトリ → ステップ 6
• ビルドとデプロイ → ステップ 7

Fusion MCP が利用可能な場合は、最新の API サーフェスを確認するために、"portal manifest definePortalManifest ffc portal" や "createFrameworkProvider PortalModuleInitiator portal configure" のようなクエリで mcp_fusion_search_framework を優先して使用します。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 は使用しません）。設定コールバックでモジュールを有効にします。

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/* をアプリローダーにルーティングします。方法は 2 つあります。

シンプルな埋め込み — 組み込みの 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 要素

ポータルレベルの 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. （有効な場合）アプリの読み込み／選択時に分析イベントが発生する

期待される出力

• アプリの読み込み、ルーティング、UI 要素を備えた、動作するポータルシェル
• 正しい FrameworkConfigurator の使用によるポータルレベルのモジュール設定
• アプリの初期化時の読み込み状態とエラー状態への対応
• 作成または変更した内容の簡潔な概要

ヘルパーエージェント

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 を使用してください