spree-project

Spree Commerce プロジェクト

Spree Commerce を利用した Rails アプリケーションです。

プロジェクトの種類 — まず最初に判定してください。実行するコマンドが変わります

Spree アプリがすべて create-spree-app プロジェクトとは限りません。コマンドを実行する前に、次のシグナルを順に確認してください。

シグナル	種類	コマンドの実行方法
backend/Gemfile に spree の記載があり、ルートに docker-compose.yml がある	create-spree-app プロジェクト（5.4 以降）	spree <cmd> — @spree/cli が Docker の web コンテナ内でコマンドを実行します
ルートに Rails アプリ（config/application.rb、spree を含む Gemfile）があり、Spree のイメージまたはビルドを指定した docker-compose.yml がある	spree-starter 形式の Docker アプリ	CLI が解決される場合は spree <cmd>（npx spree --version で確認）。そうでない場合は docker compose exec web <cmd>
ルートに spree gem を含む Rails アプリがあり、Docker の設定がない	従来型 Rails アプリ（通常は 5.4 より前）	アプリのルートからネイティブに実行します：bin/rails …、bundle exec rake …

コマンドの対応関係 — Spree CLI 形式 → 従来型アプリでのネイティブ形式：

タスク	Spree CLI（Docker）	従来型 Rails アプリ
開発環境を起動	spree dev	bin/dev（または bin/rails server）
Rails コンソール	spree console	bin/rails console
マイグレーションをインストールして実行	spree migrate	bin/rake spree:install:migrations && bin/rails db:migrate
バージョンをアップグレード	spree upgrade	bundle update <spree gems>、マイグレーションを実行し、その後 bin/rake spree:upgrade
ジェネレーターを実行	spree generate api_resource …	bin/rails g spree:api_resource …（自動でプレフィックスを付けるのは CLI の機能なので、spree: を自分で指定してください）
任意の rake タスク	spree rake <task>	bundle exec rake <task>
シードデータ／サンプルデータ	spree seed / spree sample-data	bin/rails db:seed / bin/rails spree:load_sample_data
任意のコマンド	spree exec <cmd>	<cmd> をそのまま実行

その他の種類による違い：

• Rails のルート：create-spree-app プロジェクトでは backend/、従来型アプリでは . です。このスキルで backend/app/… と記載されているパスは、従来型アプリでは app/… です。
• ローカルドキュメント（node_modules/@spree/docs/dist/）は、プロジェクトに @spree/docs がインストールされている場合にのみ存在します。従来型アプリでは、代わりに https://spreecommerce.org/docs/llms.txt を使用してください。
• rake タスク（spree:install:migrations、spree:upgrade、spree:model／spree:api_resource ジェネレーター）は spree gem に含まれており、どちらの種類でも同じように動作します。異なるのは実行時のラッパーだけです。spree:upgrade とジェネレーターは spree_core 5.5 以降に含まれます。5.5 より前のアプリでは、アップグレード時の bundle update の後に利用可能になるため、古いアプリではまず gem を更新してください。

create-spree-app プロジェクトのディレクトリ構成

ディレクトリ	説明
backend/	Rails アプリ — Spree をエンジンとしてマウント
apps/storefront/	オプションの Next.js ストアフロント
node_modules/@spree/docs/dist/	Spree 開発者向けドキュメントのローカルコピー

Spree 固有のコード（モデル、デコレーター、サブスクライバー）はすべて backend/app/ の下にあります。

Spree のドキュメントを確認する場所

モデルの動作、利用可能なイベント、カートのパイプラインなど、Spree 固有の情報が必要なときは、まずローカルドキュメントを確認してください。

node_modules/@spree/docs/dist/
├── developer/
│   ├── core-concepts/       Products, orders, payments, inventory
│   ├── customization/       Decorators, extensions, dependencies, events
│   ├── admin/               Admin panel customization
│   ├── storefront/          Storefront building guides
│   ├── sdk/                 TypeScript SDK documentation
│   └── tutorial/            Step-by-step guides
├── api-reference/
│   ├── store-api/           Store API v3 guides
│   └── store.yaml           OpenAPI spec — every Store API endpoint
└── integrations/            Stripe, Meilisearch, etc.

トレーニングデータから推測する前に、こちらを確認してください。ローカルドキュメントは、インストールされている Spree のバージョンに関する信頼できる情報源です。

カスタマイズのパターン

Spree プロジェクトの作業の 90％はカスタマイズです。外部サービスとの連携、カスタムモデルの追加、動作の調整などを行います。Spree では、設定、構成、イベント、依存性注入、管理画面の拡張 API、リソースジェネレーター、デコレーター、gem など、カスタマイズ向けの拡張ポイントが階層的に用意されています。それぞれアップグレード時の安全性が異なるため、適切なものを選ぶことが重要です。

個々のカスタマイズに適したパターンを選ぶには、spree-customization スキルを使ってください。 サブスクライバー、デコレーター、Spree.dependencies、管理画面の API、Spree.ransack の比較表と実例がすべて記載されています。適切な方法が明確でない場合は、いつでも参照してください。

優先順位の概要は次のとおりです。

1. 設定 / Spree::Config — 実行時の動作を切り替える場合に使います。
2. イベント + サブスクライバー — 副作用（「注文の完了時に ERP と同期する」など）に使います。
3. 依存性注入（Spree.dependencies）— コアサービスの計算方法を差し替える場合に使います。spree-dependencies スキルを参照してください。
4. 管理画面の拡張 API（Spree.admin.navigation、Spree.admin.partials、Spree.admin.tables、Spree.ransack）— 管理画面の UI や検索に使います。
5. ジェネレーター（spree:api_resource、spree:model）— 新しいモデルやリソースを作成する場合に使います。
6. デコレーター（spree:model_decorator、spree:controller_decorator）— 既存の Spree クラスを構造的に変更する場合に使います。
7. 拡張機能（gem）— 複数のアプリでカスタマイズを共有する場合に限り使います。

必ず従うべき規約

• Spree:: 配下に名前空間を置く — Spree 関連の Ruby クラスはすべて、app/models/spree/、app/controllers/spree/ などに配置します。
• Spree.user_class / Spree.admin_user_class — Spree::User を直接参照しないでください。ユーザークラスは設定で変更できます。
• Spree::Current.store / .currency / .locale — リクエストごとのコンテキストで、モデル、コントローラー、サービスから利用できます。
• API のプレフィックス付き ID — v3 API のすべてのレスポンスは、Stripe 形式のプレフィックス付き ID（prod_86Rf07xd4z、or_m3Rp9wXz）を返します。整数の生 ID は決して公開しないでください。書き込み時も同様に、API はプレフィックス付き ID を受け付けます。
• Spree.base_class — ActiveRecord::Base ではなく、これを継承してください。Spree の基本設定が適用されます。

よく使うコマンド

@spree/cli（create-spree-app によってインストールされます）は、Docker ベースの開発ワークフローを扱います。

spree dev                          # run the stack in the foreground (streams logs; Ctrl+C stops web + worker, DBs stay up)
spree stop                         # tear down
spree console                      # Rails console
spree logs                         # follow web container logs
spree restart                      # restart the Rails process

spree migrate                      # install engine migrations from gems + db:migrate
spree generate <name> [args]       # any Spree generator
spree bundle add <gem>             # add a gem (persists in bundle_cache volume)
spree rake <task>                  # any rake task
spree exec <cmd>                   # universal escape hatch
spree rails <cmd>                  # any bin/rails command
spree routes                       # show Rails routes
spree seed                         # seed the database
spree sample-data                  # load sample products/categories/images
spree user create                  # create an admin user
spree api-key create               # create an API key (also: list, revoke)
spree db:reset                     # drop + recreate + migrate + seed (destructive)

spree upgrade                      # version upgrade

spree が PATH にない場合は、パッケージランナーを前置してください。例：npx spree …、pnpm exec spree …、bunx spree …。

判断に迷った場合

• どのカスタマイズパターンが適切かわからない場合は、spree-customization スキルを参照してください。選択の判断に役立ちます。
• 新しいモデルと API エンドポイントを追加する場合は、spree-resource スキルを参照してください。
• 既存の Spree モデルやコントローラーを拡張する場合は、spree-decorators スキルを参照してください。
• Spree をアップグレードする場合は、spree-upgrade スキルを参照してください。
• 特定の Spree の概念について詳しく知りたい場合は、まず node_modules/@spree/docs/dist/developer/ を読んでください。