@spree/docs 0.1.225 → 0.1.227

package/dist/developer/core-concepts/inventory.md

@@ -51,7 +51,7 @@ A stock level carries four counts, and a fifth is derived from them. Keeping the
 | `incoming_count` | How much is on its way here — on a purchase order placed with a supplier, or a transfer already in transit |
 | **`available_count`** | `count_on_hand − allocated_count` — what's actually sellable, before checkout holds |
 
-Reserved and incoming are kept as counters rather than worked out on every read, because the Inventory page in the dashboard reads them for every row, many times a day, and only a handful of things change them: entering or leaving checkout moves reserved; placing, cancelling, closing or receiving a purchase order or transfer moves incoming. Nothing else writes them. If a figure ever looks wrong, `rake spree:stock:recount_levels` recomputes both from their sources and reports every row it corrected — the same task the 6.0 upgrade runs to fill them in for existing stock.
+Reserved and incoming are kept as counters rather than worked out on every read, because the Inventory page in the dashboard reads them for every row, many times a day, and only a handful of things change them: entering or leaving checkout moves reserved; marking a purchase order ordered or a transfer in transit adds to incoming, and receiving, closing, cancelling or reopening the document takes the remainder back off. Nothing else writes them. If a figure ever looks wrong, `rake spree:stock:recount_levels` recomputes both from their sources and reports every row it corrected — the same task the 6.0 upgrade runs to fill them in for existing stock.
 
 A transfer counts as incoming from the moment it is marked in transit, not when it is drafted: until the van leaves, nothing is moving. Units a delivery rejects at the dock leave incoming too — they are recorded on the receipt, but they are not coming.
 

package/dist/developer/core-concepts/reporting.md

@@ -0,0 +1,277 @@
+---
+title: Reporting
+description: The semantic layer behind the dashboard home screen, the Reports page and saved reports — a registry of metrics and dimensions compiled into one query contract.
+---
+
+## Overview
+
+Spree answers analytics questions through a **semantic layer**: a registry of
+*metrics* (numbers) and *dimensions* (ways to group and filter them), and one
+query contract that compiles a combination of the two into SQL.
+
+Developers extend the vocabulary. Merchants, the dashboard, saved reports and
+future agent tools all compose sentences from it. Nobody writes a report class
+per question.
+
+```mermaid
+flowchart LR
+    R["Spree.reporting<br/>registry"] --> Q["Spree::Reporting::Query<br/>validates + normalizes"]
+    Q --> A["Adapter<br/>(Live: SQL over orders + line items)"]
+    A --> Res["Result<br/>rows + totals"]
+    Res --> API["POST /reporting/query"]
+    R --> S["GET /reporting/schema"]
+    API --> D["Dashboard home,<br/>Reports page,<br/>saved reports, CSV export"]
+    S --> D
+```
+
+## The query contract
+
+A query names what to measure and how to slice it. This is the whole surface:
+
+```json
+{
+  "metrics": ["total_sales", "orders"],
+  "dimensions": [{ "name": "completed_at", "grain": "week" }],
+  "filters": [{ "dimension": "channel", "op": "eq", "value": "ch_86Rf07xd4z" }],
+  "time_range": { "preset": "last_4_weeks" },
+  "compare": "previous_period",
+  "sort": "-total_sales",
+  "limit": 50
+}
+```
+
+| Field | Meaning |
+|-------|---------|
+| `metrics` | One or more registered metric names. Required. |
+| `dimensions` | At most two. A `time` dimension also takes a `grain` (`day`, `week`, `month`). |
+| `filters` | `eq` or `in` against a dimension. Values are prefixed IDs where the dimension identifies a record. |
+| `time_range` | A named preset, or `since`/`until` as ISO 8601. A bare date covers the store's whole day. |
+| `compare` | `previous_period` adds `previous` and `growth` to every metric. |
+| `sort` / `limit` | Ranking controls; ignored for time series, which are always chronological and complete. |
+
+Unknown members are rejected, never dropped. A malformed query answers 422,
+not a partial result computed from the half the server understood.
+
+> **NOTE:** `GET /api/v3/admin/reporting/schema` returns the vocabulary the **calling
+> credential** may use, with labels, per-dimension compatible metrics, filter
+> operators, enumerated values and time presets. Build pickers from it rather
+> than hardcoding member names — that is how a new dimension reaches the UI
+> without a dashboard change.
+
+## Metrics
+
+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,
+  sql: 'SUM(%{orders}.total)', base: :orders, format: :money
+```
+
+- `sql` is a portable aggregate fragment. `%{orders}`, `%{line_items}`,
+  `%{variants}`, `%{products}`, `%{addresses}`, `%{product_categories}`,
+  `%{refunds}`, `%{fees}` and `%{commission_lines}` interpolate to real table
+  names.
+- `format` is `:money`, `:integer`, `:decimal` or `:percent`. A `:money` metric
+  forces a single-currency scope and arrives with a formatted `display` string;
+  a `:percent` metric arrives as the number a merchant reads (`42.5`), not the
+  fraction.
+
+  Amounts are **never converted**. A query answers in one currency — the one
+  it names, or the store's default — and every base a money metric reads must
+  filter by it, or two currencies end up added together under one symbol. A
+  store selling in several therefore has as many answers as it has
+  currencies, which is why the home screen offers a currency alongside its
+  channel and date range.
+- `ratio: [:numerator, :denominator]` defines a **derived** metric, computed
+  after aggregation so it is correct for both rows and totals. Average order
+  value is `ratio: %i[total_sales orders]`, never `AVG()`.
+
+Money that belongs to an order but lives on another table — refunds,
+commissions — is summed through a **correlated subquery** rather than a join.
+An order with three refunds must stay one row; joining would multiply the base
+row and inflate every other metric in the same query.
+
+### The sales chain
+
+Core's sales metrics follow the sequence merchants and accountants already use,
+so a Spree figure means what the same word means everywhere else:
+
+```
+gross_sales − discounts − returns = net_sales
+net_sales + shipping + duties + fees + taxes = total_sales
+```
+
+`returns` counts money refunded **in the period the refund was issued**, not
+the period of the original order. A report over a past range can therefore
+change after the fact, which is the conventional treatment and the only one an
+open accounting period can produce.
+
+`cost_of_goods`, `gross_profit` and `gross_margin` read the line item's
+`cost_price`. That column is nullable, so a variant with no cost contributes
+zero and margin over an incompletely-costed catalogue reads high.
+
+## Dimensions
+
+A dimension groups and filters. Its definition owns every behaviour keyed off
+it, which is what lets an extension-registered dimension work end to end:
+
+```ruby
+Spree.reporting.dimension :channel, base: :orders, column: :channel_id,
+  lookup: :channel,
+  subject: -> { Spree::Channel }, key_scope: 'read_channels',
+  resolve: ->(store, value) { store.channels.find_by_prefix_id!(value).id },
+  hydrate: lambda { |store, ids, _params|
+    store.channels.where(id: ids).to_h { |c| [c.id, { id: c.prefixed_id, label: c.name, meta: {} }] }
+  }
+```
+
+| Option | Purpose |
+|--------|---------|
+| `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. |
+| `type` | `:value` (default) or `:time`. Time dimensions take `grains` and zero-fill buckets. |
+| `lookup` | Tags what the keys identify (`:product`, `:customer`), so clients know display payloads are coming. |
+| `resolve` | Maps a filter's prefixed ID to the raw key, through store-scoped collections. |
+| `hydrate` | Turns raw keys into `{ id:, label:, meta: }` for display. |
+| `subject` / `key_scope` | Authorization — see below. |
+| `values` | Enumerated raw values for status-like dimensions, published as the filter list. |
+
+## Authorization
+
+Reporting never widens what a caller can see. Two axes are enforced together:
+
+- **Staff (JWT)** need `read_reports` plus `:read` on each referenced
+  dimension's `subject`. Order data is always required.
+- **API keys** need `read_reports` plus each dimension's `key_scope`.
+
+Declaring `subject` without `key_scope` raises at registration, so a member
+cannot ship with one axis unguarded. The schema endpoint filters by the same
+rule, so a picker never offers a dimension whose query would be refused.
+
+## Counters
+
+Not everything on the home screen is a report over a period. "Orders to
+fulfill", "Open returns" and "Low stock" are the state of the store right now,
+with no time range and no currency. The registry holds these as **counters**
+beside metrics and dimensions, and `GET /dashboard/counters` evaluates them:
+
+```json
+{
+  "channel_id": null,
+  "counters": [
+    {
+      "key": "orders_to_fulfill",
+      "value": 12,
+      "nav": "orders",
+      "link": {
+        "resource": "orders",
+        "filters": [{ "field": "fulfillment_status", "operator": "eq", "value": "unfulfilled" }]
+      }
+    }
+  ]
+}
+```
+
+One request serves both surfaces that show these numbers: the home screen's
+card and the sidebar's badges. A parent nav entry sums its own counter and its
+children's, because the sidebar only shows the children of the section you are
+in — a count nobody sees until they have already navigated there tells them
+nothing. Orders carries the total of what is waiting to ship plus the open
+returns, exchanges and claims; expanding the section breaks it down.
+
+Three things follow from counters living in the registry:
+
+- **No copy crosses the wire.** A counter is a key and a number; the client
+  translates the key in its own language. An interface in one language can
+  never end up labelling a number in another.
+- **Each counter carries its own `subject` and `key_scope`**, filtered by the
+  same rule as the rest of the vocabulary. A role without stock access gets
+  a shorter list, not a refused card.
+- **The link is declared beside the count.** The list a number opens shows
+  exactly the rows that were counted, because the filter and the query are
+  registered together — the counter and the list share one scope rather than
+  each expressing the question their own way. A counter with no list that can
+  honestly show what it counted carries no link.
+
+Core ships seven: orders to fulfill, payments to collect, open returns, open
+exchanges, open claims, low stock and out of stock. Orders to fulfill and the
+three post-sale counters badge the sidebar; payments to collect deliberately
+does not, since a badge that is lit on almost every store stops carrying
+information.
+
+The two stock counters read the shelves exactly as the Inventory page does —
+what a customer could still buy, counted per location — so the number and the
+filtered list it opens always agree. The low stock one reads the store's
+`low_stock_threshold` preference (default five units; zero turns it off),
+which merchants set under store settings → Inventory.
+
+## What a report counts
+
+Two rules decide what the numbers mean:
+
+**Canceled orders are excluded.** A canceled order keeps its `completed_at`,
+so both bases filter it out. Sales figures count what stayed sold. Refunds are
+unaffected — they already net out of `payment_total`.
+
+**The Total row is the dimensionless figure.** Grouping joins apply only to
+the grouped query; totals run on the base rows with the same filters. A
+product in three categories is counted once in the footer, and an order
+without a shipping address still counts in "Sales by country". A consequence
+worth stating to merchants: **rows of a fan-out breakdown need not sum to the
+total**, and that is correct.
+
+Time buckets resolve in the store's timezone, and a comparison period is the
+range shifted back by its own length, paired bucket by bucket from the start.
+
+## Saved reports
+
+A saved report (`Spree::SavedReport`, prefixed ID `sq_…`) is a stored query
+plus a name, owned by the store and visible to every staff member who may read
+reports. Its visualization is inferred from the query's shape rather than
+configured: a time dimension charts, any other dimension ranks, no dimension
+shows totals.
+
+Nine built-in reports are seeded per store. They are read-only on the model,
+not merely in the UI — copy one to change it.
+
+CSV export rides the existing [export pipeline](imports-exports.md)
+as `Spree::Exports::Report`, so it inherits the background job, attachment and
+email. The export re-authorizes its members against the requesting user, which
+is why it requires a user and API keys cannot queue one.
+
+## Current limits
+
+Worth knowing before you design an extension:
+
+- **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.
+
+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
+
+- [Extend reporting](../how-to/extend-reporting.md) — a worked example
+- [Imports and exports](imports-exports.md) — the CSV pipeline
+- [Permissions](../dashboard/customization/permissions.md) — `read_reports` and member scopes

package/dist/developer/how-to/extend-reporting.md

@@ -0,0 +1,215 @@
+---
+title: Extend Reporting
+description: Register your own metrics and dimensions so merchants can compose them in the Reports builder, saved reports and CSV exports.
+---
+
+## Overview
+
+Reporting is extended by adding *vocabulary*, not by writing report classes.
+Register a metric or a dimension in an initializer and it becomes available
+everywhere at once: the Reports builder, saved reports, CSV export and the
+schema endpoint.
+
+Read [how reporting works](../core-concepts/reporting.md) first — this
+guide assumes the query contract and the metric/dimension split.
+
+## Add a metric
+
+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
+  Spree.reporting.metric :items_per_order,
+    sql: 'SUM(%{line_items}.quantity)',
+    base: :line_items,
+    format: :integer
+end
+```
+
+That is the whole change. The metric appears in `GET /reporting/schema`, in
+the builder's metric list, and can be saved into a report.
+
+Give it a label so merchants do not read the raw name:
+
+```yaml config/locales/en.yml
+en:
+  spree:
+    reporting:
+      metrics:
+        items_per_order:
+          label: Items per order
+          description: Units sold divided across orders in the period.
+```
+
+### Derived metrics
+
+A ratio is computed after aggregation, so it stays correct for both rows and
+totals — which a plain `AVG()` would not:
+
+```ruby
+Spree.reporting.metric :average_units_per_order,
+  ratio: %i[units_sold orders], format: :decimal
+```
+
+## Add a dimension
+
+A dimension groups and filters. The simplest kind is a column on the base
+table:
+
+```ruby
+Spree.reporting.dimension :order_locale, base: :orders, column: :locale
+```
+
+### A dimension that identifies records
+
+When the keys are IDs rather than plain values, declare four things together:
+how to reach the table, how to resolve a filter value, how to render the key,
+and who may see it.
+
+```ruby
+Spree.reporting.dimension :seller, base: :line_items,
+  column: '%{variants}.seller_id',
+  joins: [:variant],
+  lookup: :seller,
+  subject: -> { Spree::Seller },
+  key_scope: 'read_sellers',
+  resolve: ->(store, value) { store.sellers.find_by_prefix_id!(value).id },
+  hydrate: lambda { |store, ids, _params|
+    store.sellers.where(id: ids).to_h do |seller|
+      [seller.id, { id: seller.prefixed_id, label: seller.name, meta: {} }]
+    end
+  }
+```
+
+What each part buys you:
+
+- `joins` is applied only to the grouped query, so the Total row stays the
+  store's real figure even when the join fans out.
+- `resolve` lets a filter accept the prefixed IDs clients already hold.
+  Scope it through the store, so an ID from another store is a 404.
+- `hydrate` is batched once per dimension per response, not per row.
+- `subject` and `key_scope` are mandatory together. Staff need `:read` on the
+  subject; API keys need the scope. Omitting `key_scope` raises at
+  registration rather than shipping a member that only guards one axis.
+
+### Status-like dimensions
+
+Publish the values so the builder can offer checkboxes instead of a text box:
+
+```ruby
+Spree.reporting.dimension :subscription_state, base: :orders,
+  column: :subscription_state,
+  values: -> { MyExtension::SUBSCRIPTION_STATES }
+```
+
+Use a lambda so model constants load lazily. Label the values under
+`spree.reporting.values.<dimension>.<value>`; they are translated server-side,
+so a plugin needs no dashboard locale edit.
+
+## Verify it
+
+Query the contract directly:
+
+```ruby
+Spree::Reporting::Query.new(
+  store: Spree::Store.default,
+  params: { metrics: %w[items_per_order], dimensions: %w[order_locale] }
+).execute
+```
+
+Or over HTTP:
+
+```bash
+curl -X POST https://example.com/api/v3/admin/reporting/query \
+  -H "X-Spree-API-Key: $SECRET_KEY" -H 'Content-Type: application/json' \
+  -d '{"metrics":["items_per_order"],"dimensions":["order_locale"]}'
+```
+
+A spec is worth writing for the parts that are easy to get wrong — the
+authorization declaration and the hydration payload:
+
+```ruby spec/lib/my_extension/reporting_spec.rb
+RSpec.describe 'seller reporting vocabulary' do
+  let(:store) { @default_store }
+
+  it 'requires the seller subject and scope' do
+    query = Spree::Reporting::Query.new(
+      store: store, params: { metrics: %w[units_sold], dimensions: %w[seller] }
+    )
+
+    expect(query.required_subjects).to include(Spree::Seller)
+    expect(query.required_key_scopes).to include('read_sellers')
+  end
+end
+```
+
+## Add a counter
+
+A counter is a point-in-time number for the home screen's Operations card:
+no time range, no currency, no base. It takes the store and the channel the
+merchant is looking at and returns an integer.
+
+```ruby
+Spree.reporting.counter :orders_on_hold,
+  subject: -> { Spree::Order }, key_scope: 'read_orders',
+  count: ->(store, channel:) { store.orders.complete.for_channel(channel).where(on_hold: true).count },
+  link: { resource: 'orders', filters: [{ field: 'on_hold', operator: 'eq', value: 'true' }] }
+```
+
+The endpoint sends the key and the number, never any text — the dashboard
+owns every string it shows. Add
+`admin.pages.home.operations.counters.orders_on_hold.label`, and optionally
+`.description`, to your dashboard locale files; a counter with no entry falls
+back to its humanized key, so it reads sensibly before you translate it.
+
+Pass `nav:` with a sidebar entry's key to badge that entry with this count.
+Declare `link` only when the list filter shows exactly the rows counted — the
+dashboard resolves `resource` to one of its lists (`orders`, `returns`,
+`exchanges`, `claims`, `products`, `inventory`) and appends the channel filter
+itself for order lists.
+
+## Overriding a built-in member
+
+Registration refuses a duplicate name unless you say so explicitly:
+
+```ruby
+Spree.reporting.metric :total_sales, replace: true,
+  sql: 'SUM(%{orders}.total - %{orders}.delivery_total)',
+  base: :orders, format: :money
+```
+
+Redefining what a built-in number means changes every saved report using it,
+including the seeded ones. Prefer a new name unless you intend exactly that.
+
+## What you cannot do yet
+
+These are limits of the compiler, not of registration:
+
+- **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.
+
+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
+
+- [Reporting](../core-concepts/reporting.md) — the concepts
+- [Permissions](../dashboard/customization/permissions.md) — scopes and subjects
+- [Imports and exports](../core-concepts/imports-exports.md) — row-level CSV

package/dist/developer/upgrades/5.6-to-6.0.md

@@ -572,6 +572,18 @@ to `Spree::Base`.
 
 The `spree_state_changes` and `spree_log_entries` tables are **not dropped until 6.1**, so your existing rows survive the upgrade. If you want the history long-term, export it before upgrading to 6.1.
 
+### `Spree::Report` is gone
+
+`Spree::Report`, its `Reports::SalesTotal` and `Reports::ProductsPerformance` subclasses, `Spree::ReportLineItem` and its subclasses, `Spree::ReportMailer`, `Spree::ReportSubscriber`, `Spree::Reports::GenerateJob`, the `Spree.reports` registry and the `reports` queue entry are all removed, along with the `reports` associations on `Spree::Store` and the admin user.
+
+Nothing in 5.6 could reach it: there was no API endpoint and no admin screen, so a report could only be created from Ruby.
+
+**Where each question goes now.** Aggregates — revenue by channel, product performance, anything you would have written a report class for — are [reporting](../core-concepts/reporting.md) queries, composed from registered metrics and dimensions rather than a class per question. Row-level CSV of records is a `Spree::Export` subclass, which is what [imports and exports](../core-concepts/imports-exports.md) covers, and unlike `Spree::Report` it has both an Admin API and a dashboard page.
+
+**Your rows are safe.** The `spree_reports` and `spree_report_line_items` tables are left exactly as they are — nothing reads them, and no migration drops them. A store installing 6.0 fresh never creates them. If you want the old report history, export it whenever suits you; there is no deadline.
+
+If you subclassed `Spree::Report` in your own application, that class no longer has a superclass and will raise on boot. Move the question to one of the two replacements above.
+
 ## Deprecated in 6.0, removed in 6.1
 
 Every rename keeps the legacy name working for one release with a deprecation warning. The notable ones:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spree/docs",
-  "version": "0.1.225",
+  "version": "0.1.227",
   "description": "Spree Commerce developer documentation for AI agents and local reference",
   "type": "module",
   "license": "CC-BY-4.0",

package/dist/developer/how-to/custom-report.md

@@ -1,387 +0,0 @@
----
-title: Build a Custom Report
-description: Step-by-step guide to creating custom reports with data queries, line item formatters, and CSV export.
----
-
-## Overview
-
-Spree's reporting system is designed for extension. Each report is a pair of classes — a **Report** that defines the data query and a **ReportLineItem** that formats each row — registered in `Spree.reports` so it appears in the admin UI.
-
-This guide walks you through building a custom report from scratch, including advanced patterns for SQL aggregations and multi-vendor support.
-
-Before starting, make sure you understand [how the reporting system works](/v5/developer/core-concepts/reports).
-
-## Creating a Custom Report
-
-### Step 1: Create the Report Class
-
-Create a new report class inheriting from `Spree::Report`. The key method to implement is `line_items_scope`, which returns an `ActiveRecord::Relation` defining the records in your report:
-
-```ruby app/models/spree/reports/customer_orders.rb
-module Spree
-  module Reports
-    class CustomerOrders < Spree::Report
-      # Define the scope of records to include in the report
-      def line_items_scope
-        store.orders.complete.where(
-          completed_at: date_from..date_to,
-          currency: currency
-        ).includes(:user, :bill_address)
-      end
-    end
-  end
-end
-```
-
-The `line_items_scope` method has access to:
-
-| Helper | Description |
-|--------|-------------|
-| `store` | The current store |
-| `date_from` | Report start date |
-| `date_to` | Report end date |
-| `currency` | Report currency |
-| `vendor` | Vendor (if multi-vendor is enabled) |
-
-### Step 2: Create the Line Item Class
-
-Create a corresponding line item class that transforms each record into report columns. The class name must match the report class name (e.g., `Reports::CustomerOrders` → `ReportLineItems::CustomerOrders`):
-
-```ruby app/models/spree/report_line_items/customer_orders.rb
-module Spree
-  module ReportLineItems
-    class CustomerOrders < Spree::ReportLineItem
-      # Define attributes that will become columns
-      attribute :order_number, :string
-      attribute :completed_at, :string
-      attribute :customer_email, :string
-      attribute :customer_name, :string
-      attribute :item_count, :integer
-      attribute :total, :string
-
-      # Map record fields to report columns
-      def order_number
-        record.number
-      end
-
-      def completed_at
-        record.completed_at.strftime('%Y-%m-%d %H:%M')
-      end
-
-      def customer_email
-        record.email
-      end
-
-      def customer_name
-        record.bill_address&.full_name
-      end
-
-      def item_count
-        record.line_items.sum(:quantity)
-      end
-
-      def total
-        Spree::Money.new(record.total, currency: currency)
-      end
-    end
-  end
-end
-```
-
-**Important notes:**
-- Use `attribute` to define columns with their types — these become CSV headers
-- Each attribute needs a corresponding method that extracts/formats data from `record`
-- `record` is a single item from `line_items_scope`
-- Use `Spree::Money` for currency formatting
-- `currency` and `store` are delegated from the report
-
-#### Available Base Class Methods
-
-`Spree::ReportLineItem` provides:
-
-```ruby
-# Returns column headers for display
-self.headers
-# => [{ name: :order_number, label: "Order Number" }, ...]
-
-# Returns column names for CSV header row
-self.csv_headers
-# => ["order_number", "completed_at", "customer_email", ...]
-
-# Converts line item to CSV row array
-to_csv
-# => ["R123456", "2025-01-15 14:30", "john@example.com", ...]
-```
-
-### Step 3: Register the Report
-
-Add your report to the registry in `config/initializers/spree.rb`:
-
-```ruby config/initializers/spree.rb
-Rails.application.config.after_initialize do
-  Spree.reports << Spree::Reports::CustomerOrders
-end
-```
-
-### Step 4: Add Translations
-
-Add the report name and column header translations:
-
-```yaml config/locales/en.yml
-en:
-  spree:
-    report_names:
-      customer_orders: Customer Orders
-    order_number: Order Number
-    completed_at: Completed At
-    customer_email: Customer Email
-    customer_name: Customer Name
-    item_count: Item Count
-    total: Total
-```
-
-After restarting your application, the new report will be available in **Admin > Reports**.
-
-## Advanced Patterns
-
-### Complex Queries with Aggregations
-
-For reports that aggregate data across records, use SQL directly in `line_items_scope`:
-
-```ruby app/models/spree/reports/revenue_by_category.rb
-module Spree
-  module Reports
-    class RevenueByCategory < Spree::Report
-      def line_items_scope
-        line_items_sql = Spree::LineItem
-          .joins(:order)
-          .where(
-            spree_orders: {
-              completed_at: date_from..date_to,
-              currency: currency
-            }
-          )
-          .select(
-            "spree_line_items.variant_id",
-            "SUM(spree_line_items.quantity) as quantity",
-            "SUM(spree_line_items.pre_tax_amount) as revenue"
-          )
-          .group(:variant_id)
-          .to_sql
-
-        store.taxons
-          .where(depth: 1)  # Top-level categories
-          .joins("LEFT JOIN spree_products_taxons ON spree_products_taxons.taxon_id = spree_taxons.id")
-          .joins("LEFT JOIN spree_variants ON spree_variants.product_id = spree_products_taxons.product_id")
-          .joins("LEFT JOIN (#{line_items_sql}) AS line_items ON line_items.variant_id = spree_variants.id")
-          .select(
-            "spree_taxons.*",
-            "COALESCE(SUM(line_items.quantity), 0) AS total_quantity",
-            "COALESCE(SUM(line_items.revenue), 0.0) AS total_revenue"
-          )
-          .group("spree_taxons.id")
-      end
-    end
-  end
-end
-```
-
-When using aggregated queries, the `record` in your line item class will have virtual attributes (like `total_quantity`, `total_revenue`) available as methods.
-
-### Custom Summary Section
-
-Override `summary` to provide aggregate metrics alongside the line items:
-
-```ruby app/models/spree/reports/customer_orders.rb
-module Spree
-  module Reports
-    class CustomerOrders < Spree::Report
-      def summary
-        {
-          total_orders: line_items_scope.count,
-          total_revenue: line_items_scope.sum(:total),
-          average_order_value: line_items_scope.average(:total)
-        }
-      end
-    end
-  end
-end
-```
-
-### Multi-Vendor Support
-
-If you're using Spree Multi-Vendor, filter by vendor when one is selected:
-
-```ruby app/models/spree/reports/vendor_sales.rb
-module Spree
-  module Reports
-    class VendorSales < Spree::Report
-      def line_items_scope
-        scope = store.line_items.where(
-          order: Spree::Order.complete.where(
-            completed_at: date_from..date_to,
-            currency: currency
-          )
-        )
-
-        # Filter by vendor if one is selected
-        scope = scope.where(vendor_id: vendor.id) if defined?(vendor) && vendor.present?
-
-        scope
-      end
-    end
-  end
-end
-```
-
-## Testing Custom Reports
-
-### Testing the Report Class
-
-Test that your report's `line_items_scope` returns the correct records:
-
-```ruby spec/models/spree/reports/customer_orders_spec.rb
-require 'rails_helper'
-
-RSpec.describe Spree::Reports::CustomerOrders, type: :model do
-  let(:store) { create(:store) }
-  let(:user) { create(:admin_user) }
-
-  subject(:report) do
-    described_class.new(
-      store: store,
-      user: user,
-      currency: 'USD',
-      date_from: 1.month.ago,
-      date_to: Time.current
-    )
-  end
-
-  describe '#line_items_scope' do
-    let!(:completed_order) do
-      create(:completed_order_with_totals, store: store, currency: 'USD', completed_at: 1.week.ago)
-    end
-
-    let!(:incomplete_order) do
-      create(:order, store: store, currency: 'USD', state: 'cart')
-    end
-
-    let!(:other_currency_order) do
-      create(:completed_order_with_totals, store: store, currency: 'EUR', completed_at: 1.week.ago)
-    end
-
-    let!(:old_order) do
-      create(:completed_order_with_totals, store: store, currency: 'USD', completed_at: 2.months.ago)
-    end
-
-    it 'returns only completed orders within the date range and currency' do
-      scope = report.line_items_scope
-
-      expect(scope).to include(completed_order)
-      expect(scope).not_to include(incomplete_order)
-      expect(scope).not_to include(other_currency_order)
-      expect(scope).not_to include(old_order)
-    end
-  end
-
-  describe '#line_items' do
-    let!(:order) do
-      create(:completed_order_with_totals, store: store, currency: 'USD', completed_at: 1.week.ago)
-    end
-
-    it 'returns ReportLineItem objects' do
-      items = report.line_items
-      expect(items).to all(be_a(Spree::ReportLineItems::CustomerOrders))
-    end
-
-    it 'respects the limit option' do
-      create(:completed_order_with_totals, store: store, currency: 'USD', completed_at: 2.days.ago)
-      items = report.line_items(limit: 1)
-      expect(items.length).to eq(1)
-    end
-  end
-end
-```
-
-### Testing the ReportLineItem Class
-
-Test that your line item correctly formats each record:
-
-```ruby spec/models/spree/report_line_items/customer_orders_spec.rb
-require 'rails_helper'
-
-RSpec.describe Spree::ReportLineItems::CustomerOrders, type: :model do
-  let(:store) { create(:store) }
-  let(:user) { create(:admin_user) }
-  let(:bill_address) { create(:address) }
-  let(:order) do
-    create(:completed_order_with_totals,
-           store: store,
-           currency: 'USD',
-           completed_at: 1.week.ago,
-           bill_address: bill_address)
-  end
-
-  let(:report) do
-    Spree::Reports::CustomerOrders.new(
-      store: store,
-      user: user,
-      currency: 'USD',
-      date_from: 1.month.ago,
-      date_to: Time.current
-    )
-  end
-
-  subject(:line_item) { described_class.new(record: order, report: report) }
-
-  describe '#order_number' do
-    it 'returns the order number' do
-      expect(line_item.order_number).to eq(order.number)
-    end
-  end
-
-  describe '#customer_name' do
-    it 'returns the billing address full name' do
-      expect(line_item.customer_name).to eq(bill_address.full_name)
-    end
-
-    context 'when no billing address' do
-      let(:bill_address) { nil }
-
-      it 'returns nil' do
-        order.update_column(:bill_address_id, nil)
-        order.reload
-        expect(line_item.customer_name).to be_nil
-      end
-    end
-  end
-
-  describe '#total' do
-    it 'returns a Spree::Money formatted total' do
-      result = line_item.total
-      expect(result).to be_a(Spree::Money)
-      expect(result.money.to_f).to eq(order.total.to_f)
-    end
-  end
-
-  describe '#to_csv' do
-    it 'returns an array of values for CSV row' do
-      csv_row = line_item.to_csv
-      expect(csv_row.length).to eq(6)
-      expect(csv_row[0]).to eq(order.number)
-    end
-  end
-end
-```
-
-### Key Testing Patterns
-
-1. **Test scope filtering** — verify `line_items_scope` returns only records matching date range, currency, and store
-2. **Test attribute formatting** — verify each attribute method returns correctly formatted data
-3. **Test CSV output** — check `headers`, `csv_headers`, and `to_csv` return expected values
-4. **Test edge cases** — handle nil values gracefully (e.g., missing addresses)
-
-## Related Documentation
-
-- [Reports](/v5/developer/core-concepts/reports) - Report architecture and built-in reports
-- [Events](../core-concepts/events.md) - How report generation uses the events system