Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

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.ts
index 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?: boolean
calculator_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.ts
new file mode 100644
index 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.ts
index 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 './OrderCancellationReas
export 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.rb
new file mode 100644
index 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
+end
diff --git a/spree/api/app/serializers/spree/api/v3/admin/reporting_result_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/reporting_result_serializer.rb
index 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 Spree
def 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)
output
end
+ # 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_s
end
def 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.rb
new file mode 100644
index 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
+end
diff --git a/spree/api/config/routes.rb b/spree/api/config/routes.rb
index 86979c46d2..a06a976bae 100644
--- a/spree/api/config/routes.rb
+++ b/spree/api/config/routes.rb
@@ -249,6 +249,7 @@ Spree::Core::Engine.add_routes do
namespace :reporting do
post :query
get :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.rb
index cd1a3a7c61..b356afd9d7 100644
--- a/spree/api/lib/spree/api/dependencies.rb
+++ b/spree/api/lib/spree/api/dependencies.rb
@@ -269,6 +269,7 @@ module Spree
admin_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.rb
new file mode 100644
index 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
+end
diff --git a/spree/core/app/models/spree/exports/report.rb b/spree/core/app/models/spree/exports/report.rb
new file mode 100644
index 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
+end
diff --git a/spree/core/app/models/spree/saved_report.rb b/spree/core/app/models/spree/saved_report.rb
new file mode 100644
index 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
+end
diff --git a/spree/core/app/models/spree/store.rb b/spree/core/app/models/spree/store.rb
index b642377e75..2a2d349c3b 100644
--- a/spree/core/app/models/spree/store.rb
+++ b/spree/core/app/models/spree/store.rb
@@ -156,7 +156,8 @@ module Spree
has_many :carts, class_name: 'Spree::Cart', inverse_of: :store, dependent: :destroy
has_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: :destroy
has_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.rb
index 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.call
ApiKeys.call
+ SavedReports.call
AllowedOrigins.call
end
end
diff --git a/spree/core/app/services/spree/seeds/saved_reports.rb b/spree/core/app/services/spree/seeds/saved_reports.rb
new file mode 100644
index 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
+end
diff --git a/spree/core/config/locales/en.yml b/spree/core/config/locales/en.yml
index 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 months
diff --git a/spree/core/db/migrate/20260903120000_create_spree_saved_reports.rb b/spree/core/db/migrate/20260903120000_create_spree_saved_reports.rb
new file mode 100644
index 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
+end
diff --git a/spree/core/lib/spree/core/engine.rb b/spree/core/lib/spree/core/engine.rb
index 1024d4e26a..7360b5af25 100644
--- a/spree/core/lib/spree/core/engine.rb
+++ b/spree/core/lib/spree/core/engine.rb
@@ -469,6 +469,7 @@ module Spree
Spree::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.rb
index 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 Spree
write: 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/MethodLength
end
diff --git a/spree/core/lib/spree/reporting/schema.rb b/spree/core/lib/spree/reporting/schema.rb
index 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
+
private
def 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.rb
new file mode 100644
index 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
+end
diff --git a/spree/core/spec/models/spree/exports/report_spec.rb b/spree/core/spec/models/spree/exports/report_spec.rb
new file mode 100644
index 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
+end
diff --git a/spree/core/spec/models/spree/saved_report_spec.rb b/spree/core/spec/models/spree/saved_report_spec.rb
new file mode 100644
index 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
+end
diff --git a/spree/core/spec/services/spree/seeds/saved_reports_spec.rb b/spree/core/spec/services/spree/seeds/saved_reports_spec.rb
new file mode 100644
index 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