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
Fix: A breakdown dropped rows whose optional association was missing
Damian Legawiec4398c157f6c4
diff --git a/docs/plans/6.0-analytics-semantic-layer.md b/docs/plans/6.0-analytics-semantic-layer.mdindex 31b7719163..d42bbc2524 100644--- a/docs/plans/6.0-analytics-semantic-layer.md+++ b/docs/plans/6.0-analytics-semantic-layer.md@@ -115,7 +115,7 @@ Settled before implementing Steps 7–9: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.+- **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 — but they must never sum to *less*: dimension joins are LEFT joins (corrected 2026-09-10, they were inner), so a record whose optional association is missing groups under the NULL key that hydration renders as "Unassigned" rather than disappearing from the breakdown while the Total still counts it.- **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.@@ -316,6 +316,7 @@ Legacy surfaces: `Spree::Admin::AnalyticsConcern` untouched (legacy admin is mai- Time-range values are ISO 8601 dates or datetimes (`iso8601`, never `parse`); bare dates cover the store's whole day on either edge and the dashboard sends custom ranges as bare dates.- **No new hand-rolled aggregate endpoints.** New analytics needs go through the registry + `POST /reporting/query`; `dashboard/operations` (point-in-time counts) is the only bespoke endpoint that stays.+- **Dimension joins are LEFT joins.** An optional association (an order's shipping address, a product's categories) must produce an "Unassigned" group, never drop the row — the Total counts it either way, and a breakdown summing to less than its own total is a silent undercount.- **A new base is registered, never hardcoded** — `registry.base` declares its family, table, relation, time column and reachability; nothing in the compiler branches on a base name, and the `resolve_sql` table map is the only remaining place a new table is named.- **One family per query.** Sales, payments and inventory never mix — a metric from one family beside a metric from another is refused, not joined.- **The sales chain is the vocabulary** (Decision 14): `net_sales` and `total_sales` are the single definitions of revenue; do not re-derive either elsewhere, and do not reintroduce `gross_revenue`/`net_revenue` as names.diff --git a/packages/admin-sdk/src/params.ts b/packages/admin-sdk/src/params.tsindex c2362756ff..6d193ae721 100644--- a/packages/admin-sdk/src/params.ts+++ b/packages/admin-sdk/src/params.ts@@ -3055,8 +3055,6 @@ export interface SavedReportCreateParams {description?: string | null/** A reporting contract query — validated against the registry on save. */query: ReportingQuery- /** Visualization config; inferred from the query shape when omitted. */- viz?: Record<string, unknown> | null}export type SavedReportUpdateParams = Partial<SavedReportCreateParams>diff --git a/packages/dashboard/src/nav/default.ts b/packages/dashboard/src/nav/default.tsindex 89f001fa3a..3191537349 100644--- a/packages/dashboard/src/nav/default.ts+++ b/packages/dashboard/src/nav/default.ts@@ -265,6 +265,7 @@ nav.add({path: '/reports',icon: AnalyticsIcon,position: 600,+ subject: Subject.SavedReport,})nav.add({diff --git a/spree/api/app/controllers/spree/api/v3/admin/dashboard_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/dashboard_controller.rbindex 58a0ab7901..d9d98ffbeb 100644--- a/spree/api/app/controllers/spree/api/v3/admin/dashboard_controller.rb+++ b/spree/api/app/controllers/spree/api/v3/admin/dashboard_controller.rb@@ -29,8 +29,6 @@ module Spree(threshold || DashboardOperationsSerializer::DEFAULT_LOW_STOCK_THRESHOLD).clamp(1, 1000)end- private-def action_kind'read'enddiff --git a/spree/core/app/services/spree/seeds/saved_reports.rb b/spree/core/app/services/spree/seeds/saved_reports.rbindex ab3bc09d5e..07ef1b5757 100644--- a/spree/core/app/services/spree/seeds/saved_reports.rb+++ b/spree/core/app/services/spree/seeds/saved_reports.rb@@ -75,7 +75,11 @@ module SpreeREPORTS.each do |report|name = Spree.t("reporting.seeds.#{report[:key]}.name")- next if existing.include?(name.downcase)+ # Every locale's name for this report, not just the current one:+ # the name is translated, so a store seeded in one language and+ # re-seeded in another would otherwise recognise none of its own+ # built-ins and create a second full set.+ next if known_names(report[:key]).intersect?(existing)store.saved_reports.create!(name: name,@@ -86,6 +90,16 @@ module Spreeendendend++ private++ # The downcased name this report carries in every locale core ships.+ def known_names(key)+ @known_names ||= {}+ @known_names[key] ||= I18n.available_locales.filter_map do |locale|+ Spree.t("reporting.seeds.#{key}.name", locale: locale, default: nil)&.downcase+ end.to_set+ endendendenddiff --git a/spree/core/db/migrate/20260903120000_create_spree_saved_reports.rb b/spree/core/db/migrate/20260903120000_create_spree_saved_reports.rbindex 9cc242c091..59d30ac087 100644--- a/spree/core/db/migrate/20260903120000_create_spree_saved_reports.rb+++ b/spree/core/db/migrate/20260903120000_create_spree_saved_reports.rb@@ -1,4 +1,6 @@class CreateSpreeSavedReports < ActiveRecord::Migration[8.1]+ INDEX_NAME = 'index_spree_saved_reports_on_store_and_lower_name'.freeze+# docs/plans/6.0-analytics-semantic-layer.md — a saved report is a reporting# contract query owned by the store and shared with every staff member who# may read reports; its visualization is inferred from the query's shape.@@ -18,6 +20,38 @@ class CreateSpreeSavedReports < ActiveRecord::Migration[8.1]t.timestampsend- add_index :spree_saved_reports, [:store_id, :name], unique: true+ add_name_uniqueness_index+ end++ private++ # One report per name per store, compared case-insensitively so it matches+ # the model's validation and the seeder's idempotency check — both of which+ # already downcase. A case-sensitive index lets "Top products" and+ # "top products" both land, which is exactly the pair re-seeding produces.+ #+ # Written per adapter because MySQL and MariaDB reject the functional-index+ # syntax PostgreSQL and SQLite accept; they index a stored generated column+ # instead. Expression per the spree_price_lists precedent.+ def add_name_uniqueness_index+ if Spree.mysql?+ reversible do |dir|+ dir.up do+ execute <<~SQL.squish+ ALTER TABLE spree_saved_reports+ ADD COLUMN name_key VARCHAR(255)+ AS (LOWER(name)) STORED+ SQL+ add_index :spree_saved_reports, [:store_id, :name_key], unique: true, name: INDEX_NAME+ end++ dir.down do+ remove_index :spree_saved_reports, name: INDEX_NAME+ remove_column :spree_saved_reports, :name_key+ end+ end+ else+ add_index :spree_saved_reports, 'store_id, LOWER(name)', unique: true, name: INDEX_NAME+ endendenddiff --git a/spree/core/lib/spree/reporting/adapters/live.rb b/spree/core/lib/spree/reporting/adapters/live.rbindex d53c985e4c..cbfb20fb02 100644--- a/spree/core/lib/spree/reporting/adapters/live.rb+++ b/spree/core/lib/spree/reporting/adapters/live.rb@@ -142,10 +142,16 @@ module Spree# Dimension joins are declared from the dimension's own base. Reaching# an :orders dimension (e.g. the ship address) from the :line_items# base goes through the order association.+ # LEFT joins, always. A dimension's association is frequently optional —+ # an order need not have a shipping address, a product need not be in a+ # category — and an inner join drops those rows from the breakdown+ # while the ungrouped Total still counts them, so the rows quietly fail+ # to add up. Left-joining produces a NULL key instead, which is a real+ # group the hydration already renders as "Unassigned".def join_for(scope, dimension, base)return scope if dimension.joins.blank?- return scope.joins(dimension.joins) if dimension.base == base- return scope.joins(order: dimension.joins) if base == :line_items && dimension.base == :orders+ return scope.left_joins(dimension.joins) if dimension.base == base+ return scope.left_joins(order: dimension.joins) if base == :line_items && dimension.base == :ordersscopeenddiff --git a/spree/core/spec/lib/spree/reporting/query_spec.rb b/spree/core/spec/lib/spree/reporting/query_spec.rbindex 12233591b7..6114995fe2 100644--- a/spree/core/spec/lib/spree/reporting/query_spec.rb+++ b/spree/core/spec/lib/spree/reporting/query_spec.rb@@ -348,6 +348,21 @@ RSpec.describe Spree::Reporting::Query doexpect(result.totals[:net_sales][:value]).to eq(ungrouped.totals[:net_sales][:value])end+ it 'keeps a row whose optional association is missing, rather than dropping it' do+ # A digital order has no shipping address. An inner join would drop it+ # from the country breakdown while the Total still counted it, so the+ # rows would silently fail to add up.+ create(:completed_order_with_totals, store: store, completed_at: 2.days.ago).+ update_columns(ship_address_id: nil)++ grouped = run(metrics: %w[orders], dimensions: %w[country])+ ungrouped = run(metrics: %w[orders])++ expect(grouped.rows.sum { |row| row[:metrics][:orders][:value] }).+ to eq(ungrouped.totals[:orders][:value])+ expect(grouped.rows.map { |row| row[:dimensions][:country] }).to include(nil)+ end+it 'counts a line item once when a filter matches it through several categories' doresult = run(metrics: %w[units_sold],filters: [{ dimension: 'category', op: 'in', value: categories.map(&:prefixed_id) }])@@ -507,9 +522,11 @@ RSpec.describe Spree::Reporting::Query doresult = run(metrics: %w[net_sales units_sold], dimensions: %w[category], sort: '-net_sales')- expect(result.rows.length).to eq(1)expect(result.rows.first[:dimensions][:category]).to eq(category.id)expect(result.rows.first[:metrics][:units_sold][:value]).to be > 0+ # order2's products were never categorised, so they group under the+ # NULL key rather than dropping out of the breakdown entirely.+ expect(result.rows.map { |row| row[:dimensions][:category] }).to include(nil)endit 'groups by payment status without a lookup' dodiff --git a/spree/core/spec/services/spree/seeds/saved_reports_spec.rb b/spree/core/spec/services/spree/seeds/saved_reports_spec.rbindex 2741611399..0b17e2f13a 100644--- a/spree/core/spec/services/spree/seeds/saved_reports_spec.rb+++ b/spree/core/spec/services/spree/seeds/saved_reports_spec.rb@@ -22,6 +22,18 @@ RSpec.describe Spree::Seeds::SavedReports doendend+ it 'does not re-create the built-ins when the locale changes' do+ described_class.call+ seeded = store.saved_reports.seeded.count++ # The names are translated, so a store seeded in one language must still+ # recognise its own built-ins when the seeder next runs in another.+ I18n.with_locale(:de) do+ expect { described_class.call }.not_to change { store.saved_reports.count }+ end+ expect(store.saved_reports.seeded.count).to eq(seeded)+ end+it 'treats a merchant report differing only in case as already present' docreate(:saved_report, store: store, name: 'top products')