Vendure シードデータ定義ガイド（Ritsubi向け）¶

このドキュメントは、Vendure の標準 InitialData 仕様と当プロジェクトの追加ルールに沿って、シードデータを安全に定義・実行するための手順とチェックポイントをまとめたものです。Vendure の標準APIと互換性が取れないフィールド定義が原因でエラーが発生しやすいため、以下の方針を必ず守ってください。

前提¶

シードは tsx で直接実行する（トランスパイル済みバンドルは不要）。
実行例: pnpm exec nx run ritsubi-vendure-server:db:seed:local
必須初期データのみ: pnpm exec nx run ritsubi-vendure-server:db:seed:required-baseline:local
実行前に DATABASE_URL, SUPERADMIN_USERNAME/SUPERADMIN_PASSWORD が環境変数として注入されていること（推奨: dev_vendure の AWS Secrets Manager）。
スキーマ初期化込みのクリーンリセットは pnpm exec nx run ritsubi-vendure-server:db:reset:clean を使用。

InitialData の定義ルール（`apps/vendure-server/src/data/initial-data.ts`）¶

Vendure Populator が要求する標準型に合わせる。独自キーを増やさない。

defaultZone: ゾーン名と完全一致させる。現在は "Japan"。
zones: { name, memberCodes }。JP を必ず含める。
countries: { code, name, zone }。zone は zones.name と一致させる。
taxRates: { name, percentage } のみ。value や enabled など独自キーは入れない。
shippingMethods: { name, price } のみ。計算式は Populator が自動付与するため不要。
paymentMethods: { name, handler }。handler は dummyPaymentHandler など既存の ConfigurableOperation を指定。
collections: Brand / menu collection の標準定義には facet-value-filter を使う。子 collection では親 filter 継承と追加 Facet 条件を組み合わせてよい。固定 LP など自動分類不要の collection はフィルタなしで定義してよい。コードは ASCII、表示名は日本語可。

Product CSV の定義（`apps/vendure-server/src/data/products.csv`）¶

Vendure CLI が期待するヘッダーに厳密に合わせる。必須列と推奨列のみを使い、camelCase を守る。

ローカルで Git 管理しない商品投入ファイルを使う場合は、 tmp/import-data/products.csv を使用する。ルート配下の tmp/ は .gitignore 対象のため、実データをコミットしないまま保持できる。今後の顧客データや他のインポート元ファイルも、同じ tmp/import-data/ 配下にまとめて配置する。

db:seed:local / db:seed の products CSV 解決順は次の通り。

環境変数 PRODUCTS_CSV_PATH
tmp/import-data/products.csv
apps/vendure-server/src/data/products.csv

必須/利用中のヘッダー（順不同可だが記載漏れ禁止）: name,slug,description,assets,facets,optionGroups,optionValues,sku,price,taxCategory,variantAssets,variantFacets,stockOnHand,trackInventory,collections,volumeDiscountTiers

注意点:

facets には storefront のブランド絞り込みで使う brand:* を必ず含める（例: brand:exuviance）。
同一 slug の複数行は許可する。これは 1 Product + 複数 Variant を表す正規形であり、同じ slug を持つ行では name / description / assets / facets / taxCategory / collections などの Product 共通列を揃える。
複数行の slug を使う場合は optionGroups と optionValues を必須にし、| 区切りで対応付ける（例: optionGroups=濃度|容量, optionValues=10%|30mL）。
逆に、同一 slug が1行だけの単一 variant 商品では optionGroups / optionValues は不要。複数 variant を表現したいときだけ付与する。
option group の実例は 容量 / 入数 / セット内容 / テクスチャ など、SKU 差分をそのまま表現できる業務語を優先する。
taxCategory は initial-data.ts の taxCategories 名称と一致させる（例: 標準税率10%）。
価格は整数（税込/税抜の扱いはチャネル設定に依存）。現在は pricesIncludeTax = false。
文字列は UTF-8、日本語可。コード系は camelCase/kebab-case を徹底。

識別子・コードの命名規約¶

code 系は camelCase を原則（Vendure 内部で normalize される場合もあるが、事前に自分で決める）。
旧フィールド名の後方互換は残さない。customerCode / shipToCode に統一済み。
PaymentMethod の code 重複は禁止。シード後に enforceUniquePaymentMethodCodes で自動整理されるが、定義段階で必ずユニークにする。

実行フローとチェックポイント¶

pnpm --filter @ritsubi/plugins run build（クリーンリセット時に自動実行される）
pnpm exec tsx scripts/synchronize-schema-once.ts
pnpm exec nx run ritsubi-vendure-server:db:seed:local
products.csv と initial-data.ts の定義に基づいて brand / series / product-type facet と collection が投入され、 seedPolicySets(app) と seedCommercialRules(app) が呼ばれ、表示制御ルール / Pricing Rule が同時に投入される
Vendure Dashboard の local E2E が参照する編集・詳細ページ用 baseline も通常 seed の責務として投入する。商品、顧客、注文、ポリシー系の detail/edit route は、テスト側で存在しない ID を作らず、seed 済みの代表データを解決して使う。
SuperAdmin の login 情報は user.identifier だけでなく native auth (authentication_method.identifier / passwordHash) まで同期する。local の既定値は ec-admin / devPassword!123
ドライ整合性チェック (DB書き込みなし)
pnpm exec nx run ritsubi-vendure-server:seed:validate -- --products ./tmp/import-data/products.csv
--json でJSON出力
defaultZone/zones/countries/taxCategories/CSVヘッダー/数値/重複の検査に加え、Vendure公式 ImportParser で必須列・翻訳列・カスタムフィールドも検証する。失敗時は exit code 1。
PRODUCTS_CSV_PATH=... を指定した場合、seed:validate も同じパスを既定値として使う。
シード完了後に管理画面で以下を確認
チャネルの言語/通貨: JA / JPY
TaxRate: 10% / 8% / 0% が作成済み
ShippingMethod: japan-post / yamato が作成済み
ShippingMode: 標準配送 / ユーザー直送 が作成済み
PaymentMethod: 重複なし (bank-transfer, credit-card, cash-on-delivery(-card) など)
PaymentMethodCollectionAssignment: collectionMethod = 1..4 に対する許可決済方法が作成済み
just dev-vendure / just local-vendure で ec-admin / devPassword!123 による Admin API login が成功すること
テスト顧客に collectionMethod = 1..4 と Address の shipToCode / deliveryPointCode が投入されていること
テスト顧客全員に shippingCompanyCode が設定されていること（未設定だと checkout で詰まる）
Consent Template / Consent Required Product が有効化済み consent ID を一通り表現していること
商品CSVが全件取り込まれていること

必須初期データだけを再投入したい場合¶

production / staging で 破壊的 reset を避けつつ、動作に必要な基礎データだけを再投入・同期する場合は、required baseline seed を使う。

# local
just vendure-db-seed-required-baseline

# staging only
just seed-required-baseline-fly staging

[!NOTE] Fly 上でこのコマンドを使うには、対象環境の Vendure image に dist/scripts/seed-required-baseline.js を含む deploy が反映済みである必要がある。

production 向けの手動 required baseline seed 導線は廃止した。

このコマンドが扱う範囲:

Japan zone / JP country
Tax Categories / Tax Rates
Payment Methods
Shipping Methods
デフォルトチャネルの JA / JPY / default zone 設定

このコマンドが扱わない範囲:

products.csv の商品投入
test customers
past orders
consent / policy / commercial rules / wishlist などの追加 seed
initial collection の補完

そのため、運用中の環境で「payment / shipping / tax / zone / channel defaults が欠けたので安全に補いたい」ときの標準導線として使う。

initial collections を補完したい場合¶

Vendure 側で campaigns / brands / product-types など initial-data.ts 定義の Collection が欠けている場合は、専用 seed を使う。

# local
just vendure-db-seed-initial-collections

# staging only
pnpm exec nx run ritsubi-vendure-server:seed:initial-collections:staging

このコマンドが扱う範囲:

initial-data.ts に定義済みの Collection の不足分作成

このコマンドが扱わない範囲:

既存 Collection の更新・移動
child collection への商品割当
campaign ルール本体の作成/更新

ブランド配下 browse grouping を同期したい場合¶

Storefront の /products?collection=exuviance で brands / exuviance / {group} の第3階層ごとに商品を束ねて確認したい場合は、ブランド配下 browse collection と既存商品の紐づけを同期する。

# local
just vendure-db-sync-brand-browse-collections

# staging only
SECRETS_CONFIG=staging_vendure ./scripts/ops/with-env.sh -- \
  bash scripts/ops/sync-vendure-brand-browse-collections-via-fly-proxy.sh staging

このコマンドは以下を idempotent に行う。

exuviance 配下に exuviance-professional / exuviance-promotion / exuviance-homecare を用意する
mesoceutical 配下に mcinstore / mcpro / promotional を用意する
既存商品を collection に紐づける
Storefront の collection filter が即時反映されるよう search index を再構築する

Storefront 側の表示順は Vendure Collection の position が正本になる。Dashboard 上でブランド直下の子 Collection の並びを変更した場合は、 /products?collection=<brand-slug> のメインカラムのグループ順と左サイドバーのアコーディオン順も同じ順序になる。

この同期は表示確認用の browse collection と membership を揃えるためのものであり、商品カタログのページネーション復活や件数表示は行わない。件数が多いグループは Storefront 側の もっと見る で追加表示する。

設定データのみを非破壊で同期したい場合¶

商用環境や開発環境で、既存の商品データや注文データを保持したまま、システム必須の設定（配送・支払い方法、税設定、ゾーン等）のみを同期・復旧したい場合は次を実行します。

# 必須ベースライン設定のみを非破壊同期
just vendure-db-seed-required-baseline

このスクリプトは内部で scripts/seed-required-baseline.ts を呼び出し、Vendure の Populator とは独立して、TypeORM レベルでデータの存在確認（upsert 相当）を行いながら設定を反映します。

ポリシーのみ再投入したい場合¶

seed-data.ts 全体を回さず、ポリシーだけを再作成/更新する場合は次を使う。

just vendure-seed-policy-sets

キャンペーン起点の表示制御 preview に必要な campaign 本体と policy をまとめて再投入する場合は、順序付き recipe を使う。

just vendure-seed-campaign-visibility-preview

この recipe は次を順に実行する。

just vendure-seed-commercial-rules
just vendure-seed-policy-sets

visibility-preview-campaign（表示名: 表示制御プレビュー用キャンペーン）を commercial_rule_entity.kind = campaign として作成し、その ID を target にした キャンペーン：表示制御プレビュー の商品対象条件と visibility rule を作る。campaign は enabled = false かつ tier なしで、実購入時の販促・価格変更には使わない。

同じ commercial rule seed では、運用診断の再現用に diagnostics-invisible-campaign（表示名: 診断用誰にも表示されないキャンペーン）も作成する。この campaign は通常 enabled = false とし、staging の健康診断を赤くしない。 /diagnostics の invisible-campaigns check を手動再現したい場合だけ一時的に有効化し、visibility allow rule を作らない campaign として検出させる。

有効な seed campaign（spring-2026 / group-a-tiered-gifts / verif-type1-* / verif-type3-* / verif-type5-*）は、policy seed の キャンペーン：表示制御プレビュー 商品対象条件に含める。commercial rule seed だけを再投入して campaign を増やした場合は、続けて policy seed も再投入し、「誰にも表示されないキャンペーン」が健康診断に残らない状態へ揃える。

required baseline seed は policy / commercial rules / consent を扱いません。
storefront の visibility / payment 判定や dashboard preview がまとめて崩れた場合は、required baseline だけでなく policy seed / commercial rule seed の再投入も検討してください。production 向けの手動 policy seed 導線は廃止しました。

collectionMethod 要件は PaymentMethodCollectionAssignment (PMCA) を正本に管理する。policy seed には含まれない。初期データは apps/vendure-server/src/data/initial-data.ts の paymentMethodCollectionAssignments と required baseline seed で投入され、運用上は Dashboard /payment-methods/collection-mapping で編集する。旧 DB の移行だけは migration apps/vendure-server/src/migrations/1779800400000_migrate_payment_policies_to_collection_assignments.ts が担う。旧 policyType = payment / allow_payment_methods / deny_payment_methods / [決済ポリシー：回収方法]:N CustomerGroup は廃止済み。

現在の access policy seed は visibility のみを生成する。conditions + actions ベースで、conditions.targets に paymentMethodCodes は置かない。

補足: global は対象者条件の実データとして作成せず、Policy の subjectScope = global で管理する。

よくある落とし穴と回避策¶

defaultZone が一致せず Populator が失敗: defaultZone と zones[].name を同一にし、JP を memberCodes に含める。
TaxRate で NULL value エラー: percentage キー以外を入れない。value/enabled は不要。
ShippingMethod で toString エラー: price 数値のみを定義する。独自キーを入れない。
旧フィールド依存のプラグイン: customerNumber など廃止済みフィールドを参照しないようプラグイン/ドキュメントを更新する。

データ整合性チェック（dry-run）¶

破壊的な db:reset:clean を共有DBへ誤実行しないため、dry-run は 使い捨てDB で行う。

実行コマンド:
pnpm exec nx run ritsubi-vendure-server:db:reset:dry-run
db:reset:dry-run はデフォルトで localhost/127.0.0.1 以外の DATABASE_URL を拒否する。
例外的に許可する場合のみ ALLOW_DB_RESET_DRY_RUN_REMOTE=1 を明示する。
CI では migrations/seed/entity 変更時に以下を実行する。
node scripts/ci/vendure-data-guards.mjs --changed-only
pnpm exec nx run ritsubi-vendure-server:db:reset:dry-run

ローカル hook 運用（lefthook）¶

pre-commit:
scripts/hooks/pre-commit-vendure-data-guards.sh
staged の migration/seed/entity 変更時のみ node scripts/ci/vendure-data-guards.mjs --staged を実行
pre-push:
scripts/hooks/pre-push-vendure-db-dry-run.sh
push差分に migration/seed/entity 変更がある場合のみ db:reset:dry-run を実行
DATABASE_URL 未設定時は dry-run 本体がローカルの使い捨て PostgreSQL (localhost:5433 / vendure_dev) を使う

ローカル環境の都合で一時的にスキップする場合:

SKIP_VENDURE_DB_DRY_RUN=1 で pre-push の dry-run をスキップ
LEFTHOOK_FAST=1 で lefthook の重いジョブ（vendure-db-dry-run / vendure-image-trivy）をまとめてスキップ

参照¶

Vendure Docs: InitialData / populate / Populator の仕様
プロジェクト固有設定: apps/vendure-server/src/seed-data.ts, apps/vendure-server/src/data/initial-data.ts