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.

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.md
index 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/:id
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`.
+ - **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.md
index 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_class
include Spree::Metafields
include 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: true
validates :sort_order, inclusion: { in: SORT_ORDERS }, presence: true
@@ -286,22 +301,27 @@ class Spree::CollectionRule < Spree.base_class
if: -> { 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: false
t.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: