WordPress ACF Pro 統合ガイド

本ドキュメントは、WordPress（ACF Pro）で管理されたメニュー・バナー構成を、Vendure プロキシを経由して Storefront へ連携する仕様について説明します。

前提アーキテクチャ

Storefront は WordPress へ直接アクセスしません。Vendure サーバーの C IntegrationPlugin がプロキシおよび正規化レイヤーとして機能します。

1. WordPress: ACF Pro でメニューやバナーを編集。
2. Vendure: WordPress の WPGraphQL を叩き、Ritsubi ドメインの GraphQL スキーマへマッピング。
3. Storefront: Vendure の Shop API (headerMenu, footerMenu 等) を叩き、React コンポーネントで表示。

---

メニュー連携仕様

ヘッダーおよびフッターのメニュー構造は、WordPress 側のメニュー機能（位置設定）に基づきます。

1. WordPress 側の設定

• ロケーション: PRIMARY (Header用) および FOOTER (Footer用) のメニュー位置を使用します。
• フィールド: 標準のメニュー項目に加え、ACF で拡張された displayType, linkType, dynamicSourceKey 等を設定可能です。

2. Vendure 側の GraphQL スキーマ

Vendure は以下のクエリを提供します。

query HeaderFooterMenu {
  headerMenu {
    items {
      label
      description
      displayType
      linkType
      storePath
      customUrl
      openInNewTab
      dynamicSourceKey
      body
      page {
        slug
        uri
      }
      children {
        label
        # ... (親と同様のフィールド)
      }
    }

  }
  footerMenu {
    # ... (headerMenu と同様の構造)
  }
}

3. Storefront 側の正規化

• URL 解決: @ritsubi/utils の normalizeCmsUrl 用して、WordPress の絶対 URL をストア内の相対パスへ自動変換します。
• フォールバック: WordPress からメニューが取得できない場合、Storefront は ritsubi/resources` に定義されたデフォルトメニュー（プレースホルダー）を表示します。

---

開発とテスト

疎通確認手順

1. バックエンドテスト: packages/plugins 内で pnpm test を実行し、WordPressService が WordPress のデータを正しく正規化できるか確認します。
2. フロントエンドテスト: apps/storefront 内で pnpm test src/lib/cms/wordpress/menus.test.ts を実行し、Vendure からのデータが UI 用にマッピングされるか確認します。
3. モックの無効化: 実データを確認するには、Storefront の .env で NEXT_PUBLIC_STOREFRONT_API_MOCKING=disabled と設定し、バックエンドの WORDPRESS_ENDPOINT を正しく設定してください。

運用上の注意

• URL スラッグ: メニュー項目の ID 生成には @ritsubi/utils の slugify が使用されます。
• キャッシュ: 現在、Vendure プロキシ層でのキャッシュは no-store (Storefront 側指定) となっています。WordPress 側でメニューを保存すると、次回のページリロードで反映されます。