Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

Documentation update

Damian Legawiec873b77a56261
diff --git a/CLAUDE.md b/CLAUDE.md
index 2fde30587e..6a4b1a531c 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -22,7 +22,6 @@ Active plans (6.0 target, work pending):
- `6.0-normalize-state-to-status.md` — Rename state → status on Payment, Shipment, InventoryUnit, ReturnAuthorization, GiftCard
- `6.0-fulfillment-and-delivery.md` — Shipment→Fulfillment, ShippingMethod→DeliveryMethod, drop ShippingCategory, FulfillmentProvider strategy, pickup (merchant StockLocation) + pickup_point (third-party PickupPointProvider)
- `6.0-returns-exchanges-claims.md` — First-class Return, Exchange, Claim models replacing ReturnAuthorization/Reimbursement chain
-- `6.0-channels-catalogs-b2b.md` — Channel, Catalog, ProductListing (replaces StoreProduct), Company/CompanyLocation/CompanyContact for B2B (Channel shipped in 5.5)
- `6.0-platform-auth.md` — Drop Devise, own auth stack, User→Customer/Staff rename (RefreshToken shipped in 5.4)
- `6.0-tax-provider.md` — Per-Market TaxProvider, replaces TaxRate.adjust + Calculator, drop Zone model (TaxRate gets direct country/state FKs)
- `6.0-delivery-rate-provider.md` — Per-DeliveryMethod DeliveryRateProvider, replaces Estimator + Calculator, DeliveryZone with postal code support
@@ -37,7 +36,8 @@ Multi-version plans (some phases shipped, some pending):
- `5.4-6.0-product-media-system.md` — Product-level media gallery. 5.5 data model (spree_variant_media, media_type, focal_point, external_video_url) shipped; admin UIs in progress; 6.0 cleanup pending.
- `5.5-6.0-order-cancellation-and-approval.md` — First-class `OrderCancellation` + `OrderApproval` models. 5.5 models + migrations shipped; 6.0 drops denormalized columns.
- `5.5-6.0-display-on-to-boolean.md` — Collapse `display_on` tri-state to a single `storefront_visible` boolean. 5.5 bridge (`storefront_visible` accessor + Ransacker on `Spree::DisplayOn`) shipped; 6.0 schema rename pending.
-- `6.0-order-routing.md` — Two-tier extension: pluggable `Spree::OrderRouting::Strategy::Base` + STI subclasses of `Spree::OrderRoutingRule`. Phase 1 (5.5) shipped: `Channel`, `OrderRoutingRule`, strategy base + Rules + Reducer + Legacy, `preferred_stock_location_id` + `channel_id` on Order. Phase 2+ (6.0) layers ProductListing/Catalog/Company on top via `6.0-channels-catalogs-b2b.md`.
+- `6.0-order-routing.md` — Two-tier extension: pluggable `Spree::OrderRouting::Strategy::Base` + STI subclasses of `Spree::OrderRoutingRule`. Phase 1 (5.5) shipped: `Channel`, `OrderRoutingRule`, strategy base + Rules + Reducer + Legacy, `preferred_stock_location_id` + `channel_id` on Order. Phase 2+ (6.0) layers Catalog/Company on top via `6.0-channels-catalogs-b2b.md`.
+- `6.0-channels-catalogs-b2b.md` — Channel + ProductPublication (replaces StoreProduct) + single-owner Product (`belongs_to :store`) + Publishing card (legacy admin + SPA) + `Channel#default` boolean shipped in 5.5. Catalog, Company/CompanyLocation/CompanyContact for B2B pending in 6.0. Multi-store catalogs (historic `Product has_many :stores`) move to the `spree_multi_store` extension.
Pending design work (drafts, no implementation yet):
- `5.4-centralized-translations-admin.md` — Centralized Translations admin page under Products, overview grid + bulk CSV import/export
@@ -108,16 +108,17 @@ Per-request context available in models, controllers, jobs, and services:
### Models
-- Inherit from `Spree.base_class`
-- Always pass `class_name` and `dependent` on associations; use `dependent: :destroy_async` for high-fanout associations to offload deletion to a background job
+- ALWAYS Inherit from `Spree.base_class`
+- ALWAYS pass `class_name` and `dependent` on associations; use `dependent: :destroy_async` for high-fanout associations to offload deletion to a background job
- Include `Spree::Metafields` for custom fields support (see docs/plans/5.4-6.0-custom-fields-rename.md)
- Include `Spree::Metadata` for JSON metadata support
-- Use string columns instead of enums
+- ALWAYS Use string columns instead of enums
- State machines: use `state_machines-activerecord` gem, default column `status` (legacy uses `state`, see docs/plans/6.0-normalize-state-to-status.md)
-- Never cast IDs to integer — always treat as strings (UUID support)
-- Uniqueness validations: always use `scope: spree_base_uniqueness_scope`, should be also enforced by database index
+- NEVER cast IDs to integer — always treat as strings (UUID support)
+- Uniqueness validations: ALWAYS use `scope: spree_base_uniqueness_scope`, should be also enforced by database index
- If needed use paranoia gem for soft delete support (via `acts_as_paranoid`)
- For configuration / options always use [Model Preferences](docs/developer/customization/model-preferences.mdx)
+- NEVER hardcode table names, always use `Model.table_name` in models, queries, scopes, etc.
```ruby
class Spree::Product < Spree.base_class
diff --git a/docs/developer/core-concepts/channels.mdx b/docs/developer/core-concepts/channels.mdx
new file mode 100644
index 0000000000..37406c67b0
--- /dev/null
+++ b/docs/developer/core-concepts/channels.mdx
@@ -0,0 +1,112 @@
+---
+title: Sales Channels
+description: Per-store distribution surfaces — online storefront, POS, marketplace, wholesale — each with its own product catalog and order attribution.
+---
+
+import { Since } from '/snippets/since.mdx';
+
+<Since version="5.5" />
+
+## Overview
+
+Sales channels segment a single [Store](/developer/core-concepts/stores) into distinct selling surfaces. A channel represents *where* an order originates from — the online storefront, an in-person point-of-sale till, a marketplace integration (Amazon, eBay), a B2B wholesale portal, a mobile app — and *which* subset of the store's products is available there.
+
+Every store ships with one default channel named *Online Store*. You can add more from **Settings → Sales channels** in the admin dashboard.
+
+## Channel Attributes
+
+| Attribute | Description | Example |
+|-----------|-------------|---------|
+| `name` | Human-readable name, displayed in the admin and reports | `Point of Sale` |
+| `code` | URL-safe slug, stable identifier sent via the `X-Spree-Channel` header | `pos` |
+| `active` | When `false`, the channel stops accepting orders | `true` |
+| `default` | Exactly one channel per store is the default. Used as a fallback when no channel header is present and as the auto-publish target for new products | `true` |
+| `preferred_order_routing_strategy` | Optional per-channel override of the store's [Order Routing](/developer/core-concepts/shipments#order-routing) strategy | `Rules` |
+
+`code` is normalized to a URL-safe slug on save — `POS` becomes `pos`, `Point of Sale!` becomes `point-of-sale`. Leaving `code` blank derives it from `name`.
+
+## How Channels Work
+
+### Resolution at request time
+
+Every incoming Store API or storefront request resolves to a channel:
+
+1. If the `X-Spree-Channel` header is present and matches a channel `code` on the current store, that channel is used.
+2. Otherwise, the store's default channel is used.
+
+The resolved channel is then available to controllers, models, and serializers throughout the request.
+
+### Product visibility
+
+A product is visible on a channel only when it has a publication record joining the two. Each publication carries an optional window:
+
+| Publication state | What customers see |
+|---|---|
+| No publication exists | Product is not on this channel — invisible |
+| Publication has no dates set | Live now and indefinitely |
+| `published_at` is in the future | Scheduled — not yet visible |
+| `unpublished_at` is in the past | Hidden — was visible, now sunset |
+| Within the window | Live |
+
+Product status (`draft` / `active` / `archived`) is the **outer gate**: a Draft or Archived product is hidden on every channel regardless of its publication window. The dashboard's Publishing card renders this as a "Not available" badge on every channel row when status isn't `active`.
+
+### Order attribution
+
+Every order is attributed to one channel. The channel is set from the `X-Spree-Channel` header on cart creation, from the merchant's selection on the "New order" form, or defaults to the store's primary channel.
+
+This attribution drives reporting (best-selling by channel, revenue per channel) and per-channel order routing — see [Order Routing](/developer/core-concepts/shipments#order-routing).
+
+## Publishing Products on Channels
+
+### Dashboard
+
+The product edit page has a **Publishing** card with one row per channel the product is on. Click *Manage* to attach or detach channels via checkboxes. Each row expands into a per-channel schedule editor.
+
+Bulk operations from the product list: *Add to sales channels…* and *Remove from sales channels…*.
+
+### Admin API
+
+Three endpoints cover the publishing surface:
+
+| Endpoint | Use case |
+|---|---|
+| `POST /api/v3/admin/channels/:id/add_products` | Publish one or more products on a specific channel |
+| `POST /api/v3/admin/channels/:id/remove_products` | Unpublish products from a specific channel |
+| `POST /api/v3/admin/products/bulk_add_to_channels` | Publish many products across many channels in a single request |
+
+```typescript SDK
+await client.channels.addProducts('ch_xxx', {
+ product_ids: ['prod_aaa', 'prod_bbb'],
+ // Optional window — when omitted, existing schedules are preserved
+ published_at: '2026-07-01T00:00:00Z',
+ unpublished_at: '2026-12-31T23:59:59Z',
+})
+```
+
+`channels.addProducts` is idempotent: re-publishing an already-published product is a no-op for its window unless `published_at` / `unpublished_at` are explicitly passed. Cross-store onboarding is allowed when the caller's key has update permission on the product.
+
+For per-product updates, use `PATCH /api/v3/admin/products/:id` with a `product_publications` array:
+
+```typescript SDK
+await client.products.update('prod_xxx', {
+ product_publications: [
+ { channel_id: 'ch_online' },
+ { channel_id: 'ch_pos', published_at: '2026-07-01T00:00:00Z' },
+ ],
+})
+```
+
+The write contract is **full-set**: the array represents the complete desired state. Channels absent from the payload are detached.
+
+## Auto-Publish Behavior
+
+- **Dashboard** — new products are auto-published on the store's default channel, matching Shopify's "Online Store" behavior. The merchant can untick channels via the Publishing card post-create.
+- **Admin API** — new products are **not** auto-published. The caller supplies `product_publications: [{ channel_id }]` on create, or calls `POST /admin/channels/:id/add_products` afterwards.
+- **Sample data** (`bin/rake spree:load_sample_data`) — all loaded products are explicitly published on the default channel.
+
+## Related Documentation
+
+- [Stores](/developer/core-concepts/stores) — Channels belong to a store
+- [Markets](/developer/core-concepts/markets) — Different from channels: markets segment geography/currency, channels segment selling surfaces
+- [Products](/developer/core-concepts/products) — Product catalog and publication
+- [Order Routing](/developer/core-concepts/shipments#order-routing) — Channels can override the store's routing strategy
diff --git a/docs/developer/core-concepts/stores.mdx b/docs/developer/core-concepts/stores.mdx
index 533f195cbd..fe9f69b778 100644
--- a/docs/developer/core-concepts/stores.mdx
+++ b/docs/developer/core-concepts/stores.mdx
@@ -1,46 +1,11 @@
---
title: Stores
-description: The central model in Spree — every resource is scoped to a store
+description: The top-level tenant in Spree — every resource belongs to a store
---
## Overview
-The Store is the central model in Spree. Every resource — products, orders, markets, payment methods, taxonomies — is scoped to a store. Most setups use a single store, but Spree supports [multi-store](/developer/multi-store/quickstart) configurations where each store operates independently with its own catalog, branding, and checkout.
-
-```mermaid
-erDiagram
- Store ||--o{ Market : "has many"
- Store ||--o{ Order : "has many"
- Store }o--o{ Product : "has many"
- Store }o--o{ PaymentMethod : "has many"
- Store }o--o{ ShippingMethod : "has many"
- Store ||--o{ Taxonomy : "has many"
- Store ||--o{ StockLocation : "has many"
-
- Store {
- string name
- string code
- string url
- boolean default
- string customer_support_email
- }
-
- Market {
- string name
- string currency
- string default_locale
- }
-
- Product {
- string name
- string status
- }
-
- Order {
- string number
- string state
- }
-```
+The Store is the top-level tenant in Spree. Every resource — products, orders, channels, markets, taxonomies, stock locations — belongs to exactly one store. A store owns its branding (logo, custom domain, mail-from address), its [channels](/developer/core-concepts/channels) (online, POS, wholesale, …), its [markets](/developer/core-concepts/markets) (region/currency/locale), and its catalog.
## Store Attributes
@@ -83,37 +48,42 @@ curl 'https://api.mystore.com/api/v3/store/store' \
</CodeGroup>
-## Markets
+## Channels vs. Markets
-[Markets](/developer/core-concepts/markets) let you segment your store into geographic regions, each with its own currency, locale, and set of countries. For example, a single store can have:
+Two different ways to split a store, often confused:
-- **North America** — USD, English, ships to US and Canada
-- **Europe** — EUR, German, ships to DE, FR, AT, NL
-- **United Kingdom** — GBP, English, ships to GB
+- **[Sales Channels](/developer/core-concepts/channels)** segment **selling surfaces** — Online Store, POS, Wholesale, marketplace integrations. They control product visibility, order attribution, and per-channel routing rules.
+- **[Markets](/developer/core-concepts/markets)** segment **geography and currency** — North America (USD/en), Europe (EUR/de), UK (GBP/en). They control which currency, locale, and tax rules apply to a given customer.
-See the [Markets](/developer/core-concepts/markets) guide for details.
+A single Online Store channel can serve multiple markets (one storefront → many regions). Conversely, POS and Online channels can share the same market (same currency/locale, different selling surfaces).
## Store Resources
-Each store has its own set of resources. This means products, orders, and promotions in one store are completely separate from another.
+Each store owns its own resources. Products, orders, channels, markets, and taxonomies in one store are independent from another.
| Resource | Relationship |
|----------|-------------|
+| [**Channels**](/developer/core-concepts/channels) | A store has many channels (Online Store, POS, Wholesale, …). One is the default. |
| [**Markets**](/developer/core-concepts/markets) | A store has many markets, each defining a geographic region with its own currency and locale |
-| [**Orders**](/developer/core-concepts/orders) | An order belongs to one store |
-| [**Products**](/developer/core-concepts/products) | A product can be available in multiple stores |
-| [**Payment Methods**](/developer/core-concepts/payments) | A payment method can be available in multiple stores |
-| [**Shipping Methods**](/developer/core-concepts/shipments) | A shipping method can be available in multiple stores |
+| [**Orders**](/developer/core-concepts/orders) | An order belongs to one store and one channel |
+| [**Products**](/developer/core-concepts/products) | A product belongs to one store. Its visibility across channels is controlled by [publications](/developer/core-concepts/channels#publishing-products-on-channels). |
| [**Taxonomies**](/developer/core-concepts/products#taxons-and-taxonomies) | A taxonomy belongs to one store |
-| [**Promotions**](/developer/core-concepts/promotions) | A promotion can apply to multiple stores |
+| [**Payment Methods**](/developer/core-concepts/payments) | A payment method belongs to one store |
+| [**Shipping Methods**](/developer/core-concepts/shipments) | A shipping method belongs to one store |
+| [**Promotions**](/developer/core-concepts/promotions) | A promotion belongs to one store |
+
+## Running Multiple Storefronts
+
+If you need one Spree backend to serve **multiple distinct merchant brands** — different domains, different catalogs, different admin teams — there are two patterns:
-## Multi-Store Setup
+- **Multiple channels under one store** (recommended for most cases) — model each storefront as a Sales Channel. Products are scoped per-channel via publications, orders carry the channel that originated them, and routing/pricing can differ per channel. This is the supported pattern in core Spree 5.5+.
+- **Multiple stores in one app** — the legacy multi-store pattern, where each store is fully independent (catalog, admin, branding). In Spree 5.5+ this requires the `spree_multi_store` extension. Core Spree treats each product as belonging to a single store.
-To run multiple stores from a single Spree installation, see the [Multi-Store guide](/developer/multi-store/quickstart). Each store gets its own domain, branding, catalog, and checkout — while sharing the same admin dashboard and infrastructure.
+For most multi-brand operations, the channel pattern is simpler and more flexible. Reach for `spree_multi_store` only when stores need genuinely independent catalogs, branding, and admin teams.
## Related Documentation
+- [Channels](/developer/core-concepts/channels) — Selling surfaces (Online, POS, Wholesale, …)
- [Markets](/developer/core-concepts/markets) — Multi-region commerce within a store
- [Products](/developer/core-concepts/products) — Product catalog
- [Orders](/developer/core-concepts/orders) — Order management and checkout
-- [Multi-Store](/developer/multi-store/quickstart) — Running multiple stores
diff --git a/docs/docs.json b/docs/docs.json
index 626d9d11d5..5ded885ec1 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -140,6 +140,7 @@
"pages": [
"developer/core-concepts/architecture",
"developer/core-concepts/stores",
+ "developer/core-concepts/channels",
"developer/core-concepts/markets",
"developer/core-concepts/customers",
"developer/core-concepts/staff-roles"
diff --git a/docs/index.mdx b/docs/index.mdx
index f7075534d7..080aaa2e3c 100644
--- a/docs/index.mdx
+++ b/docs/index.mdx
@@ -253,15 +253,15 @@ export const CopyCommand = ({ command }) => {
<ConceptItem href="/developer/core-concepts/stores"
icon={<SmallIcon><path d="m2 7 4.41-4.41A2 2 0 0 1 7.83 2h8.34a2 2 0 0 1 1.42.59L22 7" /><path d="M4 12v8a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2v-8" /><path d="M15 22v-4a2 2 0 0 0-2-2h-2a2 2 0 0 0-2 2v4" /><rect width="20" height="5" x="2" y="7" /></SmallIcon>}
title="Stores" />
+ <ConceptItem href="/developer/core-concepts/channels"
+ icon={<SmallIcon><path d="M4.9 16.1C1 12.2 1 5.8 4.9 1.9" /><path d="M7.8 4.7a6.14 6.14 0 0 0-.8 7.5" /><circle cx="12" cy="9" r="2" /><path d="M16.2 4.8c2 2 2.26 5.11.8 7.47" /><path d="M19.1 1.9a9.96 9.96 0 0 1 0 14.1" /><path d="M9.5 18h5" /><path d="m8 22 4-11 4 11" /></SmallIcon>}
+ title="Channels" />
<ConceptItem href="/developer/core-concepts/markets"
icon={<SmallIcon><circle cx="12" cy="12" r="10" /><path d="M12 2a14.5 14.5 0 0 0 0 20 14.5 14.5 0 0 0 0-20" /><path d="M2 12h20" /></SmallIcon>}
title="Markets" />
<ConceptItem href="/developer/core-concepts/customers"
icon={<SmallIcon><path d="M16 21v-2a4 4 0 0 0-4-4H6a4 4 0 0 0-4 4v2" /><circle cx="9" cy="7" r="4" /><path d="M22 21v-2a4 4 0 0 0-3-3.87" /><path d="M16 3.13a4 4 0 0 1 0 7.75" /></SmallIcon>}
title="Customers" />
- <ConceptItem href="/developer/core-concepts/search-filtering"
- icon={<SmallIcon><circle cx="11" cy="11" r="8" /><path d="m21 21-4.3-4.3" /></SmallIcon>}
- title="Search & Filtering" />
</div>
</div>
diff --git a/docs/plans/6.0-channels-catalogs-b2b.md b/docs/plans/6.0-channels-catalogs-b2b.md
index 77c0d02e14..bbaaf9a683 100644
--- a/docs/plans/6.0-channels-catalogs-b2b.md
+++ b/docs/plans/6.0-channels-catalogs-b2b.md
@@ -1,10 +1,10 @@
# Channels, Catalogs & B2B Companies
-**Status:** Phase 1 shipped in 5.5 (Channel + ProductPublication + channel-aware scopes + Admin API + Store API back-compat + legacy admin Channels CRUD + Meilisearch channel filter); Catalog, Company tree, and pricing integration land in 6.0
+**Status:** Phase 1 shipped in 5.5 (Channel + new `spree_product_publications` table + single-store Product + channel-aware scopes + Admin API action endpoints + Store API back-compat + legacy admin Channels CRUD + Publishing card + dashboard SPA + Meilisearch channel filter); Catalog, Company tree, and pricing integration land in 6.0
**Target:** Spree 5.5 (Phase 1 ✓) → 6.0 (Catalog + Company)
**Depends on:** ProductType (6.0-product-types.md), PriceList system (existing)
**Author:** Damian + Claude
-**Last updated:** 2026-05-23
+**Last updated:** 2026-06-02
## Summary
@@ -14,7 +14,9 @@ Add three new concepts to Spree's multi-store architecture:
- **Catalog** — product assortment + optional pricing override. Controls what's available and at what price for a specific audience (B2B tier, VIP group, regional assortment).
- **Company** — B2B customer hierarchy (Company → CompanyLocation → CompanyContact) for businesses with multiple buyers and offices.
-`StoreProduct` is replaced by **ProductPublication** — the join between Product and Channel that says "this product is listed on this channel."
+`StoreProduct` is replaced by **ProductPublication** — the join between Product and Channel that says "this product is listed on this channel." The legacy `spree_products_stores` join table stays as compat surface for the `spree_multi_store` extension; **core no longer reads or writes it.**
+
+`Product` is now `belongs_to :store` (single owner) in core. Multi-store catalog sharing — historically every `Product` belonged to many `Store`s via `spree_products_stores` — moves to the `spree_multi_store` extension. This matches Medusa/Saleor/Vendure: the catalog has one owner, distribution to multiple selling surfaces happens through channels.
## Problem
@@ -93,9 +95,11 @@ Store (who you are — legal entity, config boundary)
### ProductPublication (replaces StoreProduct)
-- **Replaces `StoreProduct`** — the table is renamed, the join now connects Product to Channel instead of Product to Store.
-- **Carries publication-specific data** — `published_at`, `unpublished_at` (scheduled publishing), `position` (sort order per channel).
-- **Store-level scoping derived from Channel** — `store.products` goes through `store.channels → product_publications → products`. No direct Store → Product join needed.
+- **New `spree_product_publications` table.** Joins Product to Channel, not Product to Store.
+- **No `store_id` column** — the publication's store is `channel.store` (delegated). Cross-store reporting joins through `spree_channels`.
+- **Carries publication-specific data** — `published_at`, `unpublished_at` (scheduled publishing).
+- **`position` was dropped from the original sketch** — nothing in 5.5 reads it and `acts_as_list` added a `MAX(position)` query per insert for no gain. Clean additive migration later if per-channel ordering ever becomes a real requirement.
+- **Store-level scoping is direct** — `Spree::Store has_many :products` via `store_id` on Product. The historic `store.products through: :store_products` join is gone from core.
### Catalog
@@ -117,19 +121,51 @@ Store (who you are — legal entity, config boundary)
### Channel (shipped in 5.5)
-See [`spree/core/app/models/spree/channel.rb`](../../spree/core/app/models/spree/channel.rb). Notable diffs from the original sketch:
+See [`spree/core/app/models/spree/channel.rb`](../../spree/core/app/models/spree/channel.rb). Final shape:
-- No `default_catalog_id` — waits for Catalog in 6.0.
+- **`default` boolean column** + `scope :default` + partial unique index `(store_id) WHERE default = TRUE` on Postgres/SQLite (model-level uniqueness validation on MySQL). `before_validation :promote_first_channel_to_default` auto-promotes the first channel created on a store; `after_save :demote_other_defaults` enforces single-default invariant when an admin flips the flag.
+- **No `default_catalog_id`** — waits for Catalog in 6.0.
- Includes routing-rules associations + `preference :order_routing_strategy` from `6.0-order-routing.md`.
-- `#add_products(product_ids, published_at:, unpublished_at:)` bulk-UPSERTs publications (mirrors `Spree::PriceList#bulk_update_prices` convention).
+- `#add_products(product_ids, published_at:, unpublished_at:)` bulk-UPSERTs publications. Idempotent: re-publishing an already-published product is a no-op for its window unless dates are explicitly passed (uses `Arel.sql('updated_at = <table>."updated_at"')` for the conflict clause to satisfy PG's DO UPDATE requirement without rewriting columns).
+- `#remove_products(product_ids)` mirrors `add_products` — destroys publications, touches the channel.
+- Touches every product via `Product.where(id: product_ids).touch_all` + `enqueue_search_index` after the upsert, since `upsert_all` bypasses `belongs_to :product, touch: true`.
+
+### ProductPublication (shipped in 5.5 — new table)
+
+See [`spree/core/app/models/spree/product_publication.rb`](../../spree/core/app/models/spree/product_publication.rb). Final shape:
+
+- **New table `spree_product_publications`** with columns `product_id`, `channel_id`, `published_at`, `unpublished_at`, `created_at`, `updated_at`. No `store_id` column — `delegate :store, :store_id, to: :channel` for in-memory access; cross-store reporting queries join through `spree_channels`.
+- **Unique index on `(product_id, channel_id)`**. `(product_id, channel_id, store_id)` was abandoned along with the in-place reshape.
+- **`Spree::StoreProduct` deleted.** The class is gone in 5.5. Apps on 5.4 that referenced it directly must update to `Spree::ProductPublication`.
+- **Legacy `spree_products_stores` table left untouched.** Core no longer reads or writes it. The upcoming `spree_multi_store` extension uses it to restore the `Product has_many :stores` association for merchants who need shared catalogs across stores.
+
+`prefix :pp`, validates `(product, channel)`, validates `unpublished_at_after_published_at`, has a `published` scope.
+
+### Product (shipped in 5.5 — single store ownership)
+
+See [`spree/core/app/models/spree/product.rb`](../../spree/core/app/models/spree/product.rb) and [`spree/core/app/models/spree/product/channels.rb`](../../spree/core/app/models/spree/product/channels.rb). Final shape:
-### ProductPublication (shipped in 5.5 — reshapes StoreProduct)
+- **`belongs_to :store, optional: true`** with `before_validation :assign_default_store` (uses `Spree::Current.store` → `Spree::Store.default` fallback).
+- **`has_many :product_publications`** (autosave) + `has_many :channels, -> { distinct }, through: :product_publications`.
+- **`accepts_nested_attributes_for :product_publications`** for Rails nested-attribute form writes (legacy admin Publishing card).
+- **Custom `product_publications=`** setter for SPA's hash-array payload — full-set semantics (rows absent from the payload are destroyed). Coexists with the nested-attributes path on different keys.
+- **Deprecated `available_on=` / `discontinue_on=`** setters write through to every publication's `published_at` / `unpublished_at`. Readers prefer the current-channel publication's value with a ternary fallback (`publication ? publication.send(attr) : super()`) — `||` would mask `nil` from an always-live publication.
+- **`#stores` / `#stores=` / `#store_ids` / `#store_ids=` bridges** in `Spree::Product::LegacyMultiStoreSupport` (auto-included unless `SpreeMultiStore` defines), preserved as deprecation warnings for legacy callers.
+- **`set_default_publication` callback removed.** New products created via the Admin API are *not* auto-published — the caller supplies `product_publications: [{ channel_id }]`. The dashboard SPA's create form does auto-publish on the store's default channel (Shopify-style); the legacy admin form has a Publishing card with the same UX.
-See [`spree/core/app/models/spree/product_publication.rb`](../../spree/core/app/models/spree/product_publication.rb). Rather than renaming the table and dropping `StoreProduct`, the 5.5 implementation reshapes `spree_products_stores` in place: keeps `store_id` (denormalized but harmless) and adds `channel_id` + `published_at` + `unpublished_at`. The class moves to `Spree::ProductPublication`, but the model still points at the legacy `spree_products_stores` table via `self.table_name`; the table rename happens in 6.0. [`Spree::StoreProduct < Spree::ProductPublication`](../../spree/core/app/models/spree/store_product.rb) is an STI subclass kept for one release for backwards compatibility with apps that still reference the old class name.
+### Store#default_channel via boolean column
-`before_validation :assign_channel_from_store` auto-fills `channel_id` from `store.default_channel` for callers that pass only `store` + `product` (legacy StoreProduct-style construction).
+```ruby
+# spree/core/app/models/concerns/spree/stores/channels.rb
+has_one :default_channel, -> { default }, class_name: 'Spree::Channel'
+
+def ensure_default_channel
+ return if default_channel
+ channels.create!(name: 'Online Store', code: Spree::Channel::DEFAULT_CODE)
+end
+```
-Note: `position` was dropped from the original sketch — nothing in 5.5 reads it and `acts_as_list` added a `MAX(position)` query per insert for no gain. If per-channel manual ordering becomes a real requirement later, it's a clean additive migration.
+The `default` scope on Channel resolves the right row by the boolean column — no string-code lookup, no fragile rename hazard.
### Catalog
@@ -276,22 +312,26 @@ class Spree::Order < Spree.base_class
end
```
-### Store gains Channels
+### Store gains Channels (as-shipped in 5.5)
```ruby
class Spree::Store < Spree.base_class
has_many :channels, class_name: 'Spree::Channel', dependent: :destroy
+ has_one :default_channel, -> { default }, class_name: 'Spree::Channel'
+
+ # 6.0 additions
has_many :catalogs, class_name: 'Spree::Catalog', dependent: :destroy
has_many :companies, class_name: 'Spree::Company', dependent: :destroy
- # Product access now goes through channels
- has_many :product_publications, through: :channels
- has_many :products, through: :product_publications
+ # Direct ownership in 5.5 — products belong to a single store.
+ has_many :products, class_name: 'Spree::Product', dependent: :nullify
+ has_many :product_publications, through: :channels, source: :publications
- # Remove: has_many :store_products (replaced by channels → product_publications)
+ after_create :ensure_default_channel
- def default_channel
- channels.find_by(code: 'online') || channels.first
+ def ensure_default_channel
+ return if default_channel
+ channels.create!(name: 'Online Store', code: Spree::Channel::DEFAULT_CODE)
end
end
```
@@ -349,29 +389,37 @@ end
### Phase 1 — shipped in 5.5
-Mirrors the additive-then-swap pattern already used by `Order.channel` (see `6.0-order-routing.md`).
-
**Migrations** (`spree/core/db/migrate/`):
-- `20260508204040_create_spree_channels.rb` — Channel table (shipped 5.5 with order routing).
-- `20260522000001_add_channel_to_spree_products_stores.rb` — additive only: adds `channel_id`, `published_at`, `unpublished_at` to the existing `spree_products_stores` table.
-- `20260522000002_add_unique_index_to_spree_products_stores.rb` — drops legacy `(product_id, store_id)` unique index, adds `(channel_id, product_id, store_id)` unique index.
+- `20260508204040_create_spree_channels.rb` — Channel table (shipped 5.5 with order routing). Note: the in-migration `ensure_default_market` backfill that originally lived here was removed — default-channel seeding for existing stores moves to the `spree:channels:create_defaults` rake task.
+- `20260601000001_create_spree_product_publications.rb` — **new** `spree_product_publications` table with `(product_id, channel_id, published_at, unpublished_at, created_at, updated_at)` + unique index on `(product_id, channel_id)`.
+- `20260601000002_add_store_id_to_spree_products.rb` — adds `store_id` (nullable), `units_sold_count` (default 0), `revenue` (default 0) to `spree_products` + `(store_id, units_sold_count)` index. Existing rows have `store_id IS NULL` until the backfill rake runs.
+- `20260602000001_add_default_to_spree_channels.rb` — adds `default` boolean to `spree_channels` + partial unique index on `(store_id) WHERE default = TRUE` (Postgres/SQLite; MySQL relies on the model-level uniqueness validation).
+
+**The earlier additive-then-swap pattern (reshape `spree_products_stores` in place) was abandoned.** It carried a denormalized `store_id` column on the publication table and a `Spree::StoreProduct` STI alias for back-compat. The simpler shape — separate table, single owner on Product — is what actually shipped.
-**Upgrade rake** (`spree:channels:upgrade` composes):
-- `backfill_order_channel_ids` — populates `spree_orders.channel_id` from the legacy string column.
-- `backfill_product_publication_dates` — copies `Product.available_on` → `ProductPublication.published_at` and `Product.discontinue_on` → `ProductPublication.unpublished_at` where the listing dates are still NULL. Per-product loop for SQLite/MySQL/Postgres portability.
+**Upgrade rake** (`spree:channels:upgrade` chains):
+1. `spree:channels:create_defaults` — creates the default "Online Store" channel for every existing store (via `Store#ensure_default_channel`). Idempotent.
+2. `spree:upgrade:populate_publications` — for every product with `store_id IS NULL`, reads the legacy `spree_products_stores` rows (raw SELECT with parameterized binding), picks a "home" store (preferring the row whose store is `default: true`, otherwise earliest by `created_at`), sets `spree_products.store_id`, and creates a `ProductPublication` row on each attached store's default channel. Runs in a transaction per product. Idempotent.
+3. `spree:channels:backfill_order_channel_ids` — populates `spree_orders.channel_id` from the legacy `spree_orders.channel` string column.
+4. `spree:channels:backfill_product_publication_dates` — copies the legacy `Product.available_on` / `Product.discontinue_on` columns (read raw via `product[:column]` to bypass the channel-aware reader) into each publication's `published_at` / `unpublished_at` where currently NULL.
-**Deploy order**: code → `db:migrate` (additive only) → `rake spree:channels:upgrade` → `db:migrate` (swap). The swap migration enforces this with a runtime guard.
+**Deploy order**: code → `db:migrate` → `rake spree:channels:upgrade`. No swap migration — there's nothing to swap.
+
+> **Warning**: Until `spree:channels:upgrade` runs, every product has `store_id IS NULL` and is invisible to `Product.for_store(store)`. The admin product list, storefront catalog, and search indexer all return empty. The upgrade guide [docs/developer/upgrades/5.4-to-5.5.mdx](../developer/upgrades/5.4-to-5.5.mdx) makes this prominent.
**Model layer**:
-- `Spree::ProductPublication` is the canonical class on the existing `spree_products_stores` table (table rename deferred to 6.0).
-- `Spree::StoreProduct < Spree::ProductPublication` STI subclass (with `inheritance_column = nil`) preserves all existing call sites — apps on 5.4 that reference `Spree::StoreProduct` directly keep working through the 5.5 → 6.0 transition.
-- `Spree::Product` gains `has_many :product_publications, :stores, :channels` via `Spree::Product::Channels` concern. Deprecated setters `available_on=`, `discontinue_on=`, `make_active_at=` write through to every listing via `autosave: true`.
-- `Spree::Product.available` / `.active` / `.not_discontinued` scopes are channel-aware: when `Spree::Current.channel` is set, they join `product_publications` and filter on `published_at`/`unpublished_at`. Legacy column path is the fallback for job/console/rake contexts.
-- `Spree::Current.channel` attribute + `X-Spree-Channel` header resolution in API v3 base controller. Falls back to `current_store.default_channel`.
+- `Spree::ProductPublication` on the new `spree_product_publications` table — no `store_id` column, `store`/`store_id` delegated to `channel`.
+- `Spree::Product belongs_to :store` (single). `for_store(store)` scope is now `where(store_id: store.id)` (was a join through publications).
+- `Spree::Product::Channels` concern owns `has_many :product_publications`, `has_many :channels through:`, the deprecated `available_on=`/`discontinue_on=` cascade, and the SPA's `product_publications=` hash-array setter. **No `set_default_publication` callback** — explicit publishing only.
+- `Spree::Product::LegacyMultiStoreSupport` concern owns `#stores` / `#stores=` / `#store_ids` / `#store_ids=` deprecation bridges (auto-included unless `SpreeMultiStore` is defined; the `spree_multi_store` extension supersedes them).
+- `Spree::Product.available` / `.active` / `.not_discontinued` scopes are channel-aware via `Spree::Current.channel`; jobs/rake without channel context use the legacy column fallback path.
+- `Spree::Channel#add_products` / `#remove_products` are the canonical bulk publishing API (used by both bulk-action controllers and the legacy/SPA Publishing cards).
+- `Spree::Current.channel` + `X-Spree-Channel` header resolution in API v3 base controller. Falls back to `current_store.default_channel`.
**Search provider**:
-- `Spree::SearchProvider::ProductPresenter` indexes a per-product `channel_ids: [...]` array.
-- `Spree::SearchProvider::Meilisearch#system_filter_conditions` adds `channel_ids = '<current channel>'` so storefronts on different channels of the same store see distinct product sets.
+- `Spree::SearchProvider::ProductPresenter` indexes a per-product `channel_ids: [...]` array (computed via `product.product_publications.joins(:channel).where(spree_channels: { store_id: store.id })`).
+- `Spree::SearchProvider::Meilisearch#system_filter_conditions` adds `channel_ids = '<current channel>'`.
+- `Spree::SearchIndexable#store_ids_for_indexing` reads the record's own `store_id` (was hardcoded to `Spree::Store.default.id` in an earlier sketch — that broke multi-store indexing).
**Admin API:**
@@ -381,25 +429,41 @@ POST /api/v3/admin/channels
PATCH /api/v3/admin/channels/:id
DELETE /api/v3/admin/channels/:id
-GET /api/v3/admin/channels/:channel_id/product_publications
-GET /api/v3/admin/channels/:channel_id/product_publications/:id
-POST /api/v3/admin/channels/:channel_id/product_publications
-PATCH /api/v3/admin/channels/:channel_id/product_publications/:id
-DELETE /api/v3/admin/channels/:channel_id/product_publications/:id
-POST /api/v3/admin/channels/:channel_id/product_publications/bulk
+POST /api/v3/admin/channels/:id/add_products # body: { product_ids: [...], published_at?, unpublished_at? }
+POST /api/v3/admin/channels/:id/remove_products # body: { product_ids: [...] }
+
+POST /api/v3/admin/products/bulk_add_to_channels # body: { ids: [...], channel_ids: [...] }
+POST /api/v3/admin/products/bulk_remove_from_channels # body: { ids: [...], channel_ids: [...] }
```
-- Admin Product API dropped `available_on`, `discontinue_on`, `make_active_at` from params + serializer (clean break — admin SDK is Developer Preview).
-- Admin Product serializer gains `many :product_publications` via `expand=product_publications`.
-- Bulk endpoint delegates to `Spree::Channel#add_products` (single `upsert_all`, no per-product saves).
+The originally-planned nested CRUD (`GET/POST/PATCH/DELETE /admin/channels/:channel_id/product_publications/...`) was **dropped** — the SPA never used it, no industry precedent (Shopify/Saleor/Vendure/Medusa all expose action endpoints, not nested CRUD), and the `Spree::ProductPublication` model is internal join-table noise that shouldn't be a top-level API surface.
+
+- Admin Product API dropped `available_on`, `discontinue_on`, `make_active_at` from params + serializer.
+- Admin Product serializer gains `many :product_publications` via `expand=product_publications` (with `:channel` preloaded to avoid N+1).
+- Bulk endpoints delegate to `Spree::Channel#add_products` / `#remove_products` (single upsert per channel, no per-product saves).
+- `Spree::Channel` gains a `default: boolean` serializer field so the dashboard can identify the default channel for auto-publish on product create.
**Store API:**
-- `Spree::Api::V3::ProductSerializer#available_on` resolves from the current channel's listing `published_at`, falling back to the legacy `Product.available_on` column. Shape unchanged — single-channel stores see zero behavior change.
+- `Spree::Api::V3::ProductSerializer#available_on` resolves from the current channel's publication `published_at`, falling back to the legacy `Product.available_on` column. Shape unchanged — single-channel stores see zero behavior change.
**Legacy admin:**
-- `/admin/channels` CRUD (controller + table registration + sidebar nav under Settings + permitted attributes + `ConfigurationManagement` permission grant).
+- `/admin/channels` CRUD (controller + table registration + sidebar nav under Settings + permitted attributes + `ConfigurationManagement` permission grant). The settings nav labels it "Sales channels".
+- Product edit page has a **Publishing card** (`spree/admin/app/views/spree/admin/products/form/_publishing.html.erb`) — channel checkboxes via Manage panel, per-publication date editor via `<details>` row. Writes through `accepts_nested_attributes_for :product_publications`. Mirrors the SPA's `<PublishingCard>`.
+- `make_active_at` / `available_on` / `discontinue_on` inputs removed from the legacy admin product form's Status card — date scheduling moves to the per-publication editor on the Publishing card.
+
+**Dashboard SPA:**
+
+- `<PublishingCard>` at [`packages/dashboard/src/components/spree/products/publishing-card.tsx`](../../packages/dashboard/src/components/spree/products/publishing-card.tsx) — full Shopify-style publishing UI with status badges (Live / Scheduled / Hidden / Not available, gated by product status), per-channel schedule editor, Manage sheet for attach/detach.
+- New-product form auto-publishes on the store's default channel (uses the Channel `default` boolean).
+- Settings → "Sales channels" page (`packages/dashboard/src/routes/_authenticated/$storeId/settings/channels.tsx`).
+- Bulk actions on product list: *Add to sales channels…* / *Remove from sales channels…*.
+- `useChannels` hook query-keyed by `storeId` so switching stores within the staleTime window doesn't serve the previous store's channels.
+
+**Sample data:**
+
+- `bin/rake spree:load_sample_data` seeds three channels (Online Store [default], Point of Sale, Wholesale) via `db/sample_data/channels.rb` and explicitly publishes every loaded product on the default channel via `Loader#publish_sample_products`.
### Phase 2 — 6.0: Catalog + Company tree + pricing integration
@@ -511,29 +575,46 @@ DELETE /api/v3/admin/company_contacts/:id
### Phase 3 — 6.0 cleanup
-- Drop `Spree::Product.available_on`, `discontinue_on`, `make_active_at` columns and the deprecated setters in `Spree::Product::Channels`.
-- Drop `Spree::Product.for_store`'s `store_products` join path; reroute through `product_publications`.
-- Drop `Spree::StoreProduct` STI subclass and `spree/core/app/models/spree/store_product.rb`.
-- Drop `store_id` column from the publications table (now denormalized — `channel.store_id` is the source of truth).
-- Rename `spree_products_stores` → `spree_product_publications` and drop the `self.table_name` override in the model.
+Most of the planned 6.0 cleanup already happened in 5.5 (cleaner data model from the start). Remaining items:
+
+- Drop `Spree::Product.available_on`, `Spree::Product.discontinue_on`, `Spree::Product.make_active_at` columns and the deprecated setters in `Spree::Product::Channels`.
+- Drop `Spree::Product::LegacyMultiStoreSupport` (multi-store catalogs live in the `spree_multi_store` extension from 5.5 onward).
+- Drop `Spree::Product.for_store`'s legacy column-fallback branch (`Spree::Product.available` / `.not_discontinued` always use publications once `Spree::Current.channel` is unconditionally set).
+- Make `spree_products.store_id` `NOT NULL` (it's nullable in 5.5 to accommodate the post-migrate / pre-backfill window).
- Drop `spree_orders.channel` string column (5.5+ already ignores it via `ignored_columns`).
-- Drop the channel-aware-scope legacy fallback branch (`Spree::Product.available` / `.not_discontinued` always use listings).
+- Drop the channel-aware-scope legacy fallback branch in `Spree::Product.available` / `.not_discontinued` (always uses publications).
+
+**Already done in 5.5 (don't redo in 6.0):**
+- ~~Drop `Spree::StoreProduct` STI subclass~~ — deleted in 5.5.
+- ~~Drop `store_id` column from the publications table~~ — new `spree_product_publications` table never had it.
+- ~~Rename `spree_products_stores` → `spree_product_publications`~~ — new table created; legacy `spree_products_stores` left for `spree_multi_store`.
## Constraints on Current Work
-- **Don't add new features to `Spree::StoreProduct`.** It's an STI subclass of `Spree::ProductPublication` in 5.5 and gone in 6.0. Use `Spree::ProductPublication` directly in any new code.
-- **6.0 cleanup will rename `spree_products_stores` → `spree_product_publications` and drop `store_id`.** Don't write new code that joins on `store_id` of the publications table — go through `channel.store` instead.
+- **`Spree::StoreProduct` is gone.** Use `Spree::ProductPublication` directly. Don't reintroduce the STI alias or any reference to `spree/core/app/models/spree/store_product.rb`.
+- **`Spree::ProductPublication` has no `store_id` column.** It's delegated to `channel.store`. Don't write code that calls `ProductPublication.where(store_id: …)` — use a join: `Publication.joins(:channel).where(spree_channels: { store_id: … })`.
+- **`Product belongs_to :store` (single).** Don't write new code assuming `product.stores` is a real ActiveRecord association — the deprecation bridge returns `Array(store)` and won't chain. Multi-store catalogs live in `spree_multi_store`.
+- **`Channel#default` is a boolean column.** Use `Spree::Channel.default.where(store: …)` or `store.default_channel`. Don't look up by `code: 'online'` — merchants can rename it.
- **Channel-aware scopes assume `Spree::Current.channel` is set.** API requests set it via the X-Spree-Channel header concern; jobs / rake tasks fall back to the legacy column path. Don't add new code that reads `Spree::Current.channel` without expecting either branch.
+- **`Spree::Channel#add_products` is idempotent and preserves existing publication windows** when called without `published_at` / `unpublished_at` kwargs. Don't change this — bulk-publish ergonomics depend on it.
- **6.0 adds `default_catalog_id` to `spree_channels`** (additive — won't conflict with the 5.5 schema).
- **PriceList stays as-is.** Catalog optionally references a PriceList — don't duplicate pricing logic.
## Resolved Questions
-1. **Default channel behavior.** Channel resolution via `X-Spree-Channel` request header (accepts channel `code`, e.g. `X-Spree-Channel: online`). If header is absent or doesn't match an active channel, falls back to `store.default_channel`. Shipped in 5.5 — see [`Spree::Api::V3::ChannelResolution`](../../spree/api/app/controllers/concerns/spree/api/v3/channel_resolution.rb).
+1. **Default channel behavior.** Channel resolution via `X-Spree-Channel` request header (accepts channel `code`, e.g. `X-Spree-Channel: online`). If header is absent or doesn't match an active channel, falls back to `store.default_channel` (`Channel.default` scope on the `default` boolean column). Shipped in 5.5.
+
+2. **How is the default channel identified?** Via a `default` boolean column on `Spree::Channel`, not by code. Partial unique index on Postgres/SQLite, model-level uniqueness validation on MySQL. The first channel created on a store auto-promotes; flipping the flag on a later channel auto-demotes the previous default. Looking up by `code: 'online'` would have been fragile (merchants can rename the default channel).
+
+3. **Auto-publish on product create.** Admin API: **no** auto-publish — the caller supplies `product_publications: [{ channel_id }]`. Dashboard SPA's create form: **yes**, auto-publishes on `Channel#default == true` (Shopify-style). Sample data: explicitly publishes via `Loader#publish_sample_products`. The `set_default_publication` model callback was removed — moving the decision to the layer that knows the merchant's intent.
+
+4. **Multi-store catalogs.** Core Spree 5.5+ models Product as `belongs_to :store` (single owner). Merchants who need shared catalogs across stores install the `spree_multi_store` extension, which restores `has_many :stores, through: :spree_products_stores` on top of the legacy join table. Matches the Medusa/Saleor/Vendure pattern (channels are the multi-brand primitive, stores are the tenant root).
+
+5. **Cross-store onboarding via `Channel#add_products`.** Allowed: if a multi-store admin's API key has update permission on a product owned by sibling store A, calling `POST /admin/channels/:id/add_products` (where the channel belongs to store B) co-publishes the product onto store B's channel. The product's owning `store_id` doesn't change. This is the path by which the `spree_multi_store` extension's "publish across stores" UX threads through core.
-2. **Catalog auto-sync.** Manual assignment only for 6.0, with bulk product assignment via Admin API (`POST /catalogs/:id/products/bulk`). Auto-sync using CollectionRule-style patterns is a future enhancement.
+6. **Catalog auto-sync.** Manual assignment only for 6.0, with bulk product assignment via Admin API (`POST /catalogs/:id/products/bulk`). Auto-sync using CollectionRule-style patterns is a future enhancement.
-3. **CompanyContact roles and B2B approval workflows.** Out of scope for this plan. The 6.0 deliverable is the data model: Company, CompanyLocation, CompanyContact with a simple `role` string column. Role-based permissions, approval workflows, purchase limits, and invoice management are deferred to a dedicated B2B plan post-6.0.
+7. **CompanyContact roles and B2B approval workflows.** Out of scope for this plan. The 6.0 deliverable is the data model: Company, CompanyLocation, CompanyContact with a simple `role` string column. Role-based permissions, approval workflows, purchase limits, and invoice management are deferred to a dedicated B2B plan post-6.0.
## Open Questions
@@ -541,10 +622,17 @@ None at this time.
## References
-- Current Store model: `spree/core/app/models/spree/store.rb`
-- Current Market model: `spree/core/app/models/spree/market.rb`
-- Current CustomerGroup: `spree/core/app/models/spree/customer_group.rb`
-- Current PriceList + PriceRules: `spree/core/app/models/spree/price_list.rb`, `spree/core/app/models/spree/price_rule.rb`
-- Current StoreProduct: `spree/core/app/models/spree/store_product.rb`
+- Channel model: `spree/core/app/models/spree/channel.rb`
+- ProductPublication model: `spree/core/app/models/spree/product_publication.rb`
+- Product channels concern: `spree/core/app/models/spree/product/channels.rb`
+- Legacy multi-store bridge: `spree/core/app/models/spree/product/legacy_multi_store_support.rb`
+- Store channels concern: `spree/core/app/models/concerns/spree/stores/channels.rb`
+- Upgrade rake: `spree/core/lib/tasks/channels.rake` (`spree:channels:upgrade`)
+- Population rake: `spree/core/lib/tasks/publications.rake` (`spree:upgrade:populate_publications`)
+- User-facing concept doc: `docs/developer/core-concepts/channels.mdx`
+- Upgrade guide: `docs/developer/upgrades/5.4-to-5.5.mdx`
+- SPA Publishing card: `packages/dashboard/src/components/spree/products/publishing-card.tsx`
+- Legacy admin Publishing card: `spree/admin/app/views/spree/admin/products/form/_publishing.html.erb`
- Related plan: `6.0-product-types.md` (ProductType defines product schema)
- Related plan: `6.0-replace-taxons-with-categories.md` (Collections for merchandising)
+- Related plan: `6.0-order-routing.md` (Channel-aware order routing strategies)