Collection / Facet / custom field の責務境界（補足仕様）¶

位置づけ¶

本ドキュメントは、既存仕様書を補完する追加合意事項（正本補足）です。
リツビ案件における Collection と Facet / custom field の使い分けを、Vendure の標準的な考え方に寄せて明確化します。

合意日¶

2026年3月17日

参照元¶

docs/specifications/BtoB発注システム要件 (最新).xlsx
docs/specifications/BTOB販売現状の画面構成.pdf
docs/specifications/業務について.pdf

最終ルール¶

Brand = brand Facet の FacetValue
Brand page / Brand menu = Collection
Brand Collection は facet-value-filter により brand=<facet value> で自動分類する
子 Collection は親 filter 継承と追加 facet filter を組み合わせる
バンドル商品そのもの = 親 ProductVariant + customFields.setComponents
セット商品一覧 / 特設導線 = Collection
バンドル親の識別 = product-type=set Facet を推奨する
数値や複雑な業務条件は必要に応じて custom field に残す

Facet は、属性・絞り込み・内部ルールの基礎として使います。
判断の中心は「複数の Collection や画面をまたいで再利用される属性軸か」です。

brand
exuviance
mesoceutical
imeso
general
product-type
skincare
supplement
professional
retail
set
promotion
gift
sample
system
customer-visibility
regular
premium
clinic-only
shipping-mode
normal-only
direct-ship-allowed

業務用 / 店販用
直送可否
同意要否
予約商品フラグ
顧客 tier に関係する横断属性

ブランド用途では、通常は Product に brand FacetValue を付与し、その Product 配下の Variant に共通適用します。

Collection で持つもの¶

Collection は、ストアフロントのカテゴリ / ナビゲーション階層 / 一覧ページに使います。
判断の中心は「そのままメニューやページになるか」です。

標準 Collection tree¶

brands
brands > exuviance
- brands > exuviance > professional
- brands > exuviance > promotion
- brands > exuviance > homecare
brands > mesoceutical
- brands > mesoceutical > skincare
- brands > mesoceutical > supplement
- brands > mesoceutical > retail
- brands > mesoceutical > professional
- brands > mesoceutical > promotion
brands > imeso
brands > general
campaigns
campaigns > spring
campaigns > seminar

子 Collection の例¶

brands > exuviance > professional
brands > exuviance > retail
brands > mesoceutical > premium
sets > starter-kit
campaigns > spring > seminar-only

論理識別子としては brands.exuviance.professional などの表現を使ってよいですが、実際の slug 命名は既存の ASCII 規約に従います。

Storefront でのブランド配下グループ表示¶

Storefront の商品カタログでは、/products?collection=<brand-slug> のブランド collection 選択時に、ブランド直下の子 Collection を商品グループとして表示する。

brands > {brand} はブランドページと左サイドバーの第1階層 item として使う。
brands > {brand} > {child} は商品一覧メインカラムのグループ見出しと、左サイドバーのアコーディオン第2階層 item として使う。
グループの表示順は Vendure Collection の position を正本にし、GraphQL 取得後も position で再ソートする。
現在の顧客から見える商品がない子 Collection は、可視 Collection 解決の段階で表示しない。
どの子 Collection にも属さないがブランド collection には属する商品は、一覧末尾の 「その他」 にまとめる。
ブランド root (/products?collection=brands) はブランド facet 基準の既存表示を維持し、ブランド直下グルーピングの対象外とする。

どう動くか¶

商品A

Facet: brand=exuviance

Collection brands > exuviance

filter: brand=exuviance

この構成にすると、brand=exuviance の FacetValue を持つ商品が自動的にブランド Collection に分類されます。

さらに brands > exuviance > professional のような子 Collection では、親の brand=exuviance を継承しつつ、product-type=professional を追加して絞り込めます。

バンドル商品の扱い¶

バンドル商品は、Collection ではなく商品構造として扱います。
判断の中心は「それ自体が販売単位か、導線か」です。

バンドル商品で正本にするもの¶

販売単位: 親 ProductVariant
構成関係: customFields.setComponents
セット商品の識別: product-type=set Facet を推奨

Collection にするもの¶

セット商品一覧ページ
セット商品特設ページ
ブランド配下の「セット商品」メニュー

使い分け¶

「このセット商品そのものを売る」→ 親 ProductVariant
「このセット商品群の一覧を見せる」→ Collection
「セット商品だけをまとめて絞り込む」→ product-type=set Facet
「同意・在庫・出力で構成品へ分解する」→ customFields.setComponents

custom field で持つもの¶

custom field は、Facet に載せると扱いづらい数値・複雑条件・計算専用値に使います。

最低発注数
数量ブレーク
価格計算用の詳細条件
請求書要否
売掛可否 / 先入金可否
代引き可否
送料ルールキー

境界線¶

検索・絞り込み・内部ルールで再利用する属性軸 → Facet
そのままメニューやページになる階層 → Collection
販売単位や親子の構成関係 → Product / ProductVariant + custom field
数値・真偽値・計算用の詳細条件 → custom field
顧客の通常カート追加可否 → ProductVariant customerAddable
表示可否 → visibility rule。product-type や customerAddable 単体では表示可否を決めない

この案件での具体例¶

brand = exuviance
product-type = professional
product-type = sample
product-type = gift
product-type = system
customer-visibility = premium
shipping-mode = direct-ship-allowed

Collection の例¶

brands > exuviance → filter: brand=exuviance
brands > mesoceutical → filter: brand=mesoceutical
brands > mesoceutical > supplement → inherit brand=mesoceutical + add product-type=supplement
brands > exuviance > professional → inherit brand=exuviance + add product-type=professional
campaigns > spring
campaigns > seminar
sets > starter-kit
brands > exuviance > set

custom field の例¶

minOrderQty = 12
invoiceRequired = true
shippingRuleKey = exuviance-default
setComponents = {"components":[...]}
customerAddable = false

ProductVariant の role と通常カート追加可否¶

product-type は製品種別に加えて、ギフト・サンプル・内部予約 SKU などの用途 role も表す。gift / sample / system は required baseline と runtime drift audit の対象にする。

表示制御は visibility rule を正本にし、storefrontHidden のような表示専用 custom field は使わない。顧客が通常導線から能動的にカート追加できるかだけを ProductVariant customerAddable で分ける。

例:

能動購入サンプル: product-type=sample + customerAddable=true
受動付与サンプル: product-type=sample + customerAddable=false
キャンペーンギフト: product-type=gift + customerAddable=false
ポイント調整・マイナス価格 SKU: product-type=system + customerAddable=false

詳細は ProductVariant の用途分類と通常カート追加可否を正本とする。

この構成の利点¶

Vendure の標準思想である Collection = ナビゲーション / Facet = 属性 に沿う
faceted search にそのまま使えるため、ブランド別フィルタや集計が自然
private Facet や custom field を組み合わせることで、内部ロジックにも展開しやすい

運用ルール¶

Brand のデータ真実は brand FacetValue とする
Brand page / menu は Collection とし、facet-value-filter で自動分類する
子 Collection は親 filter 継承と追加 facet filter を組み合わせる
キャンペーンページや専用メニューは Collection として運用してよい
バンドル商品そのものは親 ProductVariant とし、Collection に商品構造を持たせない
セット商品一覧や特設導線は Collection として運用してよい
バンドル親を絞り込む必要がある場合は product-type=set Facet を使う
顧客別の表示制御は、Collection 対象と customer 系 Facet / custom field を plugin / policy 側で組み合わせて判定する

Storefront 導線ルール（2026-03-18 追記）¶

Storefront の browse 導線は Facet ではなく Collection slug を正本 とする
商品一覧の絞り込み URL は ?collection=<child-collection-slug> を唯一の入口にする
brands 配下 child collection は「ブランドで探す」に表示する
product-types 配下 child collection は「製品タイプで探す」に表示する
Storefront では旧 ?brand= / ?category= パラメータを新規導線として使わない
Brand Facet は自動分類や内部ルールに残してよいが、Storefront の browse UI 判定には使わない

受け入れ観点¶

brand Facet と各 FacetValue が定義されていること
各ブランド Collection が brand=<facet value> の filter を持つこと
ブランド配下メニューが親 filter 継承と追加 facet filter で表現できること
ブランド別検索・絞り込みが Facet ベースで実行できること
セット商品一覧が Collection として表現できること
バンドル商品の構成定義が親 ProductVariant の setComponents に保持されること