コンテンツにスキップ

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

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

前提

  • シードは ts-node で直接実行する（トランスパイル済みバンドルは不要）。
  • 実行例: pnpm --filter ritsubi-vendure-server run db:seed:local
  • 実行前に .env.local で DATABASE_URL, SUPERADMIN_USERNAME/SUPERADMIN_PASSWORD を設定済みであること。
  • スキーマ初期化込みのクリーンリセットは pnpm --filter ritsubi-vendure-server run 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: フィルタは facet-value-filter のみ使用。コードは ASCII、表示名は日本語可。

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

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

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

注意点: - taxCategory は initial-data.ts の taxCategories 名称と一致させる（例: 標準税率10%）。 - 価格は整数（税込/税抜の扱いはチャネル設定に依存）。現在は pricesIncludeTax = false。 - 文字列は UTF-8、日本語可。コード系は camelCase/kebab-case を徹底。

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

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

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

  1. pnpm --filter @ritsubi/plugins run build（クリーンリセット時に自動実行される）
  2. node -r ts-node/register -r tsconfig-paths/register scripts/synchronize-schema-once.ts
  3. pnpm --filter ritsubi-vendure-server run migrate:run
  4. pnpm --filter ritsubi-vendure-server run db:seed:local
  5. ドライ整合性チェック (DB書き込みなし)
    pnpm --filter ritsubi-vendure-server run seed:validate -- --products ./apps/vendure-server/src/data/products.csv
  6. --json でJSON出力
  7. defaultZone/zones/countries/taxCategories/CSVヘッダー/数値/重複の検査を行い、失敗時は exit code 1
  8. シード完了後に管理画面で以下を確認
  9. チャネルの言語/通貨: JA / JPY
  10. TaxRate: 10% / 8% / 0% が作成済み
  11. ShippingMethod: 通常配送・速達の2件が作成済み
  12. PaymentMethod: 重複なし (bank-transfer, credit-card, cash-on-delivery(-card) など)
  13. 商品CSVが全件取り込まれていること

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

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

データ整合性チェック（将来拡張）

現状は DB 書き込みを伴うシードのみ。将来的に「dry-run バリデーション」を追加する場合は以下の方針: - CSV/InitialData を JSON Schema で検証 - Vendure の InitialData 型に合わせた静的チェック（TypeScript型 + Zod） - DB に書き込まないモックサービスで populate 相当の整合性チェックを行う

参照

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