ヘッドレス WooCommerce API (headless-woocommerce-api)
WooCommerce バックエンド API（WPGraphQL および REST）の設定、クエリ、セキュリティ保護を行い、デカップリングされたフロントエンドアプリケーション（Next.js、Remix、モバイル）を動作させるためのオーケストレーションガイド。
前提条件
- WordPress がインストールされ、WooCommerce プラグインが有効化されていること。
- GraphQL エンドポイントにアクセス可能であること（デフォルト:
https://your-store.com/graphql）。 - 詳細なクエリや技術的な例については、headless-api-reference.md を参照してください。
- フロントエンドクライアントの設定については、storefront-client.ts を確認してください。
ステップバイステップ実行チェックリスト
flowchart TD
S1["1. WPGraphQL & WooGraphQL のインストール"] --> S2["2. サンプル/ライブカタログデータのシード"]
S2 --> S3["3. 認証の設定（JWT / OAuth）"]
S3 --> S4["4. GraphiQL でスキーマを確認"]
S4 --> S5["5. Next.js でクライアントクエリを配線"]
ステージ 1: バックエンドプラグインのデプロイ
- WPGraphQL コアのインストール:
- WordPress プラグインディレクトリから
wp-graphqlをインストールし、有効化します。 - エンドポイントが稼働していることを確認します:
GET/POST /graphql。
- WordPress プラグインディレクトリから
- WooGraphQL 拡張のインストール:
- wp-graphql-woocommerce をダウンロードしてインストールします。
- タイプ（
Product、ProductCategory、Cart、Customer）が GraphQL スキーマに表示されることを確認します。
- テストデータのシード:
ツール → インポート → WooCommerce 商品（CSV）から CSV インポーターを実行し、sample-data/sample_products.csvを使用します。
ステージ 2: ヘッドレス認証の設定
- オプション A: JWT 認証（
wp-graphql-jwt-authentication）:wp-graphql-jwt-authenticationをアップロードして有効化します。- 64文字のシークレットを生成します（
openssl rand -base64 48 | tr -dc 'A-Za-z0-9_#%+=@!' | head -c 64または PowerShell の同等のコマンド）。 - コンテナに注入するか（
docker exec -it <container> sed -i ... /var/www/html/wp-config.php）、.envに追加するか（GRAPHQL_JWT_AUTH_SECRET_KEY）、またはwp-config.phpに直接追加します:define( 'GRAPHQL_JWT_AUTH_SECRET_KEY', 'your-strong-random-secret' );
- オプション B: ヘッドレスログイン（
wp-graphql-headless-login）:- 外部 OAuth 2.0 / ソーシャルログイン（Google、GitHub）が必要な場合に使用します。
- フィルターまたは管理設定を介してプロバイダーを設定します。
ステージ 3: ストアフロントデータのクエリ
- 公開カタログ: ユニオンフラグメント（
... on SimpleProduct、... on VariableProduct）を使用して、カテゴリと商品をクエリします。 - カスタマーセッション: カートミューテーション時に
woocommerce-sessionヘッダーをキャプチャし、後続のリクエストで送信します。 - 保護されたプロフィール: 顧客の注文や住所更新のために、
Authorization: Bearer <authToken>を渡します。
ステージ 4: フロントエンド統合（Next.js）
- 公開 GraphQL クエリを使用して、静的製品ページに SSG/ISR を実装します。
- カートトークンをクライアントサイドの状態（Zustand / LocalStorage）で保持し、Next.js ページをキャッシュ可能にします。
- ネイティブチェックアウトブリッジを実装: WordPress の
/checkoutにリダイレクトし、ローカルの支払いゲートウェイと e-Namad 準拠を利用します。
エッジケースと既知の AI の落とし穴
- 商品クエリにおけるユニオン: WooCommerce の商品はポリモーフィックです。
priceを直接products { nodes { price } }のようにクエリしないでください。必ず型条件（... on SimpleProduct { price }、... on VariableProduct { price }）を使用する必要があります。 - セッションヘッダーの欠落: サーバーから返された
woocommerce-sessionトークンをフロントエンドクライアントが保存して再送信しないと、カートのアイテムは次のリクエストで消えてしまいます。 - 管理画面 React 非互換性: 厳格なコア WordPress をカスタムビルドなしで使用する場合、
wp-graphql-headless-loginの設定パネルのように、レガシーな Gutenberg 管理バンドルを持つプラグインは避けてください。wp-graphql-jwt-authenticationのような定数駆動のプラグインに固執してください。 - CORS ヘッダー: フロントエンドオリジンからのリクエストを WordPress が許可するように、ヘッダーまたはリバースプロキシを設定してください。
検証とセルフチェック
-
/graphqlに対するテストクエリを実行し、productCategoriesとproductsがノードを返すことを確認します。 -
loginミューテーションを実行し、有効なauthTokenが生成されることを確認します。 - カートに商品を追加したときに、
woocommerce-sessionヘッダーが返されることを確認します。