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

本手順は Issue

24「ACF有料版への移行と編集UI最適化＋Storefront連携」に対応する。ヘッダー／フッターメニューを ACF

Pro のリピーター＋クローン構造に統合し、Storefront から GraphQL で安全に取得できるようにする。

前提・入力ファイル

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

リポジトリ配置とマウント

• Git 管理の正本: apps/wordpress-local/themes/ritsubi-cms/acf-json/*.json
• ローカル/コンテナの WordPress では apps/wordpress-local/themes を wp-content/themes にマウントするため、Local JSON は正本へ直接保存される。
• スキーマは apps/wordpress-local/themes/ritsubi-cms/acf-json/ のみを正本とし、他の場所にコピーを作らない。

スキーマ更新手順（ACF Local JSON）

1. 正本JSON（apps/wordpress-local/themes/ritsubi-cms/acf-json/*.json）を編集する。
2. git status / git diff で JSON の差分を確認し、不要ファイルがないことをレビューする。
3. 必要に応じて ACF > ツール > インポート で同一ファイルを適用する。

手順

1. ライセンス適用
2. WordPress 管理画面 → Custom Fields > ライセンス に ACF Pro キーを入力。
3. コード管理の場合は wp-config.php に define('ACF_PRO_KEY', '***'); を追加（環境変数運用でも可）。
4. 現行スキーマのバックアップ
5. 管理画面 → ACF > ツール > エクスポート で JSON を取得し、リポジトリに一時保存してからインポートを実施。
6. 新スキーマのインポート
7. 分割管理に移行済みのため、apps/wordpress-local/themes/ritsubi-cms/acf-json/field-groups.json を管理画面の ACF > ツール > インポート で適用（必要に応じて他の分割ファイルとマージしても可）。
8. 適用後、ヘッダー/フッターのオプションページに以下が反映されていることを確認。
   • display_type に text_block が追加されている（フッター用テキストカラム）
   • display_type=static のときのみ「リンクタイプ/ページ/ストア内パス/カスタムURL/子メニュー」が表示される
   • display_type=text_block のときのみ「テキスト本文(body)」が表示される（リッチテキスト・basicツールバー）

9. データ分離: options-pages.json でヘッダー/フッターの post_id を header_menu_options / footer_menu_options に設定済み。WP同期後、ヘッダー編集がフッターに上書きされないことを確認する。

10. GraphQL 連携確認

11. WPGraphQL Playground で以下を実行し、エラーがないことを確認。

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

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

変更サマリー（ACF）

• ヘッダー／フッターメニュー
• 表示タイプ: static / collection / text_block（デフォルト 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 側でも無視。
• テキストブロック: display_type=text_block のとき body を入力（リッチテキスト）。フッターでのみ使用され、ヘッダーでは無視される。
• UI最適化: 親・子リピーターとも collapsed=ラベル、rows_per_page=10、layout=row
• メインバナー（既存）
• オプションページ MainBannerOptions > homeHero.slides は既存のまま。CPT ベースの旧メインバナーは UI から利用しない。
• 共通ACF部品
• CTAセット/リンクセット/メディアセット/表示期間/トラッキング/オーバーレイ/ソート順を「共通部品」カテゴリとして追加。再利用するブロックはこれらをクローンで利用する。

フッターメニュー設定手順（text_block対応）

1. WP管理画面 → ストア設定 > フッターメニュー を開く
2. 行を追加し、以下いずれかを選択
3. static / collection：リンクカラム（第1階層がカラム見出し、第2階層がリンク）
   • static のとき linkType を選択し、必要に応じて storePath / page / customUrl を入力
   • 子リンクは「子メニュー」で追加（2階層まで）
4. text_block：テキストカラム（フッター専用）
   • body にリッチテキスト（基本タグのみ）。箇条書きもここで入力可能。
5. 並び順はドラッグで変更できる（第1階層の並びがカラム順になる）
6. 保存後、WPGraphQL Playground で以下を実行し、エラーなく値が返ることを確認:

footerMenu {
  items {
    label
    displayType
    body
    notes { text }
    children { label href:storePath }
  }
}

1. Storefront で表示確認し、未設定の場合は従来のデフォルトフッターにフォールバックすることを確認する

Storefront マッピング

• 取得ロジック: apps/storefront/src/lib/cms/wordpress/menus.ts の fetchMenus() が HeaderFooterMenu クエリを呼び出し、NavigationItem[] に正規化
• 適用先:
• Header コンポーネントは CMS メニューを優先し、未取得時は従来のハードコードにフォールバック
• Footer コンポーネントは第1階層をカラム見出しとして扱い、第2階層リンクを表示。display_type=text_block の項目はテキストカラムとしてレンダリングし、未設定時は従来の固定リンクを使用
• 動的メニュー: dynamicSource = { type: 'collection', key } のみを許容。key が未入力の場合は /collections を表示。子メニューは生成しない。

運用メモ

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