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.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
docs(plans): friendly_id slugs; keep AvailableOn as a channels-plan dependency
Łukasz Adamczykb6e041dba2e6
diff --git a/docs/plans/6.0-channels-catalogs-b2b.md b/docs/plans/6.0-channels-catalogs-b2b.mdindex 4cf4ea8d46..6cf055e434 100644--- a/docs/plans/6.0-channels-catalogs-b2b.md+++ b/docs/plans/6.0-channels-catalogs-b2b.md@@ -4,7 +4,7 @@**Target:** Spree 5.5 (Phase 1 ✓) → 5.6 (Gated Access) → 6.0 (Catalog + Company)**Depends on:** ProductType (6.0-product-types.md), PriceList system (existing)**Author:** Damian + Claude-**Last updated:** 2026-07-01+**Last updated:** 2026-07-09## Summary@@ -668,6 +668,7 @@ DELETE /api/v3/admin/company_contacts/:idMost 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`.+ - **Blocked on `6.0-replace-taxons-with-categories.md` Phase 5.** `Spree::CollectionRules::AvailableOn` reads `spree_products.available_on`; it must be reimplemented against `published_at` first, or dropping the column breaks it. That plan's Phase 5 owns the reimplementation and is sequenced before this drop.- Drop `Spree::Product::LegacyMultiStoreSupport` (multi-store catalogs live in the [spree_multi_store](/developer/multi-store/quickstart) 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).diff --git a/docs/plans/6.0-replace-taxons-with-categories.md b/docs/plans/6.0-replace-taxons-with-categories.mdindex 78656591df..a98f5706f2 100644--- a/docs/plans/6.0-replace-taxons-with-categories.md+++ b/docs/plans/6.0-replace-taxons-with-categories.md@@ -2,9 +2,9 @@**Status:** Category read/write surface shipped (5.5–5.6): `Spree::Category < Spree::Taxon` scoped subclass, direct `store_id` ownership + backfill, full Admin Categories API (CRUD + `reposition` + nested products/custom_fields/translations), and counter caches (`products_count`). **Remaining for 6.0:** table rename, the `Collection` stack (model + join + rules + API), model-level removal of automatic/rules from Category, and dropping `Taxonomy`.**Target:** Spree 6.0 (Category surface landed in 5.5–5.6; 6.0 renames the table, splits out `Collection`, and drops `Taxonomy`)-**Depends on:** API v3 conventions, ProductType plan (6.0-product-types.md), Rich Text Descriptions plan (6.0-rich-text-descriptions.md), Admin SPA plan (6.0-admin-spa.md — dashboard UI)+**Depends on:** API v3 conventions, ProductType plan (6.0-product-types.md), Rich Text Descriptions plan (6.0-rich-text-descriptions.md), Admin SPA plan (6.0-admin-spa.md — dashboard UI), Channels/Publications plan (6.0-channels-catalogs-b2b.md — the `CollectionRules::AvailableOn` rule's channel-aware implementation depends on its `available_on` → `ProductPublication#published_at` migration; see Migration Phase 5)**Author:** Damian + Claude-**Last updated:** 2026-07-08+**Last updated:** 2026-07-09## Summary@@ -93,7 +93,7 @@ Two product-count concepts, named consistently across grouping models. `products- **New model `Spree::Collection`** — flat (no tree), store-scoped- **New join table `Spree::ProductCollection`** (replaces the automatic taxon's use of Classification)- **Owns automatic/rule-based membership** — the `automatic` flag, `rules_match_policy`, and rules association move here from Taxon-- **`Spree::TaxonRule` renamed to `Spree::CollectionRule`** — STI subtypes: `AvailableOn`, `Sale`, `Tag` (plus future rules)+- **`Spree::TaxonRule` renamed to `Spree::CollectionRule`** — STI subtypes `Tag`, `Sale`, `AvailableOn`, all registered in `config.spree.collection_rules` (which **mirrors the existing `config.spree.taxon_rules`**). `AvailableOn` ships with an interim legacy-column implementation; its channel-aware behavior **depends on `6.0-channels-catalogs-b2b.md`** (see Design Details → Automatic collection regeneration; Migration Phase 5)- **Prefix: `coll_`**- **Both manual and automatic collections.** Manual collections have `ProductCollection` records managed by admins. Automatic collections have `CollectionRule` records that regenerate membership.- **Sort order on Collection**, not Category. The `SORT_ORDERS` constant (`manual`, `best_selling`, `price asc`, etc.) moves to Collection.@@ -181,6 +181,20 @@ class Spree::Collection < Spree.base_classinclude Spree::Metafieldsinclude Spree::Metadata+ # FriendlyId with history, mirroring Category/Taxon. `use: :history` records superseded+ # permalinks in the shared `friendly_id_slugs` table (polymorphic, scoped by sluggable_type)+ # so old collection URLs keep resolving after a RENAME — a deliberate SEO requirement.+ # No new table (friendly_id_slugs already exists for Taxon). Within-store uniqueness is+ # enforced separately by `validates :permalink, uniqueness: { scope: :store_id }` + the DB+ # index: a collision ERRORS (exactly as Taxon does — friendly_id is not scoped and does not+ # auto-suffix here). Generation mirrors Taxon's dual set_permalink — a model-level+ # `before_validation` (so the column_fallback base column is populated for the default+ # locale, which the Translation `before_save` alone misses) plus a Translation-level+ # `before_save` — but flat: `generate_slug` is `name.to_url` with no parent prefix.+ extend FriendlyId+ friendly_id :permalink, slug_column: :permalink, use: :history+ before_validation :set_permalink, if: :name+RULES_MATCH_POLICIES = %w[all any].freeze# Space format (same values as Spree::Taxon::SORT_ORDERS) — required by the sort# pipeline: FiltersAggregator#to_api_sort splits on a space ('price asc' -> 'price'),@@ -211,6 +225,7 @@ class Spree::Collection < Spree.base_class# Validations (store presence comes from SingleStoreResource)validates :name, presence: true+ validates :permalink, uniqueness: { scope: :store_id, case_sensitive: false, allow_blank: true }validates :rules_match_policy, inclusion: { in: RULES_MATCH_POLICIES }, presence: truevalidates :sort_order, inclusion: { in: SORT_ORDERS }, presence: true@@ -286,22 +301,27 @@ class Spree::CollectionRule < Spree.base_classif: -> { saved_change_to_value? || destroyed? || saved_change_to_match_policy? }end-# STI subtypes:-# Spree::CollectionRules::AvailableOn — products created/available within N days-# Spree::CollectionRules::Sale — products currently on sale-# Spree::CollectionRules::Tag — products with matching tags+# STI subtypes (all registered in config.spree.collection_rules, which mirrors config.spree.taxon_rules):+# Spree::CollectionRules::Tag — products with matching tags+# Spree::CollectionRules::Sale — products currently on sale+# Spree::CollectionRules::AvailableOn — products created/available within N days.+# Ships with the interim legacy-column `apply`; channel-aware reimplementation+# (against ProductPublication#published_at) is Migration Phase 5.```### Automatic collection regeneration-Automatic membership is materialized into `ProductCollection` rows (as today's `Classification` is for automatic taxons). It regenerates on **events** — a `CollectionRule` change, a `rules_match_policy` change, or a product save. Event-driven regeneration has **no clock**, so time-relative rules drift: a product that ages past an `AvailableOn` window stays in the collection until some unrelated write re-triggers evaluation.+Automatic membership is materialized into `ProductCollection` rows (as today's `Classification` is for automatic taxons). It regenerates on **events** — a `CollectionRule` change, a `rules_match_policy` change, or a product save (via `AutoMatchCollections`). Event-driven regeneration has **no clock**, so time-relative rules drift: a product that ages past an `AvailableOn` window stays in the collection until some unrelated write re-triggers evaluation.A scheduled job closes that gap for **time-based** rules:-- **Registry** — `config.spree.time_based_collection_rules = [Spree::CollectionRules::AvailableOn]` in `engine.rb` (mirrors the `collection_rules` registry; apps/plugins append their own).+- **Registry** — `config.spree.time_based_collection_rules = [Spree::CollectionRules::AvailableOn]` in `engine.rb`, **net-new** (no `taxon_rules` equivalent — taxons ship no scheduled refresh, hence their drift). This is a separate axis from the `config.spree.collection_rules` rule registry (which mirrors `config.spree.taxon_rules`); apps/plugins append their own.- **Job** — `Spree::Collections::RegenerateTimeBasedJob < Spree::BaseJob` (`queue_as Spree.queues.collections`): selects automatic collections that have a rule whose `type` is registered as time-based and calls `Spree::Collections::RegenerateProducts` on each.- **Cadence** — not hardcoded in the gem; wired by the host app's scheduler (sidekiq-cron / solid_queue recurring), the same pattern as `Spree::StockReservations::ExpireJob`. Hourly/daily is enough (`AvailableOn` windows are day-granular).+> **`AvailableOn` ships fully now, but its implementation is interim.** The STI class ships in Phase 1 (registered in `collection_rules` alongside `Tag`/`Sale`) so the Phase 3 rake migrates `TaxonRules::AvailableOn` → `CollectionRules::AvailableOn` **1:1** (value + match_policy preserved) rather than dropping the data. Its `apply` is the **same legacy `spree_products.available_on` query the taxon rule already runs** — a faithful, zero-behavior-change carry-over (the taxon rule was equally channel-unaware), which keeps migrated automatic collections computing correct membership and lets the scheduled job above refresh them. One caveat holds until the reimplementation (Migration Phase 5):+> - **Channel-unaware + on a doomed column.** The `available_on` column is superseded by the channel-scoped `ProductPublication#published_at` and is **removed** by `6.0-channels-catalogs-b2b.md` (its Phase 3 — "6.0 cleanup"). So `AvailableOn` is a **new reader of a column another 6.0 plan drops**. **Migration Phase 5** reimplements `apply` against `published_at` and — as a hard cross-plan ordering constraint — must land **before** the channels plan drops the column.+### Product changes**Already shipped:** `has_many :categories, through: :classifications` and a `category_ids=` setter that maps the API name to the underlying `taxon_ids` (accepting prefixed IDs, scoped to the product's store); `main_taxon` still exists. Still to add: `primary_category`, the `collections` association, and the `collections_count` counter. **To remove:** `brand_taxon` / `brand_name` (brands out of scope — see Key Decisions → Brands).@@ -446,7 +466,9 @@ class CreateSpreeCollections < ActiveRecord::Migration[7.2]add_index :spree_product_collections, [:collection_id, :product_id], unique: true# NEW table — NOT a rename of spree_taxon_rules (that stays live for automatic- # taxons until Phase 4). STI: type = Spree::CollectionRules::{AvailableOn,Sale,Tag}.+ # taxons until Phase 4). STI type: Spree::CollectionRules::{Tag,Sale,AvailableOn}+ # (AvailableOn ships with an interim apply — see Automatic collection regeneration;+ # no schema change when its Phase 5 channel-aware reimplementation lands).create_table :spree_collection_rules do |t|t.references :collection, null: falset.string :type, null: false@@ -481,8 +503,8 @@ end```**1b. Models + code** (built on 1a, fully spec'd before any rename):-- `Spree::Collection`, `Spree::ProductCollection`, `Spree::CollectionRule` + STI `CollectionRules::{AvailableOn,Sale,Tag}`-- `Spree::Collections::RegenerateProducts`; `RegenerateTimeBasedJob` + `time_based_collection_rules` registry (see Design Details → Automatic collection regeneration)+- `Spree::Collection`, `Spree::ProductCollection`, `Spree::CollectionRule` + STI `CollectionRules::{Tag,AvailableOn,Sale}`, all registered in `config.spree.collection_rules` (**mirrors the existing `config.spree.taxon_rules`**, `engine.rb`). `AvailableOn` ships with the interim legacy-column `apply`; channel-aware reimplementation is Phase 5+- `Spree::Collections::RegenerateProducts`; `AutoMatchCollections` (+ job) for event-driven regeneration on product save; `RegenerateTimeBasedJob` + `time_based_collection_rules = [AvailableOn]` registry (**net-new — no `taxon_rules` equivalent; taxons ship no scheduled refresh**) for time-relative rules — all on the `collections` queue (see Design Details → Automatic collection regeneration)- Product: `in_collection`/`in_collections` scopes (+ ransack whitelist), `collections`/`collections_count`, `primary_category`- Store + Admin Collection API: `collections` controllers + serializers; dedicated `collections/:id/products`; admin nested curation + `reposition`; `/products/filters` `collection_id` param + `FiltersAggregator` `sort_order:` change (see API → Collection product listing)- Meilisearch: index `collection_ids` + filterable/facet attrs + `build_filter_condition` + reindex@@ -490,6 +512,7 @@ end**Not in scope of this phase (or plan):**- **Dashboard Collection UI** — all dashboard work lives in `6.0-admin-spa.md` (the Category admin UI is already there; Collection is added to its resource list).- **Manual sort** for a collection's `sort_order: 'manual'` is deferred to Open Question #1 (provider-level manual/position sort — approach TBD). Until it's resolved, a manual collection falls back to default order on the storefront; all dynamic sorts work.+- **`CollectionRules::AvailableOn`'s channel-aware reimplementation** — the model, its interim (legacy-column) `apply`, and the scheduled refresh (`RegenerateTimeBasedJob` + `time_based_collection_rules`) all ship in this phase; only rewriting `apply` against `ProductPublication#published_at` is **Migration Phase 5**, a dependency on `6.0-channels-catalogs-b2b.md`.### Phase 2: Table renames (Taxon → Category)@@ -538,6 +561,9 @@ Runs after the Phase 2 rename, so it reads the automatic rows from `spree_catego# For every store, using store_id (backfill first — spree:taxons:backfill_store_id):# 1. Automatic taxons (automatic: true OR any taxon_rules) -> Spree::Collection# - copy their TaxonRules -> new CollectionRules (remap collection_id, rewrite STI type)+# Maps ALL types 1:1 — Tag, Sale, AND AvailableOn. AvailableOn's CollectionRule+# model ships in Phase 1 (interim legacy-column apply), so its rows migrate cleanly+# with value + match_policy preserved; they go channel-aware once Phase 5 reimplements apply.# - copy their ProductCategories -> ProductCollections# (regardless of which taxonomy / name they lived under)# then delete the automatic rows from spree_categories@@ -563,7 +589,15 @@ Now that Collections exist (Phase 1), the tables are renamed (Phase 2), and the- Downstream shim: `alias_attribute :classification_count, :categories_count` on Product for the deprecation window (any app reading the old column keeps working)- Update all serializers, controllers, services, factories, specs for the rename-### Phase 5: Cleanup (6.1)+### Phase 5: Reintroduce channel-aware `AvailableOn` (after `6.0-channels-catalogs-b2b.md`)++Gated on the channels plan finishing the `available_on` → `ProductPublication#published_at` migration. Until then, `CollectionRules::AvailableOn` runs the interim legacy-column query shipped in Phase 1.++- **Reimplement `CollectionRules::AvailableOn#apply`** against `spree_product_publications.published_at` (join), replacing the raw `spree_products.available_on` query. Decide which channel a store-owned collection's availability rule evaluates against — the store's **default channel**, or any publication with `published_at` in the window — and document it (a collection has no channel of its own).+- **No data migration, no registry change** — `AvailableOn` is already registered (Phase 1) and its `CollectionRule` rows already carry the right `value`/`match_policy` from Phase 3; only `apply` changes.+- **Cross-plan ordering constraint (hard).** `CollectionRules::AvailableOn` is a reader of `spree_products.available_on`, which `6.0-channels-catalogs-b2b.md` Phase 3 ("6.0 cleanup") drops. This phase **must land before** that column drop — the channels plan's cleanup is blocked on this reimplementation.++### Phase 6: Cleanup (6.1)- Remove all aliases and deprecation shims (incl. the `Spree::Taxon` alias and the `classification_count` `alias_attribute`)- Remove `taxonomy_id` column from categories@@ -587,7 +621,7 @@ Now that Collections exist (Phase 1), the tables are renamed (Phase 2), and the> **Resolved:**> - *Brand handling* & *Category kind/type column* — 6.0 ships no brand feature and no `kind` column; brands are modeled as a regular Category or Collection, and `brand_taxon`/`brand_name` are removed with `Taxonomy`. See Key Decisions → Brands.> - *Collection product listing* — a dedicated `GET /collections/:id/products` (base visibility scope + an injected `in_collection` filter, delegating to the shared search flow; default sort from the collection's `sort_order`), with facets via the existing `/products/filters` + a new `collection_id` param. See API → Collection product listing.-> - *Automatic collection scheduling* — a `RegenerateTimeBasedJob` scoped to a `time_based_collection_rules` registry, scheduled by the host app (the `ExpireJob` pattern). See Design Details → Automatic collection regeneration.+> - *Automatic collection scheduling* — a `RegenerateTimeBasedJob` scoped to a `time_based_collection_rules` registry, scheduled by the host app (the `ExpireJob` pattern). Ships in Phase 1 with `AvailableOn` as its one registered rule (interim legacy-column implementation; channel-aware reimplementation in Phase 5). See Design Details → Automatic collection regeneration.> - *Collection nesting* — collections stay **flat**; hierarchy lives in Category (matches Shopify and keeps the Category/Collection split clean).1. **"Manual" sort in the v3 Store API (categories *and* collections).** Manual/position ordering isn't implemented in the v3 search-provider path (see Current State → Known gap) — only in the admin controller and the legacy `Products::Find` finder. Both category pages and the collection endpoint list through the search provider, so neither can bypass it; the fix is provider-level and shared. Collections can ship without it (dynamic sorts all work; a `sort_order: 'manual'` collection just falls back to default order until this lands). The open part is the exact approach: