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.

Update taxons-to-categories plan: DB manual sort shipped, Meilisearch options

Łukasz Adamczyk2a2778d676e6
diff --git a/docs/plans/6.0-replace-taxons-with-categories.md b/docs/plans/6.0-replace-taxons-with-categories.md
index fb9eb0c18d..a5d438e154 100644
--- a/docs/plans/6.0-replace-taxons-with-categories.md
+++ b/docs/plans/6.0-replace-taxons-with-categories.md
@@ -4,7 +4,7 @@
**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), 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-09
+**Last updated:** 2026-07-16
## Summary
@@ -50,7 +50,7 @@ Much of the **Category** half has already shipped (5.5–5.6). What exists today
**No longer true:** default taxonomies ("Categories", "Brands", "Collections") and automatic taxons ("On Sale", "New Arrivals") are **no longer auto-created per store** — `Store#ensure_default_taxonomies_are_created` / `ensure_default_automatic_taxons` were deprecated (2026-03-10) and removed in 5.5 (PR #14020, 2026-05-11). New stores get no taxonomies; categories are created on demand. The `taxonomy_*_name` locale keys remain (only `brand_taxon` still reads `taxonomy_brands_name`).
-**Known gap — "manual" sort in the v3 Store API.** "Manual" sort means ordering products by their hand-set position *within the grouping* (`Classification.position` → `ProductCategory.position`). Today it works only in the admin nested products controller and the legacy `Spree::Products::Find` finder — it is **not** implemented in the v3 search-provider path: `SearchProvider::Database#apply_sort` has no `'manual'` branch and never receives the category/collection context, and the Meilisearch provider indexes no position and can't sort by a per-grouping (many-valued) join position. So a category page's default "manual" sort does not currently reflect the merchant's hand-ordering on the v3 API. This affects **collections too**: their dedicated endpoint still lists through the provider (the collection is applied as a filter, not an AR pre-scope), so it can't bypass the provider to order by position. The fix is provider-level and shared by both — see Open Questions.
+**Known gap — "manual" sort in the v3 Store API (Meilisearch only).** "Manual" sort means ordering products by their hand-set position *within the grouping* (`ProductCategory.position` / `ProductCollection.position`). The **DB provider now implements it** (shipped): `SearchProvider::Database` infers the grouping from the applied `in_category`/`in_collection` filter, defaults a grouping page's blank sort to `manual`, and orders by `ProductCollection.position` (flat, for collections) or `MIN(ProductCategory.position)` collapsed per product (subtree, for categories) — reusing the join the filter already made, no extra query. The **Meilisearch provider still does not**: it indexes no position and can't natively sort by a per-grouping (many-valued) join position, so on MS-backed stores a category page's default sort and a `sort_order: 'manual'` collection PLP don't reflect the merchant's hand-ordering. The remaining fix is Meilisearch-only and must be **native** (no DB fallback) — see Open Questions.
## Remaining for 6.0
@@ -442,7 +442,7 @@ The **Store** response is the customer-facing subset — `id`, `name`, `slug`/`p
Products in a collection are served by a **dedicated endpoint**, not a filter on `/products`. This follows the Shopify Storefront GraphQL model (`collection { products }`) where the collection is the path context and filters/sort layer on top. (Most REST APIs — WooCommerce, Medusa, commercetools, BigCommerce — use a `?collection_id=` filter instead; we deliberately choose the nested style for cleaner requests and to apply the collection's own default sort automatically. `in_collection` is still kept as a Ransack scope for composite queries.)
- `GET /api/v3/store/collections/:id/products` — a thin controller that resolves the collection and **delegates to the same search-provider flow** as `/products` (query, Ransack filters, pagination, serializer). `def scope` stays the **base visibility scope** (`available` + `accessible_by`) — it is **not** pre-scoped to the collection. Instead the controller injects `in_collection: collection.prefixed_id` into the filters, and each provider applies it: the DB provider via the `in_collection` Ransack scope, Meilisearch via the `collection_ids` filter. Collection scoping has to be a provider filter (not an AR pre-scope) because Meilisearch does its own filtering/counting/pagination and treats the AR scope only as a post-search visibility guard. No logic duplication.
-- **Sort precedence.** Effective sort = the request's `sort` param if present, otherwise the collection's `sort_order`. Position ordering (`ProductCollection.position`) applies **only when the effective sort is `manual`**; any dynamic sort — whether from the collection's own default or a shopper override — dismisses it. Because the listing runs through the provider (for the `in_collection` filter, pagination, and faceting), manual sort **cannot** be handled by bypassing the provider with a direct AR query — it must be implemented *in* the provider. That's the same provider-level manual-sort fix categories need, which is **unresolved** (Open Question #1, approach TBD); until it lands, a `sort_order: 'manual'` collection falls back to default order. The dedicated endpoint does **not** sidestep the v3 manual-sort gap.
+- **Sort precedence.** Effective sort = the request's `sort` param if present, otherwise the collection's `sort_order`. Position ordering (`ProductCollection.position`) applies **only when the effective sort is `manual`**; any dynamic sort — whether from the collection's own default or a shopper override — dismisses it. Because the listing runs through the provider (for the `in_collection` filter, pagination, and faceting), manual sort is implemented *in* the provider, not by bypassing it with a direct AR query. The **DB provider ships this** (orders by `ProductCollection.position`); the **Meilisearch provider does not yet** (Open Question #1). On MS-backed stores a `sort_order: 'manual'` collection falls back to default order until the native solution lands; all dynamic sorts work on both providers.
- **Facets/sort metadata** reuse the existing `GET /api/v3/store/products/filters` with a new **`collection_id`** param (parallel to `category_id`): it resolves the collection, scopes `in_collection`, and passes **only the collection's `sort_order`** to `FiltersAggregator` — via a `sort_order:` string param, **not** the `Collection` object (the aggregator stays decoupled from the model). No child facet (collections are flat).
- **Model:** `Spree::Product.in_collection` scope (flat join to `spree_product_collections`, no descendants), whitelisted as a ransackable scope. (No `in_collections` plural — the collection surface is single-collection; add it only if a real multi-collection filter appears.)
- **Meilisearch:** index `collection_ids` (flat, no ancestors) on the product document, add it to `filterable_attributes` / `facet_attributes`, and handle `in_collection` in `build_filter_condition`. Kept fresh by `RegenerateProducts` (touches products + `enqueue_search_index`).
@@ -534,7 +534,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.
+- **Manual sort** — the **DB provider is shipped** (position ordering for both category and collection groupings); the **Meilisearch provider is still pending** a native solution (Open Question #1). On MS-backed stores a `sort_order: 'manual'` collection falls back to default order until it lands; all dynamic sorts work on both.
- **`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)
@@ -699,10 +699,15 @@ Gated on the channels plan finishing the `available_on` → `ProductPublication#
> - *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). 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).
+> - *"Manual" sort in the v3 Store API — DB provider* — **shipped.** `SearchProvider::Database` infers the grouping from the applied `in_category`/`in_collection` filter (`manual_sort_grouping`), defaults a grouping page's blank sort to `manual`, and orders by `ProductCollection.position` (flat) for collections or `MIN(ProductCategory.position)` grouped per product (subtree collapse) for categories — reusing the join the filter already made, so no extra query. The Meilisearch half stays open (Question #1).
-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:
- - **DB provider:** add a `'manual'` branch to `SearchProvider::Database#apply_sort` and thread the category/collection context into `search_and_filter` / `apply_sort` (they don't receive it today). For a **category** this orders by the grouping's min join-position (`ascend_by_taxons_min_position` — the `MIN`/`GROUP BY` collapses a product that sits under a category *and its descendants*). A **collection** needs no such scope: it's flat and a PLP targets one collection with a unique `(collection_id, product_id)`, so it's a plain `joins(:product_collections).where(collection_id:).order('spree_product_collections.position ASC')`.
- - **Meilisearch:** fall back to the DB for the manual case (resolve ordered ids via the min-position scope, bypassing MS sort); native per-grouping position sort isn't feasible (position is a many-valued join property; MS sorts only on fixed scalar attributes).
+1. **"Manual" sort in the v3 Store API — Meilisearch provider (needs a native solution).** The DB provider ships manual/position sort (see Resolved above); the Meilisearch provider does **not**, and it must reach DB-provider parity — manual order composing with facet filters and text search. **A DB fallback is explicitly ruled out** — an MS-backed store must not route its hot listing path back through the database. The core tension: position is a *per-grouping* value (a product has a different position in each collection, and a subtree-MIN per category), while Meilisearch can only sort on attributes it has been told are sortable. Two native approaches keep the sort/filter/search composition inside Meilisearch; they trade a second index against an anti-pattern on the existing one:
+
+ - **Option 1 — Denormalized "membership" index (best practice).** Add a **second** MS index, one document per (product × grouping × locale × currency), carrying `grouping_id` + a scalar `position` + the full filterable/searchable payload. A grouping page runs one native query against index B (`filter grouping_id = X` + facets + text query, `sort position:asc`, native pagination); index A (products) stays untouched and serves shop-all/search. **Pros:** clean scalar sort, no anti-patterns, scales to any number of groupings, index A unchanged. **Cons:** a second index ~5–8× the product index (membership × ancestor depth × locale × currency) plus dual-write sync on every product/membership change.
+
+ - **Option 2 — Nested position map + registered sortable attributes (single index, anti-pattern).** Keep only the current product index; add a nested object to each product document — `group_positions: { <grouping_id> => position }` (collections: the flat position; categories: the precomputed subtree-MIN) — and **register each grouping's path** (`group_positions.<grouping_id>`) as a sortable attribute, so a grouping page sorts by `group_positions.<grouping_id>:asc` natively (an object with scalar leaves, not an array, so it avoids the array-sort global-min/max trap). **Pros:** one index, tiny added payload, no second-index dual-write. **Cons:** it is the documented Meilisearch **anti-pattern** — sortable/filterable attributes are meant to be a small *static* set, not one-per-entity. The sortable-attributes list grows with the number of collections + categories; every grouping create/delete requires an index **settings update**, which forces a **reindex** and is slow; there are practical limits on how many sortable attributes an index can carry. Viable only for stores with a small, stable set of groupings.
+
+ **Leaning toward Option 1** for correctness and scalability despite the second-index cost. Either way, **not yet implemented** — the detailed Option 1 design (schema, sync matrix, presenter, verification) is tracked separately and deferred; the interim behavior is that MS-backed `sort_order: 'manual'` groupings fall back to default order.
## References