spree-project

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Spree Commerce Project (Spree 6)

Spree Commerce 项目(Spree 6)

Spree is a headless commerce engine: a Rails app (the
spree
gems) that serves the Store, Admin and Seller REST APIs, plus TypeScript apps you own (a React admin dashboard and a Next.js storefront). Customization happens around the engine — configuration, hooks, events, providers — not by forking it.
Coming from Spree 5.x? Read the
spree-upgrade-5-to-6
skill first — cart/order split, no state machines, React dashboard, API v2 and
spree_admin
removed.
Spree 是一个 headless commerce 引擎:一个 Rails 应用(
spree
gems),负责提供 Store、Admin 和 Seller REST API,此外还包括由你自行维护的 TypeScript 应用(一个 React admin dashboard 和一个 Next.js storefront)。定制发生在引擎周围——通过 configuration、hooks、events 和 providers——而不是 fork 引擎。
从 Spree 5.x 升级而来吗?先阅读
spree-upgrade-5-to-6
skill——涉及 cart/order 拆分、移除 state machines、React dashboard、API v2,以及移除
spree_admin
。

Detect the project flavor FIRST — it changes every command

首先检测项目形态——它会改变每一条命令

SignalFlavorHow commands run
server/Gemfile
(or legacy
backend/Gemfile
) +
docker-compose.yml
+
package.json
with
@spree/cli
create-spree-app project
spree <cmd>
— the CLI routes into the Docker
web
container
Rails app at the repo root (
config/application.rb
,
Gemfile
with
spree
gems), no
server/
classic Rails appNative from the app root:
bin/rails …
,
bundle exec rake …
If
spree
isn't on PATH, use
npx spree …
/
pnpm exec spree …
. The CLI accepts both
server/
and the older
backend/
directory name.
TaskSpree CLIClassic Rails app
Run the stack
spree dev
bin/dev
or
bin/rails server
Rails console
spree console
bin/rails console
Shell in the container
spree shell
(you're already in one)
Install + run migrations
spree migrate
bin/rails spree:install:migrations && bin/rails db:migrate
Generator
spree generate api_resource Brand …
(bare names auto-prefix
spree:
)
bin/rails g spree:api_resource Brand …
Run specs
spree test spec/models/…
(RAILS_ENV=test)
bundle exec rspec spec/models/…
Rake task
spree task <name>
for Spree tasks (the CLI adds
spree:
, so leave it off);
spree exec bin/rake <task>
for any other
bundle exec rake <task>
Sample data
spree sample-data
(default store; another store:
spree task load_sample_data STORE_CODE=eu
)
bin/rails spree:load_sample_data
(
STORE_ID=store_…
or
STORE_CODE=…
to target a non-default store)
Version upgrade
spree upgrade
bundle update spree…
, migrate,
bin/rails spree:upgrade
Anything else
spree exec <cmd>
<cmd>
Paths written
server/app/...
in these skills mean
app/...
in a classic app.
信号形态命令运行方式
server/Gemfile
(或旧版
backend/Gemfile
)+
docker-compose.yml
+
package.json
中包含
@spree/cli
create-spree-app 项目
spree <cmd>
——CLI 会将命令路由到 Docker 的
web
容器
仓库根目录是 Rails 应用(
config/application.rb
、包含
spree
gems 的
Gemfile
),且没有
server/
经典 Rails 应用在应用根目录直接执行:
bin/rails …
、
bundle exec rake …
如果
spree
不在 PATH 中,请使用
npx spree …
/
pnpm exec spree …
。CLI 同时支持
server/
和较旧的
backend/
目录名。
任务Spree CLI经典 Rails 应用
启动技术栈
spree dev
bin/dev
或
bin/rails server
Rails console
spree console
bin/rails console
进入容器 shell
spree shell
(你已经在容器内)
安装并运行 migrations
spree migrate
bin/rails spree:install:migrations && bin/rails db:migrate
Generator
spree generate api_resource Brand …
(裸名称会自动添加
spree:
前缀)
bin/rails g spree:api_resource Brand …
运行 specs
spree test spec/models/…
(RAILS_ENV=test)
bundle exec rspec spec/models/…
Rake taskSpree tasks 使用
spree task <name>
(CLI 会添加
spree:
,因此不要重复填写);其他任务使用
spree exec bin/rake <task>
bundle exec rake <task>
示例数据
spree sample-data
(默认 store;其他 store:
spree task load_sample_data STORE_CODE=eu
)
bin/rails spree:load_sample_data
(可通过
STORE_ID=store_…
或
STORE_CODE=…
指定非默认 store)
版本升级
spree upgrade
bundle update spree…
、执行 migrate,再运行
bin/rails spree:upgrade
其他操作
spree exec <cmd>
<cmd>
这些 skills 中写作
server/app/...
的路径,在经典应用中表示
app/...
。

Project layout (create-spree-app)

项目结构(create-spree-app)

text
my-store/
├── server/                 # The Spree API — a full Rails 8.1 app (spree-starter). Your Ruby code lives here.
│   ├── app/{models,services,workflows,subscribers,controllers,serializers}/
│   ├── config/initializers/spree.rb   # hooks, registries, dependencies, subscribers
│   ├── Dockerfile          # builds the production image (API + dashboard)
│   └── Gemfile
├── apps/
│   ├── dashboard/          # React admin (@spree/dashboard) — plugins in src/plugins.ts
│   ├── seller-dashboard/   # Marketplace seller panel (optional)
│   └── storefront/         # Next.js storefront on @spree/sdk (optional)
├── docker-compose.yml      # prebuilt ghcr.io/spree/spree image + Postgres (Meilisearch optional, commented out)
├── .env                    # SECRET_KEY_BASE, ACTIVE_RECORD_ENCRYPTION_* keys, SPREE_PORT, SPREE_VERSION_TAG… (mode 0600)
├── AGENTS.md / CLAUDE.md   # generated agent instructions
└── package.json            # pins @spree/cli
  • server/
    is the only part that is Spree's.
    The apps are ordinary Vite/Next.js projects you own.
  • By default the stack runs the prebuilt image. To change Ruby code, run
    spree eject
    once — compose then builds from
    server/
    . If eject fails on a fresh stack with
    service "web" is not running
    , the dev server exited because its database didn't exist yet.
    @spree/cli
    3.1.0 has this bug. Releases after it build the dev image, start and wait for Postgres, and prepare the database in a one-off container before starting the stack (also on
    spree init
    of an ejected project), and they switch older dev compose files to a
    pg_isready -h 127.0.0.1
    health check. Bump
    @spree/cli
    in
    package.json
    and re-run.
  • Stack: Rails 8.1, Ruby ≥ 3.2; PostgreSQL, MySQL or SQLite. Background jobs run in-process via Solid Queue (Mission Control at
    /jobs
    ), Solid Cache; Sidekiq/Redis is optional. The dashboard is served at
    /dashboard
    by the
    spree_dashboard
    gem in production (one image, same origin).
  • APIs: Store
    /api/v3/store
    (publishable key
    pk_…
    ), Admin
    /api/v3/admin
    (secret key
    sk_…
    or staff JWT), Seller
    /api/v3/seller
    (seller JWT +
    X-Spree-Seller-Id
    ). See
    spree-api-v3
    .
text
my-store/
├── server/                 # The Spree API — a full Rails 8.1 app (spree-starter). Your Ruby code lives here.
│   ├── app/{models,services,workflows,subscribers,controllers,serializers}/
│   ├── config/initializers/spree.rb   # hooks, registries, dependencies, subscribers
│   ├── Dockerfile          # builds the production image (API + dashboard)
│   └── Gemfile
├── apps/
│   ├── dashboard/          # React admin (@spree/dashboard) — plugins in src/plugins.ts
│   ├── seller-dashboard/   # Marketplace seller panel (optional)
│   └── storefront/         # Next.js storefront on @spree/sdk (optional)
├── docker-compose.yml      # prebuilt ghcr.io/spree/spree image + Postgres (Meilisearch optional, commented out)
├── .env                    # SECRET_KEY_BASE, ACTIVE_RECORD_ENCRYPTION_* keys, SPREE_PORT, SPREE_VERSION_TAG… (mode 0600)
├── AGENTS.md / CLAUDE.md   # generated agent instructions
└── package.json            # pins @spree/cli
  • **
    server/
    是唯一属于 Spree 的部分。**这些 apps 是由你自行维护的普通 Vite/Next.js 项目。
  • 默认情况下,技术栈运行预构建镜像。要修改 Ruby 代码,请先运行一次
    spree eject
    ——之后 compose 将基于
    server/
    构建。如果在全新技术栈上 eject 失败并出现
    service "web" is not running"
    ,说明开发服务器已退出,因为数据库尚不存在。
    @spree/cli
    3.1.0 存在此 bug。3.1.0 之后的版本会构建开发镜像、启动并等待 Postgres,并在启动技术栈前于一次性容器中准备数据库(对已 eject 的项目执行
    spree init
    时也同样如此);它们还会将较旧的开发 compose 文件切换为使用
    pg_isready -h 127.0.0.1
    的 health check。请升级
    package.json
    中的
    @spree/cli
    并重新运行。
  • 技术栈:Rails 8.1、Ruby ≥ 3.2;PostgreSQL、MySQL 或 SQLite。后台任务通过 Solid Queue 在进程内运行(Mission Control 位于
    /jobs
    ),并使用 Solid Cache;Sidekiq/Redis 为可选。在生产环境中,dashboard 由
    spree_dashboard
    gem 在
    /dashboard
    提供(单一镜像,同源)。
  • API:Store
    /api/v3/store
    (publishable key
    pk_…
    )、Admin
    /api/v3/admin
    (secret key
    sk_…
    或 staff JWT)、Seller
    /api/v3/seller
    (seller JWT +
    X-Spree-Seller-Id
    )。参见
    spree-api-v3
    。

Conventions you should always follow

始终应遵循的约定

  • Namespace under
    Spree::
    , files under
    server/app/models/spree/…
    etc. Your own non-Spree classes can use your app namespace (
    MyApp::…
    ).
  • Inherit from
    Spree.base_class
    (defaults to
    Spree::Base
    ), not
    ApplicationRecord
    . It brings preferences, prefixed IDs, ransack allowlists, document numbers,
    additional_permitted_attributes
    .
  • Users are two classes:
    Spree.customer_class
    (default
    Spree::Customer
    , table
    spree_customers
    ,
    cust_…
    ) and
    Spree.admin_user_class
    (
    Spree::AdminUser
    ,
    adm_…
    ). Never hardcode either.
    Spree.user_class
    is a deprecated alias.
  • Scope every query through the store:
    current_store.products
    ,
    store.orders
    — never
    Spree::Order.all
    in request code. In dev/test
    SPREE_STORE_SCOPE_GUARD=log|raise|off
    flags unscoped queries.
  • Spree::Current
    carries per-request
    store
    ,
    channel
    ,
    market
    ,
    currency
    ,
    locale
    .
    Spree::Current.store
    falls back to
    Spree::Store.default
    , which can be nil (no store flagged default) — set
    Spree::Current.store = store
    explicitly in jobs, rake tasks and specs. Assigning it also arms the dev/test
    StoreScopeGuard
    for the rest of that job/script, so unscoped queries there get flagged too (wrap deliberately global lookups in
    Spree::StoreScopeGuard.skip { … }
    ). An installation-wide job (a nightly sweep over every store's records) must run each record in its own store, or its emails, events and store settings come from the default store. Use
    Spree::Current.with_store(store) { … }
    , which starts from a clean context and restores the previous one afterwards. Jobs subclassing
    Spree::BaseJob
    can call the private
    each_store_of(relation) { |store_records| … }
    , which core's own sweeps (stale drafts, expired carts, time-based collections, payouts) use.
  • No state machines, no enums for lifecycles. Statuses are string
    status
    columns declared with
    has_status
    (
    Spree::HasStatus
    ); transitions are workflows (
    app/workflows
    ). Extend with
    Model.add_status('on_hold', after: 'approved')
    — plus your own workflow to move records into it. See
    spree-workflows
    .
  • belongs_to
    is required by default
    — pass
    optional: true
    when the FK may be nil, or saves fail with "… must exist". Always pass
    class_name:
    and an explicit
    dependent:
    on
    has_many
    .
  • No DB foreign keys on business tables; add an index instead. Uniqueness validations are store-scoped in core.
  • IDs are strings at the API surface — Stripe-style prefixed IDs (
    prod_…
    ,
    cart_…
    ,
    or_…
    ,
    py_…
    ). Look up with
    Model.find_by_prefix_id!(id)
    ; never
    .to_i
    an ID and never expose integer IDs. Full table:
    spree-data-model
    .
  • Cart ≠ Order.
    Spree::Cart
    is mutable checkout state; completing it creates an immutable
    Spree::Order
    (
    status
    draft/placed/canceled). Code that runs on both reads
    line_item.owner
    , not
    .order
    .
  • Custom data: merchant-facing, typed, filterable → custom fields (
    product.set_custom_field('custom.material', 'Cotton')
    ,
    get_custom_field
    ). Machine/integration data →
    metadata
    (schemaless JSON, write-only in Store API). A new column only when your own code queries it heavily.
  • Side effects go in events / hooks, not callbacks. React after the fact with a
    Spree::Subscriber
    (
    order.placed
    , …); run inside a flow with
    Spree.hooks.register('carts.complete.validate', …)
    . Don't add
    after_save
    to Spree models.
  • Writable API attributes:
    Spree::Product.additional_permitted_attributes += [:brand_id]
    —
    +=
    , never
    <<
    (the default is frozen).
  • Services return results, not exceptions:
    result = Spree.cart_add_item_workflow.call(...)
    ; check
    result.success?
    .
  • Money in the API is a string (
    "135.60"
    ) with a
    display_…
    twin — render the display one.
  • Secrets go in Rails credentials or env vars; Spree's installation settings are all
    SPREE_*
    env vars (see
    spree-customization
    ). Active Record encryption keys (
    ACTIVE_RECORD_ENCRYPTION_*
    ) must be set in every environment —
    create-spree-app
    generates a dev set;
    spree encryption init
    adds one to older projects (see
    spree-security
    ).
  • 在
    Spree::
    下使用命名空间
    ,文件位于
    server/app/models/spree/…
    等目录。你自己的非 Spree 类可以使用应用命名空间(
    MyApp::…
    )。
  • 继承
    Spree.base_class
    (默认为
    Spree::Base
    ),而不是
    ApplicationRecord
    。它提供 preferences、带前缀的 ID、ransack allowlists、document numbers 和
    additional_permitted_attributes
    。
  • 用户分为两个类:
    Spree.customer_class
    (默认为
    Spree::Customer
    ,表
    spree_customers
    ,ID 前缀为
    cust_…
    )和
    Spree.admin_user_class
    (
    Spree::AdminUser
    ,ID 前缀为
    adm_…
    )。永远不要硬编码其中任何一个。
    Spree.user_class
    是已弃用的别名。
  • **每个查询都必须通过 store 限定作用域:**使用
    current_store.products
    、
    store.orders
    ——在 request 代码中绝不要使用
    Spree::Order.all
    。在 dev/test 中,
    SPREE_STORE_SCOPE_GUARD=log|raise|off
    会标记未限定作用域的查询。
  • Spree::Current
    承载每个请求的
    store
    、
    channel
    、
    market
    、
    currency
    和
    locale
    。
    Spree::Current.store
    会回退到
    Spree::Store.default
    ,而后者可能为 nil(没有任何 store 被标记为默认)——在 jobs、rake tasks 和 specs 中应显式设置
    Spree::Current.store = store
    。赋值后还会为该 job/script 的剩余执行过程启用 dev/test 的
    StoreScopeGuard
    ,从而标记未限定作用域的查询(有意进行的全局查找请包裹在
    Spree::StoreScopeGuard.skip { … }
    中)。覆盖所有 store 记录的安装级 job(例如每晚扫描所有 store 记录的 job)必须让每条记录在各自的 store 中运行,否则它发送的 emails、events 以及使用的 store settings 将来自默认 store。请使用
    Spree::Current.with_store(store) { … }
    ,它会从干净的上下文开始,并在结束后恢复之前的上下文。继承
    Spree::BaseJob
    的 jobs 可以调用私有的
    each_store_of(relation) { |store_records| … }
    ,core 自身的定期清理任务(过期草稿、过期购物车、基于时间的 collections、payouts)也使用此方法。
  • **不使用 state machines,生命周期也不使用 enums。**状态是使用
    has_status
    (
    Spree::HasStatus
    )声明的字符串
    status
    列;状态转换使用 workflows(
    app/workflows
    )。扩展时使用
    Model.add_status('on_hold', after: 'approved')
    ——同时还要编写自己的 workflow,将记录 transition 到该状态。参见
    spree-workflows
    。
  • 默认情况下
    belongs_to
    是必需的
    ——当外键可能为 nil 时传入
    optional: true
    ,否则保存会失败并提示"… must exist"。
    has_many
    始终要传入
    class_name:
    和明确的
    dependent:
    。
  • 业务表不使用数据库外键;请改为添加 index。core 中的 uniqueness validations 按 store 限定作用域。
  • API 层的 ID 是字符串——采用 Stripe 风格的前缀化 ID(
    prod_…
    、
    cart_…
    、
    or_…
    、
    py_…
    )。使用
    Model.find_by_prefix_id!(id)
    查找;绝不要对 ID 调用
    .to_i
    ,也绝不要暴露整数 ID。完整对照表见
    spree-data-model
    。
  • Cart ≠ Order。
    Spree::Cart
    是可变的结账状态;完成购物车后会创建不可变的
    Spree::Order
    (
    status
    为 draft/placed/canceled)。同时适用于二者的代码应读取
    line_item.owner
    ,而不是
    .order
    。
  • **自定义数据:**面向商家、类型明确且可筛选的数据 → 使用 custom fields(
    product.set_custom_field('custom.material', 'Cotton')
    、
    get_custom_field
    )。机器/集成数据 → 使用
    metadata
    (无 schema 的 JSON,在 Store API 中为只写)。只有在自有代码会频繁查询某个字段时,才应新增列。
  • **副作用应放在 events / hooks 中,而不是 callbacks 中。**对已发生的事情作出反应时,使用
    Spree::Subscriber
    (
    order.placed
    等);在流程内部执行时,使用
    Spree.hooks.register('carts.complete.validate', …)
    。不要在 Spree models 上添加
    after_save
    。
  • 可写 API attributes:
    Spree::Product.additional_permitted_attributes += [:brand_id]
    ——使用
    +=
    ,绝不要使用
    <<
    (默认值已 frozen)。
  • Services 返回结果,而不是抛出异常:
    result = Spree.cart_add_item_workflow.call(...)
    ;然后检查
    result.success?
    。
  • API 中的金额是字符串(
    "135.60"
    ),并配有一个
    display_…
    对应字段——请渲染 display 版本。
  • Secrets 应存放在 Rails credentials 或环境变量中;Spree 的所有安装设置均使用
    SPREE_*
    环境变量(参见
    spree-customization
    )。Active Record encryption 密钥(
    ACTIVE_RECORD_ENCRYPTION_*
    )必须在每个环境中设置——
    create-spree-app
    会生成一组开发环境密钥;
    spree encryption init
    为旧项目添加密钥(参见
    spree-security
    )。

Where customization goes (short version)

自定义放在哪里(简版)

Walk this list top-down — higher options are cheaper and survive upgrades better. The
spree-customization
skill has the full decision table.
  1. Store settings (dashboard → Settings; Admin API) — markets, currencies, delivery, taxes, order numbering. Data, not code.
  2. Configuration —
    SPREE_*
    env vars /
    Spree.config
    ; per-record
    preference
    s.
  3. Workflow hooks —
    Spree.hooks.register('<flow>.<hook>', 'MyApp::Handler')
    to veto or extend a core flow (
    spree-workflows
    ).
  4. Events & subscribers — react after something happened (
    spree-events-webhooks
    ).
  5. Checkout registry —
    Spree::Checkout::Registry.add_requirement
    /
    register_step
    (
    spree-checkout
    ).
  6. Providers — tax, delivery rates, fulfillment, search, pricing, inventory, payouts, digital assets, auth (
    spree-providers
    ).
  7. Ransack allowlists —
    Spree.ransack.add_attribute(Spree::Product, :erp_id)
    .
  8. Webhooks — notify external systems without Ruby.
  9. Dependencies — replace a whole workflow/service:
    Spree::Dependencies.cart_add_item_workflow = 'MyApp::Carts::AddItem'
    (
    spree-dependencies
    ).
  10. Decorators — last resort, for structural additions (associations, scopes) (
    spree-decorators
    ).
Admin UI changes happen in the React dashboard via plugins (
spree-dashboard
,
spree-dashboard-plugins
), not in Rails views.
请自上而下浏览此列表——越靠前的选项成本越低,且越容易在升级后继续使用。
spree-customization
skill 中有完整的决策表。
  1. Store 设置(dashboard → Settings;Admin API)——markets、currencies、delivery、taxes、order numbering。属于数据,而非代码。
  2. Configuration——
    SPREE_*
    环境变量 /
    Spree.config
    ;单条记录的
    preference
    s。
  3. Workflow hooks——
    Spree.hooks.register('<flow>.<hook>', 'MyApp::Handler')
    ,用于否决或扩展 core flow(
    spree-workflows
    )。
  4. Events & subscribers——对某件事已经发生作出反应(
    spree-events-webhooks
    )。
  5. Checkout registry——
    Spree::Checkout::Registry.add_requirement
    /
    register_step
    (
    spree-checkout
    )。
  6. Providers——tax、delivery rates、fulfillment、search、pricing、inventory、payouts、digital assets、auth(
    spree-providers
    )。
  7. Ransack allowlists——
    Spree.ransack.add_attribute(Spree::Product, :erp_id)
    。
  8. Webhooks——无需 Ruby 即可通知外部系统。
  9. Dependencies——替换整个 workflow/service:
    Spree::Dependencies.cart_add_item_workflow = 'MyApp::Carts::AddItem'
    (
    spree-dependencies
    )。
  10. Decorators——最后手段,用于结构性扩展(associations、scopes)(
    spree-decorators
    )。
Admin UI 的变更应通过 plugins 在 React dashboard 中完成(
spree-dashboard
、
spree-dashboard-plugins
),而不是在 Rails views 中完成。

Common CLI commands

常用 CLI 命令

bash
spree dev                      # run API (+ dashboard dev server if apps/dashboard exists); first run completes setup
spree stop | restart | logs [worker]
spree console | shell | db:console
spree migrate | migrate:status | migrate:rollback
spree generate api_resource Brand name:string   # → spree:api_resource
spree generate subscriber ErpSync order.placed   # class + registration in initializers/spree.rb
spree test [path[:line]]      # tests in RAILS_ENV=test; creates the test DB if missing (CLI 3.6+; older: spree rspec)
spree add --gem <gem>         # adds the gem, runs its installer + migrations; a prebuilt project is ejected first (asks; new dev DB)
spree eject                    # build from server/ instead of the prebuilt image
spree build [--production]     # rebuild dev image / build the production image (API + dashboard)
spree add dashboard            # add apps/dashboard (also: spree add seller-dashboard)
spree plugin new <name>        # scaffold a dashboard plugin monorepo
spree update                   # pull latest image, recreate containers (migrations run on boot)
spree upgrade [--plan]         # bundle update + migrate + spree:upgrade data steps
spree seed | sample-data | user create | api-key create|list|revoke
spree encryption init [--print]  # add ACTIVE_RECORD_ENCRYPTION_* keys to .env (never overwrites); --print for production
spree exec bin/rails spree:setup:token  # reprint the first-run admin setup link
spree api <verb> <path>        # call the Admin API from the terminal (see spree-cli)
spree db:reset
is destructive — confirm with the user before running it.
bash
spree dev                      # run API (+ dashboard dev server if apps/dashboard exists); first run completes setup
spree stop | restart | logs [worker]
spree console | shell | db:console
spree migrate | migrate:status | migrate:rollback
spree generate api_resource Brand name:string   # → spree:api_resource
spree generate subscriber ErpSync order.placed   # class + registration in initializers/spree.rb
spree test [path[:line]]      # tests in RAILS_ENV=test; creates the test DB if missing (CLI 3.6+; older: spree rspec)
spree add --gem <gem>         # adds the gem, runs its installer + migrations; a prebuilt project is ejected first (asks; new dev DB)
spree eject                    # build from server/ instead of the prebuilt image
spree build [--production]     # rebuild dev image / build the production image (API + dashboard)
spree add dashboard            # add apps/dashboard (also: spree add seller-dashboard)
spree plugin new <name>        # scaffold a dashboard plugin monorepo
spree update                   # pull latest image, recreate containers (migrations run on boot)
spree upgrade [--plan]         # bundle update + migrate + spree:upgrade data steps
spree seed | sample-data | user create | api-key create|list|revoke
spree encryption init [--print]  # add ACTIVE_RECORD_ENCRYPTION_* keys to .env (never overwrites); --print for production
spree exec bin/rails spree:setup:token  # reprint the first-run admin setup link
spree api <verb> <path>        # call the Admin API from the terminal (see spree-cli)
spree db:reset
是破坏性操作——执行前请先向用户确认。

Where to find Spree documentation

在哪里查找 Spree 文档

Read the installed docs before guessing from training data — they match the installed version:
text
node_modules/@spree/docs/dist/
├── developer/
│   ├── getting-started/  create-spree-app/  cli/
│   ├── core-concepts/    # products, carts, orders, payments, fulfillments, markets, …
│   ├── customization/    # quickstart, configuration, workflows, dependencies, decorators, permissions, validations
│   ├── providers/        # ERP, PIM, DAM, fulfillment, payouts, SSO, observability
│   ├── how-to/           # custom payment method, delivery rate provider, search provider, B2B, marketplace…
│   ├── dashboard/        # React admin: customization, plugins, recipes
│   ├── sdk/  storefront/  multi-tenant/  security/  deployment/  upgrades/  tutorial/
└── api-reference/        # Store/Admin API guides + OpenAPI specs
  • No local package (classic app)? Use https://spreecommerce.org/docs/llms.txt (index) or append
    .md
    to any docs URL.
  • The Spree docs MCP server (
    https://spreecommerce.org/docs/mcp
    ) searches the latest published docs:
    claude mcp add --transport http spree-docs https://spreecommerce.org/docs/mcp
    .
  • Never use
    docs/v5/
    pages for a Spree 6 project.
在猜测之前,先阅读已安装的文档——它们与已安装的版本一致:
text
node_modules/@spree/docs/dist/
├── developer/
│   ├── getting-started/  create-spree-app/  cli/
│   ├── core-concepts/    # products, carts, orders, payments, fulfillments, markets, …
│   ├── customization/    # quickstart, configuration, workflows, dependencies, decorators, permissions, validations
│   ├── providers/        # ERP, PIM, DAM, fulfillment, payouts, SSO, observability
│   ├── how-to/           # custom payment method, delivery rate provider, search provider, B2B, marketplace…
│   ├── dashboard/        # React admin: customization, plugins, recipes
│   ├── sdk/  storefront/  multi-tenant/  security/  deployment/  upgrades/  tutorial/
└── api-reference/        # Store/Admin API guides + OpenAPI specs

When in doubt

不确定时

  • Which extension pattern? →
    spree-customization
  • How models relate, which ID prefix, which status values? →
    spree-data-model
  • New model + API endpoint? →
    spree-resource
  • Hooks / writing a workflow? →
    spree-workflows
  • Tests? →
    spree-testing
    . Upgrading? →
    spree-upgrade
    /
    spree-upgrade-5-to-6
    .
  • 不确定该使用哪种扩展模式?→
    spree-customization
  • 模型如何关联、使用哪种 ID 前缀或状态值?→
    spree-data-model
  • 新建 model + API endpoint?→
    spree-resource
  • Hooks / 编写 workflow?→
    spree-workflows
  • 测试?→
    spree-testing
    。升级?→
    spree-upgrade
    /
    spree-upgrade-5-to-6
    。