WPGraphQL CMS Integration Plugin (Vendure)¶

【注意】本プラグインは現在、デフォルトで無効化されています。 本機能は「VendureからWordPressへの商品データ同期（プッシュ型）」を提供しますが、現在の運用方針（WordPress側からの都度取得・プル型）と異なるため凍結されています。同期機能が必要な場合のみ有効化してください。

機能の目的と文脈¶

本プロジェクトでは以下の2つのWordPress連携文脈が存在します。本プラグインは 文脈2 のための実装（の同期アプローチ版）です。

文脈1: VendureがWordPressをヘッドレスCMSとして利用する
VendureがWordPressからお知らせやバナー情報を取得する機能。
本プラグインの対象外です（別プラグインとして実装予定）。
文脈2: WordPressCMSで商品情報を引用・管理する
WordPress側で商品に関連するリッチコンテンツを管理するための連携。
本プラグインは「Vendureの商品マスタをWordPressに同期する」ことでこれを実現しようとしましたが、現在は「同期不要（ID参照のみで都度取得）」という方針のため、本機能は無効化されています。

概要¶

このプラグインは Vendure を正とし、商品・バリアントの更新イベントを WPGraphQL（WordPress + ACF）へ非同期同期します。WordPress側は参照型（vendure_idのみ保持）として機能し、StorefrontはVendureから商品データを取得します。

構成概要¶

イベントソース: Vendure ProductEvent / ProductVariantEvent
配送先: WPGraphQL エンドポイント（ベアラー認証に対応）
実行モード: JobQueue に積んでワーカーで処理（バックオフ/リトライは Vendure 標準）
スキーマ正本: apps/wordpress-local/themes/ritsubi-cms/acf-json/field-groups.json を参照してマッピングする
運用: apps/wordpress-local/themes を WordPress の wp-content/themes にマウントし、ACF Local JSON を自動同期する。
同期方式: 一方向同期（Vendure → WordPress）。WordPress側のデータは参照用のみ

環境変数¶

WORDPRESS_GRAPHQL_ENDPOINT (必須): https://ritsubi-ec-staging.xrea.jp/graphql など
WORDPRESS_GRAPHQL_TOKEN (任意): Application Password 等。user:pass 形式なら Basic、自動判定。
WORDPRESS_GRAPHQL_TIMEOUT_MS (任意): タイムアウト(ms)。未設定時 15000
WORDPRESS_CMS_JOB_QUEUE (任意): キュー名。未設定時 wp-cms-sync

実装済み機能¶

完全なマッピング実装¶

Product (商品): vendure_id, title, slug, description, featured_image, gallery, brand_code, category_code, direct_shipping, special_handling, categories (タクソノミー)
ProductVariant (バリアント): vendure_id, sku, product_ref, price_with_tax, stock_level, purchase_unit, min_qty, max_per_order, direct_shipping_only

詳細なマッピング仕様は wp-cms-mapping.md を参照してください。

差分更新判定¶

WordPress側の既存データを取得して比較
変更されたフィールドのみを更新対象とする
差分がなければWPGraphQLリクエストをスキップして負荷を削減

監視ロギング¶

構造化ログ（成功、スキップ、失敗、リトライ回数、処理時間）
エラー詳細の記録（スタックトレース、エンドポイント情報）
タイムアウトエラーの適切な処理

有効化手順¶

本機能を利用する場合（同期が必要になった場合）は、以下の手順で有効化してください。

1. 環境変数の設定¶

apps/vendure-server/.env に以下を追記:

WORDPRESS_GRAPHQL_ENDPOINT=https://ritsubi-ec-staging.xrea.jp/graphql
WORDPRESS_GRAPHQL_TOKEN=<Application Password>
WORDPRESS_GRAPHQL_TIMEOUT_MS=15000
WORDPRESS_CMS_JOB_QUEUE=wp-cms-sync
WP_CMS_INTEGRATION_ENABLED=true  # 明示的に有効化が必要

2. プラグイン設定の確認¶

apps/vendure-server/src/vendure-config.shared.ts で設定が読み込まれることを確認します（コード修正不要）。

...(WORDPRESS_GRAPHQL_ENDPOINT
  ? [
      WpCmsIntegrationPlugin.init({
        endpoint: WORDPRESS_GRAPHQL_ENDPOINT,
        authToken: WORDPRESS_GRAPHQL_TOKEN,
        timeoutMs: WORDPRESS_GRAPHQL_TIMEOUT_MS,
        jobQueueName: process.env.WORDPRESS_CMS_JOB_QUEUE ?? undefined,
        enabled: true,
      }),
    ]
  : []),

3. サーバーの起動¶

pnpm dev

またはワーカーを再起動し、ジョブキュー登録ログを確認:

WP CMS integration queue registered: wp-cms-sync

4. 動作確認¶

商品を更新し、以下のログが出力されることを確認:

WP sync enqueue: product updated id=123
WP sync completed: product updated id=123 (150ms)

運用上の注意事項¶

WordPress側のデータ編集について¶

重要: WordPress側で同期された管理フィールド（vendure_id, brand_code, category_code 等）を手動で変更しないでください。次回の同期時に上書きされます。
WordPress側で編集可能なのは、リッチコンテンツ（説明文、画像、関連記事等）のみです。

同期のタイミング¶

商品・バリアントの作成・更新・削除時に自動的に同期されます
同期は非同期で実行されるため、即座に反映されない場合があります
失敗時はVendureのJobQueueにより自動的にリトライされます

トラブルシューティング¶

同期が実行されない¶

環境変数が正しく設定されているか確認
プラグインが有効化されているか確認（enabled: true）
ワーカープロセスが起動しているか確認

エラーが発生する¶

WPGraphQLエンドポイントが正しく設定されているか確認
認証トークンが有効か確認
WordPress側のACFフィールドグループが正しく設定されているか確認
ログを確認してエラー詳細を確認:

WP sync failed: product updated id=123 (150ms)
WPGraphQL request failed: ...

差分更新が機能しない¶

WordPress側のデータ取得クエリが正しく動作しているか確認
ACFフィールド名がマッピング仕様と一致しているか確認

参考資料¶

マッピング仕様: Vendure → WordPress のフィールド対応表
認証ガイド: WPGraphQL認証設定手順
ACFスキーマ (apps/wordpress-local/themes/ritsubi-cms/acf-json/field-groups.json): WordPress側のフィールドグループ定義