WordPress ACF Pro 移行手順（メニュー・バナー編集UI最適化）¶

本手順は Issue #24「ACF有料版への移行と編集UI最適化＋Storefront連携」に対応する。ヘッダー／フッターメニューを ACF Pro のリピーター＋クローン構造に統合し、Storefront から GraphQL で安全に取得できるようにする。

前提・入力ファイル¶

正本スキーマ: static/cms-schemas/field-groups.json（AGENTSルールに従いバックアップしてから更新）
参照ドメイン: WordPress（WPGraphQL + ACF Pro）
目的: 編集UIの一元化と Storefront のナビゲーション/バナー連携の安定化

手順¶

ライセンス適用
WordPress 管理画面 → Custom Fields > ライセンス に ACF Pro キーを入力。
コード管理の場合は wp-config.php に define('ACF_PRO_KEY', '***'); を追加（環境変数運用でも可）。
現行スキーマのバックアップ
管理画面 → ACF > ツール > エクスポート で JSON を取得し、リポジトリに一時保存してからインポートを実施。
新スキーマのインポート
分割管理に移行済みのため、static/cms-schemas/field-groups.json を管理画面の ACF > ツール > インポート で適用（必要に応じて他の分割ファイルとマージしても可）。
適用後、ヘッダー/フッターのオプションページに「説明」「ストア内パス」「カスタムURL」「子メニュー」フィールドが追加されており、行が折りたたみ表示（クリック展開）になっていることを確認。
GraphQL 連携確認
WPGraphQL Playground で以下を実行し、エラーがないことを確認。

query HeaderFooterMenu {
  headerMenu {
    items {
      label
      description
      displayType
      linkType
      storePath
      customUrl
      openInNewTab
      dynamicSourceKey
      page { slug uri }
      children {
        label
        description
        displayType
        linkType
        storePath
        customUrl
        openInNewTab
        dynamicSourceKey
        page { slug uri }
      }
    }
  }
  footerMenu {
    items {
      label
      displayType
      linkType
      storePath
      customUrl
      openInNewTab
      dynamicSourceKey
      page { slug uri }
      children {
        label
        displayType
        linkType
        storePath
        customUrl
        openInNewTab
        dynamicSourceKey
        page { slug uri }
      }
    }
  }
}

Storefront 側スモーク
.env で WORDPRESS_GRAPHQL_ENDPOINT が指す環境を起動した状態で以下を実行:
pnpm --filter ritsubi-storefront test -- src/lib/wordpress/menus.test.ts
必要に応じてホームページを開き、ヘッダー／フッターのメニューがCMS値に置き換わることを確認。

変更サマリー（ACF）¶

ヘッダー／フッターメニュー
表示タイプ: static / collection（デフォルト static）
動的ソースキー: display_type=collection のとき必須。Vendure Collection の slug を入力（例: series-xxx）。Storefront 側で slug によってコレクション一覧を取得。
静的リンク用: linkType (store_path / page / custom_url) + 各入力フィールド（display_type=static のときのみ表示）
子メニュー: display_type=static のときのみ表示。display_type=collection の場合は入力不可＆Storefront 側でも無視。
UI最適化: 親・子リピーターとも collapsed=ラベル、rows_per_page=10、layout=row
メインバナー（既存）
オプションページ MainBannerOptions > homeHero.slides は既存のまま。CPT ベースの旧メインバナーは UI から利用しない。
共通ACF部品
CTAセット/リンクセット/メディアセット/表示期間/トラッキング/オーバーレイ/ソート順を「共通部品」カテゴリとして追加。再利用するブロックはこれらをクローンで利用する。

Storefront マッピング¶

取得ロジック: apps/storefront/src/lib/wordpress/menus.ts の fetchMenus() が HeaderFooterMenu クエリを呼び出し、NavigationItem[] に正規化
適用先:
Header コンポーネントは CMS メニューを優先し、未取得時は従来のハードコードにフォールバック
Footer コンポーネントはセクション単位で CMS の子メニューを表示（未設定時は従来の固定リンクを使用）
動的メニュー: dynamicSource = { type: 'collection', key } のみを許容。key が未入力の場合は /collections を表示。子メニューは生成しない。

運用メモ¶

フィールドキー・名前は変更せず、追加のみを行っているため既存データは保持される。不要になった旧メインバナーCPTは非表示運用とする。
ACF インポート前後で WPGraphQL のキャッシュが残る場合、wp graphql clear-cache などでクリアしてから再取得する。