woo-guard

Woo Guard

生成または変更した WooCommerce コードを、リリース前にレビューします。最初の実装が完了した後、ガードパスとして以下のルールを適用してください。WooCommerce は変化し続けるプラットフォームです。注文ストレージはエンジンが変わり、チェックアウトはフレームワークが変わりました。記憶を頼りに書かれたコードは、3 年前の WooCommerce を対象にしています。お金がかかっている以上、「デモストアでは動く」は基準になりません。

これらのルールがあるのは、AI エージェントが WooCommerce コードで体系的な不具合を起こすためです。たとえば、get_post_meta() で注文メタを読み取る（HPOS ストアでは動作しない）、ルックアップテーブルとフックをスキップして商品を直接メタ更新する、JavaScript のみでチェックアウトを検証する、価格を浮動小数点数で計算する、WooCommerce が有効か確認する前に woocommerce_* フックを登録するといった問題です。

このスキルの使い方

ガードパスモード（推奨）：WooCommerce コードの生成または編集後に、差分または対象ファイルへルールを適用し、納品前にセルフチェックを実行します。

ライブモード（明示的な指定が必要）：ユーザーが WooCommerce コードを書く前にこのスキルを呼び出した場合、コードを書きながら同じルールを適用し、納品前にセルフチェックを実行します。

レビューモード（ユーザーが WooCommerce コードのレビューまたは監査を依頼した場合）：references/review-checklist.md に沿って確認し、構造化された指摘レポートを作成します。依頼がない限り、レビューモードではコードを編集しないでください。

セキュリティの最低基準 — お金がかかっているため、すべての WooCommerce コードで以下を最高の重大度として適用します。

• コンテキストに適した esc_* 関数を使って、すべての出力をエスケープします。
• すべてのリクエストデータに対して、ロジックで使用する前に wp_unslash() を適用し、サニタイズします。
• 状態変更のたびに、権限チェックと nonce を実施します。
• 変数を含むすべてのクエリで $wpdb->prepare() を使用します。

wp-guard がインストールされている場合は、WordPress レイヤー全体を対象に、併せて実行してください。

まずプロジェクトに合わせる

1. プロジェクトのエージェント向け指示と、拡張機能が宣言する WooCommerce のバージョン範囲を確認します。競合する場合は、プロジェクトの規約を優先します。
2. このコードでサポートする必要がある注文ストレージモードを確認します。HPOS、従来の投稿、または両方です（デフォルトでは両方と想定します）。
3. 対象のチェックアウトを確認します。Blocks／Store API、従来のショートコードチェックアウト、または両方です。一方のフックは、もう一方では実行されません。
4. WooCommerce の有効性がガードされているか確認します。wc_* の呼び出しや woocommerce_* フックの登録より前に、機能チェックまたは class_exists( 'WooCommerce' ) を行います。

ルール

注文および商品データ — 必ず修正

1. 注文は投稿ではありません。 注文へのアクセスには、CRUD API のみを使用します。wc_get_order()、wc_get_orders()、$order->get_meta()、$order->update_meta_data() と ->save() が該当します。注文データに対して、get_post_meta()、update_post_meta()、post_type => shop_order を指定した WP_Query／get_posts()、および postmeta に対する $wpdb の直接結合は禁止です。これらは従来のストアでは動作しますが、HPOS ストアでは気付かないうちに壊れます。詳細：references/hpos-and-crud.md。

2. CRUD オブジェクトを使い、ゲッター／セッターを経てから保存します。 商品、顧客、クーポンには CRUD オブジェクト（wc_get_product()、セッター、->save()）を使用します。メタを直接書き込むと、ルックアップテーブルの同期や、他の拡張機能が依存するフック、キャッシュの無効化がスキップされます。在庫の変更には wc_update_product_stock() のセマンティクスを使います。注文状態の変更には $order->update_status() を使います。これらはストアが想定するメールやフックを発火します。

3. 機能互換性を宣言します。 注文を扱う拡張機能は HPOS 互換性（FeaturesUtil::declare_compatibility( 'custom_order_tables', … )）を宣言します。チェックアウトを扱う拡張機能は、cart_checkout_blocks の互換性（または非互換性を正直に）宣言します。宣言がないと、すべてのストアオーナーにプラグイン名を表示した警告バナーが表示されます。

チェックアウトと金額 — 必ず修正

4. チェックアウトの検証はサーバー側で行います。（レガシーでは）woocommerce_checkout_process で検証するか、（Blocks では）Store API の拡張スキーマを使用します。JavaScript による検証はユーザー体験のためのものであり、セキュリティ対策にはなりません。ストアでどのチェックアウトが稼働しているかを把握し、拡張機能が汎用的な互換性をうたう場合は、両方に対応させます。

5. 金額は浮動小数点数ではありません。 価格と合計の保存には wc_format_decimal()、表示には wc_price() を使用し、計算には WooCommerce 独自の税設定と丸め設定を使用します。独自に通貨記号を処理したり、価格に number_format() を使用したり、合計を浮動小数点数で比較したりしてはいけません。

実行時のルール — 修正を推奨

6. 実行コンテキストを確認します。 REST、cron、CLI、管理画面のコンテキストでは、WC()->cart と WC()->session は null です。アクセスする前に確認してください。Webhook やゲートウェイのコールバックで、顧客がログインしていると決めつけてはいけません。サポート対象バージョンの範囲で、すべての woocommerce_* フックと wc_* 関数が存在することを確認してください。WooCommerce ではメジャーバージョン間でフックの名称変更や廃止が行われます。

7. テンプレートのオーバーライドよりフックを優先します。 次の順に優先してください。既存の WooCommerce フック／フィルター → woocommerce_locate_template フィルター → テーマレベルのオーバーライド。プラグインに同梱されたテンプレートのオーバーライドは、コピーしたファイルを特定の WooCommerce バージョンに固定し、テンプレート更新時に問題を引き起こします。必ずレビューで指摘してください。

8. バックグラウンド処理は注文量に合わせて拡張できる必要があります。 バッチジョブ、同期処理、Webhook のファンアウトには、生の WP-Cron ループではなく、WooCommerce に同梱されている Action Scheduler を使用します。実際のストアでは注文イベントが複数回発火するため、ハンドラーは冪等にします。

提出前のセルフチェック

1. 差分を get_post_meta、update_post_meta、post_type => 'shop_order' で grep します。これらのいずれかが注文に触れていますか？（ルール 1）
2. CRUD オブジェクトの save() を経由しない商品／注文／顧客への書き込みがありますか？（ルール 2）
3. 拡張機能で HPOS（該当する場合は checkout-blocks も）の互換性を宣言していますか？（ルール 3）
4. ストアで実際に稼働しているチェックアウトに対して、すべてのチェックアウトルールがサーバー側で適用されていますか？（ルール 4）
5. 金額に浮動小数点数の演算、ハードコードされた通貨記号、または number_format() を使用していませんか？（ルール 5）
6. REST／cron／CLI で実行される可能性がある WC()->cart／WC()->session へのアクセスはありませんか？確認していないフック名はありませんか？（ルール 6）
7. プラグインに同梱されたテンプレートファイルはありますか？（ルール 7）
8. セキュリティの最低基準：すべての出力をエスケープし、リクエスト入力のスラッシュを解除してからサニタイズし、すべての状態変更で権限を確認して nonce を検証し、すべての可変クエリをプリペアドステートメントにしていますか？

いずれかの回答が不適切なら、ユーザーに見せる前に修正してください。

報告形式（レビューモード）

**Rule N violation** in `path/file.php:<line or function>`
- What: <one sentence>
- Risk: <HPOS breakage / skipped hooks / money error / checkout bypass — one phrase>
- Fix: <one sentence>

ファイルごとにまとめ、ルール 1〜5 の指摘を先頭に記載します。問題のないファイルには言及しません。

重大度の目安

• 必ず修正： ルール 1〜5 — ストアの不具合、ビジネスロジックの迂回、金額の誤り
• 修正を推奨： ルール 6〜8 — コンテキストによるクラッシュ、更新への脆弱性、大規模化で停止するジョブ

参考資料

• references/hpos-and-crud.md — HPOS の背景、CRUD のパターン、互換性の宣言、違反一覧
• references/checkout-and-money.md — レガシーと Blocks のチェックアウト、Store API の検証、価格と通貨の処理
• references/review-checklist.md — レビューモード用の構造化された確認手順
• references/sources.md — WooCommerce 開発者向けドキュメントの URL。引用する場合にのみ読みます。

このスキルの対象外

• セキュリティの最低基準を超える WordPress レイヤー全般。wp-guard がインストールされている場合、i18n とアセット／クエリのルールは wp-guard の担当範囲です。
• ストアの設定、テーマのスタイル、決済プロバイダーのアカウント設定のレビュー。
• 価格設定やビジネスロジックの決定。WooCommerce のコードのリリース方法をチェックするものであり、ストアで何を販売するかを決めるものではありません。