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），且 docker-compose.yml 中有 Spree 镜像/构建配置	spree-starter 风格的 Docker 应用	如果 CLI 可用（npx spree --version），使用 spree <cmd>；否则使用 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 …（需自行写出 spree: 前缀——自动添加前缀是 CLI 的功能）
任意 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 gems 中，在两种类型中都能以相同方式工作——区别仅在于调用方式。请注意，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

如果 PATH 中没有 spree，请使用包运行器作为前缀：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/。