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): keep collection merchandising config out of the Store API

Łukasz Adamczykb8c3479c35bd
diff --git a/docs/plans/6.0-replace-taxons-with-categories.md b/docs/plans/6.0-replace-taxons-with-categories.md
index c9adccb7bb..35c523792b 100644
--- a/docs/plans/6.0-replace-taxons-with-categories.md
+++ b/docs/plans/6.0-replace-taxons-with-categories.md
@@ -397,7 +397,7 @@ PATCH /api/v3/admin/collections/:id
DELETE /api/v3/admin/collections/:id
```
-Collection response:
+Collection response (**Admin** — the Store serializer omits the merchandising config `automatic`, `rules_match_policy`, and `rules`; that's back-office state, not customer-facing):
```json
{
"id": "coll_k5nR8xLq",
@@ -413,12 +413,13 @@ Collection response:
"slug": "summer-sale"
}
```
+The **Store** response is the customer-facing subset — `id`, `name`, `slug`/`permalink`, `description`/`description_html`, `image_url`/`square_image_url`, `sort_order`, `hide_from_nav`, `position`, `meta_*`, `products_count` (+ `custom_fields` on expand) — with **no** `automatic`/`rules_match_policy`/`rules` (internal merchandising state stays out of the Store API, per the store-vs-admin serializer rule).
### Collection product listing (Store API)
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.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.
+- `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.
- **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.)