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.

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.md
index 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.ts
index 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.ts
index 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.rb
index 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'
end
diff --git a/spree/core/app/services/spree/seeds/saved_reports.rb b/spree/core/app/services/spree/seeds/saved_reports.rb
index 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 Spree
REPORTS.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 Spree
end
end
end
+
+ 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
+ end
end
end
end
diff --git a/spree/core/db/migrate/20260903120000_create_spree_saved_reports.rb b/spree/core/db/migrate/20260903120000_create_spree_saved_reports.rb
index 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.timestamps
end
- 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
+ end
end
end
diff --git a/spree/core/lib/spree/reporting/adapters/live.rb b/spree/core/lib/spree/reporting/adapters/live.rb
index 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 == :orders
scope
end
diff --git a/spree/core/spec/lib/spree/reporting/query_spec.rb b/spree/core/spec/lib/spree/reporting/query_spec.rb
index 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 do
expect(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' do
result = run(metrics: %w[units_sold],
filters: [{ dimension: 'category', op: 'in', value: categories.map(&:prefixed_id) }])
@@ -507,9 +522,11 @@ RSpec.describe Spree::Reporting::Query do
result = 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)
end
it 'groups by payment status without a lookup' do
diff --git a/spree/core/spec/services/spree/seeds/saved_reports_spec.rb b/spree/core/spec/services/spree/seeds/saved_reports_spec.rb
index 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 do
end
end
+ 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' do
create(:saved_report, store: store, name: 'top products')