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
Record the reporting review rulings in the plan and decisions log
Damian Legawiecb7d3c2bd9a3b
diff --git a/docs/plans/6.0-analytics-semantic-layer.md b/docs/plans/6.0-analytics-semantic-layer.mdindex fa0ff5768f..45a6ada8e0 100644--- a/docs/plans/6.0-analytics-semantic-layer.md+++ b/docs/plans/6.0-analytics-semantic-layer.md@@ -4,7 +4,7 @@**Target:** Spree 6.0 (core + new dashboard home + Reports page) → 6.1 (facts adapter, AI) — Enterprise ClickHouse adapter out of band**Depends on:** `6.0-admin-api.md` (v3 conventions), `5.5-admin-api-key-scopes.md` (scope gating), `6.0-multi-vendor-marketplace.md` (vendor forced scope + vendor dashboard consumer), `5.5-admin-api-cli.md` (first agent surface), `5.6-solid-queue-single-container.md` (fact writes + reconciliation jobs)**Author:** Damian + Claude-**Last updated:** 2026-09-03 (Steps 7–9 implemented)+**Last updated:** 2026-09-03 (Steps 7–9 implemented; Decision 13 review rulings)## Summary@@ -110,6 +110,17 @@ Settled before implementing Steps 7–9:- **Vocabulary**: the full Step 8 set ships now — presets, `week` grain, `market`/`country`/`variant` dimensions, `discounts_total`/`delivery_total`/`tax_total` metrics.- **Delivery**: Steps 7–9 land on the same branch as Steps 1–6 as one PR; the UI is needed in the wild to validate the plan.+### 13. Review rulings on the shipped Steps 7–9 (2026-09-03)++Settled while reviewing the implementation, recorded because they change what a report means:++- **Sales metrics count what stayed sold.** A canceled order keeps its `completed_at`, so both metric bases exclude `status: 'canceled'` explicitly. Refunds already net out of `payment_total`; cancellation is the one post-placement event that would otherwise inflate revenue and order counts forever.+- **The Total row is the dimensionless figure.** Grouping joins (product ↔ categories, order ↔ shipping address) apply only to the grouped query; the ungrouped totals run on the base rows with the same filters, so a product in three categories is counted once in the footer and an order without a shipping address still counts in "Sales by country". A filter on a joined dimension narrows through an id subquery for the same reason. Rows of a fan-out breakdown therefore need not sum to the total, and that is correct.+- **Built-in reports are read-only on the model, not just in the UI.** `Spree::SavedReport` refuses name/description/query changes on a seeded row (`seeded_report_read_only`); they can be copied or deleted. The dashboard mirrors this with "Save a copy".+- **Report exports are refused at create, not in the job.** `Spree::Exports::Report` compiles the query and checks the requesting user's members in a validation, so an unreadable or malformed query is a 422 the caller sees rather than an export that never becomes done. Key-created report exports stay unsupported (a user is required) until the export can carry the key's scopes.+- **Member authorization has one predicate.** `Query#unreadable_subjects(ability)` is what the query endpoint, the export and any future agent tool call; `Registry#compatible?(metric, dimension)` is the one base-compatibility rule the schema and the compiler share.+- **The fulfillment vocabulary is the rollup domain.** The `fulfillment_status` dimension publishes `backorder | canceled | partial | unfulfilled | fulfilled | delivered` — not the legacy `pending/ready/shipped` the model constant still carries for 6.1 removal.+## Design Details### Registry (`spree/core`)diff --git a/docs/plans/decisions.md b/docs/plans/decisions.mdindex 1dcfabe62f..c07047a668 100644--- a/docs/plans/decisions.md+++ b/docs/plans/decisions.md@@ -140,6 +140,13 @@ call on what a pickup date range promises when stock has to travel.**Decision:** This plan covers how goods **ship**; how the buyer **pays** is a separate subject with its own plan. Three findings drove it. **Deposits and net terms are two halves of one arrangement** — merchants combine them ("40% deposit, balance Net 30"), and the only native implementation in the market models the deposit as an attribute *on* a payment term. Shipping half the subject inside a shipping plan leaves a vocabulary with no way to set it and no home for the other half. **The arrangement belongs to the buyer, not the shipment** — a deposit is negotiated with a company; no comparable platform configures one per shipping method, and every one that offers deposits scopes them per product, per customer, or per order. **Two OSS plans already defer net terms** to a payment-terms plan that does not exist (`6.0-payment-method-rules.md`, `6.0-6.1-b2b-payment-terms.md`), so the destination was already named — it just had not been written.**Consequences:** No delivery method carries a `deposit_percentage`, and freight must not become a second place payment arrangements are configured. One piece is deliberately kept so the payment-terms plan starts from a hook rather than from patching: `Purchase#amount_due_at_checkout`, answering the full total through `Spree::Purchases::AmountDueAtCheckout` (registered in `Spree::Dependencies`), read by the four decisions that gate on money arriving — checkout requirements, both completion guards, and dispatch. Without it, an arrangement collecting part of the total up front has to patch those four independently. It ships with a spec proving the open-source answer is the total, and a spec registering a half-up-front replacement and proving checkout, completion and dispatch all follow it. What a new payment or gateway session *defaults* to, and the capture loop, still read `total`: those are amounts rather than decisions. Partial payments are untouched — they predate this work. A related fix rides along because it holds independently: dispatch now guards on `payment_total >= amount_due_at_checkout` rather than `paid?`, which required a positive total and so refused to ship a fully discounted or store-credit-paid order.+## 2026-09-04: Catalog audiences are alternatives, not layers — a company buyer is never also priced by their customer group (V-3570)++**Context:** `Catalog.for_context` consults a buyer's customer groups only when the company axis came back empty, so a merchant who put a shared range on a dealer group's company node and each trade tier on a customer group got tier prices that never applied — every dealer paid retail, with the catalog active, the audience assigned and the percentage saved. The code said two things about whether that was intended: the plan and the resolver describe a fallback chain, while `Spree::Catalog`'s class comment said visibility across applicable catalogs is their union, which reads as both audiences being consulted. The reading had to be ruled before either could be documented.++**Decision:** The fallback chain is the intended behaviour and stays: the company subtree if any of its nodes carry a catalog, otherwise the customer's groups, otherwise the channel's default catalog. A buyer is on one agreement, resolved from the nearest party to them — layering a personal segment's prices on top of a company's negotiated ones would price one purchase under two agreements at once, and which won would depend on catalog position rather than on anything a merchant chose. Trade tiers over a company tree are expressed as company assignments: the shared range on the root, each tier's catalog on the member companies or divisions in that tier (one tier catalog carries as many assignments as the tier has members). That route already works and is what the union-within-an-audience plus nearest-node-first pricing was built for. Customer group assignments remain for buyers not purchasing for a company at all — a retail loyalty tier, a staff discount.++**Consequences:** No behaviour change; the fix is that the code and the dashboard now say so. The class comment is corrected (it was the only place claiming the two audiences combine), the `for_context` and pricing-resolver comments read "or failing that" rather than "then", and the fallback carries an inline note. The dashboard states the precedence where a merchant can act on it: help text under the audience picker when a customer group is chosen, and a standing note on the audience card and wizard step whenever a group assignment is present, pointing at the company route for tier pricing. The developer docs stop framing the three ways of reaching a buyer as combining and carry the tier recipe as a warning. Three examples in `catalog_spec.rb` lock the ruling — the group dropping out once a company catalog exists, the group still applying when none does, and the subtree union when the tier is a company assignment. What is *not* solved: nothing detects a catalog assigned only to groups whose members are all company buyers, so such a catalog is still silently unreachable; a reachability warning needs the buyer population and is a separate piece of work.## 2026-09-04: Catalog audiences are alternatives, not layers — a company buyer is never also priced by their customer group (V-3570)