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.

Added payments and inventory reporting

Damian Legawiec865e43cd35af
diff --git a/docs/developer/core-concepts/reporting.mdx b/docs/developer/core-concepts/reporting.mdx
index 5309df3321..e801673a0b 100644
--- a/docs/developer/core-concepts/reporting.mdx
+++ b/docs/developer/core-concepts/reporting.mdx
@@ -62,8 +62,19 @@ without a dashboard change.
## Metrics
-A metric is an aggregate over one **base** relation, either `:orders` or
-`:line_items`:
+A metric is an aggregate over one **base** relation. Core registers four, in
+three families:
+
+| Family | Bases | Anchored on |
+|--------|-------|-------------|
+| `sales` | `:orders`, `:line_items` | when the order completed |
+| `payments` | `:payments` | when the payment was taken |
+| `inventory` | `:stock_movements` | when the stock moved |
+
+A query draws from **one family only**. The three answer different questions on
+different clocks, so a payment total beside a units-received count is two
+reports wearing one table — the query refuses the mix rather than inventing a
+join between grains that have no honest relationship.
```ruby
Spree.reporting.metric :total_sales,
@@ -123,7 +134,7 @@ Spree.reporting.dimension :channel, base: :orders, column: :channel_id,
| Option | Purpose |
|--------|---------|
-| `base` | `:orders` or `:line_items`. Order-level dimensions are reachable from line items through the order join; not the reverse. |
+| `base` | Which relation this axis belongs to. A base declares which other bases it reaches: `:line_items` reaches `:orders` through the order join, not the reverse. |
| `column` | A column on the base table, or a `%{table}.column` string. Must resolve to a plain identifier. |
| `expression` | SQL computing the key instead of reading a column — how `customer_type` decides first-time from returning. Use it only where a column genuinely cannot answer; it carries the same trust as a metric's `sql`. |
| `joins` | Association joins the grouping needs, applied only to the grouped query. |
@@ -200,18 +211,18 @@ metrics and dimensions instead. See
Worth knowing before you design an extension:
-- **Two bases only.** Metrics aggregate over `:orders` or `:line_items`. A
- metric declaring another base is refused at query time.
-- **Six interpolatable tables.** The `%{table}` map is fixed; naming a table
- outside it raises inside the adapter.
+- **A new base is a registration, but a new table is not.** `registry.base`
+ adds a relation to query; the `%{table}` interpolation map is still fixed, so
+ a base over your own table needs an entry added to the adapter.
- **Columns are identifiers, not expressions.** A dimension's `column` must
resolve to `table.column`; computed groupings such as `SUBSTR(...)` are
refused.
- **The dashboard maps `lookup` to a picker from a fixed list.** A new lookup
value still filters correctly, but through a plain ID input.
-Reporting on data outside orders and line items therefore needs a core change
-today, not just a registration.
+So a new axis or number over data core already knows is a registration; a base
+over a table core has never seen still needs one line in the adapter's table
+map.
## Related
diff --git a/docs/developer/how-to/extend-reporting.mdx b/docs/developer/how-to/extend-reporting.mdx
index 15b787b44f..da30b0e653 100644
--- a/docs/developer/how-to/extend-reporting.mdx
+++ b/docs/developer/how-to/extend-reporting.mdx
@@ -22,7 +22,8 @@ questions, register vocabulary instead.
## Add a metric
-A metric is an aggregate over `:orders` or `:line_items`:
+A metric is an aggregate over one registered base — `:orders`, `:line_items`,
+`:payments` or `:stock_movements`:
```ruby config/initializers/spree.rb
Rails.application.config.after_initialize do
@@ -167,19 +168,27 @@ including the seeded ones. Prefer a new name unless you intend exactly that.
These are limits of the compiler, not of registration:
-- **Only `:orders` and `:line_items` are valid bases.** A metric over
- payments or stock movements is refused at query time.
-- **Only six tables interpolate.** `%{orders}`, `%{line_items}`,
- `%{variants}`, `%{products}`, `%{addresses}`, `%{product_categories}`.
- Naming your own table raises inside the adapter.
+- **The `%{table}` map is fixed.** Registering a base over your own table
+ needs an entry added to the adapter's interpolation map — the one place a
+ new table still has to be named in core.
- **A dimension's column must be a plain identifier.** Computed groupings
such as `SUBSTR(email, ...)` are refused; add a real column, or a database
view, if you need one.
- **Custom `lookup` values fall back to an ID input** in the builder, since
the dashboard maps known lookups to pickers.
-If your data does not hang off orders or line items, reporting cannot reach it
-today without a core change.
+Registering a base is otherwise ordinary: declare its family, its table, a
+store-scoped relation, its time column and which bases its dimensions reach.
+
+```ruby
+Spree.reporting.base :subscriptions, family: :subscriptions,
+ table: '%{subscriptions}',
+ time_column: '%{subscriptions}.created_at',
+ relation: ->(store, range, _currency) { store.subscriptions.where(created_at: range) }
+```
+
+Give it its own family unless its rows genuinely answer the same question, on
+the same clock, as an existing one.
## Related
diff --git a/docs/plans/6.0-analytics-semantic-layer.md b/docs/plans/6.0-analytics-semantic-layer.md
index f36799dc9a..31b7719163 100644
--- a/docs/plans/6.0-analytics-semantic-layer.md
+++ b/docs/plans/6.0-analytics-semantic-layer.md
@@ -164,14 +164,33 @@ Two mechanics follow from the chain:
incompletely-costed catalog reads high. The metric documents that rather than
guessing a cost.
-**Still out of vocabulary reach** (recorded so nobody re-derives them by hand):
-net payments and payment-method breakdowns need a `:payments` base; inventory
-history (units received, sell-through, days of supply) needs a
-`:stock_movements` base over the typed ledger. Both are additive once the
-compiler takes bases from the registry instead of its hardcoded pair — the base
-list and the `resolve_sql` table map are the two closed sets left in the
-compiler. Sessions, referrers and conversion rates stay unavailable: a headless
-storefront does not send us the data.
+**Bases are registry data, and there are three families** (2026-09-09, same
+pass): the compiler's hardcoded `:orders`/`:line_items` pair became
+`registry.base`, each base declaring its family, its own table, how to reach it
+store-scoped, its time column and which bases its dimensions can group by.
+`compatible?` generalised from the two-base special case into that reachability
+rule. Core registers four bases in three families — **sales** (`:orders`,
+`:line_items`), **payments** (`:payments`) and **inventory**
+(`:stock_movements`) — and a query drawing from two families is refused, because
+they answer different questions on different clocks: sales money is anchored on
+order completion, a payment on when it was taken, a movement on when stock
+moved. The schema publishes the families so a builder never offers a pair the
+query would reject.
+
+Payments answer what was actually taken and given back, by instrument
+(`payments_received`, `payments_refunded`, `net_payments`, `payments_count`,
+`payments_failed`; axes `payment_method`, `payment_result`, `paid_at`).
+Inventory answers movement over the typed ledger (`units_received`,
+`units_shipped`, `units_adjusted`, derived `sell_through`; axes `moved_at`,
+`movement_kind`, `moved_variant`, `stock_location`). Two mechanics worth
+recording: the movement `kind` carries direction, so each metric sums one kind
+rather than raw quantity — netting a receipt against a dispatch is the bug that
+shape prevents; and `spree_stock_movements` carries no store column, so its
+base scopes through `StockMovement.for_store`'s stock level → variant → product
+walk, the only tenancy path that table has.
+
+Sessions, referrers and conversion rates stay unavailable: a headless storefront
+does not send us the data. That is now the only recorded gap.
## Design Details
@@ -297,6 +316,8 @@ Legacy surfaces: `Spree::Admin::AnalyticsConcern` untouched (legacy admin is mai
- Time-range values are ISO 8601 dates or datetimes (`iso8601`, never `parse`); bare dates cover the store's whole day on either edge and the dashboard sends custom ranges as bare dates.
- **No new hand-rolled aggregate endpoints.** New analytics needs go through the registry + `POST /reporting/query`; `dashboard/operations` (point-in-time counts) is the only bespoke endpoint that stays.
+- **A new base is registered, never hardcoded** — `registry.base` declares its family, table, relation, time column and reachability; nothing in the compiler branches on a base name, and the `resolve_sql` table map is the only remaining place a new table is named.
+- **One family per query.** Sales, payments and inventory never mix — a metric from one family beside a metric from another is refused, not joined.
- **The sales chain is the vocabulary** (Decision 14): `net_sales` and `total_sales` are the single definitions of revenue; do not re-derive either elsewhere, and do not reintroduce `gross_revenue`/`net_revenue` as names.
- **Order-level money on another table is a correlated subquery**, never a join on the aggregating scope — an order with three refunds stays one row.
- **New filters are dimensions.** Register a dimension (with `resolve`/`hydrate`/`subject`/`key_scope` when it identifies a resource); never add filter-only parameters to the endpoint.
diff --git a/docs/plans/decisions.md b/docs/plans/decisions.md
index 28ebe4df38..823a14fef4 100644
--- a/docs/plans/decisions.md
+++ b/docs/plans/decisions.md
@@ -49,6 +49,14 @@ yet in the catalog, dropship, consignment, and a quarantine location for rejecte
the first is a buying feature that drags product creation into purchasing, and the rest are
their own plans.
+## 2026-09-09: Reporting bases are registry data, in three families that never mix
+
+**Context:** The reporting compiler hardcoded its two bases (`:orders`, `:line_items`) in a case statement, and `compatible?` was written as a two-base special case where `:orders` is universal. That left the two report families merchants ask for next — payments and inventory — unreachable, and they were recorded as out of scope on an implementation-difficulty judgment rather than a product one. They are not session data, so nothing about a headless storefront excludes them.
+
+**Decision:** Bases become registry entries. `registry.base` declares a base's family, its own table, a store-scoped relation, its time column and which bases its dimensions can reach; `compatible?` generalises into that reachability rule and the compiler stops branching on base names. Core registers four bases in three families: **sales** (`:orders`, `:line_items`), **payments** (`:payments`), **inventory** (`:stock_movements`). **A query draws from one family only** — the three answer different questions on different clocks (order completion, when a payment was taken, when stock moved), and a payment total beside a units-received count is two reports wearing one table. The schema publishes families so a builder never offers a cross-family pair.
+
+**Consequences:** Payments and inventory ship with vocabulary and five more seeded reports (19 in total). Two mechanics are load-bearing: a stock movement's `kind` carries direction, so each metric sums one kind rather than raw quantity — summing across kinds nets a receipt against a dispatch; and `spree_stock_movements` has no store column, so its base scopes through `StockMovement.for_store`'s stock level → variant → product walk, which is the only tenancy path that table has. A base now declares its `table` separately from its `time_column`, because deriving one from the other read every line-item dimension off the orders table (a line item's clock lives on its order). `payment_result` is deliberately not called `payment_status`: the order-level dimension of that name says how much of an order is paid, this one says whether one charge went through. Sessions, referrers and conversion rates remain the only recorded gap, and are unavailable by construction.
+
## 2026-09-09: Reporting speaks the industry sales chain; commission and payout numbers are permission-gated
**Context:** A survey of what merchants expect a commerce back office to report — the whole catalogue minus marketing and behaviour, which need session data a headless storefront never collects — showed the shipped reporting vocabulary answered the right questions under the wrong names. `gross_revenue` was in fact *total sales*, `net_revenue` was neither of the industry's two terms, and the two figures merchants ask for first (real net revenue, and what each seller is owed) could not be expressed at all. Registered names are public API from the release, so a rename had to happen before saved reports baked the wrong ones in.
diff --git a/packages/admin-sdk/src/admin-client.ts b/packages/admin-sdk/src/admin-client.ts
index e6c74112a6..1194d12a94 100644
--- a/packages/admin-sdk/src/admin-client.ts
+++ b/packages/admin-sdk/src/admin-client.ts
@@ -73,6 +73,8 @@ export interface ReportingResult {
export interface ReportingSchemaMetric {
name: string
+ /** Metrics from different families cannot be combined in one query. */
+ family?: string
label: string
description?: string
format: 'money' | 'integer' | 'decimal' | 'percent' | string
@@ -95,9 +97,18 @@ export interface ReportingSchemaDimension {
compatible_metrics: string[]
}
+/** Members that can be queried together: sales, payments, inventory. */
+export interface ReportingSchemaFamily {
+ name: string
+ label: string
+ metrics: string[]
+ dimensions: string[]
+}
+
/** The self-describing contract, filtered to what the caller may reference. */
export interface ReportingSchema {
meta: { currency: string; timezone: string; supported_currencies: string[] }
+ families: ReportingSchemaFamily[]
metrics: ReportingSchemaMetric[]
dimensions: ReportingSchemaDimension[]
time_range: {
diff --git a/packages/admin-sdk/src/index.ts b/packages/admin-sdk/src/index.ts
index ef73c52245..203d883154 100644
--- a/packages/admin-sdk/src/index.ts
+++ b/packages/admin-sdk/src/index.ts
@@ -19,6 +19,7 @@ export type {
ReportingRow,
ReportingSchema,
ReportingSchemaDimension,
+ ReportingSchemaFamily,
ReportingSchemaMetric,
} from './admin-client'
// Admin client class (for advanced use / subclassing)
diff --git a/spree/core/app/services/spree/seeds/saved_reports.rb b/spree/core/app/services/spree/seeds/saved_reports.rb
index 128578b9cc..ab3bc09d5e 100644
--- a/spree/core/app/services/spree/seeds/saved_reports.rb
+++ b/spree/core/app/services/spree/seeds/saved_reports.rb
@@ -44,6 +44,21 @@ module Spree
{ key: 'seller_payouts',
query: { 'metrics' => %w[net_sales commission seller_payout units_sold], 'dimensions' => %w[seller],
'time_range' => { 'preset' => 'last_month' }, 'sort' => '-seller_payout', 'limit' => 50 } },
+ { key: 'payments_over_time',
+ query: { 'metrics' => %w[payments_received payments_refunded net_payments], 'dimensions' => [{ 'name' => 'paid_at', 'grain' => 'day' }],
+ 'time_range' => { 'preset' => 'last_4_weeks' }, 'compare' => 'previous_period' } },
+ { key: 'payments_by_method',
+ query: { 'metrics' => %w[net_payments payments_count], 'dimensions' => %w[payment_method],
+ 'time_range' => { 'preset' => 'last_4_weeks' }, 'sort' => '-net_payments' } },
+ { key: 'failed_payments',
+ query: { 'metrics' => %w[payments_failed payments_count], 'dimensions' => %w[payment_method],
+ 'time_range' => { 'preset' => 'last_4_weeks' }, 'sort' => '-payments_failed' } },
+ { key: 'stock_movement_over_time',
+ query: { 'metrics' => %w[units_received units_shipped], 'dimensions' => [{ 'name' => 'moved_at', 'grain' => 'week' }],
+ 'time_range' => { 'preset' => 'last_12_months' } } },
+ { key: 'sell_through_by_variant',
+ query: { 'metrics' => %w[units_shipped units_received sell_through], 'dimensions' => %w[moved_variant],
+ 'time_range' => { 'preset' => 'last_4_weeks' }, 'sort' => '-units_shipped', 'limit' => 20 } },
{ key: 'orders_by_payment_status',
query: { 'metrics' => %w[orders total_sales], 'dimensions' => %w[payment_status],
'time_range' => { 'preset' => 'last_4_weeks' } } },
diff --git a/spree/core/config/locales/en.yml b/spree/core/config/locales/en.yml
index 9a57174d94..6e1f3a26c6 100644
--- a/spree/core/config/locales/en.yml
+++ b/spree/core/config/locales/en.yml
@@ -1710,6 +1710,24 @@ en:
market:
description: The market the order was placed in.
label: Market
+ moved_at:
+ description: When stock moved, bucketed by day, week or month in the store timezone.
+ label: Movement date
+ moved_variant:
+ description: The variant whose stock moved.
+ label: Variant moved
+ movement_kind:
+ description: What happened to the stock.
+ label: Movement type
+ paid_at:
+ description: When the payment was taken, bucketed by day, week or month in the store timezone.
+ label: Payment date
+ payment_method:
+ description: The instrument the payment was taken through.
+ label: Payment method
+ payment_result:
+ description: Whether an individual charge succeeded.
+ label: Payment result
payment_status:
description: Payment state of the order.
label: Payment status
@@ -1719,11 +1737,21 @@ en:
seller:
description: The seller who sold the item.
label: Seller
+ stock_location:
+ description: The location the stock moved in or out of.
+ label: Stock location
variant:
description: The product variant (SKU) sold.
label: Variant
export:
total: Total
+ families:
+ inventory:
+ label: Inventory
+ payments:
+ label: Payments
+ sales:
+ label: Sales
metrics:
average_order_value:
description: Total sales divided by the number of orders.
@@ -1755,15 +1783,33 @@ en:
gross_sales:
description: Item prices multiplied by quantity, before discounts, returns and tax.
label: Gross sales
+ net_payments:
+ description: Money taken less money refunded, by the instrument that moved it.
+ label: Net payments
net_sales:
description: Gross sales less discounts and returns. What you actually sold.
label: Net sales
orders:
description: Number of placed orders.
label: Orders
+ payments_count:
+ description: Number of successful charges.
+ label: Payments
+ payments_failed:
+ description: Number of charges that failed.
+ label: Failed payments
+ payments_received:
+ description: Money successfully taken, counted when the payment was made.
+ label: Payments received
+ payments_refunded:
+ description: Money refunded through these payments.
+ label: Payments refunded
returns:
description: Money refunded, counted in the period the refund was issued.
label: Returns
+ sell_through:
+ description: Units shipped as a share of units received.
+ label: Sell-through
seller_payout:
description: What the sellers are owed on these sales, after commission.
label: Seller payout
@@ -1776,6 +1822,15 @@ en:
total_sales:
description: Net sales plus shipping, duties, fees and taxes. The money taken.
label: Total sales
+ units_adjusted:
+ description: Units added or removed by stock corrections.
+ label: Units adjusted
+ units_received:
+ description: Units booked into stock.
+ label: Units received
+ units_shipped:
+ description: Units dispatched from stock.
+ label: Units shipped
units_sold:
description: Sum of line item quantities.
label: Units sold
@@ -1809,6 +1864,9 @@ en:
yesterday:
label: Yesterday
seeds:
+ failed_payments:
+ description: Charges that failed over the last four weeks, by payment method.
+ name: Failed payments
first_time_vs_returning:
description: Sales split between first-time and returning buyers over the last four weeks.
name: First-time vs returning
@@ -1821,6 +1879,12 @@ en:
orders_by_payment_status:
description: Order counts and sales grouped by payment status over the last four weeks.
name: Orders by payment status
+ payments_by_method:
+ description: What each payment method took, net of refunds, over the last four weeks.
+ name: Payments by method
+ payments_over_time:
+ description: Daily payments taken and refunded over the last four weeks, compared with the previous period.
+ name: Payments over time
product_margin:
description: Products ranked by gross profit over the last four weeks, with cost and margin.
name: Product margin
@@ -1839,9 +1903,15 @@ en:
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
+ sell_through_by_variant:
+ description: Units shipped against units received per variant over the last four weeks.
+ name: Sell-through by variant
seller_payouts:
description: What each seller earned last month, after the marketplace commission.
name: Seller payouts
+ stock_movement_over_time:
+ description: Weekly units received and shipped over the last twelve months.
+ name: Stock movement over time
top_categories:
description: Best-selling categories by net sales over the last four weeks.
name: Top categories
diff --git a/spree/core/lib/spree/reporting/adapters/live.rb b/spree/core/lib/spree/reporting/adapters/live.rb
index a0aa7902ba..d53c985e4c 100644
--- a/spree/core/lib/spree/reporting/adapters/live.rb
+++ b/spree/core/lib/spree/reporting/adapters/live.rb
@@ -82,22 +82,13 @@ module Spree
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). A
- # canceled order keeps its completed_at, so it is excluded explicitly:
- # sales figures count what stayed sold.
+ # The base's own registered relation, already store-scoped and
+ # range-filtered. Sales bases need no `complete` scope on top of the
+ # range predicate (merging it would replace the range condition — Rails
+ # merge overwrites same-column wheres), and exclude canceled orders
+ # explicitly: sales figures count what stayed sold.
def base_relation(base, range)
- order_conditions = { currency: query.currency, completed_at: range }
- scope = case base
- when :orders
- query.store.orders.not_canceled.where(order_conditions)
- when :line_items
- query.store.line_items.merge(Spree::Order.not_canceled)
- .where(Spree::Order.table_name => order_conditions)
- else
- raise InvalidQuery, "unknown metric base #{base}"
- end
+ scope = query.registry.base!(base).relation.call(query.store, range, query.currency)
# Association default orderings break grouped selects on PostgreSQL.
scope.reorder(nil)
@@ -203,6 +194,13 @@ module Spree
"m_#{metric.name}"
end
+ # A bare `column:` symbol is read from its own base's table, which the
+ # base declares. Guessing it from a two-way ternary silently read every
+ # base but :orders as line items.
+ def base_table(base)
+ resolve_sql(query.registry.base!(base).table)
+ end
+
# Registered fragments defer table names as %{placeholders} because
# model classes cannot load while initializers register the vocabulary.
def resolve_sql(fragment)
@@ -215,7 +213,11 @@ module Spree
product_categories: Spree::ProductCategory.table_name,
refunds: Spree::Refund.table_name,
fees: Spree::Fee.table_name,
- commission_lines: Spree::CommissionLine.table_name)
+ commission_lines: Spree::CommissionLine.table_name,
+ payments: Spree::Payment.table_name,
+ payment_methods: Spree::PaymentMethod.table_name,
+ stock_movements: Spree::StockMovement.table_name,
+ stock_levels: Spree::StockLevel.table_name)
end
def dimension_alias(dim)
@@ -249,8 +251,7 @@ module Spree
resolved = if dimension.column.is_a?(String)
resolve_sql(dimension.column)
else
- table = dimension.base == :orders ? Spree::Order.table_name : Spree::LineItem.table_name
- "#{table}.#{dimension.column}"
+ "#{base_table(dimension.base)}.#{dimension.column}"
end
identifier!(resolved, dimension.name)
diff --git a/spree/core/lib/spree/reporting/default_vocabulary.rb b/spree/core/lib/spree/reporting/default_vocabulary.rb
index ba03bfb471..69e7e169d7 100644
--- a/spree/core/lib/spree/reporting/default_vocabulary.rb
+++ b/spree/core/lib/spree/reporting/default_vocabulary.rb
@@ -60,8 +60,60 @@ module Spree
WHERE c.line_item_id = %{line_items}.id), 0))
SQL
+ # A payment's own refunds, so "what we gave back" is attributed to the
+ # instrument that took the money rather than to the order.
+ PAYMENTS_COMPLETED_SUM = "SUM(CASE WHEN %{payments}.status = 'completed' THEN %{payments}.amount ELSE 0 END)".freeze
+ PAYMENTS_REFUNDED_SUM = <<~SQL.squish.freeze
+ SUM(COALESCE((SELECT SUM(pr.amount) FROM %{refunds} pr
+ WHERE pr.payment_id = %{payments}.id), 0))
+ SQL
+
+ # One movement kind's quantity. The kind carries the direction, so
+ # summing across kinds would net a receipt against a dispatch.
+ def self.movement_sum(kind)
+ "SUM(CASE WHEN %{stock_movements}.kind = '#{kind}' THEN %{stock_movements}.quantity ELSE 0 END)"
+ end
+
def self.install(registry)
registry.instance_eval do
+ # ---- bases ----
+ #
+ # Two families, because they answer different questions. Sales money
+ # is anchored on when an order completed; a payment is anchored on
+ # when it was taken, and inventory on when stock moved. Mixing them
+ # in one row would put three different clocks in one table.
+
+ base :orders, family: :sales, table: '%{orders}',
+ time_column: '%{orders}.completed_at',
+ relation: lambda { |store, range, currency|
+ store.orders.not_canceled.where(currency: currency, completed_at: range)
+ }
+
+ base :line_items, family: :sales, table: '%{line_items}', reaches: %i[line_items orders],
+ time_column: '%{orders}.completed_at',
+ relation: lambda { |store, range, currency|
+ store.line_items.merge(Spree::Order.not_canceled).
+ where(Spree::Order.table_name => { currency: currency, completed_at: range })
+ }
+
+ # A payment carries no completion timestamp, so it is anchored on
+ # when the row was created — near enough to when the money moved, and
+ # the only honest answer the schema can publish.
+ base :payments, family: :payments, table: '%{payments}',
+ time_column: '%{payments}.created_at',
+ relation: lambda { |store, range, _currency|
+ store.payments.where(created_at: range)
+ }
+
+ # The movement table carries no store of its own; tenancy is the walk
+ # through stock level → variant → product, which `for_store` owns.
+ base :stock_movements, family: :inventory, table: '%{stock_movements}', reaches: %i[stock_movements],
+ time_column: '%{stock_movements}.created_at',
+ relation: lambda { |store, range, _currency|
+ Spree::StockMovement.for_store(store).
+ where(Spree::StockMovement.table_name => { created_at: range })
+ }
+
# ---- the sales chain ----
#
# gross_sales - discounts - returns = net_sales
@@ -126,6 +178,35 @@ module Spree
base: :line_items, format: :money,
subject: -> { Spree::SellerTransfer }, key_scope: 'read_payouts'
+ # ---- payments ----
+ #
+ # What was actually taken and given back, by the instrument that
+ # moved it. Anchored on when the payment row was created, not on the
+ # order's completion — a balance paid weeks later belongs to the week
+ # it was paid.
+
+ metric :payments_received, sql: PAYMENTS_COMPLETED_SUM, base: :payments, format: :money
+ metric :payments_refunded, sql: PAYMENTS_REFUNDED_SUM, base: :payments, format: :money
+ metric :net_payments, sql: "#{PAYMENTS_COMPLETED_SUM} - #{PAYMENTS_REFUNDED_SUM}",
+ base: :payments, format: :money
+ metric :payments_count, sql: "COUNT(CASE WHEN %{payments}.status = 'completed' THEN 1 END)",
+ base: :payments, format: :integer
+ metric :payments_failed, sql: "COUNT(CASE WHEN %{payments}.status = 'failed' THEN 1 END)",
+ base: :payments, format: :integer
+
+ # ---- inventory ----
+ #
+ # Movement of stock, from the typed ledger. The kind carries the
+ # direction, so each metric sums one kind rather than raw quantity —
+ # `received` and `shipped` are both positive rows.
+
+ metric :units_received, sql: DefaultVocabulary.movement_sum('received'), base: :stock_movements, format: :integer
+ metric :units_shipped, sql: DefaultVocabulary.movement_sum('shipped'), base: :stock_movements, format: :integer
+ metric :units_adjusted, sql: DefaultVocabulary.movement_sum('adjusted'), base: :stock_movements, format: :integer
+ # What share of what arrived has left again. Both terms are counts of
+ # the same unit, so this reads as a percentage.
+ metric :sell_through, ratio: %i[units_shipped units_received], format: :percent
+
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 }
@@ -243,6 +324,59 @@ module Spree
}]
end
}
+
+ # ---- payment axes ----
+
+ dimension :payment_method, base: :payments, column: :payment_method_id, lookup: :payment_method,
+ subject: -> { Spree::PaymentMethod }, key_scope: 'read_settings',
+ resolve: ->(store, value) { store.payment_methods.find_by_prefix_id!(value).id },
+ hydrate: lambda { |store, ids, _params|
+ store.payment_methods.where(id: ids).to_h do |method|
+ [method.id, { id: method.prefixed_id, label: method.name, meta: { type: method.type } }]
+ end
+ }
+
+ # Distinct from the order-level `payment_status`, which says how much
+ # of an order is paid; this says whether one charge went through.
+ dimension :payment_result, base: :payments, column: :status,
+ values: -> { Spree::Payment.statuses }
+
+ dimension :paid_at, base: :payments, column: :created_at, type: :time,
+ grains: %i[day week month]
+
+ # ---- inventory axes ----
+
+ dimension :moved_at, base: :stock_movements, column: :created_at, type: :time,
+ grains: %i[day week month]
+
+ dimension :movement_kind, base: :stock_movements, column: :kind,
+ values: -> { Spree::StockMovement::KINDS }
+
+ # Reached through the movement's stock level, which is also how the
+ # base scopes itself to the store.
+ dimension :moved_variant, base: :stock_movements, column: '%{stock_levels}.variant_id',
+ joins: [:stock_level], 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
+ }
+
+ dimension :stock_location, base: :stock_movements, column: '%{stock_levels}.stock_location_id',
+ joins: [:stock_level], lookup: :stock_location,
+ subject: -> { Spree::StockLocation }, key_scope: 'read_stock',
+ resolve: ->(store, value) { store.stock_locations.find_by_prefix_id!(value).id },
+ hydrate: lambda { |store, ids, _params|
+ store.stock_locations.where(id: ids).to_h do |location|
+ [location.id, { id: location.prefixed_id, label: location.name, meta: {} }]
+ end
+ }
end
end
end
diff --git a/spree/core/lib/spree/reporting/query.rb b/spree/core/lib/spree/reporting/query.rb
index d86a0a4fa2..b44ede6d5b 100644
--- a/spree/core/lib/spree/reporting/query.rb
+++ b/spree/core/lib/spree/reporting/query.rb
@@ -272,6 +272,8 @@ 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!
+ validate_one_family!
+
incompatible = referenced_dimensions.reject { |d| metrics.all? { |m| registry.compatible?(m, d) } }
return if incompatible.empty?
@@ -279,6 +281,18 @@ module Spree
raise InvalidQuery,
"metrics #{offenders.map(&:name).join(', ')} cannot be grouped by #{incompatible.map(&:name).join(', ')}"
end
+
+ # Sales, payments and inventory answer different questions on different
+ # clocks — a payment total beside a units-received count is two reports
+ # wearing one table. The refusal names the families so a caller can split
+ # the query rather than guess why it was rejected.
+ def validate_one_family!
+ families = aggregated_metrics.map { |metric| registry.family_of(metric) }.uniq
+ return if families.size <= 1
+
+ raise InvalidQuery,
+ "metrics from different families cannot be combined in one query: #{families.sort.join(', ')}"
+ end
end
end
end
diff --git a/spree/core/lib/spree/reporting/registry.rb b/spree/core/lib/spree/reporting/registry.rb
index 4535b1b369..301b1e7da2 100644
--- a/spree/core/lib/spree/reporting/registry.rb
+++ b/spree/core/lib/spree/reporting/registry.rb
@@ -74,15 +74,65 @@ module Spree
end
end
+ # A relation metrics aggregate over, and the family it belongs to.
+ #
+ # Bases exist because the things a store measures sit at different grains:
+ # an order has no payment method, a payment has no line items, a stock
+ # movement has neither a customer nor a currency. A base names one grain,
+ # says how to reach it store-scoped, and declares which family it can be
+ # queried alongside.
+ #
+ # @!attribute family
+ # Bases sharing a family combine in one query (:orders and :line_items
+ # both answer questions about sales). Bases in different families never
+ # do — the query refuses the mix rather than inventing a join between
+ # grains that have no honest relationship.
+ # @!attribute relation
+ # ->(store, range, currency) returning the store-scoped, range-filtered
+ # relation. Money bases filter the currency; countable ones ignore it.
+ # @!attribute table
+ # The base's own table, as a %{placeholder}. Where a bare `column:`
+ # symbol on one of its dimensions is read from. Deliberately separate
+ # from time_column: a line item's clock lives on its order.
+ # @!attribute time_column
+ # Table-qualified column the range filters on, named in the schema so a
+ # caller knows what "last 30 days" means for this base.
+ # @!attribute reaches
+ # Bases whose dimensions this one can group by, itself included. An
+ # :orders dimension is reachable from :line_items through the order join;
+ # not the reverse.
+ Base = Struct.new(:name, :family, :table, :relation, :time_column, :reaches, keyword_init: true) do
+ def reaches?(dimension_base) = Array(reaches).include?(dimension_base)
+ end
+
# Allowlist of queryable metrics + dimensions. One global instance lives at
# `Spree.reporting`; core seeds the starter vocabulary in the engine
# initializer and applications/extensions append theirs in initializer files.
class Registry
- attr_reader :metrics, :dimensions
+ attr_reader :metrics, :dimensions, :bases
def initialize
@metrics = {}
@dimensions = {}
+ @bases = {}
+ end
+
+ # @param name [Symbol]
+ # @param family [Symbol] bases sharing a family combine in one query
+ # @param table [String] the base's own table as a %{placeholder}
+ # @param relation [Proc] ->(store, range, currency) → store-scoped relation
+ # @param time_column [String] table-qualified column the range filters on
+ # @param reaches [Array<Symbol>] bases whose dimensions this one can group by
+ def base(name, replace: false, family:, table:, relation:, time_column:, reaches: nil)
+ name = name.to_sym
+ raise ArgumentError, "base #{name} already registered (pass replace: true to override)" if @bases.key?(name) && !replace
+
+ @bases[name] = Base.new(name: name, family: family, table: table, relation: relation,
+ time_column: time_column, reaches: reaches || [name])
+ end
+
+ def base!(name)
+ @bases[name.to_sym] || raise(UnknownMember.new(:base, name, @bases.keys))
end
def metric(name, replace: false, **opts)
@@ -119,19 +169,35 @@ module Spree
@dimensions[name.to_sym] || raise(UnknownMember.new(:dimension, name, @dimensions.keys))
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.
+ # Whether a metric can be grouped or filtered by a dimension: every
+ # aggregated component of the metric must sit on a base that reaches the
+ # dimension's base. Order totals per product would double count, so
+ # :orders does not reach :line_items; the reverse holds through the order
+ # join. 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).all? { |component| base!(component.base).reaches?(dimension.base) }
+ end
+
+ # Whether two bases can appear in one query. Sales metrics combine with
+ # each other; a payment total beside a units-received count is two
+ # different questions wearing one answer, so the query refuses it.
+ def same_family?(one, other)
+ base!(one).family == base!(other).family
+ end
+
+ # A derived metric aggregates nothing itself — its components do.
+ def components(metric)
+ metric.derived? ? metric.ratio.map { |name| metric!(name) } : [metric]
+ end
- components = metric.derived? ? metric.ratio.map { |name| metric!(name) } : [metric]
- components.all? { |component| component.base == :line_items }
+ # The family a metric belongs to, read through its components so a
+ # derived metric answers with its ingredients' family rather than nil.
+ def family_of(metric)
+ base!(components(metric).first.base).family
end
end
diff --git a/spree/core/lib/spree/reporting/schema.rb b/spree/core/lib/spree/reporting/schema.rb
index 28a9bc2a70..6d9f838030 100644
--- a/spree/core/lib/spree/reporting/schema.rb
+++ b/spree/core/lib/spree/reporting/schema.rb
@@ -26,6 +26,9 @@ module Spree
timezone: (Time.find_zone(@store.preferred_timezone) || Time.zone).name,
supported_currencies: @store.supported_currencies_list.map(&:iso_code)
},
+ # Published so a builder can group the pickers and never offer a
+ # cross-family pair the query would refuse.
+ families: families(metrics),
metrics: metrics.map { |m| metric_entry(m) },
dimensions: dimensions.map { |d| dimension_entry(d, metrics) },
time_range: {
@@ -47,9 +50,24 @@ module Spree
private
+ # Each family with the members that belong to it, so a client can present
+ # sales, payments and inventory as the separate reports they are.
+ def families(metrics)
+ metrics.group_by { |metric| @registry.family_of(metric) }.map do |family, family_metrics|
+ {
+ name: family,
+ label: translate('families', family, :label),
+ metrics: family_metrics.map(&:name),
+ dimensions: @registry.dimensions.values.
+ select { |d| @allowed.call(d) && @registry.base!(d.base).family == family }.map(&:name)
+ }
+ end
+ end
+
def metric_entry(metric)
{
name: metric.name,
+ family: @registry.family_of(metric),
label: translate('metrics', metric.name, :label),
description: translate('metrics', metric.name, :description),
format: metric.format,
diff --git a/spree/core/spec/lib/spree/reporting/query_spec.rb b/spree/core/spec/lib/spree/reporting/query_spec.rb
index 047f33dbff..33a8b5631e 100644
--- a/spree/core/spec/lib/spree/reporting/query_spec.rb
+++ b/spree/core/spec/lib/spree/reporting/query_spec.rb
@@ -239,6 +239,80 @@ RSpec.describe Spree::Reporting::Query do
end
end
+ describe 'the payments family' do
+ let!(:order) { create(:completed_order_with_totals, store: store, completed_at: 3.days.ago) }
+ let!(:payment) { create(:payment, order: order, amount: 30, status: 'completed') }
+
+ it 'counts what was taken, net of what went back through the same instrument' do
+ result = run(metrics: %w[payments_received payments_refunded net_payments payments_count])
+ expect(result.totals[:payments_received][:value]).to eq(30.0)
+ expect(result.totals[:net_payments][:value]).to eq(30.0)
+ expect(result.totals[:payments_count][:value]).to eq(1)
+
+ create(:refund, amount: 12, payment: payment, order: order)
+
+ after = run(metrics: %w[payments_received payments_refunded net_payments])
+ expect(after.totals[:payments_refunded][:value]).to eq(12.0)
+ expect(after.totals[:net_payments][:value]).to eq(18.0)
+ end
+
+ it 'breaks payments down by the instrument that took them' do
+ result = run(metrics: %w[net_payments], dimensions: %w[payment_method])
+ expect(result.rows.first[:dimensions][:payment_method]).to eq(payment.payment_method_id)
+ end
+
+ it 'leaves a failed charge out of the money but counts it as a failure' do
+ create(:payment, order: order, amount: 99, status: 'failed')
+
+ result = run(metrics: %w[payments_received payments_failed])
+ expect(result.totals[:payments_received][:value]).to eq(30.0)
+ expect(result.totals[:payments_failed][:value]).to eq(1)
+ end
+
+ it 'refuses to answer a payments question and a sales question at once' do
+ expect { run(metrics: %w[net_payments total_sales]) }
+ .to raise_error(Spree::Reporting::InvalidQuery, /different families/)
+ end
+
+ it 'refuses a payments metric grouped by a sales axis' do
+ expect { run(metrics: %w[net_payments], dimensions: %w[product]) }
+ .to raise_error(Spree::Reporting::InvalidQuery, /cannot be grouped by/)
+ end
+ end
+
+ describe 'the inventory family' do
+ let(:variant) { create(:variant) }
+ let(:stock_level) { variant.stock_levels.first }
+
+ before do
+ stock_level.stock_movements.create!(quantity: 40, kind: 'received')
+ stock_level.stock_movements.create!(quantity: 10, kind: 'shipped')
+ end
+
+ def inventory(params)
+ run({ time_range: { since: 2.days.ago.to_date.to_s, until: Date.current.to_s } }.merge(params))
+ end
+
+ it 'sums each movement kind on its own, since the kind carries direction' do
+ result = inventory(metrics: %w[units_received units_shipped sell_through])
+ expect(result.totals[:units_received][:value]).to eq(40)
+ expect(result.totals[:units_shipped][:value]).to eq(10)
+ expect(result.totals[:sell_through][:value]).to eq(25.0)
+ end
+
+ it 'breaks movement down by the variant that moved' do
+ result = inventory(metrics: %w[units_received], dimensions: %w[moved_variant])
+ expect(result.rows.first[:dimensions][:moved_variant]).to eq(variant.id)
+ end
+
+ it 'leaves another store\'s movements out' do
+ other = create(:variant, product: create(:product, store: create(:store)))
+ other.stock_levels.first.stock_movements.create!(quantity: 500, kind: 'received')
+
+ expect(inventory(metrics: %w[units_received]).totals[:units_received][:value]).to eq(40)
+ 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 }
diff --git a/spree/core/spec/lib/spree/reporting/registry_spec.rb b/spree/core/spec/lib/spree/reporting/registry_spec.rb
index e537439780..5ecec40737 100644
--- a/spree/core/spec/lib/spree/reporting/registry_spec.rb
+++ b/spree/core/spec/lib/spree/reporting/registry_spec.rb
@@ -49,4 +49,35 @@ RSpec.describe Spree::Reporting::Registry do
expect(Spree.reporting.dimension!(:product).lookup).to eq(:product)
end
end
+
+ describe 'bases' do
+ it 'registers a base with the shape the how-to guide documents' do
+ registry = described_class.new
+ registry.base :subscriptions, family: :subscriptions, table: '%{subscriptions}',
+ time_column: '%{subscriptions}.created_at',
+ relation: ->(store, range, _currency) { store.orders.where(created_at: range) }
+
+ base = registry.base!(:subscriptions)
+ expect(base.family).to eq(:subscriptions)
+ # A base reaches only itself unless it says otherwise.
+ expect(base.reaches?(:subscriptions)).to be true
+ expect(base.reaches?(:orders)).to be false
+ end
+
+ it 'groups core bases into the three families that never mix' do
+ families = Spree.reporting.bases.values.group_by(&:family).transform_values { |b| b.map(&:name).sort }
+
+ expect(families[:sales]).to eq(%i[line_items orders])
+ expect(families[:payments]).to eq(%i[payments])
+ expect(families[:inventory]).to eq(%i[stock_movements])
+ end
+
+ it 'reads a line item axis from line items, never from the order its clock lives on' do
+ # The two were conflated while bases were hardcoded, which silently read
+ # every line-item dimension off spree_orders.
+ line_items = Spree.reporting.base!(:line_items)
+ expect(line_items.table).to include('line_items')
+ expect(line_items.time_column).to include('orders')
+ end
+ end
end
diff --git a/spree/core/spec/lib/spree/reporting/schema_spec.rb b/spree/core/spec/lib/spree/reporting/schema_spec.rb
index c40b2ef1e1..266f5fe14b 100644
--- a/spree/core/spec/lib/spree/reporting/schema_spec.rb
+++ b/spree/core/spec/lib/spree/reporting/schema_spec.rb
@@ -40,4 +40,24 @@ RSpec.describe Spree::Reporting::Schema do
expect(names).to include(:channel, :completed_at)
expect(names).not_to include(:product, :customer, :category, :variant)
end
+
+ it 'groups members into the families that can be queried together' do
+ families = schema[:families].index_by { |f| f[:name] }
+
+ expect(families.keys).to contain_exactly(:sales, :payments, :inventory)
+ expect(families[:sales][:metrics]).to include(:net_sales, :total_sales, :average_order_value)
+ expect(families[:payments][:metrics]).to include(:net_payments)
+ expect(families[:payments][:dimensions]).to include(:payment_method, :paid_at)
+ expect(families[:inventory][:metrics]).to include(:units_received, :sell_through)
+ # A sales axis never appears under another family's dimensions.
+ expect(families[:inventory][:dimensions]).not_to include(:product)
+ end
+
+ it 'stamps each metric with its family, resolving derived ones through their components' do
+ by_name = schema[:metrics].index_by { |m| m[:name] }
+
+ expect(by_name[:net_sales][:family]).to eq(:sales)
+ expect(by_name[:average_order_value][:family]).to eq(:sales)
+ expect(by_name[:sell_through][:family]).to eq(:inventory)
+ end
end