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): record Phase 3 de-rule, brand removal, and taxon→category cleanup

Łukasz Adamczyk61146777b2ba
diff --git a/docs/plans/6.0-replace-taxons-with-categories.md b/docs/plans/6.0-replace-taxons-with-categories.md
index 8a3ae976ce..796ef74268 100644
--- a/docs/plans/6.0-replace-taxons-with-categories.md
+++ b/docs/plans/6.0-replace-taxons-with-categories.md
@@ -59,7 +59,7 @@ The Category read/write surface is done. What's left:
1. **Table rename** — `spree_taxons` → `spree_categories`, `spree_products_taxons` → `spree_product_categories` (+ FK columns), plus the inheritance flip (Category becomes the base class, `Taxon` becomes a deprecation alias). `spree_taxon_rules` is dropped (not renamed) — `spree_collection_rules` is a new table.
2. **The full `Collection` stack** — `Spree::Collection`, `Spree::ProductCollection` join, `Spree::CollectionRule` (STI), and the Store + Admin API. Nothing exists yet. (Dashboard UI is tracked in `6.0-admin-spa.md`.)
3. **Model-level split** — move `automatic`, `rules_match_policy`, `sort_order`, and `taxon_rules` off Category onto Collection (today they still live on `Taxon`/`Category` and are only excluded at the API layer).
-4. **Drop `Taxonomy`** — remove the model, table, and the `taxonomy_id` column. Also removes `Product#brand_taxon` / `#brand_name` (brands are out of scope for 6.0 — see Key Decisions → Brands).
+4. **Drop `Taxonomy`** — remove the model, table, and the `taxonomy_id` column (6.1). The brand methods `Product#brand_taxon` / `#brand_name` (the only remaining `Taxonomy`-dependent runtime path) are removed in **6.0 (Phase 3)**; brands are out of scope with no replacement (see Key Decisions → Brands).
## Key Decisions (do not deviate without discussion)
@@ -107,7 +107,7 @@ Two product-count concepts, named consistently across grouping models. `products
**Decision:** Spree 6.0 ships **no brand-specific construct** — no `Spree::Brand` model, no brand attribute/column, no `:brands` tag context, no category `kind` column. The going-forward model is just **Category** (hierarchy) + **Collection** (curated/rule-based); a store that wants to group products by brand models it as a regular Category or Collection like any other grouping.
-- The existing `Product#brand_taxon` / `#brand_name` and the "Brands" taxonomy convention are **removed along with `Taxonomy`**, with no replacement. The brand lookup was the only remaining `Taxonomy`-dependent runtime path, so removing it is what unblocks dropping `Taxonomy`.
+- The existing `Product#brand_taxon` / `#brand_name` and the "Brands" taxonomy convention are **removed with no replacement**. The brand methods go in **6.0 (Phase 3)** — they were the only remaining `Taxonomy`-dependent runtime path, so removing them is what unblocks dropping `Taxonomy` itself (model/table) in 6.1.
- The `taxonomy_brands_name` locale key is removed.
- Rationale: none of the surveyed platforms model brand as a category, and a proper first-class brand is a larger feature than 6.0 warrants. Rather than ship a half-measure (brand-as-category or brand-as-tag), 6.0 ships nothing brand-specific — a dedicated `Spree::Brand` can be designed later (core or extension) without a rushed decision here.
@@ -196,7 +196,8 @@ class Spree::Collection < Spree.base_class
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
+ # Space format — required by the sort pipeline (FiltersAggregator splits on a space).
+ # Owned by Collection (Category is manual-only and no longer defines SORT_ORDERS).
# pipeline: FiltersAggregator#to_api_sort splits on a space ('price asc' -> 'price'),
# and apply_sort maps to 'price'/'-price'/'best_selling'. Underscores would break default_sort.
SORT_ORDERS = [
@@ -331,11 +332,16 @@ A scheduled job closes that gap for **time-based** rules:
```ruby
class Spree::Product < Spree.base_class
- # Categories (renamed from taxons/classifications)
+ # Categories (renamed from taxons/classifications). `manual`-scoped during the
+ # transition — automatic categories are migrated to Collections in Phase 4, after
+ # which the scope is a no-op; it (and `taxons`) are dropped in 6.1.
has_many :product_categories, dependent: :delete_all, inverse_of: :product
- has_many :categories, through: :product_categories
- # Backward compat alias (deprecation period)
- alias_method :taxons, :categories
+ has_many :categories, -> { manual }, through: :product_categories, source: :category
+ # Deprecation period (removed in 6.1). `taxons` stays a *real* association (not an
+ # alias_method) because it is Ransack-whitelisted (`taxons_id_in`) and Ransack
+ # needs a reflectable association; it lists every category via the join.
+ # `classifications` is a plain method alias (it is not Ransack-whitelisted).
+ has_many :taxons, through: :product_categories, source: :category, before_remove: :remove_category
alias_method :classifications, :product_categories
# Collections (new)
@@ -544,6 +550,14 @@ class RenameTaxonsToCategories < ActiveRecord::Migration[7.2]
# the rename — do NOT re-add it. Backfill first:
# bundle exec rake spree:taxons:backfill_store_id
+ # Promotion↔category join + Mobility translations rename now too, so no class
+ # needs a table_name/foreign_key pin. (spree_taxon_rules + spree_prototype_taxons
+ # keep taxon_id — dropped in 6.1 / renamed by 6.0-product-types respectively.)
+ rename_table :spree_promotion_rule_taxons, :spree_promotion_rule_categories
+ rename_column :spree_promotion_rule_categories, :taxon_id, :category_id
+ rename_table :spree_taxon_translations, :spree_category_translations
+ rename_column :spree_category_translations, :spree_taxon_id, :spree_category_id
+
# Counter caches (category side): keep products_count (descendant-inclusive,
# already present); drop the direct classification_count (only the legacy Rails
# admin read it). collections_count was added additively in Phase 1.
@@ -571,7 +585,7 @@ end
**Additional Phase 2 decisions (implemented):**
- **`classification_count` is dropped now** (not deferred). The direct taxon-side Rails counter was only read by the legacy `spree/admin` engine; the descendant-inclusive `products_count` is kept. The product-side counter is renamed `classification_count` → `categories_count`. `Classification`'s counter_cache follows to `categories_count`; the three taxon bulk services recompute `products_count` via `recalculate_products_count` instead of the removed counter. Legacy `spree/admin` views that read `taxon.classification_count` are **not** fixed (that engine is being replaced by the SPA) — the specs they break are marked `pending`.
-- **Mobility translation table is pinned transitionally.** Setting `Spree::Taxon.table_name = 'spree_categories'` makes Mobility derive `spree_category_translations` / `spree_category_id`, but that table is still `spree_taxon_translations` (renamed in 6.1). So the `translates` call pins `table_name: 'spree_taxon_translations', foreign_key: 'spree_taxon_id'` until the 6.1 sweep.
+- **Mobility translation table is renamed here too** (`spree_taxon_translations` → `spree_category_translations`, `spree_taxon_id` → `spree_category_id`), for consistency with the other table renames. Once the class is renamed to `Spree::Category` (Phase 3), Mobility derives `spree_category_translations` / `spree_category_id` naturally, so **no `translates` pin** is needed in delivered 6.0. (A Phase-2-only intermediate — class still `Spree::Taxon`, table already renamed — would need a transient pin to the *new* table, but 6.0 ships all phases together.)
- **Automatic-taxon matching code is removed here** (see Phase 3 rationale). Because 6.0 is single-delivery, the taxon auto-match path doesn't need to survive the rename: deleted `Products::AutoMatchTaxons` (+ job), `Taxons::RegenerateProducts`, `Product#auto_match_taxons` + `after_commit`, `Product.bulk_auto_match_taxons`, `Taxon#regenerate_taxon_products` + `after_commit`, and the `TaxonRule` regeneration callback. Rule-based membership now lives on `Collection`. `Price` re-match + the bulk-tags API endpoint now trigger `auto_match_collections` / `Product.bulk_auto_match_collections`; the bulk-category endpoints no longer re-match (category membership never affected rule matching).
- **`eligible_for_taxon_matching?` → `eligible_for_collection_matching?`** (the `Product` predicate + the `Price` attribute).
@@ -583,11 +597,18 @@ Now that Collections exist (Phase 1) and the tables are renamed (Phase 2), renam
- `Spree::Taxonomy` → deprecated, no replacement
- `Spree::Classification` → `Spree::ProductCategory` (alias for one release)
- `Spree::PromotionRuleTaxon` → `Spree::PromotionRuleCategory`; `Spree::Promotion::Rules::Taxon` → `Spree::Promotion::Rules::Category` (wire format is already `category` — `api_type` / `category_ids` — so the API contract is unchanged)
+- **The rename is Ruby-level, not just class names: associations and methods go to `category` now.** The join models expose `belongs_to :category` (`ProductCategory`, `PromotionRuleCategory`), `Category`/`Product` expose `has_many :product_categories`, and the promotion rule exposes `has_many :promotion_rule_categories` + `has_many :categories` with category-named internals (`eligible_category_ids`, `category_ids_in_order_including_ancestors`, `add_categories`, `category_ids_to_add`). Because Phase 2 renames the join tables too (`spree_product_categories`, `spree_promotion_rule_categories`, `spree_category_translations` + their `category_id`/`spree_category_id` columns), **no `foreign_key`/`table_name`/`translates` pins are needed** — the natural `category_id` is used everywhere and Mobility derives `spree_category_translations` on its own. Pins remain **only** for the join tables that are *not* renamed in this plan: `Category#has_many :prototype_taxons, foreign_key: :taxon_id` (`spree_prototype_taxons` is renamed by `6.0-product-types.md`) and `Category#has_many :taxon_rules, foreign_key: :taxon_id` (`spree_taxon_rules` is dropped in 6.1). A `belongs_to :taxon, foreign_key: :category_id` — new name paired with a renamed column — is the exact backwards state to avoid.
+- **`Product`/`Store` keep `categories` as the one real, canonical association** (`-> { manual }`); `taxons` is a **deprecated method alias** of `categories`, not a real association (removed in 6.1). `taxons` is therefore dropped from the Product Ransack whitelist — filter by `categories_id_in` (the v3 API uses the `in_taxon`/`in_category` scopes, not `taxons_` ransack). Other deprecated method aliases bridge old names for one release: `taxon`/`taxon=` on the join models; `taxons`/`taxon_ids`/`eligible_taxon_ids`/`taxon_ids_to_add` on the rule; `classifications` on `Product`/`Category`.
- **Automatic-taxon matching code was removed in Phase 2, not here** — since 6.0 ships all phases at once (no released intermediate state), the taxon auto-match services + triggers were deleted in Phase 2 and rule-based membership moved to `Collection`. `Spree::TaxonRule` / `TaxonRules::*` remain as **data-only** models.
- **Dropping `spree_taxon_rules` + `Spree::TaxonRule` / `TaxonRules::*` + the `config.spree.taxon_rules` registry is deferred to 6.1 (Phase 6), NOT 6.0.** The Phase 4 data migration *reads* `spree_taxon_rules` to build `CollectionRules`, but schema migrations (`db:migrate`) run automatically at deploy while the data migration is a manual rake task run afterward — a same-release `drop_table` would wipe the source before the data task runs. So the table + models are retained through 6.0 and dropped in 6.1.
-- The Mobility translation-table pin from Phase 2 carries over to `Spree::Category`; the actual table rename (`spree_taxon_translations` → `spree_category_translations` + FK) and dropping the pin are 6.1 (Phase 6).
- 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
+- **Stored class-name strings become `'Spree::Category'`** — the metafield/translation resource_type registries move to `'Spree::Category'`, and renamed classes write the new name into polymorphic/STI/slug columns. Existing rows still hold `'Spree::Taxon*'`; they're backfilled by the **Phase 4** data migration (see its step 4). This is a deliberate reversal of the Phase 2 pin-the-old-name approach — 6.0 does NOT keep using `'Spree::Taxon'` in data.
+- **De-rule `Spree::Category` at the model level** (the `automatic`/`rules_match_policy`/`sort_order` columns + `spree_taxon_rules` table stay for the Phase 4 migration, dropped in 6.1): remove `products_matching_rules`, the `taxon_rules` association + `accepts_nested_attributes_for` + `rules` alias, the `rules_match_policy`/`sort_order` validations, `scope :automatic`, and `manual_sort_order?`. **`SORT_ORDERS` + `RULES_MATCH_POLICIES` move to `Spree::Collection`** (its rightful owner); `FiltersAggregator` reads `Spree::Collection::SORT_ORDERS`. `scope :manual` + the `manual?`/`automatic?` column readers stay (the manual scope guards the category surfaces). `TaxonRule#belongs_to :taxon` drops its now-dangling `inverse_of: :taxon_rules`.
+- **Brand removal (moved here from 6.1):** delete `Product#brand_taxon` / `#brand_name` (+ the `MEMOIZED_METHODS` entry), the `brand` field on the Products Performance report, and the `brand_name` column from the product CSV export — brands are out of scope with no replacement (see Key Decisions → Brands). The `spree_taxonomies` table + `taxonomy_brands_name` locale key still drop in 6.1 with `Taxonomy`; only the brand *methods/fields* go now.
+- **Wording sweep** (Ruby names → category): `Product#main_taxon` → `#primary_category` (deprecated delegate), `touch_taxons` → `touch_categories`, `Spree::Products::TouchTaxonsJob` → `TouchCategoriesJob` + `Spree.queues.taxons` → `categories` (both with deprecation aliases), `taxon_and_ancestors` → `category_and_ancestors`, `remove_taxon` → `remove_category`, the `grouped_taxon_ids_for_products` scope → `grouped_category_ids_for_products`, and `recalculate_products_count`'s param; delete the dead, buggy `Product#taxons_for_store`. Comments/param names across `Category`/`Product` de-taxoned.
+- **Remove the deprecated taxon-tied `Product` scopes** marked remove-in-6.0: `in_taxons`, `for_filters`, `taxons_name_eq`, plus their now-orphaned private helpers `prepare_taxon_conditions` / `get_taxons`. The active scopes stay (`in_taxon`, `in_category`, `in_categories`, `in_collection`, `ascend_by_taxons_min_position`). Non-taxon deprecated scopes (master-price, option, name, etc.) are left for their own plans.
+- **Rename the manual-membership services** `Spree::Taxons::AddProducts` / `RemoveProducts` → `Spree::Categories::AddProducts` / `RemoveProducts` (param `taxons:` → `categories:`, matching `Spree::Collections::*`). No alias — a clean 6.0 break with all monorepo callers updated (Phase 2 already removed the sibling `Spree::Taxons::RegenerateProducts` without one). The optional `Spree::Taxons::TouchFeaturedSections` hook (guarded by `defined?`, its namespace owned by another gem) is left untouched.
### Phase 4: Data migration (rake task)
@@ -610,6 +631,16 @@ Runs after the Phase 2 rename **and the Phase 3 class rename** — so the script
# categories; merchants re-file them as collections via the new UI
# (safe, reversible — no name-based guessing)
# 3. Drop the now-empty taxonomy roots and the taxonomy_id references
+# 4. Backfill stored class-name strings 'Spree::Taxon*' -> 'Spree::Category*'
+# (Phase 3 renamed the classes and writes the new names; existing rows still
+# hold the old ones, so migrate them here):
+# - spree_metafields.resource_type
+# - spree_metafield_definitions.resource_type
+# - friendly_id_slugs.sluggable_type
+# - active_storage_attachments.record_type (taxon image / square_image)
+# - spree_promotion_rules.type (Promotion::Rules::Taxon -> Category, STI)
+# Direct FK columns (taxon_id/category_id) and the pinned translation table
+# need no change. Same rake run as above, so no additional upgrade window.
#
# Handles both upgraded stores (may have localized/renamed standard trees) and
# new 5.5+ stores (arbitrary or zero taxonomies).
@@ -627,10 +658,11 @@ Gated on the channels plan finishing the `available_on` → `ProductPublication#
- Remove all aliases and deprecation shims (incl. the `Spree::Taxon` alias and the `classification_count` `alias_attribute`)
- Remove `taxonomy_id` column from categories
-- Remove `spree_taxonomies` table, plus `Product#brand_taxon` / `#brand_name` and the `taxonomy_brands_name` locale key (brands out of scope — no replacement)
+- Remove `spree_taxonomies` table + the `taxonomy_id` column + the `taxonomy_brands_name` locale key (brands out of scope — no replacement; `Product#brand_taxon`/`#brand_name` were already removed in 6.0/Phase 3)
- Remove `automatic`, `rules_match_policy`, `sort_order` columns from categories (moved to collections)
- **Drop `spree_taxon_rules` + `Spree::TaxonRule` / `TaxonRules::*` + the `config.spree.taxon_rules` registry** (retained data-only through 6.0 so the Phase 4 data migration can read them; rows were copied to `spree_collection_rules`, and `CollectionRule` is net-new so there's no alias to keep)
-- Rename the Mobility translation table `spree_taxon_translations` → `spree_category_translations` (+ FK `spree_taxon_id` → `spree_category_id`) and drop the transitional `table_name`/`foreign_key` pin on `translates`
+- Remove the deprecated Ruby-level aliases kept through 6.0: the `taxons` and `classifications` method aliases on `Product`/`Category`/`Store`, the `taxon`/`taxon=` readers on the join models, and the rule's `taxons`/`taxon_ids`/`eligible_taxon_ids`/`taxon_ids_to_add` aliases
+- Rename `spree_prototype_taxons` (with `6.0-product-types.md`), dropping the `foreign_key: :taxon_id` pin on `Category#prototype_taxons` (the `#taxon_rules` pin goes away with the `spree_taxon_rules` drop above)
## Constraints on Current Work