商品リッチ説明の Product 単位紐づけ仕様¶

位置づけ¶

商品詳細ページで表示する WordPress のリッチ説明と商品代表画像の扱いについて、紐づけ条件を恒久的に定義する補足仕様です。

商品ページは SKU / variant ごとのページではなく Vendure Product ごとのページであるため、商品リッチ説明も代表画像も Product 単位で扱います。

決定事項¶

項目	仕様
紐づけ単位	Vendure Product
主キー	`vendureProductSlugs`
補助条件	`vendureCollectionSlugs`、`isDefault`
代表画像	Product の `featuredAsset` / `assets`
本文スタイル	`styleMode`（`wordpress_theme` / `storefront_theme`）
非採用	`vendureSku` による紐づけ、Variant 画像の自動切替

運用ルール¶

WordPress の product_detail では、商品・コレクション・デフォルトのみを管理対象にする。
デフォルト商品説明は、個別の商品紐づけ・コレクション紐づけを持たない。
商品 slug 一致がある場合は、コレクション条件やデフォルト条件を直列表示せず、商品 slug 一致の本文だけを採用する。
商品 slug 一致がなく、複数のコレクション条件に一致する場合は、Vendure の collection breadcrumb 上でより深い階層の collection を優先する。親 collection と子 collection が同時に一致しても直列表示しない。
同じ優先度で複数のコレクション条件が一致した場合は、重複候補としてログに残し、表示は 1 件に絞る。
styleMode = wordpress_theme は WordPress 側の stylesheet を読み込み、CMS 側の本文スタイルを優先する。
styleMode = storefront_theme は WordPress 側の stylesheet を本文へ適用せず、storefront 側の typography / preflight を優先する。
WordPress 側 stylesheet は Storefront の CMS 表示境界でだけ読み込む。Vendure Server / Vendure Dashboard / React Dashboard 側の CSS 正本には WordPress core CSS や .editor-styles-wrapper 前提の補正を持ち込まない。
styleMode = wordpress_theme で表示する WordPress block markup の幅・余白・埋め込み比率は、 Storefront 独自 CSS ではなく WordPress core の wp-block-library / wp-block-library-theme を継承する。.wp-embed-aspect-16-9 や .wp-has-aspect-ratio のような個別 class を Storefront 側で再実装しない。
WordPress core stylesheet は <link rel="stylesheet"> として読み込むため、読み込まれた Storefront ページ内では global stylesheet として振る舞う。適用範囲を狭めたい CMS 本文では styleMode = storefront_theme を使い、includeStyles=false の経路を維持する。
SKU / variant のみを設定しても、商品詳細ページの紐づけ条件にはしない。
商品詳細のメイン画像、variant 選択カード、クイックオーダー、カート、注文履歴、注文詳細で使う代表画像は Product 単位でそろえる。
Variant に固有画像があっても、商品詳細ページで variant 選択や hover をしたことだけを理由に代表画像を差し替えない。
WordPress core stylesheet の実環境継承は GitHub issue #968 で staging / production の実表示確認を記録する。
複数コレクション条件の優先順位は GitHub issue #969 に紐づける。

受け入れ観点¶

商品詳細ページのリッチ説明は、対象商品の slug 一致を最優先で選ぶ。
商品一致がない場合のみ、コレクション一致を候補にする。
複数のコレクション一致がある場合は、より深い階層のコレクション条件を優先する。
商品一致・コレクション一致のいずれもない場合のみ、デフォルト商品説明を使う。
styleMode = wordpress_theme では WordPress 側 stylesheet を読み込み、本文 wrapper に .wp-raw を付ける。
styleMode = storefront_theme では WordPress 側 stylesheet を本文 wrapper に適用せず、storefront 側の本文スタイルを優先する。
WordPress の product_detail 編集画面に SKU 紐づけ入力を置かない。
商品詳細のメイン画像は Product の代表画像を表示し、Variant 画像へ自動で切り替わらない。
variant 選択カード、クイックオーダー、カート、注文履歴、注文詳細でも、同じ Product 代表画像が表示される。
リッチ説明 HTML は apps/storefront/src/lib/safe-html.tsx の sanitizer 経由でのみ描画する。直書きは CI lint (lint:storefront-rich-text) で検出される。許可タグ・画像 src 正規化・外部リンクの rel 付与の挙動は 2026-05-storefront-rich-text-rendering.md を参照。