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.

Describe the reporting contract and widen its vocabulary

Damian Legawiecf1b49b9ba169
diff --git a/docs/plans/6.0-analytics-semantic-layer.md b/docs/plans/6.0-analytics-semantic-layer.md
index e6cb14d416..f87e75be64 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; Decision 13 review rulings)
+**Last updated:** 2026-09-03 (Decision 12)
## Summary
@@ -110,17 +110,6 @@ 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`)
@@ -256,7 +245,7 @@ Legacy surfaces: `Spree::Admin::AnalyticsConcern` untouched (legacy admin is mai
- **Fact currency handling**: per-currency fact rows (query one currency at a time, mirroring Live) vs converted-at-write "reporting currency" columns. Leaning per-currency rows; conversion is a display concern until merchants demand blended totals.
- **Store timezone changes** restate historical day buckets in the facts adapter — accept + document, or version the timezone per row?
-- **SavedReport visibility**: store-wide vs per-user rows (execution-time authorization is decided — Step 9); how seller-scoped saved reports appear in the seller panel.
+- **Seller-scoped saved reports**: how store-wide saved reports appear in the seller panel once the seller forced scope lands (visibility itself is decided — Decision 12).
- **Checks/alerts** (Blazer-style scheduled saved-report thresholds → email/webhook): follow-up plan or a rider on the facts-adapter work?
- **Operations "state metrics"**: the operations card stays a bespoke point-in-time endpoint on this branch (decided — see Implementation Path); whether time-less "state metrics" ever join the registry is deferred until a second consumer wants them.
diff --git a/spree/api/app/controllers/spree/api/v3/admin/reporting_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/reporting_controller.rb
index b01d0a2227..ab69940e1c 100644
--- a/spree/api/app/controllers/spree/api/v3/admin/reporting_controller.rb
+++ b/spree/api/app/controllers/spree/api/v3/admin/reporting_controller.rb
@@ -28,8 +28,14 @@ module Spree
end
# GET /api/v3/admin/reporting/schema
+ #
+ # Filtered to what this caller may reference: pickers never offer,
+ # and agents never propose, a member that would be refused.
def schema
- render json: Spree.reporting.schema
+ render json: Spree::Reporting::Schema.new(
+ store: current_store,
+ allowed: ->(dimension) { dimension_allowed?(dimension) }
+ ).to_h
end
private
@@ -63,7 +69,16 @@ module Spree
)
else
authorize!(:read, :reports)
- reporting_query.required_subjects.each { |subject| authorize!(:read, subject) }
+ forbidden = reporting_query.unreadable_subjects(current_ability).first
+ raise CanCan::AccessDenied.new(nil, :read, forbidden) if forbidden
+ end
+ end
+
+ def dimension_allowed?(dimension)
+ if current_api_key.present?
+ dimension.key_scope.blank? || current_api_key.has_scope?(dimension.key_scope)
+ else
+ dimension.subject.nil? || can?(:read, dimension.subject.call)
end
end
diff --git a/spree/api/app/serializers/spree/api/v3/admin/reporting_result_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/reporting_result_serializer.rb
index 67a0d9a61b..447667e61a 100644
--- a/spree/api/app/serializers/spree/api/v3/admin/reporting_result_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/admin/reporting_result_serializer.rb
@@ -3,9 +3,8 @@ module Spree
module V3
module Admin
# Decorates a Spree::Reporting::Result for the wire: money display
- # strings, ISO ranges, and dimension hydration — raw group keys become
- # { id, label, meta } display payloads via each dimension's registered
- # `hydrate` lambda, batched once per dimension across all rows.
+ # strings, ISO ranges, and dimension hydration (raw group keys become
+ # { id, label, meta } display payloads — see Spree::Reporting::Hydration).
class ReportingResultSerializer
attr_reader :result, :store, :params
@@ -50,29 +49,11 @@ module Spree
end
def dimension_value(name, raw)
- return raw unless dimension_defs[name].hydrate
-
- hydrated_dimensions[name][raw] || { id: nil, label: raw.to_s, meta: {} }
- end
-
- def dimension_defs
- @dimension_defs ||= Hash.new { |cache, name| cache[name] = Spree.reporting.dimension!(name) }
+ hydration.value(name, raw)
end
- # One batched `hydrate` call per hydrated dimension across all rows.
- def hydrated_dimensions
- @hydrated_dimensions ||= begin
- keys = Hash.new { |h, k| h[k] = [] }
- result.rows.each do |row|
- row[:dimensions].each do |name, raw|
- keys[name] << raw if dimension_defs[name].hydrate
- end
- end
-
- keys.to_h do |name, raws|
- [name, dimension_defs[name].hydrate.call(store, raws.uniq, params)]
- end
- end
+ def hydration
+ @hydration ||= Spree::Reporting::Hydration.new(result, store: store, params: params)
end
end
end
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/reporting_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/reporting_controller_spec.rb
index a31d1bbded..d3b240b272 100644
--- a/spree/api/spec/controllers/spree/api/v3/admin/reporting_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/admin/reporting_controller_spec.rb
@@ -8,6 +8,15 @@ RSpec.describe Spree::Api::V3::Admin::ReportingController, type: :controller do
before { request.headers.merge!(headers) }
describe 'POST #query' do
+ it 'hydrates enumerated dimensions with labels' do
+ create(:completed_order_with_totals, store: store, completed_at: 2.days.ago).update_columns(payment_status: 'partially_paid')
+
+ post :query, params: { metrics: %w[orders_count], dimensions: %w[payment_status] }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ expect(json_response['rows'].first['dimensions']['payment_status']).to eq('id' => 'partially_paid', 'label' => 'Partially paid', 'meta' => {})
+ end
+
subject { post :query, params: query_params, as: :json }
let(:query_params) do
@@ -171,14 +180,40 @@ RSpec.describe Spree::Api::V3::Admin::ReportingController, type: :controller do
end
describe 'GET #schema' do
- it 'returns the registry introspection payload' do
+ it 'returns the self-describing contract' do
get :schema, as: :json
expect(response).to have_http_status(:ok)
- metric_names = json_response['metrics'].map { |m| m['name'] }
- expect(metric_names).to include('net_revenue', 'orders_count', 'aov')
+ metric = json_response['metrics'].find { |m| m['name'] == 'gross_revenue' }
+ expect(metric).to include('label', 'description', 'format', 'currency')
dimension = json_response['dimensions'].find { |d| d['name'] == 'completed_at' }
- expect(dimension['grains']).to include('day')
+ expect(dimension['grains']).to include('day', 'week', 'month')
+ expect(json_response['time_range']['presets']).to be_present
+ expect(json_response['meta']).to include('currency', 'timezone')
+ end
+
+ it 'omits members a secret key cannot reference' do
+ key = create(:api_key, :secret, store: store, scopes: %w[read_reports])
+ request.headers['x-spree-api-key'] = key.plaintext_token
+ request.headers['Authorization'] = nil
+
+ get :schema, as: :json
+ names = json_response['dimensions'].map { |d| d['name'] }
+ expect(names).to include('channel', 'completed_at')
+ expect(names).not_to include('product', 'customer', 'category')
+ end
+
+ context 'for a limited staff role' do
+ include_context 'API v3 Admin with custom permissions'
+
+ let(:custom_permissions) { %w[read_reports read_orders] }
+
+ it 'omits dimensions whose subject the role cannot read' do
+ get :schema, as: :json
+ names = json_response['dimensions'].map { |d| d['name'] }
+ expect(names).to include('channel', 'market', 'country')
+ expect(names).not_to include('product', 'customer')
+ end
end
end
end
diff --git a/spree/core/config/locales/en.yml b/spree/core/config/locales/en.yml
index 46b72b8568..1cb993465f 100644
--- a/spree/core/config/locales/en.yml
+++ b/spree/core/config/locales/en.yml
@@ -642,6 +642,7 @@ en:
errors:
messages:
already_confirmed: was already confirmed
+ forbidden_reporting_member: references data you are not allowed to read
invalid_document_number_affix: 'can only contain uppercase letters, digits, dashes and #'
invalid_system_key: can only contain lowercase letters, digits and underscores
locked_after_first_number: cannot change once numbering has started
@@ -652,6 +653,7 @@ en:
one: '1 error prohibited this %{resource} from being saved:'
other: "%{count} errors prohibited this %{resource} from being saved:"
refund_amount_requires_shared_payment: can only be set when the payment is shared across a split checkout
+ seeded_report_read_only: is a built-in report and cannot be changed — save a copy instead
number:
currency:
format:
@@ -1682,6 +1684,143 @@ en:
report_names:
products_performance: Products performance
sales_total: Sales total
+ reporting:
+ dimensions:
+ category:
+ description: The category the sold product belongs to.
+ label: Category
+ channel:
+ description: The channel the order came through.
+ label: Sales channel
+ completed_at:
+ description: When the order was placed, bucketed by day, week or month in the store timezone.
+ label: Date
+ country:
+ description: Country of the shipping address (ISO code).
+ label: Shipping country
+ customer:
+ description: The customer who placed the order, by email.
+ label: Customer
+ fulfillment_status:
+ description: Fulfillment state of the order.
+ label: Fulfillment status
+ market:
+ description: The market the order was placed in.
+ label: Market
+ payment_status:
+ description: Payment state of the order.
+ label: Payment status
+ product:
+ description: The product sold.
+ label: Product
+ variant:
+ description: The product variant (SKU) sold.
+ label: Variant
+ export:
+ total: Total
+ metrics:
+ aov:
+ description: Total sales divided by the number of orders.
+ label: Average order value
+ customers_count:
+ description: Distinct customer emails that placed orders.
+ label: Customers
+ delivery_total:
+ description: Sum of delivery charges.
+ label: Delivery
+ discounts_total:
+ description: Sum of order discounts.
+ label: Discounts
+ gross_revenue:
+ description: Sum of order totals (items, delivery and tax, after discounts).
+ label: Total sales
+ net_revenue:
+ description: Line item revenue after discounts and net of included taxes.
+ label: Net revenue
+ orders_count:
+ description: Number of placed orders.
+ label: Orders
+ tax_total:
+ description: Sum of additional and included taxes.
+ label: Tax
+ units_sold:
+ description: Sum of line item quantities.
+ label: Units sold
+ presets:
+ last_12_months:
+ label: Last 12 months
+ last_30_days:
+ label: Last 30 days
+ last_4_weeks:
+ label: Last 4 weeks
+ last_7_days:
+ label: Last 7 days
+ last_90_days:
+ label: Last 90 days
+ last_month:
+ label: Last month
+ last_quarter:
+ label: Last quarter
+ last_week:
+ label: Last week
+ month_to_date:
+ label: Month to date
+ quarter_to_date:
+ label: Quarter to date
+ today:
+ label: Today
+ week_to_date:
+ label: Week to date
+ year_to_date:
+ label: Year to date
+ yesterday:
+ label: Yesterday
+ seeds:
+ orders_by_fulfillment_status:
+ description: Order counts and sales grouped by fulfillment status over the last four weeks.
+ name: Orders by fulfillment status
+ orders_by_payment_status:
+ description: Order counts and sales grouped by payment status over the last four weeks.
+ name: Orders by payment status
+ sales_by_channel:
+ description: Sales and orders per sales channel over the last four weeks.
+ name: Sales by channel
+ sales_by_country:
+ description: Sales and orders by shipping country over the last four weeks.
+ name: Sales by country
+ sales_by_market:
+ description: Sales and orders per market over the last four weeks.
+ name: Sales by market
+ sales_over_time:
+ description: Daily sales, orders and average order value for the last four weeks, compared with the previous period.
+ name: Sales over time
+ top_categories:
+ description: Best-selling categories by net revenue over the last four weeks.
+ name: Top categories
+ top_customers:
+ description: Customers ranked by spend over the last four weeks.
+ name: Top customers
+ top_products:
+ description: Best-selling products by net revenue over the last four weeks.
+ name: Top products
+ unassigned: Unassigned
+ values:
+ fulfillment_status:
+ backorder: Backordered
+ canceled: Canceled
+ delivered: Delivered
+ fulfilled: Fulfilled
+ partial: Partially fulfilled
+ unfulfilled: Unfulfilled
+ payment_status:
+ authorized: Authorized
+ none: Unpaid
+ overcharged: Overcharged
+ paid: Paid
+ partially_paid: Partially paid
+ partially_refunded: Partially refunded
+ refunded: Refunded
+ voided: Voided
reports: Reports
required: "*"
required_fields: required fields
diff --git a/spree/core/lib/spree/reporting.rb b/spree/core/lib/spree/reporting.rb
index 5118be591e..3f6159fa29 100644
--- a/spree/core/lib/spree/reporting.rb
+++ b/spree/core/lib/spree/reporting.rb
@@ -1,7 +1,9 @@
require 'spree/reporting/registry'
require 'spree/reporting/default_vocabulary'
require 'spree/reporting/query'
+require 'spree/reporting/schema'
require 'spree/reporting/result'
+require 'spree/reporting/hydration'
require 'spree/reporting/adapters/base'
require 'spree/reporting/adapters/live'
@@ -16,6 +18,18 @@ module Spree
# Consumers (Admin API, dashboard, saved reports, AI tools) compose queries
# against registered names only — see Spree::Reporting::Query.
module Reporting
+ # Public URL for a media row a hydrated dimension carries, or nil when the
+ # record has no file. Mirrors what the API serializers render.
+ #
+ # @param media [Spree::Media, nil]
+ # @return [String, nil]
+ def self.image_url(media)
+ attachment = media.respond_to?(:attachment) ? media.attachment : media
+ return nil unless attachment.respond_to?(:attached?) && attachment.attached?
+
+ Rails.application.routes.url_helpers.cdn_image_url(attachment)
+ end
+
class UnknownMember < StandardError
attr_reader :kind, :name, :valid
diff --git a/spree/core/lib/spree/reporting/adapters/live.rb b/spree/core/lib/spree/reporting/adapters/live.rb
index 0eefd246e7..c6b2b142e6 100644
--- a/spree/core/lib/spree/reporting/adapters/live.rb
+++ b/spree/core/lib/spree/reporting/adapters/live.rb
@@ -13,7 +13,6 @@ module Spree
class Live < Base
def execute(query)
@query = query
- @store = query.store
current = period_data(query.time_range, push_sort: sql_sortable?)
previous = query.compare? ? period_data(query.previous_time_range, key_filter: compare_key_filter(current)) : nil
@@ -33,8 +32,6 @@ module Spree
private
- attr_reader :store
-
# ---- period execution ----
def period_data(range, push_sort: false, key_filter: nil)
@@ -51,15 +48,15 @@ module Spree
rows = Hash.new { |h, k| h[k] = {} }
query.aggregated_metrics.group_by(&:base).each do |base, metrics|
- scope = base_scope(base, range)
+ scope = base_scope(base, range, grouped: grouped)
selects = metrics.map { |m| "#{resolve_sql(m.sql)} AS #{metric_alias(m)}" }
if grouped
dimension_selects = query.dimensions.map do |d|
- "#{dimension_expression(d, base)} AS #{dimension_alias(d)}"
+ "#{dimension_expression(d)} AS #{dimension_alias(d)}"
end
- scope = scope.group(query.dimensions.map { |d| Arel.sql(dimension_expression(d, base)) })
- scope = apply_key_filter(scope, base, key_filter) if key_filter
+ scope = scope.group(query.dimensions.map { |d| Arel.sql(dimension_expression(d)) })
+ scope = apply_key_filter(scope, key_filter) if key_filter
scope = apply_sql_sort(scope, metrics) if push_sort
selects = dimension_selects + selects
end
@@ -74,24 +71,36 @@ module Spree
rows
end
+ # The grouped query carries the dimension joins; the ungrouped totals
+ # deliberately do not — a join that is not 1:1 with the base rows (a
+ # product in three categories, an order without a shipping address)
+ # would otherwise multiply or drop rows, and the Total row must equal
+ # the dimensionless figure for the same range and filters.
+ def base_scope(base, range, grouped:)
+ scope = base_relation(base, range)
+ scope = apply_dimension_joins(scope, base) if grouped
+ apply_filters(scope, base, range)
+ end
+
# The completed_at range predicate implies completeness, so neither
# base needs the `complete` scope on top (merging it would replace the
- # range condition — Rails merge overwrites same-column wheres).
- def base_scope(base, range)
+ # range condition — Rails merge overwrites same-column wheres). A
+ # canceled order keeps its completed_at, so it is excluded explicitly:
+ # sales figures count what stayed sold.
+ def base_relation(base, range)
+ order_conditions = { currency: query.currency, completed_at: range }
scope = case base
when :orders
- store.orders.where(currency: query.currency, completed_at: range)
+ query.store.orders.not_canceled.where(order_conditions)
when :line_items
- store.line_items
- .where(Spree::Order.table_name => { currency: query.currency, completed_at: range })
+ query.store.line_items.merge(Spree::Order.not_canceled)
+ .where(Spree::Order.table_name => order_conditions)
else
raise InvalidQuery, "unknown metric base #{base}"
end
# Association default orderings break grouped selects on PostgreSQL.
- scope = scope.reorder(nil)
- scope = apply_dimension_joins(scope, base)
- apply_filters(scope, base)
+ scope.reorder(nil)
end
# Dimension joins are declared from their own base; they only apply
@@ -99,33 +108,57 @@ module Spree
# joins line-item tables — validate_bases! guarantees compatibility).
def apply_dimension_joins(scope, base)
query.dimensions.each do |d|
- joins = d[:dimension].joins
- scope = scope.joins(joins) if joins.present? && d[:dimension].base == base
+ scope = join_for(scope, d[:dimension], base)
end
scope
end
- def apply_filters(scope, base)
+ # A filter on a joined dimension narrows through an id subquery rather
+ # than joining the aggregating scope itself: `category IN (a, b)` must
+ # keep a line item once even when its product sits in both categories.
+ def apply_filters(scope, base, range)
query.filters.each do |filter|
- column = qualified_column(filter[:dimension], base)
- scope = scope.joins(filter[:dimension].joins) if filter[:dimension].joins.present? && base == :line_items
- scope = scope.where("#{column} IN (?)", filter[:values])
+ dimension = filter[:dimension]
+ predicate = ["#{qualified_column(dimension)} IN (?)", filter[:values]]
+
+ if dimension.joins.blank?
+ scope = scope.where(*predicate)
+ else
+ # Bounded like the outer query (store, currency, range) so the
+ # planner starts from the same indexed slice.
+ table = scope.klass.table_name
+ ids = join_for(base_relation(base, range), dimension, base).where(*predicate).select("#{table}.id")
+ scope = scope.where("#{table}.id IN (#{ids.to_sql})")
+ end
end
scope
end
+ # 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.
+ 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
+
+ scope
+ end
+
# ---- sorted/limited rankings ----
# ORDER BY + LIMIT can move into SQL when one base group carries every
# aggregated metric (so the sort metric and the limit apply to the
# same query) and the grouping is by value, not time buckets.
def sql_sortable?
- query.sort && query.limit && query.time_dimension.nil? && query.dimensions.any? &&
- !sort_metric.derived? && query.aggregated_metrics.map(&:base).uniq.one?
+ return @sql_sortable unless @sql_sortable.nil?
+
+ @sql_sortable = query.sort && query.limit && query.time_dimension.nil? && query.dimensions.any? &&
+ !sort_metric.derived? && query.aggregated_metrics.map(&:base).uniq.one? || false
end
def sort_metric
- query.registry.metric!(query.sort[:metric])
+ @sort_metric ||= query.registry.metric!(query.sort[:metric])
end
def apply_sql_sort(scope, metrics)
@@ -146,9 +179,9 @@ module Spree
keys if keys.any?
end
- def apply_key_filter(scope, base, keys)
+ def apply_key_filter(scope, keys)
dim = query.dimensions.first
- scope.where("#{dimension_expression(dim, base)} IN (?)", keys)
+ scope.where("#{dimension_expression(dim)} IN (?)", keys)
end
# ---- SQL expressions ----
@@ -165,6 +198,7 @@ module Spree
line_items: Spree::LineItem.table_name,
variants: Spree::Variant.table_name,
products: Spree::Product.table_name,
+ addresses: Spree::Address.table_name,
product_categories: Spree::ProductCategory.table_name)
end
@@ -172,14 +206,14 @@ module Spree
"d_#{dim[:dimension].name}"
end
- def dimension_expression(dim, base)
+ def dimension_expression(dim)
dimension = dim[:dimension]
- return time_bucket_sql(qualified_column(dimension, base), dim[:grain]) if dimension.time?
+ return time_bucket_sql(qualified_column(dimension), dim[:grain]) if dimension.time?
- qualified_column(dimension, base)
+ qualified_column(dimension)
end
- def qualified_column(dimension, _base)
+ def qualified_column(dimension)
return resolve_sql(dimension.column) if dimension.column.is_a?(String)
table = dimension.base == :orders ? Spree::Order.table_name : Spree::LineItem.table_name
@@ -198,31 +232,31 @@ module Spree
def time_bucket_sql(column, grain)
case connection.adapter_name
when /postgres/i
- tz = store_time_zone.tzinfo.identifier
+ local = "#{column} AT TIME ZONE 'UTC' AT TIME ZONE '#{query.time_zone.tzinfo.identifier}'"
case grain
- when :day then "(#{column} AT TIME ZONE 'UTC' AT TIME ZONE '#{tz}')::date"
- when :month then "date_trunc('month', #{column} AT TIME ZONE 'UTC' AT TIME ZONE '#{tz}')::date"
+ when :day then "(#{local})::date"
+ when :week then "date_trunc('week', #{local})::date"
+ when :month then "date_trunc('month', #{local})::date"
end
when /mysql/i
- offset = format_offset(utc_offset)
+ local = "CONVERT_TZ(#{column}, '+00:00', '#{format_offset(utc_offset)}')"
case grain
- when :day then "DATE(CONVERT_TZ(#{column}, '+00:00', '#{offset}'))"
- when :month then "DATE_FORMAT(CONVERT_TZ(#{column}, '+00:00', '#{offset}'), '%Y-%m-01')"
+ when :day then "DATE(#{local})"
+ when :week then "DATE(DATE_SUB(#{local}, INTERVAL WEEKDAY(#{local}) DAY))"
+ when :month then "DATE_FORMAT(#{local}, '%Y-%m-01')"
end
- else # SQLite
+ else # SQLite — weeks start on Monday (ISO), matching the other adapters
case grain
when :day then "DATE(#{column}, '#{utc_offset} seconds')"
+ when :week then "DATE(#{column}, '#{utc_offset} seconds', '+1 day', 'weekday 1', '-7 days')"
when :month then "strftime('%Y-%m-01', #{column}, '#{utc_offset} seconds')"
end
end
end
- def store_time_zone
- @store_time_zone ||= ActiveSupport::TimeZone[store.preferred_timezone.presence || 'UTC'] || ActiveSupport::TimeZone['UTC']
- end
def utc_offset
- @utc_offset ||= store_time_zone.now.utc_offset
+ @utc_offset ||= query.time_zone.now.utc_offset
end
def format_offset(seconds)
@@ -274,44 +308,58 @@ module Spree
end
def expected_buckets(range, grain)
- from = range.first.in_time_zone(store_time_zone).to_date
- to = range.last.in_time_zone(store_time_zone).to_date
+ from = range.first.in_time_zone(query.time_zone).to_date
+ to = range.last.in_time_zone(query.time_zone).to_date
case grain
when :day then (from..to).map(&:to_s)
- when :month
- months = []
- cursor = from.beginning_of_month
- while cursor <= to
- months << cursor.to_s
- cursor = cursor.next_month
- end
- months
+ when :week then step_buckets(from.beginning_of_week(:monday), to) { |d| d + 7 }
+ when :month then step_buckets(from.beginning_of_month, to, &:next_month)
end
end
- # Aligns each current bucket with its previous-period counterpart
- # (same offset from the range start); value-dimension keys align 1:1.
+ def step_buckets(cursor, to)
+ buckets = []
+ while cursor <= to
+ buckets << cursor.to_s
+ cursor = yield(cursor)
+ end
+ buckets
+ end
+
+ # Aligns each current bucket with its previous-period counterpart by
+ # POSITION: the nth bucket of this period pairs with the nth bucket of
+ # the previous one. Date arithmetic on the bucket itself cannot do this
+ # — a range starting mid-week or mid-month has a partial first bucket
+ # whose start lies before the range, so shifting it lands outside the
+ # comparison window and orphans real data. Only the time component of
+ # a key moves; value-dimension components align 1:1.
def previous_key_map(keys)
time_dim = query.time_dimension
- return {} unless time_dim && query.dimensions.size == 1
+ return {} unless time_dim
- span = offset_span(time_dim[:grain])
- keys.to_h do |key|
- date = Date.parse(key.first.to_s)
- prev = time_dim[:grain] == :day ? date - span : date << span
- [key, [prev.to_s]]
- end
+ index = query.dimensions.index(time_dim)
+ pairs = bucket_pairs(time_dim[:grain])
+
+ keys.filter_map do |key|
+ counterpart = pairs[key[index].to_s]
+ next unless counterpart
+
+ shifted = key.dup
+ shifted[index] = counterpart
+ [key, shifted]
+ end.to_h
end
- def offset_span(grain)
- from = query.time_range.first.in_time_zone(store_time_zone).to_date
- to = query.time_range.last.in_time_zone(store_time_zone).to_date
+ # Both periods span the same number of days, so their bucket counts
+ # differ by at most one partial edge; pairing from the end keeps the
+ # most recent buckets — the ones a merchant reads first — aligned.
+ def bucket_pairs(grain)
+ current = expected_buckets(query.time_range, grain)
+ previous = expected_buckets(query.previous_time_range, grain)
+ offset = previous.size - current.size
- case grain
- when :day then (to - from).to_i + 1
- when :month then ((to.year - from.year) * 12) + (to.month - from.month) + 1
- end
+ current.each_with_index.to_h { |bucket, position| [bucket, previous[position + offset]] }
end
# SQL already ordered/limited the pushdown case; this re-sort is a
diff --git a/spree/core/lib/spree/reporting/default_vocabulary.rb b/spree/core/lib/spree/reporting/default_vocabulary.rb
index a1566b7625..ec47bf0097 100644
--- a/spree/core/lib/spree/reporting/default_vocabulary.rb
+++ b/spree/core/lib/spree/reporting/default_vocabulary.rb
@@ -16,10 +16,36 @@ module Spree
metric :units_sold, sql: 'SUM(%{line_items}.quantity)', base: :line_items, format: :integer
metric :customers_count, sql: 'COUNT(DISTINCT %{orders}.email)', base: :orders, format: :integer
metric :aov, ratio: %i[gross_revenue orders_count], format: :money
+ metric :discounts_total, sql: 'SUM(%{orders}.discount_total)', base: :orders, format: :money
+ metric :delivery_total, sql: 'SUM(%{orders}.delivery_total)', base: :orders, format: :money
+ metric :tax_total, sql: 'SUM(%{orders}.additional_tax_total + %{orders}.included_tax_total)',
+ base: :orders, format: :money
- dimension :completed_at, base: :orders, column: :completed_at, type: :time, grains: %i[day month]
- dimension :payment_status, base: :orders, column: :payment_status
- dimension :fulfillment_status, base: :orders, column: :fulfillment_status
+ dimension :completed_at, base: :orders, column: :completed_at, type: :time, grains: %i[day week month]
+ dimension :payment_status, base: :orders, column: :payment_status,
+ values: -> { Spree::Order::PAYMENT_STATUSES }
+ # The rollup values Orders::UpdateStatuses writes today; the model
+ # constant still carries the legacy machine states until 6.1.
+ dimension :fulfillment_status, base: :orders, column: :fulfillment_status,
+ values: -> { %w[backorder canceled partial unfulfilled fulfilled delivered] }
+
+ # Keyed by ISO code straight off the shipping address — countries are
+ # reference data (Spree::Country is not a record), so the code is the id.
+ dimension :country, base: :orders, column: '%{addresses}.country_code', joins: [:ship_address],
+ lookup: :country,
+ hydrate: lambda { |_store, codes, _params|
+ codes.to_h do |code|
+ [code, { id: code, label: Spree::Country.by_iso(code)&.name || code, meta: {} }]
+ end
+ }
+
+ dimension :market, base: :orders, column: :market_id, lookup: :market,
+ resolve: ->(store, value) { store.markets.find_by_prefix_id!(value).id },
+ hydrate: lambda { |store, ids, _params|
+ store.markets.where(id: ids).to_h do |market|
+ [market.id, { id: market.prefixed_id, label: market.name, meta: {} }]
+ end
+ }
dimension :channel, base: :orders, column: :channel_id, lookup: :channel,
resolve: ->(store, value) { store.channels.find_by_prefix_id!(value).id },
@@ -29,10 +55,13 @@ module Spree
end
}
- # Keys are order emails, so guests rank too; the id/profile link is
- # only present when a registered customer matches.
+ # Keyed by the order's email (guests have no customer row); a
+ # prefixed customer id in a filter resolves to that customer's email.
dimension :customer, base: :orders, column: :email, lookup: :customer,
subject: -> { Spree.customer_class }, key_scope: 'read_customers',
+ resolve: lambda { |store, value|
+ Spree::PrefixedId.prefixed_id?(value.to_s) ? Spree.customer_class.find_by_prefix_id!(value).email : value
+ },
hydrate: lambda { |store, emails, _params|
users = store.customers.distinct.where(email: emails).index_by(&:email)
emails.to_h do |email|
@@ -51,23 +80,42 @@ module Spree
end
}
+ # SKU-level merchandising; the label carries the option values so
+ # variants of one product stay distinguishable in a ranking.
+ dimension :variant, base: :line_items, column: :variant_id, lookup: :variant,
+ subject: -> { Spree::Product }, key_scope: 'read_products',
+ resolve: ->(store, value) { store.variants.find_by_prefix_id!(value).id },
+ hydrate: lambda { |store, ids, _params|
+ store.variants.where(id: ids).includes(:product, option_values: :option_type).to_h do |variant|
+ [variant.id, {
+ id: variant.prefixed_id,
+ label: variant.descriptive_name,
+ meta: { sku: variant.sku, product_id: variant.product&.prefixed_id }
+ }]
+ end
+ }
+
# Meta rides on the admin product serializer so thumbnails match the
# rest of the Admin API; the lambda only runs inside API requests.
dimension :product, base: :line_items, column: '%{variants}.product_id', joins: [:variant],
lookup: :product,
subject: -> { Spree::Product }, key_scope: 'read_products',
resolve: ->(store, value) { store.products.with_deleted.find_by_prefix_id!(value).id },
- hydrate: lambda { |store, ids, params|
- serializer = Spree.api.admin_product_serializer
- store.products.with_deleted.includes(:primary_media).where(id: ids).to_h do |product|
- serialized = serializer.new(product, params: params).to_h
+ # Four display fields, read directly: the product serializer
+ # would resolve buy-box variants, price lists, seller, type
+ # and tax category per row and throw all of it away.
+ hydrate: lambda { |store, ids, _params|
+ currency = Spree::Current.currency || store.default_currency
+ products = store.products.with_deleted.includes(:primary_media).where(id: ids)
+ products.to_h do |product|
+ amount = product.default_variant&.amount_in(currency)
[product.id, {
- id: serialized['id'],
- label: serialized['name'],
+ id: product.prefixed_id,
+ label: product.name,
meta: {
- slug: serialized['slug'],
- thumbnail_url: serialized['thumbnail_url'],
- price: serialized.dig('price', 'display_amount')
+ slug: product.slug,
+ thumbnail_url: Spree::Reporting.image_url(product.primary_media),
+ price: (Spree::Money.new(amount, currency: currency).to_s if amount)
}
}]
end
diff --git a/spree/core/lib/spree/reporting/hydration.rb b/spree/core/lib/spree/reporting/hydration.rb
new file mode 100644
index 0000000000..22ec3031ca
--- /dev/null
+++ b/spree/core/lib/spree/reporting/hydration.rb
@@ -0,0 +1,64 @@
+module Spree
+ module Reporting
+ # Turns a result's raw group keys into display payloads through each
+ # dimension's registered `hydrate` lambda, batched once per dimension
+ # across every row. Shared by the API serializer and the CSV export so a
+ # report reads the same on screen and in a file.
+ class Hydration
+ attr_reader :result, :store, :params, :registry
+
+ def initialize(result, store:, params: {}, registry: Spree.reporting)
+ @result = result
+ @store = store
+ @params = params
+ @registry = registry
+ end
+
+ # @param name [String, Symbol] dimension name
+ # @param raw [Object] the group key as aggregated
+ # @return [Hash, Object] `{ id:, label:, meta: }` for hydrated dimensions, the raw key otherwise
+ def value(name, raw)
+ dimension = definition(name)
+ # A row whose key is NULL is a real group — an order with no market or
+ # channel — and needs a name a person can read, not a blank cell.
+ return { id: nil, label: Spree.t('reporting.unassigned'), meta: {} } if raw.nil? && !plain?(dimension)
+ return { id: raw.to_s, label: Schema.value_label(dimension, raw), meta: {} } if dimension.enumerated_values
+ return raw unless dimension.hydrate
+
+ hydrated[name.to_sym][raw] || { id: nil, label: raw.to_s, meta: {} }
+ end
+
+ # @return [String] what a person should read for this key
+ def label(name, raw)
+ value = value(name, raw)
+ value.is_a?(Hash) ? value[:label].to_s : value.to_s
+ end
+
+ private
+
+ # A dimension the wire carries as a bare value (a status, a country code)
+ # rather than a { id, label, meta } payload.
+ def plain?(dimension)
+ dimension.enumerated_values.nil? && dimension.hydrate.nil?
+ end
+
+ def definition(name)
+ @definitions ||= Hash.new { |cache, key| cache[key] = registry.dimension!(key) }
+ @definitions[name.to_sym]
+ end
+
+ def hydrated
+ @hydrated ||= begin
+ keys = Hash.new { |hash, key| hash[key] = [] }
+ result.rows.each do |row|
+ row[:dimensions].each do |name, raw|
+ keys[name.to_sym] << raw if definition(name).hydrate
+ end
+ end
+
+ keys.to_h { |name, raws| [name, definition(name).hydrate.call(store, raws.uniq, params)] }
+ end
+ end
+ end
+ end
+end
diff --git a/spree/core/lib/spree/reporting/query.rb b/spree/core/lib/spree/reporting/query.rb
index b0b78e65fd..b8d788f4d2 100644
--- a/spree/core/lib/spree/reporting/query.rb
+++ b/spree/core/lib/spree/reporting/query.rb
@@ -12,7 +12,13 @@ module Spree
MAX_DIMENSIONS = 2
FILTER_OPS = %w[eq in].freeze
COMPARE_MODES = %w[previous_period].freeze
- RELATIVE_RANGE = /\A-(\d+)d\z/
+ LAST_N_RANGE = /\Alast_(\d+)_(days|weeks|months)\z/
+ # Named presets, resolved in the store's timezone (see #time_zone).
+ PRESETS = %w[today yesterday week_to_date month_to_date quarter_to_date year_to_date
+ last_week last_month last_quarter].freeze
+ # The `last_<n>_<unit>` ranges worth a labelled entry in pickers; any
+ # other count/unit pair is accepted through LAST_N_RANGE.
+ RELATIVE_PRESETS = %w[last_7_days last_30_days last_4_weeks last_90_days last_12_months].freeze
attr_reader :store, :registry, :currency, :metrics, :dimensions, :filters,
:time_range, :compare, :sort, :limit
@@ -20,7 +26,9 @@ module Spree
def initialize(store:, params:, registry: Spree.reporting)
@store = store
@registry = registry
- params = params.deep_symbolize_keys
+ raise InvalidQuery, 'query must be an object' unless params.respond_to?(:to_h)
+
+ params = params.to_h.deep_symbolize_keys
@currency = params[:currency].presence || store.default_currency
@metrics = normalize_metrics(params[:metrics])
@@ -54,6 +62,12 @@ module Spree
dimensions.find { |d| d[:dimension].time? }
end
+ # Day+ grains and relative ranges resolve in the store's timezone
+ # (Decision 7); adapters read it from here so every consumer agrees.
+ def time_zone
+ @time_zone ||= Time.find_zone(store.preferred_timezone) || Time.zone
+ end
+
# Authorization subjects for this query: order data (the floor for all
# reporting) plus every referenced member's declared subject. Every
# consumer — API controller, saved reports, agent tools — must ensure
@@ -62,6 +76,16 @@ module Spree
([Spree::Order] + referenced_dimensions.filter_map(&:subject).map(&:call)).uniq
end
+ # The subjects a given ability may not read — empty when the query is
+ # fully authorized. The one rule every consumer (API, exports, agent
+ # tools) applies, so member-level authorization cannot drift.
+ #
+ # @param ability [CanCan::Ability]
+ # @return [Array<Class, Symbol>]
+ def unreadable_subjects(ability)
+ required_subjects.reject { |subject| ability.can?(:read, subject) }
+ end
+
# API-key scopes required beyond `read_reports` (which gates the
# endpoint and covers the order-data floor): the `key_scope` of every
# referenced member with an authorization subject.
@@ -73,10 +97,14 @@ module Spree
(dimensions.map { |d| d[:dimension] } + filters.map { |f| f[:dimension] }).uniq
end
- # The immediately preceding period of equal length.
+ # The immediately preceding period of equal length, shifted by calendar
+ # days in the store zone so a range that spans a DST change keeps its
+ # midnight edges instead of drifting by an hour.
def previous_time_range
- duration = time_range.last - time_range.first
- (time_range.first - duration)..(time_range.last - duration)
+ first = time_range.first.in_time_zone(time_zone)
+ last = time_range.last.in_time_zone(time_zone)
+ days = (last.to_date - first.to_date).to_i + 1
+ (first - days.days)..(last - days.days)
end
def compare?
@@ -94,15 +122,25 @@ module Spree
private
def normalize_metrics(names)
- raise InvalidQuery, 'metrics must be a non-empty array' if names.blank?
+ raise InvalidQuery, 'metrics must be a non-empty array of metric names' unless names.is_a?(Array) && names.any?
- Array(names).map { |name| registry.metric!(name) }
+ names.map { |name| registry.metric!(member_name(name, 'metric')) }
+ end
+
+ # Member references are plain strings; anything else is a malformed
+ # contract, not an unknown member.
+ def member_name(value, kind)
+ raise InvalidQuery, "#{kind} names must be strings" unless value.is_a?(String) || value.is_a?(Symbol)
+
+ value
end
def normalize_dimensions(list)
+ raise InvalidQuery, 'dimensions must be an array' unless list.nil? || list.is_a?(Array)
+
dims = Array(list).map do |entry|
name, grain = entry.is_a?(Hash) ? [entry[:name], entry[:grain]] : [entry, nil]
- dimension = registry.dimension!(name)
+ dimension = registry.dimension!(member_name(name, 'dimension'))
if dimension.time?
grain = (grain || dimension.grains.first).to_sym
@@ -123,8 +161,12 @@ module Spree
end
def normalize_filters(list)
+ raise InvalidQuery, 'filters must be an array' unless list.nil? || list.is_a?(Array)
+
Array(list).map do |filter|
- dimension = registry.dimension!(filter[:dimension])
+ raise InvalidQuery, 'each filter must be an object with dimension, op and value' unless filter.is_a?(Hash)
+
+ dimension = registry.dimension!(member_name(filter[:dimension], 'dimension'))
op = filter[:op].to_s
raise InvalidQuery, "invalid filter op #{op}. Valid ops: #{FILTER_OPS.join(', ')}" unless FILTER_OPS.include?(op)
raise InvalidQuery, "filter on #{dimension.name} requires a value" if filter[:value].blank?
@@ -137,31 +179,58 @@ module Spree
dimension.resolve ? dimension.resolve.call(store, value) : value
end
+ # Accepts `{ preset: "last_month" }` (named or `last_<n>_<unit>`) or
+ # `{ since:, until: }` with ISO 8601 dates/datetimes.
+ # Everything resolves in the store's timezone so "yesterday" means the
+ # merchant's yesterday.
def normalize_time_range(range)
range ||= {}
- from = parse_time(range[:since], edge: :begin) || 30.days.ago.beginning_of_day
- to = parse_time(range[:until], edge: :end) || Time.current.end_of_day
+ raise InvalidQuery, 'time_range must be an object' unless range.is_a?(Hash)
+ return preset_range(range[:preset]) if range[:preset].present?
+
+ from = parse_time(range[:since], edge: :begin) || 30.days.ago.in_time_zone(time_zone).beginning_of_day
+ to = parse_time(range[:until], edge: :end) || Time.current.in_time_zone(time_zone).end_of_day
raise InvalidQuery, 'time_range.since must precede time_range.until' if from > to
from..to
end
+ def preset_range(name)
+ now = Time.current.in_time_zone(time_zone)
+ case name.to_s
+ when 'today' then now.beginning_of_day..now.end_of_day
+ when 'yesterday' then (now - 1.day).beginning_of_day..(now - 1.day).end_of_day
+ when 'week_to_date' then now.beginning_of_week..now.end_of_day
+ when 'month_to_date' then now.beginning_of_month..now.end_of_day
+ when 'quarter_to_date' then now.beginning_of_quarter..now.end_of_day
+ when 'year_to_date' then now.beginning_of_year..now.end_of_day
+ when 'last_week' then (now - 1.week).beginning_of_week..(now - 1.week).end_of_week
+ when 'last_month' then (now - 1.month).beginning_of_month..(now - 1.month).end_of_month
+ when 'last_quarter' then (now - 3.months).beginning_of_quarter..(now - 3.months).end_of_quarter
+ else
+ if (match = LAST_N_RANGE.match(name.to_s))
+ count, unit = match[1].to_i, match[2]
+ (now - count.public_send(unit)).beginning_of_day..now.end_of_day
+ else
+ raise InvalidQuery, "invalid time_range preset #{name}. Valid presets: #{PRESETS.join(', ')}, last_<n>_<days|weeks|months>"
+ end
+ end
+ end
+
def parse_time(value, edge:)
return if value.blank?
- if (match = RELATIVE_RANGE.match(value.to_s))
- return match[1].to_i.days.ago.beginning_of_day
- end
-
- time = Time.zone.parse(value.to_s) || raise(InvalidQuery, "invalid time: #{value}")
- # Date-only inputs cover the whole day on either edge.
- if value.to_s !~ /\d:\d/
+ # `iso8601`, never `parse`: parse fills in whatever a value omits, so
+ # "09:00" would become today at nine and a saved window would move
+ # every midnight. A bare date covers the whole day on either edge.
+ time = time_zone.iso8601(value.to_s)
+ if value.to_s.match?(/\A\d{4}-\d{2}-\d{2}\z/)
edge == :begin ? time.beginning_of_day : time.end_of_day
else
time
end
- rescue ArgumentError
- raise InvalidQuery, "invalid time: #{value}"
+ rescue ArgumentError, TypeError, KeyError
+ raise InvalidQuery, "invalid time: #{value} (expected an ISO 8601 date or datetime)"
end
def normalize_compare(value)
@@ -190,15 +259,12 @@ module Spree
# :orders-based metrics cannot be grouped or filtered by :line_items
# dimensions (order totals per product/category would double count).
def validate_bases!
- line_item_dims = (dimensions.map { |d| d[:dimension] } + filters.map { |f| f[:dimension] })
- .select { |d| d.base == :line_items }.uniq
- return if line_item_dims.empty?
-
- offenders = aggregated_metrics.select { |m| m.base == :orders }
- return if offenders.empty?
+ incompatible = referenced_dimensions.reject { |d| metrics.all? { |m| registry.compatible?(m, d) } }
+ return if incompatible.empty?
+ offenders = metrics.reject { |m| incompatible.all? { |d| registry.compatible?(m, d) } }
raise InvalidQuery,
- "metrics #{offenders.map(&:name).join(', ')} cannot be grouped by #{line_item_dims.map(&:name).join(', ')}"
+ "metrics #{offenders.map(&:name).join(', ')} cannot be grouped by #{incompatible.map(&:name).join(', ')}"
end
end
end
diff --git a/spree/core/lib/spree/reporting/registry.rb b/spree/core/lib/spree/reporting/registry.rb
index 5b9eb2f818..812e05be21 100644
--- a/spree/core/lib/spree/reporting/registry.rb
+++ b/spree/core/lib/spree/reporting/registry.rb
@@ -47,9 +47,17 @@ module Spree
# API-key scope (e.g. 'read_products') required alongside `read_reports`
# for secret keys to reference the member. Mandatory whenever `subject`
# is declared, so key access is decided at registration, never skipped.
+ # @!attribute values
+ # Enumerable raw values for status-like dimensions (an Array, or a lambda
+ # returning one so model constants load lazily). Published in the schema
+ # as the filter value list.
Dimension = Struct.new(:name, :base, :column, :joins, :type, :grains, :lookup,
- :resolve, :hydrate, :subject, :key_scope, keyword_init: true) do
+ :resolve, :hydrate, :subject, :key_scope, :values, keyword_init: true) do
def time? = type == :time
+
+ def enumerated_values
+ values.respond_to?(:call) ? values.call : values
+ end
end
# Allowlist of queryable metrics + dimensions. One global instance lives at
@@ -90,16 +98,21 @@ module Spree
@dimensions[name.to_sym] || raise(UnknownMember.new(:dimension, name, @dimensions.keys))
end
- # Serializable introspection payload — drives `GET /reporting/schema`,
- # admin pickers, and the AI tool schema.
- def schema
- {
- metrics: @metrics.values.map { |m| { name: m.name, format: m.format, derived: m.derived? } },
- dimensions: @dimensions.values.map do |d|
- { name: d.name, type: d.type, grains: d.grains, lookup: d.lookup }.compact
- end
- }
+ # Whether a metric can be grouped or filtered by a dimension: order-based
+ # dimensions suit every metric, line-item dimensions only metrics whose
+ # aggregated components all live on line items (order totals per product
+ # would double count). The single rule the schema and the compiler share.
+ #
+ # @param metric [Metric]
+ # @param dimension [Dimension]
+ # @return [Boolean]
+ def compatible?(metric, dimension)
+ return true if dimension.base == :orders
+
+ components = metric.derived? ? metric.ratio.map { |name| metric!(name) } : [metric]
+ components.all? { |component| component.base == :line_items }
end
+
end
end
end
diff --git a/spree/core/lib/spree/reporting/schema.rb b/spree/core/lib/spree/reporting/schema.rb
new file mode 100644
index 0000000000..012e8f5d5a
--- /dev/null
+++ b/spree/core/lib/spree/reporting/schema.rb
@@ -0,0 +1,86 @@
+module Spree
+ module Reporting
+ # The self-describing contract for one caller: labels and descriptions
+ # (localized), metric formats with the store currency, per-dimension
+ # metric compatibility, filter ops and enumerated values, the time-range
+ # grammar, and store meta — filtered to the members the caller may
+ # reference, so pickers never offer and agents never propose a member that
+ # would be refused. Drives `GET /reporting/schema` and the agent tool schema.
+ class Schema
+ # @param store [Spree::Store]
+ # @param registry [Registry]
+ # @param allowed [Proc] ->(Dimension) { true/false } — permission gate
+ def initialize(store:, registry: Spree.reporting, allowed: ->(_dimension) { true })
+ @store = store
+ @registry = registry
+ @allowed = allowed
+ end
+
+ def to_h
+ dimensions = @registry.dimensions.values.select { |d| @allowed.call(d) }
+ {
+ meta: {
+ currency: @store.default_currency,
+ timezone: (Time.find_zone(@store.preferred_timezone) || Time.zone).name,
+ supported_currencies: @store.supported_currencies_list.map(&:iso_code)
+ },
+ metrics: @registry.metrics.values.map { |m| metric_entry(m) },
+ dimensions: dimensions.map { |d| dimension_entry(d) },
+ time_range: {
+ presets: (Query::PRESETS + Query::RELATIVE_PRESETS).map { |p| { name: p, label: translate('presets', p, :label) } },
+ relative: %w[last_<n>_days last_<n>_weeks last_<n>_months],
+ absolute: 'ISO 8601 dates or datetimes in `since` / `until`, resolved in the store timezone'
+ },
+ # Ranking defaults the compiler applies, published so a client never
+ # has to mirror them.
+ limits: { default: Query::DEFAULT_VALUE_LIMIT, max: Query::MAX_LIMIT }
+ }
+ end
+
+ private
+
+ def metric_entry(metric)
+ {
+ name: metric.name,
+ label: translate('metrics', metric.name, :label),
+ description: translate('metrics', metric.name, :description),
+ format: metric.format,
+ currency: (metric.money? ? @store.default_currency : nil),
+ derived: metric.derived?
+ }.compact
+ end
+
+ def dimension_entry(dimension)
+ {
+ name: dimension.name,
+ label: translate('dimensions', dimension.name, :label),
+ description: translate('dimensions', dimension.name, :description),
+ type: dimension.type,
+ grains: dimension.grains,
+ lookup: dimension.lookup,
+ filter_ops: Query::FILTER_OPS,
+ values: dimension.enumerated_values&.map { |value| { name: value, label: self.class.value_label(dimension, value) } },
+ # Order-level metrics cannot be broken down by line-item dimensions
+ # (they would double count) — the compiler enforces the same rule.
+ compatible_metrics: @registry.metrics.values.select { |m| @registry.compatible?(m, dimension) }.map(&:name)
+ }.compact
+ end
+
+ def translate(group, name, facet)
+ Spree.t("reporting.#{group}.#{name}.#{facet}", default: (facet == :label ? name.to_s.humanize : nil))
+ end
+
+
+ # Enumerated values are labelled server-side so a plugin dimension
+ # declaring `values:` needs no dashboard locale edit; the schema, the
+ # result hydration and the CSV export all read the same label.
+ #
+ # @param dimension [Registry::Dimension]
+ # @param value [String]
+ # @return [String]
+ def self.value_label(dimension, value)
+ Spree.t("reporting.values.#{dimension.name}.#{value}", default: value.to_s.humanize)
+ end
+ end
+ end
+end
diff --git a/spree/core/spec/lib/spree/reporting/query_spec.rb b/spree/core/spec/lib/spree/reporting/query_spec.rb
index ffebb129b6..f6c089b5f2 100644
--- a/spree/core/spec/lib/spree/reporting/query_spec.rb
+++ b/spree/core/spec/lib/spree/reporting/query_spec.rb
@@ -47,6 +47,136 @@ RSpec.describe Spree::Reporting::Query do
end
end
+ describe 'contract shape' do
+ it 'rejects malformed shapes as invalid queries, never as server errors' do
+ expect { run(metrics: { a: 'b' }) }.to raise_error(Spree::Reporting::InvalidQuery)
+ expect { run(metrics: %w[orders_count], dimensions: [{ grain: 'day' }]) }.to raise_error(Spree::Reporting::InvalidQuery)
+ expect { run(metrics: %w[orders_count], filters: %w[channel]) }.to raise_error(Spree::Reporting::InvalidQuery)
+ expect { run(metrics: %w[orders_count], time_range: 'last_month') }.to raise_error(Spree::Reporting::InvalidQuery)
+ end
+
+ it 'refuses partial times instead of filling in today' do
+ expect { run(metrics: %w[orders_count], time_range: { since: '09:00' }) }
+ .to raise_error(Spree::Reporting::InvalidQuery, /ISO 8601/)
+ end
+
+ it 'widens a date-only until to the end of that day' do
+ create(:completed_order_with_totals, store: store, completed_at: 1.hour.ago)
+ result = run(metrics: %w[orders_count], time_range: { since: 2.days.ago.to_date.to_s, until: Date.current.to_s })
+ expect(result.totals[:orders_count][:value]).to eq(1)
+ end
+ end
+
+ describe '#previous_time_range' do
+ it 'keeps midnight edges across a DST change by shifting whole days' do
+ allow(store).to receive(:preferred_timezone).and_return('Europe/Warsaw')
+ query = described_class.new(store: store, params: { metrics: %w[orders_count], time_range: { since: '2026-03-20', until: '2026-04-02' } })
+
+ previous = query.previous_time_range
+ expect(previous.first.in_time_zone('Europe/Warsaw').strftime('%F %T')).to eq('2026-03-06 00:00:00')
+ expect(previous.last.in_time_zone('Europe/Warsaw').strftime('%F %T')).to eq('2026-03-19 23:59:59')
+ end
+ end
+
+ describe 'time presets' do
+ it 'resolves named presets in the store timezone' do
+ query = described_class.new(store: store, params: { metrics: %w[orders_count], time_range: { preset: 'yesterday' } })
+ expect(query.time_range.first).to eq(1.day.ago.in_time_zone(query.time_zone).beginning_of_day)
+ expect(query.time_range.last).to eq(1.day.ago.in_time_zone(query.time_zone).end_of_day)
+
+ query = described_class.new(store: store, params: { metrics: %w[orders_count], time_range: { preset: 'last_month' } })
+ expect(query.time_range.first).to eq(1.month.ago.in_time_zone(query.time_zone).beginning_of_month)
+
+ query = described_class.new(store: store, params: { metrics: %w[orders_count], time_range: { preset: 'last_4_weeks' } })
+ expect(query.time_range.first.to_date).to eq(4.weeks.ago.in_time_zone(query.time_zone).to_date)
+ end
+
+ it 'rejects unknown presets naming the valid ones' do
+ expect { described_class.new(store: store, params: { metrics: %w[orders_count], time_range: { preset: 'fortnight' } }) }
+ .to raise_error(Spree::Reporting::InvalidQuery, /last_month/)
+ end
+ end
+
+ describe 'week grain' do
+ let!(:order) { create(:completed_order_with_totals, store: store, completed_at: 3.days.ago) }
+
+ it 'buckets by ISO week start and zero-fills the range' do
+ result = run(metrics: %w[orders_count], dimensions: [{ name: 'completed_at', grain: 'week' }],
+ time_range: { since: 3.weeks.ago.to_date.to_s, until: Time.current.to_date.to_s })
+
+ buckets = result.rows.map { |row| row[:dimensions][:completed_at] }
+ expect(buckets).to all(satisfy { |b| Date.parse(b).monday? })
+ expect(buckets.length).to be_between(4, 5)
+ expect(result.rows.sum { |row| row[:metrics][:orders_count][:value] }).to eq(1)
+ end
+ end
+
+ describe 'extended vocabulary' do
+ let!(:order) { create(:completed_order_with_totals, store: store, completed_at: 3.days.ago) }
+
+ it 'groups by shipping country from the line-items base too' do
+ by_orders = run(metrics: %w[orders_count], dimensions: %w[country])
+ by_items = run(metrics: %w[units_sold], dimensions: %w[country])
+
+ code = order.ship_address.country_code
+ expect(by_orders.rows.first[:dimensions][:country]).to eq(code)
+ expect(by_items.rows.first[:dimensions][:country]).to eq(code)
+ end
+
+ it 'exposes money breakdown metrics' do
+ result = run(metrics: %w[discounts_total delivery_total tax_total])
+ expect(result.totals[:delivery_total][:value]).to eq(order.delivery_total.to_f.round(2))
+ expect(result.totals.keys).to contain_exactly(:discounts_total, :delivery_total, :tax_total)
+ end
+
+ it 'ranks variants' do
+ result = run(metrics: %w[units_sold], dimensions: %w[variant], sort: '-units_sold')
+ expect(result.rows.first[:dimensions][:variant]).to eq(order.line_items.first.variant_id)
+ end
+ end
+
+ describe 'joins that are not one-to-one' do
+ let!(:order) { create(:completed_order_with_totals, store: store, completed_at: 3.days.ago) }
+ let(:product) { order.line_items.first.variant.product }
+ let!(:categories) { create_list(:category, 2).each { |category| product.categories << category } }
+
+ it 'keeps the totals on the base rows while grouping still fans out per category' do
+ result = run(metrics: %w[net_revenue units_sold], dimensions: %w[category])
+ ungrouped = run(metrics: %w[net_revenue units_sold])
+
+ expect(result.rows.length).to eq(2)
+ expect(result.totals[:units_sold][:value]).to eq(ungrouped.totals[:units_sold][:value])
+ expect(result.totals[:net_revenue][:value]).to eq(ungrouped.totals[:net_revenue][:value])
+ 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) }])
+ expect(result.totals[:units_sold][:value]).to eq(order.line_items.sum(:quantity))
+ end
+ end
+
+ describe 'customer filter' do
+ let!(:order) { create(:completed_order_with_totals, store: store, completed_at: 3.days.ago) }
+
+ it 'resolves a prefixed customer id to the order email key' do
+ customer = order.customer
+ result = run(metrics: %w[orders_count], filters: [{ dimension: 'customer', op: 'eq', value: customer.prefixed_id }])
+ expect(result.totals[:orders_count][:value]).to eq(1)
+ end
+
+ it 'accepts a customer with no orders in this store as an empty filter' do
+ stranger = create(:user)
+ result = run(metrics: %w[orders_count], filters: [{ dimension: 'customer', op: 'eq', value: stranger.prefixed_id }])
+ expect(result.totals[:orders_count][:value]).to eq(0)
+ end
+
+ it 'still accepts a plain email' do
+ result = run(metrics: %w[orders_count], filters: [{ dimension: 'customer', op: 'eq', value: order.email }])
+ expect(result.totals[:orders_count][:value]).to eq(1)
+ end
+ end
+
describe '#required_subjects' do
it 'includes order data plus every referenced member subject' do
query = described_class.new(store: store, params: { metrics: %w[net_revenue], dimensions: %w[product] })
@@ -190,6 +320,18 @@ RSpec.describe Spree::Reporting::Query do
expect(result.totals[:gross_revenue][:growth]).to be_a(Numeric)
end
+ it 'aligns previous buckets when a value dimension sits beside the time dimension' do
+ # Exactly one range length (31 days) before recent_order — without
+ # zero-filled buckets only the observed keys can carry a previous value.
+ create(:completed_order_with_totals, store: store, completed_at: 36.days.ago)
+ result = run(metrics: %w[orders_count],
+ dimensions: [{ name: 'completed_at', grain: 'day' }, 'channel'],
+ compare: 'previous_period')
+
+ row = result.rows.find { |r| r[:dimensions][:completed_at] == 5.days.ago.to_date.to_s }
+ expect(row[:metrics][:orders_count][:previous]).to eq(1)
+ end
+
it 'aligns previous-period day buckets by range offset' do
result = run(metrics: %w[orders_count], dimensions: [{ name: 'completed_at', grain: 'day' }],
compare: 'previous_period')
@@ -199,6 +341,86 @@ RSpec.describe Spree::Reporting::Query do
end
end
+ context 'with a canceled order' do
+ let!(:order) { create(:completed_order_with_totals, store: store, completed_at: 3.days.ago) }
+ let!(:canceled) { create(:completed_order_with_totals, store: store, completed_at: 2.days.ago) }
+
+ before { canceled.update_columns(status: 'canceled') }
+
+ it 'counts only what stayed sold on both bases' do
+ result = run(metrics: %w[gross_revenue orders_count units_sold])
+ expect(result.totals[:orders_count][:value]).to eq(1)
+ expect(result.totals[:gross_revenue][:value]).to eq(order.total.to_f.round(2))
+ expect(result.totals[:units_sold][:value]).to eq(order.line_items.sum(:quantity))
+ end
+ end
+
+ context 'with buckets that do not divide the range evenly' do
+ # Aug 5 – Sep 3 is 30 days: the first week bucket starts Aug 3, before
+ # the range. Its counterpart must be the previous period's first bucket,
+ # not that Monday shifted back 30 days (which falls outside the window).
+ let!(:recent_order) { create(:completed_order_with_totals, store: store, completed_at: '2026-08-06 12:00'.in_time_zone) }
+ let!(:previous_order) { create(:completed_order_with_totals, store: store, completed_at: '2026-07-07 12:00'.in_time_zone) }
+
+ it 'pairs week buckets by position so no counterpart falls outside the previous period' do
+ result = run(metrics: %w[orders_count], dimensions: [{ name: 'completed_at', grain: 'week' }],
+ compare: 'previous_period', time_range: { since: '2026-08-05', until: '2026-09-03' })
+
+ bucket = result.rows.find { |row| row[:dimensions][:completed_at] == '2026-08-03' }
+ expect(bucket[:metrics][:orders_count][:value]).to eq(1)
+ expect(bucket[:metrics][:orders_count][:previous]).to eq(1)
+ end
+
+ it 'pairs month buckets by position on a rolling range that starts on the 1st' do
+ # Sep 1 – Oct 1 is 31 days, so the previous period is Aug 1 – Aug 31:
+ # September must compare with August, never with a July outside it.
+ create(:completed_order_with_totals, store: store, completed_at: '2026-09-15 12:00'.in_time_zone)
+ create(:completed_order_with_totals, store: store, completed_at: '2026-08-15 12:00'.in_time_zone)
+
+ result = run(metrics: %w[orders_count], dimensions: [{ name: 'completed_at', grain: 'month' }],
+ compare: 'previous_period', time_range: { since: '2026-09-01', until: '2026-10-01' })
+
+ august_orders = store.orders.complete.where(completed_at: '2026-08-01'.in_time_zone..'2026-08-31'.in_time_zone.end_of_day).count
+ september = result.rows.find { |row| row[:dimensions][:completed_at] == '2026-09-01' }
+ expect(september[:metrics][:orders_count][:value]).to eq(1)
+ expect(september[:metrics][:orders_count][:previous]).to eq(august_orders)
+ expect(august_orders).to be_positive
+ end
+ end
+
+ context 'with a quarter-to-date style range at month grain' do
+ # Range: the 1st of the month before last → today, spanning three
+ # calendar months with the current one partial. Each month bucket must
+ # compare with the month three back, never with a month inside the
+ # current period.
+ let(:from) { 2.months.ago.beginning_of_month.to_date }
+ let!(:recent_order) { create(:completed_order_with_totals, store: store, completed_at: (from + 45).in_time_zone.change(hour: 12)) }
+ let!(:previous_order) { create(:completed_order_with_totals, store: store, completed_at: ((from + 45) << 3).in_time_zone.change(hour: 12)) }
+
+ it 'compares each month with the month one period earlier, never a neighbour' do
+ result = run(metrics: %w[orders_count], dimensions: [{ name: 'completed_at', grain: 'month' }],
+ compare: 'previous_period', time_range: { since: from.to_s, until: Date.current.to_s })
+
+ bucket = result.rows.find { |row| row[:dimensions][:completed_at] == (from + 45).beginning_of_month.to_s }
+ expect(bucket[:metrics][:orders_count][:value]).to eq(1)
+ expect(bucket[:metrics][:orders_count][:previous]).to eq(1)
+ end
+ end
+
+ context 'with a range that is not whole weeks' do
+ let!(:recent_order) { create(:completed_order_with_totals, store: store, completed_at: 3.days.ago) }
+ let!(:previous_order) { create(:completed_order_with_totals, store: store, completed_at: 10.days.ago) }
+
+ it 'aligns week buckets by the exact range length snapped to the week start' do
+ result = run(metrics: %w[orders_count], dimensions: [{ name: 'completed_at', grain: 'week' }],
+ compare: 'previous_period',
+ time_range: { since: 6.days.ago.to_date.to_s, until: Date.current.to_s })
+
+ bucket = result.rows.find { |row| row[:dimensions][:completed_at] == 3.days.ago.to_date.beginning_of_week.to_s }
+ expect(bucket[:metrics][:orders_count][:previous]).to eq(1)
+ end
+ end
+
context 'scoping' do
# Reassigned after creation: the factory pipeline needs a fully configured
# store (delivery setup, prices in currency) and only the stored store_id /
diff --git a/spree/core/spec/lib/spree/reporting/registry_spec.rb b/spree/core/spec/lib/spree/reporting/registry_spec.rb
index d05ec76e65..1e33e01e70 100644
--- a/spree/core/spec/lib/spree/reporting/registry_spec.rb
+++ b/spree/core/spec/lib/spree/reporting/registry_spec.rb
@@ -41,16 +41,6 @@ RSpec.describe Spree::Reporting::Registry do
end
end
- describe '#schema' do
- it 'serializes registered members for introspection' do
- registry.metric :margin, sql: 'SUM(x)', base: :orders, format: :money
- registry.dimension :day, base: :orders, column: :completed_at, type: :time, grains: %i[day]
-
- expect(registry.schema[:metrics]).to contain_exactly({ name: :margin, format: :money, derived: false })
- expect(registry.schema[:dimensions]).to contain_exactly({ name: :day, type: :time, grains: %i[day] })
- end
- end
-
describe 'core starter vocabulary' do
it 'is registered on Spree.reporting' do
expect(Spree.reporting.metric!(:net_revenue).base).to eq(:line_items)
diff --git a/spree/core/spec/lib/spree/reporting/schema_spec.rb b/spree/core/spec/lib/spree/reporting/schema_spec.rb
new file mode 100644
index 0000000000..72abaa1779
--- /dev/null
+++ b/spree/core/spec/lib/spree/reporting/schema_spec.rb
@@ -0,0 +1,43 @@
+require 'spec_helper'
+
+RSpec.describe Spree::Reporting::Schema do
+ let(:store) { @default_store }
+
+ subject(:schema) { described_class.new(store: store).to_h }
+
+ it 'describes metrics with localized labels, formats and currency' do
+ metric = schema[:metrics].find { |m| m[:name] == :gross_revenue }
+ expect(metric[:label]).to eq('Total sales')
+ expect(metric[:description]).to be_present
+ expect(metric[:format]).to eq(:money)
+ expect(metric[:currency]).to eq(store.default_currency)
+ end
+
+ it 'publishes compatible metrics, filter ops and enumerated values per dimension' do
+ category = schema[:dimensions].find { |d| d[:name] == :category }
+ expect(category[:compatible_metrics]).to include(:net_revenue, :units_sold)
+ expect(category[:compatible_metrics]).not_to include(:gross_revenue, :aov)
+
+ channel = schema[:dimensions].find { |d| d[:name] == :channel }
+ expect(channel[:compatible_metrics]).to include(:gross_revenue, :aov, :units_sold)
+ expect(channel[:filter_ops]).to eq(%w[eq in])
+
+ status = schema[:dimensions].find { |d| d[:name] == :payment_status }
+ expect(status[:values].map { |v| v[:name] }).to include('paid', 'authorized')
+ expect(status[:values].find { |v| v[:name] == 'partially_paid' }[:label]).to eq('Partially paid')
+ end
+
+ it 'describes the time range grammar and store meta' do
+ expect(schema[:time_range][:presets].map { |p| p[:name] }).to include('last_month', 'yesterday', 'last_30_days')
+ expect(schema[:limits]).to eq(default: 50, max: 1000)
+ expect(schema[:time_range][:presets].first[:label]).to be_present
+ expect(schema[:meta]).to include(:currency, :timezone, :supported_currencies)
+ end
+
+ it 'omits dimensions the caller may not reference' do
+ filtered = described_class.new(store: store, allowed: ->(d) { d.subject.nil? }).to_h
+ names = filtered[:dimensions].map { |d| d[:name] }
+ expect(names).to include(:channel, :completed_at)
+ expect(names).not_to include(:product, :customer, :category, :variant)
+ end
+end