fusion-help-integration

Fusion Help の統合

Fusion Help Center をアプリのページに接続し、ユーザーが PageLayout のヘルプボタンからコンテキストに応じたヘルプ記事を開けるようにします。

使用する場合

• ページにヘルプボタンを追加する
• ページコンポーネントに useHelpCenter を接続する
• ヘルプ記事の定数ファイルを作成／更新する
• PageLayout を Fusion Help Center に接続する
• ページで openHelpArticle を指定せずに PageLayout を使用している
• アプリにヘルプ機能を追加する
• ページから特定のヘルプ記事を開く

使用しない場合

• Markdown 形式のヘルプ記事を作成する場合 → fusion-help-docs
• Help サービスへの REST API を直接呼び出す場合 → fusion-help-api
• @fra/ui の共有コンポーネント（PageLayout、PageHeader、FusionHelpButton）を変更する場合
• Fusion フレームワーク以外のアプリ、またはこのモノレポ外のアプリの場合

必要な入力

変更を行う前に、以下の情報を収集します。

入力	必須	デフォルト	説明
アプリ名	はい	—	apps/ 配下のアプリディレクトリ名（例：fra-app-management）
対象ページ	はい	—	接続するページ、または PageLayout を使用するすべてのページを対象とする場合は "all"
記事スラッグ	はい	自動導出	各ページのスラッグ文字列。指定がない場合は {app-name}-{page-kebab} として導出します
リリースノートを含める	いいえ	true	PageLayout に openReleaseNotes も渡すかどうか
定数ファイルの場所	いいえ	src/constants/helpArticles.ts	FUSION_HELP_ARTICLES オブジェクトのパス

記事スラッグを自動導出する場合は、適用する前にユーザーに確認してください。スラッグは fhelp で公開された記事と一致する必要があります。

手順

1. 既存のヘルプ統合を確認する

対象のアプリで、既存のヘルプ接続を検索します。

apps/{app-name}/src/**/helpArticles.ts
apps/{app-name}/src/**/fusionHelpArticles.ts

useHelpCenter のインポートも検索します。アプリに部分的な統合がすでにある場合は、重複させずに拡張します。

2. スラッグの規則を確認する

アプリにスラッグを記載した定数ファイルがすでにあるか確認します。

• 既存のスラッグがある → その命名パターンに従います
• 既存のスラッグがない → {app-name}-{page-kebab} の規則を使用します

既存の規則を参考にします。

アプリ	規則	例
fra-access-manager	{app-name}-{page-kebab}	fra-access-manager-access-groups
fra-app-management	ページ名にプレフィックスを付けない	overview、requests
personnel-allocation	{app-name}-{page-kebab}	personnel-allocation-overview

新しいアプリには、アプリ名のプレフィックスを付ける規則を推奨します。アプリ間のスラッグの競合を避けられます。

3. 定数ファイルを作成または更新する

src/constants/helpArticles.ts（またはアプリで選択した場所）を作成します。

export const FUSION_HELP_ARTICLES = {
    PAGE_NAME: '{app-name}-{page-kebab}',
};

キーはページの概念に対応する SCREAMING_SNAKE_CASE、値は kebab-case のスラッグ文字列にします。

実際の例を含む標準パターン全体については、references/wiring-pattern.md を参照してください。

4. 対象の各ページを接続する

PageLayout を使用する各ページコンポーネントで、以下を行います。

a. インポートを追加する（外部ライブラリを先にし、次に @fra/*、@/* エイリアス、相対パスの順にします）。

import { useHelpCenter } from '@equinor/fusion-framework-react-app/help-center';

import { PageLayout } from '@fra/ui';

import { FUSION_HELP_ARTICLES } from '@/constants/helpArticles';

b. コンポーネント本体内でフックを分割代入します。

const { openArticle, openReleaseNotes } = useHelpCenter();

リリースノートが不要な場合は、{ openArticle } のみを分割代入します。

c. PageLayout にプロパティを渡します。

<PageLayout
    title="Page Title"
    openHelpArticle={() => openArticle(FUSION_HELP_ARTICLES.PAGE_NAME)}
    openReleaseNotes={openReleaseNotes}
>

重要：openHelpArticle は、openArticle(slug) を呼び出すコールバックラッパー () => openArticle(slug) にする必要があります。openArticle にはスラッグ引数が必要なため、直接参照を渡してはいけません。

5. 統合を検証する

接続後、以下を行います。

1. TypeScript のチェックを実行します：pnpm --filter {app-name} exec tsc --noEmit
2. リントを確認します：pnpm --filter {app-name} exec eslint src/
3. 表示を確認します：ページヘッダーにインフォメーションサークル（ⓘ）アイコンが表示されます。クリックすると Fusion Help のサイドシートが開きます。

6. 公開済みコンテンツと照合する

FUSION_HELP_ARTICLES の各スラッグは、公開済みの記事に対応している必要があります。記事が存在しない場合は、以下の対応を行います。

• 記事の作成については fusion-help-docs を案内します
• 定数内のスラッグは help-articles.json の slug フィールドと完全に一致させます
• 記事は環境ごとに fhelp で公開します

期待される出力

• 記事スラッグのマッピングを記載した定数ファイルが作成または更新されている
• 対象ページに useHelpCenter と PageLayout の props が設定されている
• TypeScript のコンパイルが成功する
• 対応するヘルプ記事が必要なスラッグの一覧（fusion-help-docs への引き継ぎ用）

安全性と制約

• 確認なしにスラッグ名を決して作らないでください — スラッグは公開済みの記事と一致している必要があります
• @fra/ui のコンポーネントを変更しないでください — PageLayout、PageHeader、FusionHelpButton はすでにヘルプ用 props に対応しています
• 新しい依存関係を追加しないでください — @equinor/fusion-framework-react-app はすでにすべてのアプリに含まれています
• アプリのインポートエイリアスの規約に従ってください — ほとんどのアプリでは @/* → src/* を使用しています
• 既存のコードスタイルを尊重してください — 型のみのインポートには type を使用し、インポートグループの順序を維持してください
• ヘルプの設定を重複させないでください — ページですでに useHelpCenter を使用している場合は、再追加せずに拡張してください
• 適用前に自動導出されたスラッグを確認してください — 誤ったスラッグを指定してもエラーは表示されず、記事も表示されません