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
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.mdindex 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.rbindex 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 Spreeend# 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_hendprivate@@ -63,7 +69,16 @@ module Spree)elseauthorize!(: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)endenddiff --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.rbindex 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 Spreemodule V3module 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 ReportingResultSerializerattr_reader :result, :store, :params@@ -50,29 +49,11 @@ module Spreeenddef 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)endendenddiff --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.rbindex 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 dobefore { 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 doenddescribe 'GET #schema' do- it 'returns the registry introspection payload' do+ it 'returns the self-describing contract' doget :schema, as: :jsonexpect(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')+ endendendenddiff --git a/spree/core/config/locales/en.yml b/spree/core/config/locales/en.ymlindex 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 readinvalid_document_number_affix: 'can only contain uppercase letters, digits, dashes and #'invalid_system_key: can only contain lowercase letters, digits and underscoreslocked_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 insteadnumber:currency:format:@@ -1682,6 +1684,143 @@ en:report_names:products_performance: Products performancesales_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: Voidedreports: Reportsrequired: "*"required_fields: required fieldsdiff --git a/spree/core/lib/spree/reporting.rb b/spree/core/lib/spree/reporting.rbindex 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 < StandardErrorattr_reader :kind, :name, :validdiff --git a/spree/core/lib/spree/reporting/adapters/live.rb b/spree/core/lib/spree/reporting/adapters/live.rbindex 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 Spreeclass Live < Basedef execute(query)@query = query- @store = query.storecurrent = 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 Spreeprivate- attr_reader :store-# ---- period execution ----def period_data(range, push_sort: false, key_filter: nil)@@ -51,15 +48,15 @@ module Spreerows = 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 groupeddimension_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_filterscope = apply_sql_sort(scope, metrics) if push_sortselects = dimension_selects + selectsend@@ -74,24 +71,36 @@ module Spreerowsend+ # 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 basewhen :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)elseraise 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)endscopeend- 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})")+ endendscopeend+ # 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? || falseenddef sort_metric- query.registry.metric!(query.sort[:metric])+ @sort_metric ||= query.registry.metric!(query.sort[:metric])enddef apply_sql_sort(scope, metrics)@@ -146,9 +179,9 @@ module Spreekeys 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 Spreeline_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 Spreedef time_bucket_sql(column, grain)case connection.adapter_namewhen /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"endwhen /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 adapterscase grainwhen :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')"endendend- def store_time_zone- @store_time_zone ||= ActiveSupport::TimeZone[store.preferred_timezone.presence || 'UTC'] || ActiveSupport::TimeZone['UTC']- enddef utc_offset- @utc_offset ||= store_time_zone.now.utc_offset+ @utc_offset ||= query.time_zone.now.utc_offsetenddef format_offset(seconds)@@ -274,44 +308,58 @@ module Spreeenddef 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_datecase grainwhen :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)endend- # 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_hend- 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 adiff --git a/spree/core/lib/spree/reporting/default_vocabulary.rb b/spree/core/lib/spree/reporting/default_vocabulary.rbindex 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 Spreemetric :units_sold, sql: 'SUM(%{line_items}.quantity)', base: :line_items, format: :integermetric :customers_count, sql: 'COUNT(DISTINCT %{orders}.email)', base: :orders, format: :integermetric :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 Spreeend}- # 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 Spreeend}+ # 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)}}]enddiff --git a/spree/core/lib/spree/reporting/hydration.rb b/spree/core/lib/spree/reporting/hydration.rbnew file mode 100644index 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+enddiff --git a/spree/core/lib/spree/reporting/query.rb b/spree/core/lib/spree/reporting/query.rbindex b0b78e65fd..b8d788f4d2 100644--- a/spree/core/lib/spree/reporting/query.rb+++ b/spree/core/lib/spree/reporting/query.rb@@ -12,7 +12,13 @@ module SpreeMAX_DIMENSIONS = 2FILTER_OPS = %w[eq in].freezeCOMPARE_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].freezeattr_reader :store, :registry, :currency, :metrics, :dimensions, :filters,:time_range, :compare, :sort, :limit@@ -20,7 +26,9 @@ module Spreedef 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 Spreedimensions.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)).uniqend+ # 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] }).uniqend- # 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)enddef compare?@@ -94,15 +122,25 @@ module Spreeprivatedef 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)++ valueenddef 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 Spreeenddef 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_sraise 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 Spreedimension.resolve ? dimension.resolve.call(store, value) : valueend+ # 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_dayraise InvalidQuery, 'time_range.since must precede time_range.until' if from > tofrom..toend+ 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_dayelsetimeend- rescue ArgumentError- raise InvalidQuery, "invalid time: #{value}"+ rescue ArgumentError, TypeError, KeyError+ raise InvalidQuery, "invalid time: #{value} (expected an ISO 8601 date or datetime)"enddef 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(', ')}"endendenddiff --git a/spree/core/lib/spree/reporting/registry.rb b/spree/core/lib/spree/reporting/registry.rbindex 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) dodef time? = type == :time++ def enumerated_values+ values.respond_to?(:call) ? values.call : values+ endend# 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+endendenddiff --git a/spree/core/lib/spree/reporting/schema.rb b/spree/core/lib/spree/reporting/schema.rbnew file mode 100644index 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+enddiff --git a/spree/core/spec/lib/spree/reporting/query_spec.rb b/spree/core/spec/lib/spree/reporting/query_spec.rbindex 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 doendend+ 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' doit 'includes order data plus every referenced member subject' doquery = described_class.new(store: store, params: { metrics: %w[net_revenue], dimensions: %w[product] })@@ -190,6 +320,18 @@ RSpec.describe Spree::Reporting::Query doexpect(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' doresult = run(metrics: %w[orders_count], dimensions: [{ name: 'completed_at', grain: 'day' }],compare: 'previous_period')@@ -199,6 +341,86 @@ RSpec.describe Spree::Reporting::Query doendend+ 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.rbindex 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 doendend- 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' doit 'is registered on Spree.reporting' doexpect(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.rbnew file mode 100644index 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