respira-woocommerce

Respira WooCommerce

このスキルの対象範囲

Respira WooCommerce アドオン（v2.1.0 以降）は、WordPress Abilities API を通じて 21 個の機能を提供し、さらに Elementor、Divi、Flatsome UX Builder、Bricks、Gutenberg のショップ／商品テンプレート向けのストアフロントレイアウト機能も提供します。このアドオンは有料で、ライセンスが必要です。アドオンが有効でない場合、すべての Woo ツールは明確な respira_webmcp_woo_unavailable エラーを返すため、ユーザーには respira.press/addons/woocommerce を案内してください。

21 個の機能は respira-woocommerce/* 名前空間に属します。

• 商品：get-products、get-product、create-product、update-product、duplicate-product。
• カテゴリー：get-categories、get-category、create-category、update-category、delete-category。
• タグ：get-tags、get-tag、create-tag、update-tag、delete-tag。
• 注文：get-orders、get-order、update-order-status。
• 在庫：get-stock-status、update-stock。
• レポート：get-sales-report。

ストアフロント機能（/respira/v1/woocommerce/storefront/ 配下）では、analyze-shop、analyze-product、update-card-layout、add-low-stock-badge を利用できます。これらは WC コアデータではなく、ビルダーで管理される商品カードテンプレートに作用します。

よくある間違い

間違い	正しい方法
WooCommerce の商品ページで respira_update_page を使う	商品データには WooCommerce の update-product 機能を使います。ページ上のビルダー管理のビジュアルコンテンツには、respira_find_element と respira_update_element を使います。
ページコンテンツ内で商品価格や在庫を直接編集する	これらは投稿メタフィールドです。update-product または update-stock 機能を使います。
大規模なカタログでページネーションなしに get-products を実行する	必ず per_page（最大 100）を設定し、ページネーションしてください。大規模なカタログではタイムアウトが発生します。
投稿メタでクーポンを適用する	クーポンの変更には、正規の WooCommerce クーポン変更機能（または WC 管理画面）を使ってください。メタを直接編集すると、WC の検証を迂回します。
update_page でビルダー管理のショップアーカイブテンプレートを編集する	まず respira_get_builder_info を使ってテンプレートの種類を特定します。ストアフロントツールは商品カードのレイアウト変更に対応します。ビジュアル編集には respira_update_element を使います。
Woo ツールを呼び出す前に WooCommerce が有効か確認しない	respira_get_site_context で確認します。プラグインが無効な場合、またはアドオンのライセンスがない場合、Woo ツールは構造化されたエラーを返します。
update-order-status で変更されるのはステータスのみであることを忘れる	注文のその他の項目（明細、合計、住所）の更新には、WC 管理画面または専用ツールが必要です。この機能の範囲は意図的に限定されています。

入力

• 商品 ID、SKU、または検索語。
• カテゴリースラッグまたは ID、あるいはタグスラッグまたは ID。
• 注文 ID、または注文ステータスのフィルター（pending、processing、on-hold、completed、cancelled、refunded、failed）。
• クーポンコードまたはクーポン ID。
• 読み取る、または更新するフィールド。

ワークフロー

商品操作

1. respira_get_site_context。WooCommerce が有効で、アドオンのライセンスがあることを確認します。
2. get-products。名前、SKU、またはフィルターで商品を検索します。per_page を設定し、ページネーションしてください。
3. update-product。変更（価格、在庫、ステータス、タイトル、説明、画像）を適用します。
4. 商品ページのビジュアルコンテンツ／ビルダーコンテンツには、respira_get_builder_info、respira_find_element、respira_update_element を使います。

カテゴリーとタグの操作

1. get-categories または get-tags。スラッグまたは名前で対象を検索します。
2. create-、update-、または delete-。変更操作には権限チェックが適用されます。
3. 並べ替えや親カテゴリーの変更には、update-category（parent + display order）を使います。

注文操作

1. ステータスフィルターを指定して get-orders を実行します。
2. 特定のレコードには get-order を使います。
3. ステータス変更には update-order-status を使います。それ以上の変更には WC 管理画面が必要です。

在庫操作

1. スナップショットの取得には get-stock-status を使います。
2. 数量やステータスの変更には update-stock を使います。この機能は商品ごとの manage_stock 設定に従います。

ストアフロントのレイアウト

1. analyze-shop または analyze-product を呼び出します。有効なビルダーと、編集可能なカード／テンプレートのパスが返されます。
2. update-card-layout で商品カードの構造を変更します。
3. add-low-stock-badge で条件付きバッジウィジェットを挿入します。
4. 必ず先に respira_create_page_duplicate でページのスナップショットを作成してください。

商品の一括更新

複数の商品を更新する場合（カテゴリー全体の価格引き上げなど）：

1. カテゴリーフィルターを指定して get-products を呼び出し、対象の ID を収集します。
2. respira_batch_update を呼び出し、収集したすべての ID に同じフィールド変更を一度の呼び出しで適用します。

ルール

• WooCommerce が有効で、アドオンのライセンスが有効であることを確認してから、WooCommerce ツールを呼び出してください。
• 商品ページの価格、在庫、商品メタデータを変更するために、respira_update_page を使用してはいけません。これらは WC のデータフィールドです。
• 商品説明については、商品ページでビルダーが使用されている場合、ビジュアル上の説明はビルダーの JSON 内にある可能性があります。respira_find_element を使って特定してください。WC の description フィールドは、ビルダーを使用しない場合の説明のフォールバックです。
• respira_batch_update で一度に処理できるアイテムは最大 100 件です。それを超える操作は分割してください。
• 割引の種類をユーザーに確認せずに、クーポンを作成または変更してはいけません。パーセントクーポンを fixed_cart として適用すると、収益が大幅に失われる可能性があります。
• 通貨はサイトごとに異なります。USD や EUR と決めつけず、respira_get_site_context で確認してください。

検証

update-product の実行後：

1. get-product を呼び出し、変更したフィールドが一致することを確認します。
2. 価格を変更した場合は、regular_price と sale_price の両方が正しいことを確認します。
3. 在庫を変更した場合は、stock_quantity と stock_status を確認します。

update-order-status の実行後：

1. get-order を呼び出し、ステータスの遷移を確認します。
2. 特定の遷移では WC のメールが自動的に送信されることに注意し、ユーザーに伝えてください。

一括更新の実行後：

1. 一括更新した商品から 2～3 件を抽出し、変更したフィールドを確認します。
2. 更新した商品の合計数と、エラーが返された商品を報告します。

エスカレーション

以下の場合は処理を中断し、ユーザーに確認してください：

• 商品カタログが 1,000 件を超えており、依頼が「すべての商品を更新」である場合。まず対象範囲と一括処理の方針を確認します。
• クーポンの変更が、無制限の利用またはサイト全体の割引に影響する場合。適用前に確認します。
• WooCommerce Subscriptions、Memberships、または Bookings が関係する場合。これらは独自のデータモデルを使用します。作業を進める前に利用可能なツールを確認してください。
• 更新によって商品の status が publish から draft に変わる場合。ユーザーが非公開にする意図があるか確認します。
• 注文が支払い済みかつ発送済みで、依頼がその注文の変更を伴う場合。WC は支払い済みの注文の変更不可能な履歴を保存するため、変更前に確認してください。

例

目的：「Merino Wool Tee」の通常価格を €49 から €59 に変更します。

1. respira_get_site_context        → WooCommerce 8.7 active, Woo add-on licensed ✓
2. get-products                    → search "Merino Wool Tee" → ID 2847
3. update-product                  → ID 2847, regular_price: "59"
4. get-product                     → ID 2847 → regular_price: "59.00" ✓