seo-ecommerce

seo-ecommerce (M18)

条件付きのコマースモジュールです。コマース関連のシグナルが検出された場合にのみ実行され、（a）検索向けの商品構造化データと、（b）AI ショッピングエージェントが実際にストアを読み取り、操作できるかどうかを監査します。参照先は references/schema-tier1.md（Product と Offer、Review/AggregateRating の行）です。Shopify の Catalog や UCP のデフォルト値など、プラットフォーム固有の ID は references/platforms/shopify.md に記載されています。これらはプラットフォーム条件付きチェックで出力され、このモジュールからは出力されません。

Inputs

ディスパッチエンベロープで指定された PageSnapshot を使用します。<run_dir>/pages/<slug>.json から parsed（jsonld[]、metas[]、text_sample）を読み取り、エンベロープから vertical を読み取ってください。コマースゲートはそこで判定されます。<run_dir>/site/discovery.json には /.well-known/ucp と /api/ucp/mcp のプローブ（ステータス、content-type、body）が記録されています。<run_dir>/profile.json にはプラットフォームが記録されています。完全一致の根拠を確認するには pages/<slug>.html を grep してください。サイトの成果物は <run_dir>/site/{robots.json,sitemaps.json,discovery.json} にあります。audit.mjs がすでに出力した決定論的な検出結果は <run_dir>/findings.deterministic.json に記載されています。これらの ID を再出力せず、モデル判定の検出結果のみ追加してください。スナップショットがなく、URL またはパスを直接指定して実行する場合は、まず node "${CLAUDE_PLUGIN_ROOT}/scripts/snapshot.mjs" <target> --out "${CLAUDE_PLUGIN_DATA}/runs" を実行し、出力されたスナップショットパスを使用してください。

Audits

PageSnapshot を使用して監査します（render.used が none 以外の場合は parsed_rendered、それ以外の場合は parsed）。

1. コマースゲート：コマース関連のシグナル（価格／通貨のテキスト、カートに追加／購入のコントロール、Product／Offer スキーマ、og:type=product）を検出します。シグナルがない場合、M18 のすべての検出結果は not_applicable（重要度 0）です。コマース以外のページに商品スキーマを無理に適用しないでください。
2. Product + Offer：Product には name と image、Offer には price、priceCurrency、availability（schema.org/InStock など）が必要です。references/schema-tier1.md を参照してください。
3. AggregateRating / Review：評価がページ上に表示されている場合は、AggregateRating（ratingValue、reviewCount／bestRating）および／または Review（author）を想定します。ページ上に表示されていない評価をマークアップしてはいけません。
4. ページ → スキーマ → フィードの一貫性：スキーマの price／priceCurrency／availability は、ページ上に表示される値および販売者のフィードと一致している必要があります。不一致は、承認却下やリッチリザルトの喪失につながるおそれがあります。
5. ファセットナビゲーション：フィルター／並べ替え URL（?color=、?sort=）は、インデックスの肥大化や重複コンテンツによる評価の分散を防ぐため、クリーンな商品／カテゴリ URL を canonical として指定するか、noindex にする必要があります。
6. バリエーション／ProductGroup：複数のバリエーションがある商品には、SKU ごとに重複した単独の Product ブロックを使うのではなく、hasVariant と variesBy を含む ProductGroup を使用する必要があります。

エージェント型コマースへの対応状況（eコマースのみ）

ショッピングエージェントは、買い物客と同じように商品ページを読むわけではありません。機械可読なマーチャントプロフィール、列挙が許可されたカタログ、そして各フィールドを解析できるフィードを探します。これらのチェックは、eコマースの垂直市場が有効な場合にのみ実行され、Search カテゴリーとともに、M18 の条件付き AI カテゴリー（重み 6）に結果が反映されます。

7. UCP マーチャントプロフィール — /.well-known/ucp に認証なしで（200）パブリックアクセスでき、有効な JSON であり、ucp.version が YYYY-MM-DD 形式で、services／capabilities が、逆引き DNS 形式の名前をキーとし、{version, spec, transport?, endpoint?, schema} の配列を値とするオブジェクトである必要があります。ストアがeコマースの垂直市場ではない場合、このファイルは M21（seo-ai-discovery）の対象です。ストアがeコマースの場合は M18 が対象になります。
8. カタログ掲載要件 — サンプル対象の商品ごとに、カタログへの掲載に必要なプロパティを確認します。タイトル、1つ以上の画像、0より大きい価格、安定して識別可能な商品 URL、ストアフロントで非表示または購入不可になっていない商品が必要です。判定は一括ではなく、商品ごとに報告してください。
9. エージェント型チェックアウトフィード（ACP） — ユーザーが --feed <path> でフィードを指定した場合、必須フィールド、金額と通貨コードで記載された価格（"79.99 USD"）、許可された列挙値の availability、mod-10 チェックに合格する GTIN、絶対 URL、重複のない item_id を検証します。フィードが指定されていない場合、結果は needs_api です。合格としてはなりません。
10. フィードとページの価格 — フィードがある場合は、フィードの価格と availability を、レンダリングされたページおよびスキーマと照合します。3つの情報源から、1つの正しい値を確認します。
11. Merchant Center／プラットフォームの手がかり — Google が権威ある商品データを受け取る方法は、検証済みのマーチャントフィードです。それが存在する可能性があるか（構造化データだけではフィードになりません）、またプラットフォームがカタログ連携を宣言しているかを記録してください。

修正

• 自動（fixable: auto）：DOM から推定した情報（name、image、price、currency、availability、表示されている評価）をもとに、完全で有効な Product／Offer／AggregateRating JSON-LD を、安定した @id を持つ単一の @graph 内に生成します。このブロックは fix 用の差分です。
• 提案（fixable: proposed）：ファセット URL の canonical／noindex タグ、ProductGroup の再構成、フィールドの修正など、商品ごとの承認が必要なドラフトです。
• 助言（fixable: advisory）：ページ、スキーマ、フィード間の価格／availability の不一致、UCP プロフィールの公開、カタログ登録などが対象です。正しい情報源はストアのバックエンド、フィード、プラットフォームであるため、ツールがこれらを書き換えることはありません。価格、通貨、availability、評価、GTIN、エンドポイントを決して捏造せず、ユーザーに確認するか、明確に示した TODO プレースホルダーを残してください。

検証

• オフライン：node "${CLAUDE_PLUGIN_ROOT}/scripts/validate-jsonld.mjs" --snapshot <pages/<slug>.json>（または --url <u>）（schema_validator） — JSON の有効性と、必須の Product／Offer プロパティを検証します。
• フィードの検証：node "${CLAUDE_PLUGIN_ROOT}/scripts/acp-feed-lint.mjs" --feed <path>（JSONL、CSV、TSV） — 必須フィールド、価格形式、availability の列挙値、GTIN の mod-10、絶対 URL、重複する item_id を検証します（schema_validator）。
• UCP／カタログのプローブ：node "${CLAUDE_PLUGIN_ROOT}/scripts/ai-discovery.mjs" --snapshot <pages/<slug>.json> — site/discovery.json を再読み込みし、プロフィールの形式を検証します（schema_validator）。
• Tier 1：マーチャントリスティングの掲載要件について、Google Rich Results Test／schema.org validator（rich_results_api）を使用します。
• 必須の Tier（フィード、API、マーチャントアカウント）が利用できない場合、ステータスは needs_api です。誤って pass と判定してはなりません。

検出結果

schema/finding.schema.json に従って検出結果を出力します。EC 以外のページでは、すべての ID は not_applicable、重要度は 0 です。重要度のポリシー：5 は、サイト／テンプレート全体に関わる致命的で適格性を失わせる事実にのみ適用します。4 は重大、3 は中程度、2 は軽微、1 はごく軽微、0 は情報提供のみです。スコアを上限設定できるのは、該当カテゴリーが有効な場合に限り、重要度 5 の established な fail のみです（references/scoring-model.md）。

商品データ — 軸 both：

• M18.offer.missing_price — Offer.price／priceCurrency がない商品（fail、重要度 4、fixable: auto、信頼度 established）。
• M18.offer.price_feed_mismatch — スキーマの価格がページ上またはフィードの価格と異なる（warn、重要度 3、fixable: advisory、信頼度 directional。フィードが指定されていない場合は needs_api）。
• M18.facets.uncanonicalized — canonical も noindex もない、インデックス可能なファセット URL（warn、重要度 3、fixable: proposed、信頼度 directional）。
• M18.variants.no_productgroup — ProductGroup + hasVariant の代わりに、SKU ごとに重複した Product ブロックがある（warn、重要度 3、fixable: proposed、信頼度 directional）。宣言のみをカウントします。すでに hasVariant でバリエーションをモデル化しているページでは、列挙するバリエーション数にかかわらず検出されません。
• カタログの適格性は ProductGroup 自体を判定し、グループ独自の価格がない場合はバリエーションのオファーから価格を取得します。各バリエーションに価格があるグループは、「価格がない」とは見なされません。

エージェント型コマースへの対応状況 — EC のみ：

• M18.agentic.ucp_profile_missing — ストアに /.well-known/ucp がない（warn、重要度 3、軸 ai、fixable: advisory、信頼度 directional）。
• M18.agentic.ucp_profile_invalid — プロファイルは存在するものの、バージョン、services、または capabilities の形式を解析できない（warn、重要度 3、軸 ai、fixable: advisory、信頼度 directional）。
• M18.agentic.ucp_not_public — プロファイルが認証の背後にある、ログインにリダイレクトされる、または JSON 以外のコンテンツタイプであるため、エージェントが読み取れない（fail、重要度 3、軸 ai、fixable: advisory、信頼度 directional）。
• M18.agentic.catalog_eligibility — 商品ごとのカタログチェック：タイトル、画像、価格 > 0、識別可能な URL、ストアフロントでの表示状態のすべてが満たされていれば pass。いずれかが欠けていれば warn。商品をまったく掲載できない場合は fail（重要度 3、軸 both、fixable: proposed、信頼度 directional）。
• M18.agentic.acp_feed_errors — フィードの lint エラー。エラーの種類ごとに、問題のある行を示す 1 行を出力します（fail、重要度 3、軸 both、fixable: proposed、信頼度 directional。--feed が指定されていない場合は needs_api）。
• M18.agentic.feed_page_price_mismatch — フィードの価格または在庫状況が、レンダリングされたページと一致しない（warn、重要度 3、軸 both、fixable: advisory、信頼度 directional）。
• M18.agentic.merchant_center_hint — 検証済みのマーチャントフィードは、信頼できる商品データを Google のショッピングおよび AI サーフェスに届けるための文書化された経路です（pass、重要度 1、軸 both、fixable: advisory、信頼度 established。情報提供のみ。マーチャントアカウントは確認できません）。
• M18.agentic.shopify_catalog_declared — プラットフォームが UCP プロファイルでカタログ統合を宣言している（pass、重要度 1、軸 ai、信頼度 directional。マーチャントの実績ではなく、プラットフォームのデフォルトです）。

各検出結果では、evidence.observed にページ、プロファイル、またはフィード行の内容をそのまま引用します（例：レンダリングされた価格テキスト、問題のある ?filter= URL、item_id と列）。verification.reproduce は実行可能なコマンドです。expected_impact は区分化し、信頼度タグを付けます（根拠のないパーセンテージは不可）。

誠実性

• AggregateRating／Review マークアップが、星評価のリッチリザルトを保証するわけではありません。Google は独自の裁量で表示し、ポリシーに基づいて制限します。マークアップだけで星評価が表示されると約束してはいけません。
• ファセット URL の適切な管理は、クロールやインデックスの無駄を減らしますが、直接的なランキング要因ではありません。directional であり、効果が保証されるわけではありません。
• エージェント型コマースは初期段階にあり、文書化の程度にもばらつきがあります。 UCP、カタログ登録ルール、エージェント型チェックアウトはベンダーのプログラムであり、急速に変化しています。また、どのベンダーも「準備状況スコア」を公開していません。すべての M18.agentic.* の調査結果は directional です。この一連の中で established と言えるのは、販売事業者のフィードが信頼できる商品データの正式なチャネルとして文書化されているという主張だけです。
• Shopify では、/.well-known/ucp、agents.md、エージェント型の検出ファイルはデフォルトで提供されます。Shopify ストアにこれらが存在しても、プラットフォームのデフォルト設定であり、販売事業者が何らかの対応を行った証拠ではありません。Shopify 以外のストアに存在しない場合は、失敗ではなく不足です。
• フィードの lint エラーが示すのはファイルに関する事実であり、ストアのランキングではありません。該当する行、フィールド、ルールを報告し、収益や可視性の数値へと推測を広げてはいけません。
• スキーマは、ページ上で見える内容とフィードに厳密に一致させてください。捏造した値やフィードと一致しない値は、成果につながるどころか、販売事業者の不承認を招きます。GTIN を決して捏造してはいけません。