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
Add saved reports with seeded classics and CSV export
Damian Legawiec256a2e3250e8
diff --git a/packages/admin-sdk/src/params.ts b/packages/admin-sdk/src/params.tsindex 4427992a38..a535197f72 100644--- a/packages/admin-sdk/src/params.ts+++ b/packages/admin-sdk/src/params.ts@@ -3044,3 +3044,16 @@ export interface TaxRateParams {show_rate_in_label?: booleancalculator_type?: string}++// ============================================+// Saved reports (semantic reporting layer)+// ============================================++export interface SavedReportCreateParams {+ name: string+ description?: string | null+ /** A reporting contract query — validated against the registry on save. */+ query: ReportingQuery+}++export type SavedReportUpdateParams = Partial<SavedReportCreateParams>diff --git a/packages/admin-sdk/src/types/generated/SavedReport.ts b/packages/admin-sdk/src/types/generated/SavedReport.tsnew file mode 100644index 0000000000..ca1f0bdea3--- /dev/null+++ b/packages/admin-sdk/src/types/generated/SavedReport.ts@@ -0,0 +1,17 @@+// Typelizer digest 55a932a6dbcabef7913bc7162168f134+//+// DO NOT MODIFY: This file was automatically generated by Typelizer.++interface SavedReport {+ id: string;+ name: string;+ description: string | null;+ query: Record<string, unknown>;+ seeded: boolean;+ created_at: string;+ updated_at: string;+ user_id: string | null;+ author_name: string | null;+}++export default SavedReport;diff --git a/packages/admin-sdk/src/types/generated/index.ts b/packages/admin-sdk/src/types/generated/index.tsindex 752fc83047..188611db2f 100644--- a/packages/admin-sdk/src/types/generated/index.ts+++ b/packages/admin-sdk/src/types/generated/index.ts@@ -1,7 +1,6 @@-// Typelizer digest 04745457d698821928c98263295cc8a6+// Typelizer digest 7a6fa629f4a9b4275495944b3e8d36a9//// DO NOT MODIFY: This file was automatically generated by Typelizer.-export type { ClaimStatus, DataRequestStatus, ExchangeStatus, FeeKind, FulfillmentItemStatus, FulfillmentStatus, GiftCardStatus, ImportRowStatus, ImportStatus, InvitationStatus, PaymentStatus, PriceListStatus, ProductStatus, ProductSubmissionStatus, ReturnStatus, SellerPayoutStatus, SellerRequirementSubmissionStatus, SellerStatus, SellerTransferStatus, ShippingLabelStatus, StockLocationKind, TaxExemptionCertificateStatus } from './Enums'export type { default as Address } from './Address'export type { default as AdminUser } from './AdminUser'export type { default as AllowedOrigin } from './AllowedOrigin'@@ -11,7 +10,6 @@ export type { default as Cart } from './Cart'export type { default as CatalogAssignment } from './CatalogAssignment'export type { default as CatalogOrderMinimum } from './CatalogOrderMinimum'export type { default as CatalogPrice } from './CatalogPrice'-export type { default as CatalogPriceTier } from './CatalogPriceTier'export type { default as CatalogProduct } from './CatalogProduct'export type { default as CatalogProductTerm } from './CatalogProductTerm'export type { default as CatalogQuantityRule } from './CatalogQuantityRule'@@ -54,8 +52,6 @@ export type { default as ExchangeLineItem } from './ExchangeLineItem'export type { default as Exchange } from './Exchange'export type { default as Export } from './Export'export type { default as Fee } from './Fee'-export type { default as FreightSummaryLine } from './FreightSummaryLine'-export type { default as FreightSummary } from './FreightSummary'export type { default as FulfillmentItem } from './FulfillmentItem'export type { default as Fulfillment } from './Fulfillment'export type { default as GiftCardBatch } from './GiftCardBatch'@@ -68,7 +64,6 @@ export type { default as Invitation } from './Invitation'export type { default as LineItem } from './LineItem'export type { default as Market } from './Market'export type { default as Media } from './Media'-export type { default as MembershipProduct } from './MembershipProduct'export type { default as NewsletterSubscriber } from './NewsletterSubscriber'export type { default as OptionType } from './OptionType'export type { default as OptionValue } from './OptionValue'@@ -76,16 +71,12 @@ export type { default as OrderCancellationReason } from './OrderCancellationReasexport type { default as OrderGroup } from './OrderGroup'export type { default as OrderRoutingRule } from './OrderRoutingRule'export type { default as Order } from './Order'-export type { default as PackageType } from './PackageType'export type { default as PaymentMethod } from './PaymentMethod'export type { default as Payment } from './Payment'export type { default as PaymentSource } from './PaymentSource'-export type { default as PaymentSplit } from './PaymentSplit'export type { default as Permission } from './Permission'export type { default as Policy } from './Policy'-export type { default as PriceAdjustmentTier } from './PriceAdjustmentTier'export type { default as PriceHistory } from './PriceHistory'-export type { default as PriceListProduct } from './PriceListProduct'export type { default as PriceList } from './PriceList'export type { default as PriceRule } from './PriceRule'export type { default as Price } from './Price'@@ -97,15 +88,13 @@ export type { default as ProductType } from './ProductType'export type { default as PromotionAction } from './PromotionAction'export type { default as PromotionRule } from './PromotionRule'export type { default as Promotion } from './Promotion'-export type { default as PurchaseOrderItem } from './PurchaseOrderItem'-export type { default as PurchaseOrder } from './PurchaseOrder'export type { default as RefundReason } from './RefundReason'export type { default as Refund } from './Refund'export type { default as ReturnLineItem } from './ReturnLineItem'export type { default as ReturnReason } from './ReturnReason'export type { default as Return } from './Return'export type { default as Role } from './Role'-export type { default as SellerBalance } from './SellerBalance'+export type { default as SavedReport } from './SavedReport'export type { default as SellerPayout } from './SellerPayout'export type { default as SellerRequirement } from './SellerRequirement'export type { default as SellerRequirementStatus } from './SellerRequirementStatus'@@ -119,14 +108,10 @@ export type { default as State } from './State'export type { default as StockLevel } from './StockLevel'export type { default as StockLocation } from './StockLocation'export type { default as StockMovement } from './StockMovement'-export type { default as StockReceiptItem } from './StockReceiptItem'-export type { default as StockReceipt } from './StockReceipt'export type { default as StockReservation } from './StockReservation'-export type { default as StockTransferItem } from './StockTransferItem'export type { default as StockTransfer } from './StockTransfer'export type { default as StoreCredit } from './StoreCredit'export type { default as Store } from './Store'-export type { default as Supplier } from './Supplier'export type { default as TaxCategory } from './TaxCategory'export type { default as TaxExemptionCertificate } from './TaxExemptionCertificate'export type { default as TaxIdentifier } from './TaxIdentifier'diff --git a/spree/api/app/controllers/spree/api/v3/admin/reporting/saved_reports_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/reporting/saved_reports_controller.rbnew file mode 100644index 0000000000..d300a6b2b7--- /dev/null+++ b/spree/api/app/controllers/spree/api/v3/admin/reporting/saved_reports_controller.rb@@ -0,0 +1,45 @@+module Spree+ module Api+ module V3+ module Admin+ module Reporting+ # Store-wide saved reports (docs/plans/6.0-analytics-semantic-layer.md,+ # Decision 12). Reads ride `read_reports`, mutations `write_reports`;+ # the stored query is validated against the registry on save, and+ # every viewer is re-authorized when the report is executed through+ # the query endpoint.+ class SavedReportsController < ResourceController+ scoped_resource :reports++ protected++ def model_class+ Spree::SavedReport+ end++ def serializer_class+ Spree.api.admin_saved_report_serializer+ end++ def scope_includes+ [:user]+ end++ # Deliberately NOT routed through `normalize_params`: the stored+ # query carries filter values such as `cust_…`/`ch_…` prefixed ids+ # inside a nested hash, and prefixed-ID resolution recurses into+ # nested hashes — they would be decoded to integers on save and+ # never resolve again. Extension attributes are splatted in.+ def permitted_params+ params.permit(:name, :description, *model_additional_permitted_attributes, query: {})+ end++ def build_resource+ super.tap { |report| report.user = try_spree_current_user }+ end+ end+ end+ end+ end+ end+enddiff --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 447667e61a..e31068ca72 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@@ -40,12 +40,22 @@ module Spreedef metric_payload(name, payload)output = payload.dup- output[:display] = money(payload[:value]) if Spree.reporting.metrics[name]&.money?+ output[:display] = money(payload[:value]) if money_metrics.include?(name)outputend+ # Resolved once per response rather than per cell — a 1000-row report+ # with five metrics would otherwise build 5000 Money objects.+ def money_metrics+ @money_metrics ||= result.meta[:metrics].select { |name| Spree.reporting.metrics[name]&.money? }.to_set+ end++ def currency+ @currency ||= ::Money::Currency.find(result.meta[:currency])+ end+def money(amount)- Spree::Money.new(amount, currency: result.meta[:currency]).to_s+ Spree::Money.new(amount, currency: currency).to_senddef dimension_value(name, raw)diff --git a/spree/api/app/serializers/spree/api/v3/admin/saved_report_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/saved_report_serializer.rbnew file mode 100644index 0000000000..a75cf3e31c--- /dev/null+++ b/spree/api/app/serializers/spree/api/v3/admin/saved_report_serializer.rb@@ -0,0 +1,33 @@+module Spree+ module Api+ module V3+ module Admin+ # Admin API serializer for {Spree::SavedReport}: the reporting contract+ # query and its attribution.+ class SavedReportSerializer < V3::BaseSerializer+ typelize name: :string,+ description: [:string, nullable: true],+ query: 'Record<string, unknown>',+ seeded: :boolean,+ user_id: [:string, nullable: true],+ author_name: [:string, nullable: true],+ created_at: :string,+ updated_at: :string++ attributes :name, :description, :query, :seeded, :created_at, :updated_at++ attribute :user_id do |report|+ report.user&.prefixed_id+ end++ attribute :author_name do |report|+ user = report.user+ next nil unless user++ user.full_name.presence || user.email+ end+ end+ end+ end+ end+enddiff --git a/spree/api/config/routes.rb b/spree/api/config/routes.rbindex 86979c46d2..a06a976bae 100644--- a/spree/api/config/routes.rb+++ b/spree/api/config/routes.rb@@ -249,6 +249,7 @@ Spree::Core::Engine.add_routes donamespace :reporting dopost :queryget :schema+ resources :saved_reports, only: %i[index show create update destroy]end# Dashboard (point-in-time operational counts)diff --git a/spree/api/lib/spree/api/dependencies.rb b/spree/api/lib/spree/api/dependencies.rbindex cd1a3a7c61..b356afd9d7 100644--- a/spree/api/lib/spree/api/dependencies.rb+++ b/spree/api/lib/spree/api/dependencies.rb@@ -269,6 +269,7 @@ module Spreeadmin_role_serializer: 'Spree::Api::V3::Admin::RoleSerializer',admin_permission_serializer: 'Spree::Api::V3::Admin::PermissionSerializer',admin_export_serializer: 'Spree::Api::V3::Admin::ExportSerializer',+ admin_saved_report_serializer: 'Spree::Api::V3::Admin::SavedReportSerializer',admin_import_serializer: 'Spree::Api::V3::Admin::ImportSerializer',admin_import_row_serializer: 'Spree::Api::V3::Admin::ImportRowSerializer',admin_import_mapping_serializer: 'Spree::Api::V3::Admin::ImportMappingSerializer',diff --git a/spree/api/spec/controllers/spree/api/v3/admin/reporting/saved_reports_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/reporting/saved_reports_controller_spec.rbnew file mode 100644index 0000000000..52eab84f3b--- /dev/null+++ b/spree/api/spec/controllers/spree/api/v3/admin/reporting/saved_reports_controller_spec.rb@@ -0,0 +1,83 @@+require 'spec_helper'++RSpec.describe Spree::Api::V3::Admin::Reporting::SavedReportsController, type: :controller do+ render_views++ include_context 'API v3 Admin authenticated'++ before { request.headers.merge!(headers) }++ let(:query) { { 'metrics' => %w[gross_revenue orders_count], 'dimensions' => %w[channel], 'sort' => '-gross_revenue' } }+ let!(:report) { create(:saved_report, store: store, name: 'Sales by channel', query: query) }++ describe 'GET #index' do+ it "lists the store's saved reports" do+ create(:saved_report, store: create(:store), name: 'Elsewhere', query: query)++ get :index, as: :json++ expect(response).to have_http_status(:ok)+ expect(json_response['data'].map { |r| r['name'] }).to eq(['Sales by channel'])+ expect(json_response['data'].first['id']).to start_with('sq_')+ end+ end++ describe 'POST #create' do+ it 'saves a compilable query and records the author' do+ post :create, params: { name: 'Top products', query: { metrics: %w[net_revenue], dimensions: %w[product], limit: 10 } }, as: :json++ expect(response).to have_http_status(:created)+ expect(json_response['query']['metrics']).to eq(%w[net_revenue])+ expect(json_response['seeded']).to be false+ expect(json_response['author_name']).to be_present+ end++ it 'rejects a query the registry cannot compile' do+ post :create, params: { name: 'Broken', query: { metrics: %w[gross_revenue], dimensions: %w[category] } }, as: :json++ expect(response).to have_http_status(:unprocessable_content)+ expect(response.body).to include('cannot be grouped')+ end+ end++ describe 'PATCH #update / DELETE #destroy' do+ it 'refuses to edit a built-in report' do+ seeded = create(:saved_report, store: store, name: 'Built in', query: query, seeded: true)++ patch :update, params: { id: seeded.prefixed_id, name: 'Renamed' }, as: :json++ expect(response).to have_http_status(:unprocessable_content)+ end++ it 'updates the name and query' do+ patch :update, params: { id: report.prefixed_id, name: 'Sales by market', query: query.merge('dimensions' => %w[market]) }, as: :json++ expect(response).to have_http_status(:ok)+ expect(report.reload.query['dimensions']).to eq(%w[market])+ end++ it 'destroys the report' do+ delete :destroy, params: { id: report.prefixed_id }, as: :json+ expect(response).to have_http_status(:no_content)+ expect(Spree::SavedReport.exists?(report.id)).to be false+ end++ it "returns 404 for another store's report" do+ foreign = create(:saved_report, store: create(:store), name: 'Elsewhere', query: query)+ patch :update, params: { id: foreign.prefixed_id, name: 'x' }, as: :json+ expect(response).to have_http_status(:not_found)+ end+ end++ describe 'secret key scopes' do+ let(:headers) { { 'x-spree-api-key' => create(:api_key, :secret, store: store, scopes: %w[read_reports]).plaintext_token } }++ it 'reads with read_reports but needs write_reports to create' do+ get :index, as: :json+ expect(response).to have_http_status(:ok)++ post :create, params: { name: 'Nope', query: query }, as: :json+ expect(response).to have_http_status(:forbidden)+ end+ end+enddiff --git a/spree/core/app/models/spree/exports/report.rb b/spree/core/app/models/spree/exports/report.rbnew file mode 100644index 0000000000..b0ba9edf68--- /dev/null+++ b/spree/core/app/models/spree/exports/report.rb@@ -0,0 +1,86 @@+module Spree+ module Exports+ # CSV of one reporting query (docs/plans/6.0-analytics-semantic-layer.md).+ # `search_params` carries `{ "query" => <contract JSON> }`; the rows are the+ # compiled result plus a totals line. Runs as the requesting user so the+ # query is authorized member-by-member exactly like the API — which is+ # why a user is required (API keys cannot queue report exports).+ class Report < Spree::Export+ validates :user, presence: true+ # Refuse now what the background job would refuse later: a query that+ # does not compile, or a member the requesting user may not read, must+ # be a 422 the caller sees rather than an export that never becomes done.+ validate :query_must_compile_and_be_readable, on: :create, if: -> { user.present? }++ def self.required_scope+ :reports+ end++ # Not a bulk export of a model — the derived `Spree::Report` (legacy CSV+ # reports) would be wrong, so anchor on the saved-report model instead.+ def self.model_class+ Spree::SavedReport+ end++ def model_class+ self.class.model_class+ end++ def csv_headers+ labels = Spree::Reporting::Schema.new(store: store)+ dimension_labels = reporting_query.dimensions.map { |d| labels.label_for(:dimensions, d[:dimension].name) }+ metric_labels = reporting_query.metrics.map { |m| labels.label_for(:metrics, m.name) }+ dimension_labels + metric_labels+ end++ def generate_csv+ query = reporting_query+ authorize_members!(query)+ result = query.execute++ # Labels, not group keys: the file must read like the screen, so a+ # channel column says "Web", never the channel's database id.+ hydration = Spree::Reporting::Hydration.new(result, store: store)++ ::CSV.open(export_tmp_file_path, 'wb', encoding: 'UTF-8', col_sep: ',', row_sep: "\r\n") do |csv|+ csv << csv_headers+ result.rows.each do |row|+ csv << Spree::CSV::FormulaSanitizer.row(+ row[:dimensions].map { |name, raw| hydration.label(name, raw) } ++ query.metrics.map { |m| row[:metrics][m.name][:value] }+ )+ end+ totals = query.metrics.map { |m| result.totals[m.name][:value] }+ # With a breakdown the totals close the file under a "Total" label in+ # the first dimension column; without one the totals are the only row.+ label = query.dimensions.empty? ? [] : [Spree.t('reporting.export.total')] + Array.new(query.dimensions.size - 1, '')+ csv << Spree::CSV::FormulaSanitizer.row(label + totals)+ end+ end++ private++ def reporting_query+ @reporting_query ||= Spree::Reporting::Query.new(store: store, params: query_params)+ end++ def query_params+ raw = search_params.is_a?(String) ? JSON.parse(search_params) : (search_params || {})+ raw['query'] || raw[:query] || {}+ end++ def authorize_members!(query)+ forbidden = query.unreadable_subjects(current_ability).first+ raise CanCan::AccessDenied.new(nil, :read, forbidden) if forbidden+ end++ def query_must_compile_and_be_readable+ errors.add(:base, :forbidden_reporting_member) if reporting_query.unreadable_subjects(current_ability).any?+ rescue Spree::Reporting::UnknownMember, Spree::Reporting::InvalidQuery => e+ errors.add(:search_params, e.message)+ rescue JSON::ParserError+ errors.add(:search_params, :invalid)+ end+ end+ end+enddiff --git a/spree/core/app/models/spree/saved_report.rb b/spree/core/app/models/spree/saved_report.rbnew file mode 100644index 0000000000..03070cbe35--- /dev/null+++ b/spree/core/app/models/spree/saved_report.rb@@ -0,0 +1,56 @@+module Spree+ # A reporting query kept for reuse: the contract JSON (see+ # Spree::Reporting::Query); its visualization is inferred from the query's+ # shape. Owned by the store and visible to every staff member who may read+ # reports; the author is recorded for attribution only — execution+ # re-authorizes the viewer.+ class SavedReport < Spree.base_class+ has_prefix_id :sq++ include Spree::SingleStoreResource++ publishes_lifecycle_events++ belongs_to :user, class_name: Spree.admin_user_class.to_s, optional: true++ validates :name, presence: true, uniqueness: { scope: spree_base_uniqueness_scope + [:store_id], case_sensitive: false }+ validates :query, presence: true+ validate :query_must_compile+ # A built-in report is a fixed reference point: it can be copied or+ # deleted, never edited in place — the same rule the dashboard shows.+ validate :seeded_reports_are_read_only, on: :update++ scope :seeded, -> { where(seeded: true) }++ self.whitelisted_ransackable_attributes = %w[name seeded created_at updated_at]++ def event_serializer_class+ 'Spree::Api::V3::Admin::SavedReportSerializer'.safe_constantize+ end++ # The stored query, normalized against the registry.+ #+ # @return [Spree::Reporting::Query]+ def reporting_query+ Spree::Reporting::Query.new(store: store, params: query || {})+ end++ private++ # Refuse to save a query the registry cannot compile — a report must never+ # 422 the day it is opened.+ def query_must_compile+ return if store.blank? || query.blank?++ reporting_query+ rescue Spree::Reporting::UnknownMember, Spree::Reporting::InvalidQuery => e+ errors.add(:query, e.message)+ end++ def seeded_reports_are_read_only+ return unless seeded_was && (changed & %w[name description query]).any?++ errors.add(:base, :seeded_report_read_only)+ end+ end+enddiff --git a/spree/core/app/models/spree/store.rb b/spree/core/app/models/spree/store.rbindex b642377e75..2a2d349c3b 100644--- a/spree/core/app/models/spree/store.rb+++ b/spree/core/app/models/spree/store.rb@@ -156,7 +156,8 @@ module Spreehas_many :carts, class_name: 'Spree::Cart', inverse_of: :store, dependent: :destroyhas_many :orders, class_name: 'Spree::Order'has_many :order_groups, class_name: 'Spree::OrderGroup'- has_many :customers, through: :orders, source: :customer+ has_many :customers, through: :orders, source: :customer, class_name: "::#{Spree.customer_class}"+ has_many :saved_reports, class_name: 'Spree::SavedReport', dependent: :destroyhas_many :line_items, through: :orders, class_name: 'Spree::LineItem'has_many :digital_links, through: :line_items, class_name: 'Spree::DigitalLink'has_many :fulfillments, through: :orders, class_name: 'Spree::Fulfillment'diff --git a/spree/core/app/services/spree/seeds/all.rb b/spree/core/app/services/spree/seeds/all.rbindex 9853e2461e..96c9c38276 100644--- a/spree/core/app/services/spree/seeds/all.rb+++ b/spree/core/app/services/spree/seeds/all.rb@@ -41,6 +41,7 @@ module Spree# them trade. Runs after stores for the same reason roles do.SellerRequirements.callApiKeys.call+ SavedReports.callAllowedOrigins.callendenddiff --git a/spree/core/app/services/spree/seeds/saved_reports.rb b/spree/core/app/services/spree/seeds/saved_reports.rbnew file mode 100644index 0000000000..5a24fec6ab--- /dev/null+++ b/spree/core/app/services/spree/seeds/saved_reports.rb@@ -0,0 +1,61 @@+module Spree+ module Seeds+ # The classic report set every store starts with on the Reports page.+ # Idempotent per store (matched by name); merchants can edit or delete+ # them, so a missing seeded report is not recreated once removed by hand —+ # only never-created ones are added.+ class SavedReports+ prepend Spree::ServiceModule::Base++ REPORTS = [+ { key: 'sales_over_time',+ query: { 'metrics' => %w[gross_revenue orders_count aov], 'dimensions' => [{ 'name' => 'completed_at', 'grain' => 'day' }],+ 'time_range' => { 'preset' => 'last_4_weeks' }, 'compare' => 'previous_period' } },+ { key: 'sales_by_channel',+ query: { 'metrics' => %w[gross_revenue orders_count], 'dimensions' => %w[channel],+ 'time_range' => { 'preset' => 'last_4_weeks' }, 'sort' => '-gross_revenue' } },+ { key: 'sales_by_market',+ query: { 'metrics' => %w[gross_revenue orders_count], 'dimensions' => %w[market],+ 'time_range' => { 'preset' => 'last_4_weeks' }, 'sort' => '-gross_revenue' } },+ { key: 'sales_by_country',+ query: { 'metrics' => %w[gross_revenue orders_count], 'dimensions' => %w[country],+ 'time_range' => { 'preset' => 'last_4_weeks' }, 'sort' => '-gross_revenue' } },+ { key: 'top_products',+ query: { 'metrics' => %w[net_revenue units_sold], 'dimensions' => %w[product],+ 'time_range' => { 'preset' => 'last_4_weeks' }, 'sort' => '-net_revenue', 'limit' => 20 } },+ { key: 'top_categories',+ query: { 'metrics' => %w[net_revenue units_sold], 'dimensions' => %w[category],+ 'time_range' => { 'preset' => 'last_4_weeks' }, 'sort' => '-net_revenue', 'limit' => 20 } },+ { key: 'top_customers',+ query: { 'metrics' => %w[gross_revenue orders_count], 'dimensions' => %w[customer],+ 'time_range' => { 'preset' => 'last_4_weeks' }, 'sort' => '-gross_revenue', 'limit' => 20 } },+ { key: 'orders_by_payment_status',+ query: { 'metrics' => %w[orders_count gross_revenue], 'dimensions' => %w[payment_status],+ 'time_range' => { 'preset' => 'last_4_weeks' } } },+ { key: 'orders_by_fulfillment_status',+ query: { 'metrics' => %w[orders_count gross_revenue], 'dimensions' => %w[fulfillment_status],+ 'time_range' => { 'preset' => 'last_4_weeks' } } }+ ].freeze++ def call+ Spree::Store.find_each do |store|+ # Compared case-insensitively like the model's uniqueness rule, so a+ # merchant's own "top products" never makes a re-seed raise.+ existing = store.saved_reports.pluck(:name).map(&:downcase).to_set++ REPORTS.each do |report|+ name = Spree.t("reporting.seeds.#{report[:key]}.name")+ next if existing.include?(name.downcase)++ store.saved_reports.create!(+ name: name,+ description: Spree.t("reporting.seeds.#{report[:key]}.description"),+ query: report[:query],+ seeded: true+ )+ end+ end+ end+ end+ end+enddiff --git a/spree/core/config/locales/en.yml b/spree/core/config/locales/en.ymlindex 1cb993465f..95062a8ee8 100644--- a/spree/core/config/locales/en.yml+++ b/spree/core/config/locales/en.yml@@ -1746,6 +1746,34 @@ en:units_sold:description: Sum of line item quantities.label: Units sold+ seeds:+ sales_over_time:+ name: Sales over time+ description: Daily sales, orders and average order value for the last four weeks, compared with the previous period.+ sales_by_channel:+ name: Sales by channel+ description: Sales and orders per sales channel over the last four weeks.+ sales_by_market:+ name: Sales by market+ description: Sales and orders per market over the last four weeks.+ sales_by_country:+ name: Sales by country+ description: Sales and orders by shipping country over the last four weeks.+ top_products:+ name: Top products+ description: Best-selling products by net revenue over the last four weeks.+ top_categories:+ name: Top categories+ description: Best-selling categories by net revenue over the last four weeks.+ top_customers:+ name: Top customers+ description: Customers ranked by spend over the last four weeks.+ orders_by_payment_status:+ name: Orders by payment status+ description: Order counts and sales grouped by payment status over the last four weeks.+ orders_by_fulfillment_status:+ name: Orders by fulfillment status+ description: Order counts and sales grouped by fulfillment status over the last four weeks.presets:last_12_months:label: Last 12 monthsdiff --git a/spree/core/db/migrate/20260903120000_create_spree_saved_reports.rb b/spree/core/db/migrate/20260903120000_create_spree_saved_reports.rbnew file mode 100644index 0000000000..9cc242c091--- /dev/null+++ b/spree/core/db/migrate/20260903120000_create_spree_saved_reports.rb@@ -0,0 +1,23 @@+class CreateSpreeSavedReports < ActiveRecord::Migration[8.1]+ # docs/plans/6.0-analytics-semantic-layer.md — a saved report is a reporting+ # contract query owned by the store and shared with every staff member who+ # may read reports; its visualization is inferred from the query's shape.+ def change+ create_table :spree_saved_reports do |t|+ # No standalone store index: the unique [store_id, name] index leads with it.+ t.belongs_to :store, null: false, foreign_key: false, index: false+ t.belongs_to :user, foreign_key: false, index: true+ t.string :name, null: false+ t.text :description+ if t.respond_to?(:jsonb)+ t.jsonb :query, null: false+ else+ t.json :query, null: false+ end+ t.boolean :seeded, null: false, default: false+ t.timestamps+ end++ add_index :spree_saved_reports, [:store_id, :name], unique: true+ end+enddiff --git a/spree/core/lib/spree/core/engine.rb b/spree/core/lib/spree/core/engine.rbindex 1024d4e26a..7360b5af25 100644--- a/spree/core/lib/spree/core/engine.rb+++ b/spree/core/lib/spree/core/engine.rb@@ -469,6 +469,7 @@ module SpreeSpree::Exports::CouponCodes,Spree::Exports::PriceListPrices,Spree::Exports::PurchaseOrders+ Spree::Exports::Report]Rails.application.config.spree.import_types = [diff --git a/spree/core/lib/spree/core/permission_configuration.rb b/spree/core/lib/spree/core/permission_configuration.rbindex e2f6508d27..c1cc29825b 100644--- a/spree/core/lib/spree/core/permission_configuration.rb+++ b/spree/core/lib/spree/core/permission_configuration.rb@@ -487,7 +487,7 @@ module Spreewrite: false, audiences: %i[seller])# Semantic reporting (docs/plans/6.0-analytics-semantic-layer.md). Staff# only until seller queries get a compiler-forced seller scope.- register_resource(:reports, group: :analytics, subjects: -> { [:reports] }, write: false)+ register_resource(:reports, group: :analytics, subjects: -> { [:reports, Spree::SavedReport, Spree::Exports::Report] })end# rubocop:enable Metrics/MethodLengthenddiff --git a/spree/core/lib/spree/reporting/schema.rb b/spree/core/lib/spree/reporting/schema.rbindex 012e8f5d5a..b7460f5283 100644--- a/spree/core/lib/spree/reporting/schema.rb+++ b/spree/core/lib/spree/reporting/schema.rb@@ -37,6 +37,12 @@ module Spree}end+ # @param group [Symbol] :metrics | :dimensions+ # @return [String] localized label (humanized name when none registered)+ def label_for(group, name)+ translate(group, name, :label)+ end+privatedef metric_entry(metric)diff --git a/spree/core/lib/spree/testing_support/factories/saved_report_factory.rb b/spree/core/lib/spree/testing_support/factories/saved_report_factory.rbnew file mode 100644index 0000000000..8c28129a06--- /dev/null+++ b/spree/core/lib/spree/testing_support/factories/saved_report_factory.rb@@ -0,0 +1,7 @@+FactoryBot.define do+ factory :saved_report, class: Spree::SavedReport do+ store { Spree::Store.default }+ sequence(:name) { |n| "Report #{n}" }+ query { { 'metrics' => %w[gross_revenue orders_count], 'dimensions' => %w[channel] } }+ end+enddiff --git a/spree/core/spec/models/spree/exports/report_spec.rb b/spree/core/spec/models/spree/exports/report_spec.rbnew file mode 100644index 0000000000..099c6f857f--- /dev/null+++ b/spree/core/spec/models/spree/exports/report_spec.rb@@ -0,0 +1,60 @@+require 'spec_helper'++RSpec.describe Spree::Exports::Report, type: :model do+ let(:store) { @default_store }+ let(:admin) { create(:admin_user) }+ let(:query) { { 'metrics' => %w[gross_revenue orders_count], 'dimensions' => %w[channel] } }++ before { create(:completed_order_with_totals, store: store, completed_at: 3.days.ago) }++ it 'requires a user so members are authorized like the API' do+ export = described_class.new(store: store, search_params: { query: query })+ expect(export).not_to be_valid+ expect(export.errors[:user]).to be_present+ end++ it 'writes a dimensionless report as a single totals row' do+ export = described_class.create!(store: store, user: admin,+ search_params: { query: { 'metrics' => %w[gross_revenue orders_count] } })+ export.generate_csv++ rows = CSV.read(export.send(:export_tmp_file_path))+ expect(rows.first).to eq(['Total sales', 'Orders'])+ expect(rows.length).to eq(2)+ expect(rows.last.last.to_i).to eq(1)+ end++ it 'refuses at create a query that does not compile' do+ export = described_class.new(store: store, user: admin, search_params: { query: { 'metrics' => %w[nope] } })+ expect(export).not_to be_valid+ expect(export.errors[:search_params]).to be_present+ end++ it 'refuses at create a member the requesting user may not read' do+ viewer = create(:admin_user, :without_admin_role)+ create(:role_user, user: viewer, role: create(:role, permissions: %w[read_reports read_orders]))+ export = described_class.new(store: store, user: viewer,+ search_params: { query: { 'metrics' => %w[net_revenue], 'dimensions' => %w[product] } })++ expect(export).not_to be_valid+ expect(export.errors[:base]).to be_present+ end++ it 'gates on the reports scope and anchors on saved reports' do+ expect(described_class.required_scope).to eq(:reports)+ expect(described_class.model_class).to eq(Spree::SavedReport)+ end++ it 'writes labeled headers, one row per group, and a totals line' do+ export = described_class.create!(store: store, user: admin, search_params: { query: query })+ export.generate_csv++ rows = CSV.read(export.send(:export_tmp_file_path))+ expect(rows.first).to eq(['Sales channel', 'Total sales', 'Orders'])+ expect(rows.length).to eq(3) # header + one channel + total+ # Hydrated like the API: the channel's name, never its database id.+ expect(rows[1].first).to eq(Spree::Order.complete.last.channel.name)+ expect(rows.last.first).to eq('Total')+ expect(rows.last.last.to_i).to eq(1)+ end+enddiff --git a/spree/core/spec/models/spree/saved_report_spec.rb b/spree/core/spec/models/spree/saved_report_spec.rbnew file mode 100644index 0000000000..2ab9a53496--- /dev/null+++ b/spree/core/spec/models/spree/saved_report_spec.rb@@ -0,0 +1,38 @@+require 'spec_helper'++RSpec.describe Spree::SavedReport, type: :model do+ let(:store) { @default_store }++ it 'saves a compilable query' do+ report = described_class.new(store: store, name: 'Sales by channel',+ query: { 'metrics' => %w[gross_revenue], 'dimensions' => %w[channel] })+ expect(report).to be_valid+ expect(report.reporting_query.metrics.map(&:name)).to eq([:gross_revenue])+ end++ it 'refuses a query the registry cannot compile' do+ report = described_class.new(store: store, name: 'Broken', query: { 'metrics' => %w[revenues] })+ expect(report).not_to be_valid+ expect(report.errors[:query].first).to include('net_revenue')++ report = described_class.new(store: store, name: 'Broken', query: { 'metrics' => %w[gross_revenue], 'dimensions' => %w[category] })+ expect(report).not_to be_valid+ expect(report.errors[:query].first).to include('cannot be grouped')+ end++ it 'keeps names unique per store' do+ create(:saved_report, store: store, name: 'Top products', query: { 'metrics' => %w[units_sold] })+ dup = described_class.new(store: store, name: 'top products', query: { 'metrics' => %w[units_sold] })+ expect(dup).not_to be_valid+ end++ it 'keeps built-in reports read-only while allowing their deletion' do+ report = create(:saved_report, store: store, seeded: true)++ report.name = 'Renamed'+ expect(report).not_to be_valid+ expect(report.errors[:base]).to be_present++ expect { report.reload.destroy! }.to change(described_class, :count).by(-1)+ end+enddiff --git a/spree/core/spec/services/spree/seeds/saved_reports_spec.rb b/spree/core/spec/services/spree/seeds/saved_reports_spec.rbnew file mode 100644index 0000000000..897c6ec7dc--- /dev/null+++ b/spree/core/spec/services/spree/seeds/saved_reports_spec.rb@@ -0,0 +1,20 @@+require 'spec_helper'++RSpec.describe Spree::Seeds::SavedReports do+ let(:store) { @default_store }++ it 'seeds the classic report set once per store' do+ expect { described_class.call }.to change { store.saved_reports.seeded.count }+ .from(0).to(described_class::REPORTS.size)++ expect { described_class.call }.not_to change { store.saved_reports.count }+ expect(store.saved_reports.find_by(name: 'Top products').reporting_query.dimensions.first[:dimension].name).to eq(:product)+ end++ it 'treats a merchant report differing only in case as already present' do+ create(:saved_report, store: store, name: 'top products')++ expect { described_class.call }.not_to raise_error+ expect(store.saved_reports.where('LOWER(name) = ?', 'top products').count).to eq(1)+ end+end