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 ability for merchants to customize order number format (#14430)

Damian Legawiec9a4eb466c269
diff --git a/.changeset/document-number-customization.md b/.changeset/document-number-customization.md
new file mode 100644
index 0000000000..f5db2c6aa0
--- /dev/null
+++ b/.changeset/document-number-customization.md
@@ -0,0 +1,12 @@
+---
+'@spree/admin-sdk': minor
+'@spree/dashboard': minor
+---
+
+Order numbers are now configurable from the dashboard.
+
+**Settings → Store → Order numbers** controls how document numbers are shaped: the numbering format (sequential or random), the order number prefix and suffix, and the value the sequence starts at. A live preview shows what the next number will look like.
+
+Sequential numbering is the new default — orders count up from 1001 (`R1001`, `R1002`) instead of carrying nine random digits. Merchants who would rather not disclose their order volume can switch the format back to random. Either way, changes apply to future orders only; numbers already issued never change.
+
+`StoreUpdateParams` and the `Store` type gain `preferred_document_number_format`, `preferred_order_number_prefix`, `preferred_order_number_suffix` and `preferred_order_number_sequence_start`.
diff --git a/CLAUDE.md b/CLAUDE.md
index 8935ac8d36..f0e581855d 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -21,6 +21,7 @@ Active plans (6.0 target, work pending):
- `6.0-remove-master-variant.md` — Eliminate is_master, add default_variant_id FK on Product. **Shipped to 6-0-dev (PR #14265):** is_master removed from all models, default_variant_id + `spree:remove_master_variant` data-migration rake landed; only the physical is_master column drop remains (6.1 cleanup).
- `6.0-typed-stock-movements.md` — Replace generic StockMovement with typed kinds + concrete FKs
- `6.0-normalize-state-to-status.md` — Rename state → status on Payment, Shipment, InventoryUnit, ReturnAuthorization, GiftCard
+- `6.0-document-numbers.md` — Document number customization (**implemented 2026-08-13**): `Spree::Core::NumberGenerator` module factory → **`has_spree_number prefix: 'R'`** (macro from `Spree::HasNumber`, included into `Spree::Base` — no per-model include) + runtime `Spree.number_generators` registry (`Sequential` | `Random` strategies). **Sequential is the 6.0 default** (per-`(store, resource_type)` `spree_number_sequences` counter, `with_lock`, start 1001), random opt-in; merchant settings = one "Order numbers" card (prefix/suffix/format/start as Store preferences) — orders only. Fulfillment + Payment numbers become **derived methods** (`R1001-F1`/`R1001-P1`; stored value honored on legacy rows, columns frozen — never write them; gateway `order_id` = `payment.number`); every other numbered model keeps its stored number (Import/Export mail theirs, so they stayed numbered too), and `Spree::PurchaseOrder` must be born with `has_spree_number prefix: 'PO'`. Saving a numbered record with `validate: false` requires calling `generate_number` first. Never parse/regex a `number`; mostly-gapless, never legal invoice numbering.
- `6.0-delivery-profiles.md` — **Implemented in PR #14404 (2026-08-09).** `Spree::DeliveryProfile` = ShippingCategory promoted via table rename (`spree_shipping_categories`→`spree_delivery_profiles`, `products.shipping_category_id`→`delivery_profile_id`): store-scoped STI (kinds `DeliveryProfiles::Shipping`/`::Digital` via `Spree.delivery_profile_types`), one default per store, products reference it directly and it's required (auto-assigned: type template else store default; ProductType stamps at creation only — template doctrine). Profile ↔ stock locations (origins, empty=all) + profile→zones + profile→methods; method binds ≤1 zone (m:n join dropped), optional ships-from narrowing per method (no location-group layer — considered, dropped). **Classes only, NO string vocabularies:** method `fulfillment_type` column dropped, `Spree.fulfillment_types` registry + ProductType array deleted; behavior = `FulfillmentProvider` class predicates (`digital?`/`pickup?`/`pickup_point?`/`requires_address?`), rate-provider `requires_address?`, profile kind `digital?`/`requires_shipping_address?` + composition validations. Carts split per profile (`Splitter::DeliveryProfile`); Coordinator allocates only from profile-covered locations. `spree:migrate_delivery_profiles` (5.6→6.0 manifest) does store assignment/kind detection/non-narrowing fold-in/method m:n collapse (`spree_shipping_method_categories` survives to 6.1 as source). ShippingCategory/ShippingMethodCategory classes + associations deleted. Supersedes the string-registry + "named groups 6.1" decisions.
- `6.0-fulfillment-and-delivery.md` — Shipment→Fulfillment, ShippingMethod→DeliveryMethod, drop ShippingCategory, FulfillmentProvider strategy, pickup (merchant StockLocation) + pickup_point (third-party PickupPointProvider). **Shipped to 6-0-dev (Waves 2+4+6):** renames + deprecated twins, providers (Manual/Digital/Pickup/PickupPoint), dual-emit events, store pickup discovery endpoints, admin delivery_methods/delivery_zones CRUD + dashboard settings pages, FulfillmentMailer; Wave 7 shipping→delivery data migration remains. Pickup work beyond shipped code deferred to 6.1 (2026-08-06): contract hardening (`new(delivery_method)` ctor, `find_nearby` zipcode/query) + how-to guide; `PickupPointProvider::Base` stays **undocumented in 6.0** (v6 docs cover only the delivery rate provider interface) — never add pickup-provider docs in 6.0 work. Delivery mechanics live on provider classes (`pickup_point` provider ships but stays unregistered until 6.1; `local_delivery` cut = shipping + postal-code zone); the string fulfillment-type registry was deleted by `6.0-delivery-profiles.md`. **Partial fulfillment (2026-08-10, resolved question 12):** shipping a subset is `Spree::Fulfillments::Fulfill` (optional per-line-item `items:` + `tracking:` + `notify_customer:`; splits then fulfills in one transaction) — never a state-machine event, since split-then-ship in an `after_transition` is what service-workflows prohibits. **Side effects left the machine (2026-08-10, question 13):** `after_cancel`/`after_resume` are gone as transition callbacks — restock + carrier stand-down live in `Fulfillments::Cancel`/`::Resume` as inline steps (provider call is an `external_step`; `notify_provider: false` lets `Orders::Cancel` delegate and batch carrier I/O after its own transaction), `after_cancel`/`after_resume` are deprecated shells and the only trace left on the model — never add public model methods for workflows to call. **Status model (2026-08-11, question 14): the machine is REMOVED.** `status` = plain `HasStatus` `unfulfilled → fulfilled → delivered | canceled` (`pending`/`ready`/`ready_for_pickup` collapse — payment/stock gating is a `Fulfillments::Fulfill` validate guard, pickup renders modality-aware labels); `delivered` = confirmed receipt (`Fulfillments::MarkDelivered`, `delivered_at`, `fulfillment.delivered`) — the returns window + EU withdrawal anchor; carrier truth is the separate `tracking_status` axis (data, never a machine) written by `Fulfillments::UpdateTracking`, fed by EasyPost tracker webhooks (opt-in trackers for hand-entered numbers). Rollup domain `backorder | canceled | partial | unfulfilled | fulfilled | delivered`. **Phase 7 shipped 2026-08-11** (core + API + dashboard + EasyPost tracker webhook + `spree:migrate_fulfillment_statuses`); **label leads, fulfilled follows (2026-08-12):** `Fulfillments::PurchaseLabel` = explicit pre-ship label buy (loud failure, no email); `Fulfill` buys label BEFORE marking fulfilled (email always carries tracking; post-split failure keeps the split, never rolls it back); providers declare `generates_labels?` + idempotent `create_fulfillment`. **One tracking number per fulfillment (2026-08-11, question 15):** diverging parcels are split fulfillments; a `spree_fulfillment_trackings` model is 6.1 work and must absorb the entire carrier axis (per-row status/`delivered_at`, webhook matching by row) — never split the axis across fulfillment and tracking rows
- `6.0-returns-exchanges-claims.md` — First-class Return, Exchange, Claim models replacing ReturnAuthorization/Reimbursement chain. **COMPLETE (2026-08-05):** all three entities (+ permanent `ReturnLineItem`/`ExchangeLineItem`/`ClaimLineItem` line items), `Spree::HasStatus`, all fifteen workflows (each with a leading `validate` hook), `Refund#originator`, admin + store v3 APIs (transitions as PATCH member actions; no destroy — cancel instead), dashboard pages. Legacy chain **removed**: ReturnAuthorization/CustomerReturn/Reimbursement/ReimbursementType/legacy ReturnItem + eligibility validators + ReturnsCalculator classes all deleted, but their **tables deliberately survive to 6.1** as the data migration's source and rollback path. `spree:upgrade:migrate_returns` (`Spree::ReturnsMigrator`, defined in the rake file like its sibling upgrade tasks; anonymous-AR readers) is in the 5.6→6.0 manifest after the adjustments step; it needs no cursor because the preserved `number` is uniquely indexed on the new tables, so "what's left" is a `where.not(number: ...)` query and an interrupted run resumes for free. `ReturnAuthorizationReason`→`ReturnReason` (alias one release) + new `ClaimReason`; `Metafields` on all three. Capability replacements: `Spree::ReturnMailer#refunded_email` on `return.refunded` (replaces the reimbursement email), `Order#outstanding_balance` drops the reimbursement term (refunds already net out of `payment_total`), `Return#refunded_total` counts store credits too, `StoreCreditCategory.default_refund_category` (alias kept). **Reasons** ship admin-only CRUD (`/api/v3/admin/{return,claim,refund}_reasons`, `settings` scope) + a combined Settings → Reasons dashboard page + reason pickers on the create dialogs; `mutable` is never client-writable and the immutability guard lives on `Spree::NamedType` (`can_be_deleted?` + rename/destroy guards) because secret API keys authorize by scope and never consult CanCanCan. **No state machines (2026-08-02):** plain `status` string + inclusion validation; all fifteen transitions are workflows (`Returns::Receive`, `Exchanges::Fulfill`, `Claims::Resolve`, …) with `validate` hooks for return-eligibility policy and refunds as `external_step`. Nothing happens in a model or transition callback. Statuses live in a `class_attribute` via the core `Spree::HasStatus` concern (`has_status` + additive `add_status(value, after:)`, generating predicates and scopes) — extensible by design, additive only, and no transition graph (that would be a state machine again). **Return eligibility is a hook, not a policy engine (2026-08-03):** no window/restocking-fee/final-sale flag in core — a `validate` handler decides, enforcing for customers while letting staff override (it reads `created_by`), and region-varying policy reads `order.market`. Medusa/Saleor/Vendure ship no policy at all; Shopify's engine has no API. A `ReturnPolicy` model can arrive later behind the same hook.
diff --git a/docs/docs.json b/docs/docs.json
index 48e608fb09..ca39e6b770 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -1143,6 +1143,13 @@
"v6/developer/how-to/custom-delivery-rate-provider"
]
},
+ {
+ "group": "Orders",
+ "icon": "receipt",
+ "pages": [
+ "v6/developer/how-to/custom-document-numbers"
+ ]
+ },
{
"group": "Reports",
"icon": "chart-bar",
diff --git a/docs/plans/6.0-document-numbers.md b/docs/plans/6.0-document-numbers.md
new file mode 100644
index 0000000000..ce99d0dea8
--- /dev/null
+++ b/docs/plans/6.0-document-numbers.md
@@ -0,0 +1,324 @@
+# Document Number Customization
+
+**Status:** Implemented (core + API + dashboard, 2026-08-13)
+**Target:** Spree 6.0
+**Depends on:** `6.0-cart-order-split.md` (order creation point), `6.0-store-scoped-configuration.md` (settings doctrine), `6.0-returns-exchanges-claims.md` (number columns as migration cursor), `6.0-inventory-operations.md` (PurchaseOrder born with `HasNumber`)
+**Author:** Damian Legawiec
+**Last updated:** 2026-08-13
+
+## Summary
+
+Human-readable document numbers (`R1001`, `RET1005`) are today generated by
+`Spree::Core::NumberGenerator` — a `Module` subclass whose prefix and length
+are frozen into each model at boot (`include
+Spree::Core::NumberGenerator.new(prefix: 'R')`). Customizing a number format
+requires a decorator that re-includes the module, there is no store awareness,
+and every number is random. This plan replaces the module factory with
+runtime-resolved generator strategy classes, makes **sequential numbering the
+default from 6.0** with random as an opt-in, gives merchants a dashboard
+setting for the **order** number format, derives fulfillment and payment
+numbers from their parent order (`R1001-F1`, `R1001-P1`) instead of storing
+them, and keeps every other model's stored number while moving them all onto
+one swappable generator.
+
+## Key Decisions (do not deviate without discussion)
+
+- **Sequential numbers are the 6.0 default; random is opt-in** (2026-08-13).
+ Sequential, invoice-like numbers are what merchants expect from every major
+ commerce platform. The settings UI must state plainly that sequential
+ numbers reveal order volume to repeat customers — but the default follows
+ merchant expectations, not the information-hiding argument.
+- **Only the order number is merchant-customizable** (2026-08-13). One
+ "Order numbers" settings card: prefix, suffix, format (sequential |
+ random), and sequence starting value. All other documents keep code-level
+ defaults; developers can swap any generator via the registry. No
+ per-document settings grid.
+- **One format switch, respected by every independently numbered model**
+ (2026-08-13). The store's `sequential`/`random` choice applies to orders,
+ returns, exchanges and claims alike; per-document prefixes remain code
+ defaults (`RET`, `EX`, `CLM`).
+- **Settings live on `Spree::Store`, never `Spree::Config`** — per the
+ store-scoped-configuration doctrine. "Global" means one setting for all
+ document types, not one setting for all stores.
+- **Fulfillment and payment numbers are derived, not stored** (2026-08-13).
+ `number` becomes a method: historical rows return the stored column value
+ unchanged (gateway references and packing slips already in the wild stay
+ stable); new rows derive `"#{order.number}-F#{position}"` /
+ `"#{order.number}-P#{position}"` from the parent order and the record's
+ position among its siblings (ordered by id, canceled included). Generation
+ stops entirely — no counter rows, no stored values. Accepted trade-off:
+ a derived number shifts if an earlier sibling is hard-deleted; payments
+ are invalidated rather than deleted and fulfillments cancel rather than
+ delete, so in practice positions are stable.
+- **Gateway references simplify to the derived number** (2026-08-13).
+ `GatewayOptions#order_id` becomes `payment.number` alone (it already
+ contains the order number — no more `"#{order.number}-#{payment.number}"`
+ doubling). References already stored at gateways are opaque strings and
+ stay valid. **The idempotency key is the exception (revised in review,
+ 2026-08-13): `"spree-#{payment.prefixed_id}"`, never the number** — a
+ derived number shifts if an earlier sibling is destroyed, and a shifted
+ idempotency key could collide with one already consumed at the gateway.
+ Display references may shift (accepted trade-off); idempotency keys must
+ not.
+- **Import and Export keep their numbers** (revised 2026-08-13 during
+ implementation, reversing the draft's "drop them"). Both mail the number to
+ the merchant in a subject line (`Your export EF1001 was successfully
+ processed!`), which puts them on the numbered side of the same dividing
+ line that kept StockTransfer and PurchaseOrder: a reference handled outside
+ the dashboard. No model now loses its number — the "back-office models drop
+ numbers" idea did not survive contact with the code.
+- **StockTransfer keeps its stored number; PurchaseOrder is born with one**
+ (2026-08-13). The dividing line is not customer-facing versus staff-facing
+ but *document handled outside the dashboard* versus *row in an admin
+ table*. Purchase orders are external documents (quoted in supplier emails
+ and accounts payable); transfer slips travel with physical boxes and are
+ read by receiving staff at other warehouses and third-party logistics
+ locations — `6.0-inventory-operations.md` already assumes both carry
+ numbers. StockTransfer keeps prefix `T`; `Spree::PurchaseOrder` gets
+ `has_spree_number prefix: 'PO'` from its first migration. Both
+ follow the store's sequential/random format switch with their own
+ counters.
+- **Return, Exchange and Claim keep independent stored numbers**
+ (2026-08-13). They are customer-visible (Store API today, self-service
+ portal in 6.1), shown on the dashboard post-sale cards, and the preserved
+ `number` unique index is the resume cursor for
+ `spree:upgrade:migrate_returns`.
+- **Each document type counts independently** (2026-08-13): one counter row
+ per `(store, resource_type)`. Numbers stay dense within each type
+ (`R1001, R1002, …` while returns sit at `RET1001`); a shared chronological
+ counter would put holes in the order sequence, which merchants read as
+ missing orders.
+- **The default sequence starting value is 1001** (2026-08-13) —
+ industry-familiar, hides that a store is brand new; merchant-editable
+ **until the first number is issued**, after which the counter owns the
+ value. The store serializer exposes `order_number_sequence_started` and the
+ dashboard disables the field with an explanation, because a setting that
+ silently stops working is worse than one that says why it cannot.
+- **The macro is `has_spree_number prefix: 'R'`** (2026-08-13), matching the
+ existing `has_spree_rich_text` naming. `Spree::HasNumber` is included into
+ `Spree::Base` — like `Spree::PrefixedId` — so no model writes its own
+ include and nothing happens until a model calls the macro. `.has_spree_number?`
+ answers whether a model opted in.
+- **Sequence state lives in a `spree_number_sequences` counter table**
+ (2026-08-13), not derived from the `number` column. Deriving "next" from
+ data is impossible: legacy random values poison any `MAX` parse, text
+ columns don't sort numerically, concurrent writers computing `MAX + 1`
+ collide, and a merchant-set starting value is not derivable from rows.
+ A counter row incremented under `with_lock` is the portable equivalent of a
+ native sequence across PostgreSQL, MySQL and SQLite.
+- **The global unique index on `number` stays.** If a sequential candidate
+ collides (with another store's number or a legacy random one), the
+ generator finds the first free value with batched queries and jumps the
+ counter past the taken stretch in one move (revised in review, 2026-08-13
+ — advancing one retry at a time would exhaust the save's retry budget when
+ a sibling store owns ten or more consecutive numbers, and the counter
+ advances roll back with the failed save, leaving the store permanently
+ stuck). Consequence: sequential numbering is *mostly* gapless, never
+ guaranteed gapless — this feature must never be marketed as legal invoice
+ numbering.
+- **The starting value applies to orders only** (revised in review,
+ 2026-08-13): it belongs to the order-numbers settings card, so returns,
+ transfers and the rest always count from the default. It is also locked
+ server-side once the counter has issued a number — the API rejects a
+ change with a validation error, matching the disabled dashboard field.
+- **Settings changes affect future numbers only.** Existing numbers are
+ permanent identifiers and are never regenerated or rewritten.
+- **`Spree::Core::NumberGenerator` remains as a deprecated shell for one
+ release**, translating its options into the new concern with a
+ `Spree::Deprecation` warning; removed in 6.1.
+
+## Design Details
+
+### The concern and strategy classes
+
+```ruby
+class Spree::Order < Spree.base_class
+ has_spree_number prefix: 'R'
+end
+```
+
+`Spree::HasNumber` owns the mechanics that never vary: the
+`before_validation` assignment, the collision retry loop, and a rescue for
+the unique-index race (`ActiveRecord::RecordNotUnique` → regenerate). The
+strategy class answers only "give me a candidate string for this record":
+
+```ruby
+module Spree
+ module NumberGenerators
+ class Base
+ # @param record [ActiveRecord::Base] the numbered record (store reachable)
+ # @return [String] a candidate number; uniqueness is the concern's job
+ def generate(record); end
+ end
+ end
+end
+```
+
+Core ships two strategies:
+
+- `Spree::NumberGenerators::Sequential` — the default. Reads the store's
+ prefix/suffix settings (orders) or the model's code-level prefix, takes
+ the next value from the counter table, no zero-padding (`R1001`, `R1002`).
+- `Spree::NumberGenerators::Random` — today's behavior: prefix + 9 random
+ digits, zero-padded.
+
+Generators are resolved **at runtime, per record**, through a registry:
+
+```ruby
+Spree.number_generators.default # => 'Spree::NumberGenerators::Sequential'
+Spree.number_generators[:order] = 'MyApp::OrderNumberGenerator'
+```
+
+Because the record is passed in, a custom generator can read the store, the
+market, the date — anything — with no decorator and no boot-time freezing.
+
+### Derived numbers (Fulfillment, Payment)
+
+Fulfillment and Payment drop `HasNumber` entirely. `number` becomes a
+stored-else-derived method:
+
+```ruby
+# Spree::Fulfillment
+def number
+ self[:number] || "#{order.number}-F#{position_among_siblings}"
+end
+```
+
+`position_among_siblings` is 1 + the count of sibling rows with a smaller
+id (canceled included), so labels are stable across status changes. New rows
+never write the column. Serializers keep exposing `number` — the value just
+changes shape for new records (`R1001-F1`, `R1001-P2`), grouping visibly
+with the parent order and automatically following whatever order format the
+merchant configured.
+
+### Store settings (orders only)
+
+New `Spree::Store` preferences, consumed by the default generator:
+
+| Preference | Default |
+|---|---|
+| `order_number_prefix` | `R` |
+| `order_number_suffix` | `''` |
+| `document_number_format` | `sequential` (`random` opt-in) |
+| `order_number_sequence_start` | `1001`, editable until the counter starts |
+
+Prefix/suffix validation: 0–10 characters, `A–Z`, `0–9`, `-`, `#`. The
+combination of empty prefix and empty suffix is allowed (bare integers).
+
+Dashboard: an "Order numbers" card on the store settings page with a live
+preview of the next number shape, and a note on the volume-disclosure
+trade-off next to the format switch. Exposed through the existing store
+settings Admin API surface; no new endpoints.
+
+### The counter table
+
+```ruby
+create_table :spree_number_sequences do |t|
+ t.references :store, null: false
+ t.string :resource_type, null: false # 'order', 'return', ...
+ t.bigint :value, null: false, default: 0
+ t.timestamps
+end
+add_index :spree_number_sequences, [:store_id, :resource_type], unique: true
+```
+
+`Sequential#generate` finds-or-creates the row for `(store, resource_type)`
+(seeding `value` from the store's configured starting value) and increments
+under `with_lock`. Rows exist only for the independently numbered document
+types (order, return, exchange, claim, stock transfer, purchase order) on
+stores using sequential format; nothing else ever reads them.
+
+### Numbered models after 6.0
+
+| Model | Number | Source |
+|---|---|---|
+| Order | stored, merchant-customizable | store settings + counter |
+| Return / Exchange / Claim | stored | code prefixes `RET`/`EX`/`CLM`, store format switch + counters |
+| Fulfillment | derived (`R1001-F1`), stored value honored on legacy rows | parent order + position |
+| Payment | derived (`R1001-P1`), stored value honored on legacy rows | parent order + position |
+| StockTransfer | stored | code prefix `T`, store format switch + counter |
+| PurchaseOrder (new, `6.0-inventory-operations.md`) | stored | code prefix `PO`, store format switch + counter |
+| Import / Export | stored | code prefixes `IM`/`EF` (both mail the number) |
+
+### Uniqueness has three layers
+
+Each catches what the one before it cannot, and the implementation needs all
+three: the generator's `number_taken?` pre-check (cheap, advisory), the
+`Spree::NumberIdentifier` uniqueness validation, and the database's unique
+index. Only the index holds when two writers commit in the same instant, so
+`HasNumber` overrides `create_or_update` to renumber once on
+`ActiveRecord::RecordNotUnique`. That override must keep Rails' own
+`(**, &block)` signature — an over-broad `(*, **)` silently drops it out of
+the call chain, leaving the retry as dead code that no ordinary test notices.
+
+Two PostgreSQL-specific rules (2026-08-13, from review): the insert must run
+in a **savepoint** (`transaction(requires_new: true)`), because a constraint
+violation poisons the surrounding transaction — without the savepoint the
+regenerate queries die with `PG::InFailedSqlTransaction` instead of
+recovering (SQLite hides this, which is why the local suite passed). And the
+generator, not the retry loop, must skip stretches of taken numbers: counter
+advances made inside a save that ultimately fails **roll back with it**, so
+a store colliding with 10+ consecutive numbers of a sibling store would
+retry the same range forever. `Sequential` scans forward in batches and
+jumps the counter past the stretch before the save ever attempts an insert.
+
+The registry is seeded in an engine initializer `before:
+:load_config_initializers` — like the subscriber and order-routing
+registries — so host apps can register generators from
+`config/initializers/spree.rb`. Seeding it in `after_initialize` makes every
+documented registration crash at boot.
+
+## Migration Path
+
+1. **Additive migration**: create `spree_number_sequences`.
+2. **New code**: `Spree::HasNumber`, `Spree::NumberGenerators::{Base,
+ Sequential, Random}`, the registry, store preferences, dashboard card.
+3. **Model flips**: Order, Return, Exchange, Claim, StockTransfer move to
+ `has_spree_number`; `Spree::Core::NumberGenerator` becomes a
+ deprecated shell delegating to the concern. `Spree::PurchaseOrder` is
+ born with the concern when `6.0-inventory-operations.md` lands.
+4. **Derived numbers**: Fulfillment and Payment drop generation, gain the
+ stored-else-derived `number` method; `GatewayOptions` switches to
+ `payment.number` / `"spree-#{payment.number}"`.
+5. **Callers that save with `validate: false`** — the sample-data import
+ builder and the returns migrator — call `generate_number` explicitly,
+ because the numbering hook is `before_validation` and those saves skip it.
+6. **Upgraded stores** simply start generating sequential numbers alongside
+ their historical random ones — no data migration, no renumbering.
+ Collisions with legacy numbers are absorbed by the retry loop.
+7. **6.1**: drop the deprecated `Spree::Core::NumberGenerator` shell and the
+ now-unwritten Fulfillment and Payment `number` columns. Every other
+ numbered model keeps its column.
+
+## Constraints on Current Work
+
+- New numbered models use `has_spree_number`; never instantiate
+ `Spree::Core::NumberGenerator` in new code.
+- Never parse, regex-match, or assume the format of a `number` value —
+ formats are now merchant-configurable. Lookups are exact-string only.
+- `Spree::PurchaseOrder` (from `6.0-inventory-operations.md`) must be built
+ with `has_spree_number prefix: 'PO'` from the start — never a
+ hand-rolled generator.
+- Code that saves a numbered record with `validate: false` must call
+ `generate_number` first; the hook it skips is what normally assigns one.
+- Never write to `spree_fulfillments.number` or `spree_payments.number` —
+ the columns are frozen legacy data awaiting the 6.1 drop.
+- New store-visible documents that need a human-readable reference get a
+ `HasNumber` inclusion and a registry entry — never a hand-rolled
+ `before_validation` generator. Child documents of an order should prefer
+ the derived pattern over a new counter.
+
+## Open Questions
+
+None — all four draft questions (fulfillment numbering, starting value,
+counter granularity, payment number handling) were resolved 2026-08-13 and
+folded into Key Decisions above.
+
+## References
+
+- `docs/plans/6.0-store-scoped-configuration.md` — settings doctrine
+- `docs/plans/6.0-returns-exchanges-claims.md` — `number` as migration cursor
+- `docs/plans/6.0-cart-order-split.md` — order creation point (`Carts::Complete`)
+- `docs/plans/6.0-inventory-operations.md` — StockTransfer lifecycle + PurchaseOrder
+- `spree/core/lib/spree/core/number_generator.rb` — legacy implementation
+- `spree/core/app/models/spree/payment/gateway_options.rb` — gateway references
diff --git a/docs/plans/6.0-inventory-operations.md b/docs/plans/6.0-inventory-operations.md
index 2e99a1025e..a084df14ca 100644
--- a/docs/plans/6.0-inventory-operations.md
+++ b/docs/plans/6.0-inventory-operations.md
@@ -100,7 +100,9 @@ These additions live in `6.0-typed-stock-movements.md`; this plan only consumes
```ruby
class Spree::StockTransfer < Spree.base_class
has_prefix_id :st
- include Spree::Core::NumberGenerator.new(prefix: 'T')
+ # Transfers have no store column; #number_store resolves through
+ # destination_location.store — see 6.0-document-numbers.md
+ has_spree_number prefix: 'T'
include Spree::NumberIdentifier
include Spree::Metafields
include Spree::Metadata
@@ -179,7 +181,7 @@ end
```ruby
class Spree::PurchaseOrder < Spree.base_class
has_prefix_id :po
- include Spree::Core::NumberGenerator.new(prefix: 'PO')
+ has_spree_number prefix: 'PO' # see 6.0-document-numbers.md
include Spree::NumberIdentifier
include Spree::SingleStoreResource
include Spree::Metafields
diff --git a/docs/plans/decisions.md b/docs/plans/decisions.md
index 556b46bd5e..c84f2a5deb 100644
--- a/docs/plans/decisions.md
+++ b/docs/plans/decisions.md
@@ -1,3 +1,43 @@
+## 2026-08-13: Document numbers — sequential by default, store-configurable orders, derived child numbers
+
+`Spree::Core::NumberGenerator` (the boot-frozen `Module` factory) is replaced
+at 6.0 by a `has_spree_number prefix: 'R'` macro (`Spree::HasNumber`, included
+into `Spree::Base` so no model needs its own include) plus runtime-resolved
+strategy classes
+(`Spree.number_generators` registry, `NumberGenerators::Sequential` |
+`::Random`). Sequential is the new default — invoice-like `R1001, R1002` with
+a per-`(store, resource_type)` counter table (`spree_number_sequences`,
+`with_lock` increment, portable across all three databases); random becomes
+opt-in. Merchants get exactly one dashboard surface: an "Order numbers" card
+(prefix, suffix, format, starting value — default 1001) stored as
+`Spree::Store` preferences. Other document types keep code defaults;
+developers swap generators via the registry.
+
+The numbered-model census shrank. Numbers predate prefixed IDs as the
+human-readable identifier, so each model was audited for who actually reads
+its number: **Order** keeps the flagship stored number; **Return / Exchange /
+Claim** keep stored numbers (customer-visible, dashboard cards, and the
+`migrate_returns` resume cursor); **Fulfillment and Payment numbers become
+derived methods** — stored value honored on legacy rows, new rows compute
+`"#{order.number}-F1"` / `"-P1"` from parent + sibling position, generation
+and counters gone (gateway `order_id` simplifies to `payment.number`;
+idempotency to `"spree-#{payment.number}"`). Every other numbered model keeps
+its stored number. The dividing line is *document handled outside the
+dashboard* versus *row in an admin table* — which on inspection kept more
+than the draft expected: transfer slips travel on boxes, POs are quoted to
+suppliers, and **imports and exports mail their number in a subject line**
+(`Your export EF1001 was successfully processed!`), so the planned removal of
+back-office numbers was dropped during implementation.
+
+Consequences: never parse or regex a `number` (format is merchant data now);
+never write `spree_fulfillments.number` / `spree_payments.number` (frozen
+until the 6.1 column drop); the global unique index stays, so sequential is
+mostly-gapless and must never be sold as legal invoice numbering; settings
+changes only affect future numbers; and code saving a numbered record with
+`validate: false` must call `generate_number` itself, since the hook that
+normally assigns one is `before_validation`. Plan:
+`6.0-document-numbers.md`.
+
## 2026-08-13: Store context is credential-derived — hostname resolution retired; first-run setup replaces the dummy admin
Every v3 API request resolved to `Spree::Store.default`: the configured finder
diff --git a/docs/v6/developer/core-concepts/orders.mdx b/docs/v6/developer/core-concepts/orders.mdx
index d106ae7c2a..54807f4363 100644
--- a/docs/v6/developer/core-concepts/orders.mdx
+++ b/docs/v6/developer/core-concepts/orders.mdx
@@ -30,7 +30,7 @@ erDiagram
| Attribute | Description |
|---|---|
| `id` | Order ID, e.g. `or_86Rf07xd4z` |
-| `number` | Order number shown to customers, e.g. `R123456789` |
+| `number` | Order number shown to customers, e.g. `R1001` — sequential by default, [customizable](/v6/developer/how-to/custom-document-numbers) |
| `cart_id` | The cart this order came from |
| `email` | Customer's email address |
| `currency` | Order currency, e.g. `USD` |
diff --git a/docs/v6/developer/how-to/custom-document-numbers.mdx b/docs/v6/developer/how-to/custom-document-numbers.mdx
new file mode 100644
index 0000000000..61f84857ee
--- /dev/null
+++ b/docs/v6/developer/how-to/custom-document-numbers.mdx
@@ -0,0 +1,156 @@
+---
+title: Customize Document Numbers
+description: Change the shape of order, return and other document numbers — from the dashboard for order numbers, or in code for full control.
+---
+
+## Overview
+
+Every order, return, exchange, claim, stock transfer, import and export carries a **document number** — the short, human-readable reference a merchant reads out on a support call and a customer quotes in an email. Orders look like `R1001`, returns like `RET1001`.
+
+Numbers are separate from IDs. Every record also has a prefixed ID (`order_86Rf07xd4z`) which is what the API uses and what you should reference in code. The number exists purely so people can read, say and type it.
+
+There are two ways to change it. Merchants can reshape **order numbers** from the dashboard without any code. Developers can replace the generator for **any** document type when the settings are not enough.
+
+## Merchant settings
+
+**Settings → Store → Order numbers** controls four things:
+
+| Setting | Effect |
+|---|---|
+| Numbering format | Sequential (default) or random. Applies to every numbered document. |
+| Prefix | Leads each order number. Defaults to `R`. |
+| Suffix | Ends each order number. Empty by default. |
+| Start numbering at | The first order number. Defaults to `1001`. |
+
+Sequential numbering counts up: `R1001`, `R1002`, `R1003`. Random numbering produces nine unpredictable digits, which is what Spree did before 6.0. The trade-off is worth stating to merchants: sequential numbers are far easier to read back over the phone, but a customer who orders twice can see how many orders you took in between. Random numbers give that away nothing, at the cost of legibility.
+
+Two rules apply to every change:
+
+- **Changes affect future numbers only.** Numbers already issued are permanent — they are printed on invoices, quoted in emails, and stored at payment gateways.
+- **The starting value only applies before the first order.** Set it to `10001` on a new store and the first order is `R10001`, the second `R10002`. Once the counter has issued a number the field is locked in the dashboard, because raising it then would do nothing — the counter keeps going from where it is.
+
+Prefix and suffix have no such restriction. Change them whenever you like: `INV` with suffix `-EU` and a start of `5001` gives `INV5001-EU`, and existing orders keep the numbers they were issued.
+
+<Note>
+Sequential numbering is *mostly* gapless, not guaranteed gapless — an abandoned checkout or a rare collision consumes a value. Do not rely on it for legal invoice numbering, which in most jurisdictions requires a provably unbroken sequence.
+</Note>
+
+## Custom generators
+
+When the settings are not enough — you need the year in the number, a per-warehouse prefix, or a format your ERP already expects — register a generator class.
+
+A generator answers one question: what should this record's number be? Uniqueness is handled for you, so a generator only has to propose.
+
+```ruby
+# lib/my_app/branch_order_numbers.rb
+module MyApp
+ class BranchOrderNumbers < Spree::NumberGenerators::Base
+ # @param record [Spree::Order]
+ # @return [String]
+ def generate(record)
+ branch = record.number_store.code.upcase
+ year = Time.current.year
+
+ "#{branch}-#{year}-#{SecureRandom.random_number(10_000).to_s.rjust(4, '0')}"
+ end
+ end
+end
+```
+
+Register it in an initializer:
+
+```ruby
+# config/initializers/spree.rb
+Spree.number_generators[:order] = 'MyApp::BranchOrderNumbers'
+```
+
+That is the whole contract. Orders now get numbers like `NYC-2026-0042`; every other document type keeps following the store's settings.
+
+The resource key matches the model name, underscored: `:order`, `:return`, `:exchange`, `:claim`, `:stock_transfer`, `:import`, `:export`. Register the same class under several keys to share one format across document types.
+
+A registered generator wins over the store's format setting — that is the point of registering one. If you want merchants to keep some control, read their settings yourself through `prefix_for` and `suffix_for` (below).
+
+`Spree.number_generators.delete(:order)` removes the registration and hands numbering back to the store settings.
+
+### What a generator can read
+
+The record is passed to `generate`, so anything reachable from it is available:
+
+- `record.number_store` — the store whose settings apply, wherever it lives on the model
+- `record.class.number_prefix` — the model's built-in prefix (`R`, `RET`, …)
+- Any attribute of the record itself
+
+Inheriting from `Spree::NumberGenerators::Base` also gives you `prefix_for(record)` and `suffix_for(record)`, which return the merchant's configured values for orders and the code-level prefix for everything else. Use them when you want to extend the merchant's choice rather than override it.
+
+### Sequential counters
+
+If your generator needs its own counter, use the same one the built-in sequential generator uses rather than deriving a maximum from existing rows. This generator combines both — the merchant's prefix, a year, and a zero-padded counter:
+
+```ruby
+module MyApp
+ class YearScopedNumbers < Spree::NumberGenerators::Base
+ def generate(record)
+ sequence = Spree::NumberSequence.next_value(
+ store: record.number_store,
+ resource_type: 'order',
+ start_at: 1
+ )
+
+ "#{prefix_for(record)}-#{Time.current.year}-#{sequence.to_s.rjust(5, '0')}"
+ end
+ end
+end
+```
+
+With the default prefix that produces `R-2026-00001`; a merchant who changes their prefix to `ACME` gets `ACME-2026-00001` without you touching the class.
+
+Deriving the next value by parsing existing numbers looks simpler but breaks in three ways: legacy numbers from before your format existed do not parse, string columns sort `R999` above `R1000`, and two concurrent checkouts read the same maximum and produce the same number. The counter is locked for the increment, so it hands out distinct values under load.
+
+## Adding numbers to your own model
+
+Models you add can carry document numbers too:
+
+```ruby
+class MyApp::Consignment < Spree.base_class
+ has_spree_number prefix: 'CN'
+end
+```
+
+The record is numbered before validation on create, and the number follows the store's format setting like everything else. The model needs a `number` column with a unique index:
+
+```ruby
+add_column :my_app_consignments, :number, :string, null: false
+add_index :my_app_consignments, :number, unique: true
+```
+
+If the model does not respond to `store`, define `number_store` so the generator knows whose settings to read:
+
+```ruby
+def number_store
+ warehouse.store
+end
+```
+
+## Fulfillments and payments
+
+Fulfillments and payments do **not** have their own numbers. Theirs are derived from the order they belong to — `R1001-F1` for the first parcel, `R1001-P1` for the first payment — so they group visibly with their order and follow whatever format the merchant chose.
+
+This is not configurable and there is no generator to register. If you need a different shape, override `number` on the model.
+
+## Upgrading from Spree 5.x
+
+Two changes matter.
+
+**Numbers are sequential by default.** Stores upgrading from 5.x keep every existing number untouched, but new documents get sequential numbers starting at 1001. To keep the old behavior, set the store's numbering format to **Random** in Settings → Store → Order numbers.
+
+**`Spree::Core::NumberGenerator` is deprecated.** Models using it still work through Spree 6.0 and log a deprecation warning. Replace it with the concern:
+
+```ruby
+# before
+include Spree::Core::NumberGenerator.new(prefix: 'R', length: 9)
+
+# after
+has_spree_number prefix: 'R'
+```
+
+The `length:` and `letters:` options are gone — they described the random format, which is now the generator's business rather than the model's. If you were relying on a specific length, register a custom generator.
diff --git a/packages/admin-sdk/src/params.ts b/packages/admin-sdk/src/params.ts
index 72f9f46550..d352a0c002 100644
--- a/packages/admin-sdk/src/params.ts
+++ b/packages/admin-sdk/src/params.ts
@@ -40,6 +40,14 @@ export interface StoreUpdateParams {
preferred_show_products_without_price?: boolean
/** Lets more than one variant share the same SKU. */
preferred_disable_sku_validation?: boolean
+ /** How document numbers are produced: `sequential` or `random`. Applies to every numbered document. */
+ preferred_document_number_format?: string
+ /** Leads every order number, e.g. `R`. Uppercase letters, digits, dashes and # only. */
+ preferred_order_number_prefix?: string
+ /** Ends every order number. Uppercase letters, digits, dashes and # only. */
+ preferred_order_number_suffix?: string
+ /** First sequential order number. Only applies before the store's first order. */
+ preferred_order_number_sequence_start?: number
/** Sender address used on all transactional emails (required by the model). */
mail_from_address?: string
/** Customer-facing reply-to address shown in the storefront/email footer. */
diff --git a/packages/admin-sdk/src/types/generated/Store.ts b/packages/admin-sdk/src/types/generated/Store.ts
index da664a9728..ffac9ce021 100644
--- a/packages/admin-sdk/src/types/generated/Store.ts
+++ b/packages/admin-sdk/src/types/generated/Store.ts
@@ -1,4 +1,4 @@
-// Typelizer digest 43220c0f31c2c31c5ed6989321e76ea3
+// Typelizer digest 9542d796d1878ded0b5a1cebf69f97ff
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
import type {SetupTask} from '@/types'
@@ -35,8 +35,13 @@ interface Store {
preferred_show_products_without_price: boolean;
preferred_disable_sku_validation: boolean;
preferred_order_routing_strategy: string;
+ preferred_document_number_format: string;
+ preferred_order_number_prefix: string;
+ preferred_order_number_suffix: string;
+ preferred_order_number_sequence_start: number;
created_at: string;
updated_at: string;
+ order_number_sequence_started: boolean;
url: string;
api_url: string;
setup_tasks: Array<SetupTask>;
diff --git a/packages/dashboard/src/locales/ar.json b/packages/dashboard/src/locales/ar.json
index c1470be49a..2657113c20 100644
--- a/packages/dashboard/src/locales/ar.json
+++ b/packages/dashboard/src/locales/ar.json
@@ -1281,6 +1281,14 @@
"help": "السماح لأكثر من متغير باستخدام رمز SKU نفسه.",
"label": "السماح بتكرار رمز SKU"
},
+ "document_number_format": {
+ "label": "صيغة الترقيم",
+ "help": "تنطبق على جميع المستندات المرقمة. الأرقام المتسلسلة تتصاعد ويسهل قراءتها، أما الأرقام العشوائية فلا تكشف عدد الطلبات التي تلقاها متجرك.",
+ "options": {
+ "sequential": "متسلسل — يتصاعد من رقم البداية",
+ "random": "عشوائي — أرقام غير متوقعة"
+ }
+ },
"guest_checkout": {
"help": "الإعداد الافتراضي على مستوى المتجر لما إذا كان بإمكان المتسوّقين إتمام الشراء دون حساب. يمكن للقنوات تجاوزه.",
"label": "الدفع كضيف"
@@ -1302,6 +1310,25 @@
"label": "إشعارات الطلبات الجديدة",
"placeholder": "[email protected]"
},
+ "order_number_prefix": {
+ "label": "البادئة",
+ "help": "تتصدر كل رقم طلب.",
+ "invalid": "استخدم الأحرف الكبيرة والأرقام والشرطات و# فقط."
+ },
+ "order_number_preview": {
+ "label": "معاينة",
+ "help": "تسري التغييرات على الطلبات المستقبلية فقط. الأرقام الصادرة بالفعل لا تتغير أبدًا."
+ },
+ "order_number_sequence_start": {
+ "label": "ابدأ الترقيم من",
+ "help": "ينطبق قبل أول طلب فقط. تغييره لاحقًا لا يعيد ترقيم الطلبات الحالية.",
+ "locked": "بدأ الترقيم بالفعل، لذا لم يعد هذا الإعداد ساريًا. أرقام الطلبات الحالية لا تتغير أبدًا."
+ },
+ "order_number_suffix": {
+ "label": "اللاحقة",
+ "help": "تأتي في نهاية كل رقم طلب.",
+ "invalid": "استخدم الأحرف الكبيرة والأرقام والشرطات و# فقط."
+ },
"preferred_admin_locale": {
"label": "لغة لوحة الإدارة",
"placeholder": "استخدام اللغة الافتراضية"
@@ -2678,6 +2705,7 @@
"tab_default_package": "الطرد الافتراضي",
"tab_general": "عام",
"tab_inventory": "المخزون",
+ "tab_order_numbers": "أرقام الطلبات",
"tab_payments": "المدفوعات",
"tab_standards": "المعايير والأشكال",
"tab_storefront_access": "الوصول إلى المتجر",
diff --git a/packages/dashboard/src/locales/de.json b/packages/dashboard/src/locales/de.json
index bd894f8544..8cf85861cd 100644
--- a/packages/dashboard/src/locales/de.json
+++ b/packages/dashboard/src/locales/de.json
@@ -1270,6 +1270,14 @@
"help": "Mehrere Varianten dürfen dieselbe SKU verwenden.",
"label": "Doppelte SKUs erlauben"
},
+ "document_number_format": {
+ "label": "Nummerierungsformat",
+ "help": "Gilt für alle nummerierten Dokumente. Fortlaufende Nummern zählen hoch und lassen sich leichter vorlesen; zufällige Nummern verraten nicht, wie viele Bestellungen Ihr Shop erhalten hat.",
+ "options": {
+ "sequential": "Fortlaufend — zählt von einem Startwert hoch",
+ "random": "Zufällig — unvorhersehbare Ziffern"
+ }
+ },
"guest_checkout": {
"help": "Store-weite Vorgabe dafür, ob Kunden ohne Konto zur Kasse gehen können. Vertriebskanäle können dies überschreiben.",
"label": "Gast-Checkout"
@@ -1291,6 +1299,25 @@
"label": "Benachrichtigungen über neue Bestellungen",
"placeholder": "[email protected]"
},
+ "order_number_prefix": {
+ "label": "Präfix",
+ "help": "Steht vor jeder Bestellnummer.",
+ "invalid": "Nur Großbuchstaben, Ziffern, Bindestriche und # verwenden."
+ },
+ "order_number_preview": {
+ "label": "Vorschau",
+ "help": "Änderungen gelten nur für künftige Bestellungen. Bereits vergebene Nummern ändern sich nie."
+ },
+ "order_number_sequence_start": {
+ "label": "Nummerierung beginnen bei",
+ "help": "Gilt nur vor Ihrer ersten Bestellung. Eine spätere Änderung nummeriert bestehende Bestellungen nicht neu.",
+ "locked": "Die Nummerierung hat bereits begonnen, daher gilt dies nicht mehr. Bestehende Bestellnummern ändern sich nie."
+ },
+ "order_number_suffix": {
+ "label": "Suffix",
+ "help": "Steht am Ende jeder Bestellnummer.",
+ "invalid": "Nur Großbuchstaben, Ziffern, Bindestriche und # verwenden."
+ },
"preferred_admin_locale": {
"label": "Admin-Sprache",
"placeholder": "Standardsprache verwenden"
@@ -2668,6 +2695,7 @@
"tab_default_package": "Standardpaket",
"tab_general": "Allgemein",
"tab_inventory": "Lagerbestand",
+ "tab_order_numbers": "Bestellnummern",
"tab_payments": "Zahlungen",
"tab_standards": "Standards und Formate",
"tab_storefront_access": "Storefront-Zugriff",
diff --git a/packages/dashboard/src/locales/en.json b/packages/dashboard/src/locales/en.json
index 339d96f22a..66d5c7ce02 100644
--- a/packages/dashboard/src/locales/en.json
+++ b/packages/dashboard/src/locales/en.json
@@ -1270,6 +1270,14 @@
"help": "Let more than one variant share the same SKU.",
"label": "Allow duplicate SKUs"
},
+ "document_number_format": {
+ "label": "Numbering format",
+ "help": "Applies to every numbered document. Sequential numbers count up and are easier to read back; random numbers do not reveal how many orders your store has taken.",
+ "options": {
+ "sequential": "Sequential — count up from a starting number",
+ "random": "Random — unpredictable digits"
+ }
+ },
"guest_checkout": {
"help": "Store-wide default for whether shoppers can check out without an account. Channels can override this.",
"label": "Guest checkout"
@@ -1291,6 +1299,25 @@
"label": "New order notifications",
"placeholder": "[email protected]"
},
+ "order_number_prefix": {
+ "label": "Prefix",
+ "help": "Leads every order number.",
+ "invalid": "Use only uppercase letters, digits, dashes and #."
+ },
+ "order_number_preview": {
+ "label": "Preview",
+ "help": "Changes apply to future orders only. Numbers already issued never change."
+ },
+ "order_number_sequence_start": {
+ "label": "Start numbering at",
+ "help": "Only applies before your first order. Changing it later does not renumber existing orders.",
+ "locked": "Numbering has already started, so this no longer applies. Existing order numbers never change."
+ },
+ "order_number_suffix": {
+ "label": "Suffix",
+ "help": "Ends every order number.",
+ "invalid": "Use only uppercase letters, digits, dashes and #."
+ },
"preferred_admin_locale": {
"label": "Admin language",
"placeholder": "Use the default language"
@@ -2668,6 +2695,7 @@
"tab_default_package": "Default package",
"tab_general": "General",
"tab_inventory": "Inventory",
+ "tab_order_numbers": "Order numbers",
"tab_payments": "Payments",
"tab_standards": "Standards and formats",
"tab_storefront_access": "Storefront access",
diff --git a/packages/dashboard/src/locales/fr.json b/packages/dashboard/src/locales/fr.json
index 8e2196f44c..86ebab848b 100644
--- a/packages/dashboard/src/locales/fr.json
+++ b/packages/dashboard/src/locales/fr.json
@@ -1270,6 +1270,14 @@
"help": "Permettre à plusieurs déclinaisons de partager la même UGS.",
"label": "Autoriser les UGS en double"
},
+ "document_number_format": {
+ "label": "Format de numérotation",
+ "help": "S'applique à tous les documents numérotés. Les numéros séquentiels se suivent et sont plus faciles à lire à voix haute ; les numéros aléatoires ne révèlent pas le nombre de commandes reçues.",
+ "options": {
+ "sequential": "Séquentiel — incrémenté à partir d’un numéro de départ",
+ "random": "Aléatoire — chiffres imprévisibles"
+ }
+ },
"guest_checkout": {
"help": "Valeur par défaut à l'échelle de la boutique pour la possibilité de commander sans compte. Les canaux peuvent la remplacer.",
"label": "Commande invité"
@@ -1291,6 +1299,25 @@
"label": "Notifications de nouvelles commandes",
"placeholder": "[email protected]"
},
+ "order_number_prefix": {
+ "label": "Préfixe",
+ "help": "Placé au début de chaque numéro de commande.",
+ "invalid": "Utilisez uniquement des majuscules, des chiffres, des tirets et #."
+ },
+ "order_number_preview": {
+ "label": "Aperçu",
+ "help": "Les modifications ne s'appliquent qu'aux commandes futures. Les numéros déjà attribués ne changent jamais."
+ },
+ "order_number_sequence_start": {
+ "label": "Commencer la numérotation à",
+ "help": "S'applique uniquement avant votre première commande. Une modification ultérieure ne renumérote pas les commandes existantes.",
+ "locked": "La numérotation a déjà commencé, ce réglage ne s'applique donc plus. Les numéros de commande existants ne changent jamais."
+ },
+ "order_number_suffix": {
+ "label": "Suffixe",
+ "help": "Placé à la fin de chaque numéro de commande.",
+ "invalid": "Utilisez uniquement des majuscules, des chiffres, des tirets et #."
+ },
"preferred_admin_locale": {
"label": "Langue de l'administration",
"placeholder": "Utiliser la langue par défaut"
@@ -2668,6 +2695,7 @@
"tab_default_package": "Colis par défaut",
"tab_general": "Général",
"tab_inventory": "Stock",
+ "tab_order_numbers": "Numéros de commande",
"tab_payments": "Paiements",
"tab_standards": "Normes et formats",
"tab_storefront_access": "Accès à la vitrine",
diff --git a/packages/dashboard/src/locales/pl.json b/packages/dashboard/src/locales/pl.json
index 4930571bb3..12088349d8 100644
--- a/packages/dashboard/src/locales/pl.json
+++ b/packages/dashboard/src/locales/pl.json
@@ -1284,6 +1284,14 @@
"help": "Pozwól, aby kilka wariantów miało ten sam SKU.",
"label": "Zezwalaj na powtórzone SKU"
},
+ "document_number_format": {
+ "label": "Format numeracji",
+ "help": "Dotyczy wszystkich numerowanych dokumentów. Numery kolejne rosną i łatwiej je podyktować; numery losowe nie zdradzają, ile zamówień otrzymał sklep.",
+ "options": {
+ "sequential": "Kolejny — liczony od wartości początkowej",
+ "random": "Losowy — nieprzewidywalne cyfry"
+ }
+ },
"guest_checkout": {
"help": "Domyślne ustawienie dla całego sklepu określające, czy klienci mogą składać zamówienia bez konta. Kanały mogą je nadpisać.",
"label": "Zakupy jako gość"
@@ -1305,6 +1313,25 @@
"label": "Powiadomienia o nowych zamówieniach",
"placeholder": "[email protected]"
},
+ "order_number_prefix": {
+ "label": "Prefiks",
+ "help": "Poprzedza każdy numer zamówienia.",
+ "invalid": "Używaj tylko wielkich liter, cyfr, myślników i #."
+ },
+ "order_number_preview": {
+ "label": "Podgląd",
+ "help": "Zmiany dotyczą wyłącznie przyszłych zamówień. Już nadane numery nigdy się nie zmieniają."
+ },
+ "order_number_sequence_start": {
+ "label": "Zacznij numerację od",
+ "help": "Dotyczy tylko okresu przed pierwszym zamówieniem. Późniejsza zmiana nie przenumeruje istniejących zamówień.",
+ "locked": "Numeracja już się rozpoczęła, więc to ustawienie nie ma już zastosowania. Istniejące numery zamówień nigdy się nie zmieniają."
+ },
+ "order_number_suffix": {
+ "label": "Sufiks",
+ "help": "Kończy każdy numer zamówienia.",
+ "invalid": "Używaj tylko wielkich liter, cyfr, myślników i #."
+ },
"preferred_admin_locale": {
"label": "Język panelu administracyjnego",
"placeholder": "Użyj języka domyślnego"
@@ -2706,6 +2733,7 @@
"tab_default_package": "Domyślna paczka",
"tab_general": "Ogólne",
"tab_inventory": "Stan magazynowy",
+ "tab_order_numbers": "Numery zamówień",
"tab_payments": "Płatności",
"tab_standards": "Standardy i formaty",
"tab_storefront_access": "Dostęp do sklepu",
diff --git a/packages/dashboard/src/locales/zh-CN.json b/packages/dashboard/src/locales/zh-CN.json
index 556f824ead..c7d5d1688d 100644
--- a/packages/dashboard/src/locales/zh-CN.json
+++ b/packages/dashboard/src/locales/zh-CN.json
@@ -1267,6 +1267,14 @@
"help": "允许多个变体使用相同的 SKU。",
"label": "允许重复 SKU"
},
+ "document_number_format": {
+ "label": "编号格式",
+ "help": "适用于所有带编号的单据。顺序编号依次递增、更便于口头核对;随机编号则不会透露店铺的订单量。",
+ "options": {
+ "sequential": "顺序编号 — 从起始号依次递增",
+ "random": "随机编号 — 不可预测的数字"
+ }
+ },
"guest_checkout": {
"help": "店铺范围内的默认设置,控制顾客是否可以无需账户即可结账。渠道可以覆盖此设置。",
"label": "访客结账"
@@ -1288,6 +1296,25 @@
"label": "新订单通知",
"placeholder": "[email protected]"
},
+ "order_number_prefix": {
+ "label": "前缀",
+ "help": "位于每个订单编号的开头。",
+ "invalid": "只能使用大写字母、数字、连字符和 #。"
+ },
+ "order_number_preview": {
+ "label": "预览",
+ "help": "更改仅影响后续订单。已生成的编号永远不会改变。"
+ },
+ "order_number_sequence_start": {
+ "label": "起始编号",
+ "help": "仅在首个订单之前生效。之后修改不会为已有订单重新编号。",
+ "locked": "编号已经开始,因此该设置不再生效。已有订单编号永远不会改变。"
+ },
+ "order_number_suffix": {
+ "label": "后缀",
+ "help": "位于每个订单编号的末尾。",
+ "invalid": "只能使用大写字母、数字、连字符和 #。"
+ },
"preferred_admin_locale": {
"label": "后台语言",
"placeholder": "使用默认语言"
@@ -2664,6 +2691,7 @@
"tab_default_package": "默认包裹",
"tab_general": "通用",
"tab_inventory": "库存",
+ "tab_order_numbers": "订单编号",
"tab_payments": "支付",
"tab_standards": "标准与格式",
"tab_storefront_access": "店铺访问权限",
diff --git a/packages/dashboard/src/routes/_authenticated/$storeId/settings/store.tsx b/packages/dashboard/src/routes/_authenticated/$storeId/settings/store.tsx
index 94b7f6768c..b5e47ffd67 100644
--- a/packages/dashboard/src/routes/_authenticated/$storeId/settings/store.tsx
+++ b/packages/dashboard/src/routes/_authenticated/$storeId/settings/store.tsx
@@ -49,6 +49,7 @@ import { toast } from 'sonner'
import { useStoreSettings, useUpdateStoreSettings } from '../../../../hooks/use-store-settings'
import { getAvailableUiLocales } from '../../../../i18n-setup'
import {
+ DOCUMENT_NUMBER_FORMATS,
STOREFRONT_ACCESS_LEVELS,
type StoreSettingsFormValues,
storeSettingsFormSchema,
@@ -103,6 +104,14 @@ function storeToFormValues(store: Store): StoreSettingsFormValues {
preferred_track_price_history: store.preferred_track_price_history ?? true,
preferred_show_products_without_price: store.preferred_show_products_without_price ?? false,
preferred_disable_sku_validation: store.preferred_disable_sku_validation ?? false,
+ preferred_document_number_format:
+ (store.preferred_document_number_format as (typeof DOCUMENT_NUMBER_FORMATS)[number]) ??
+ 'sequential',
+ preferred_order_number_prefix: store.preferred_order_number_prefix ?? 'R',
+ preferred_order_number_suffix: store.preferred_order_number_suffix ?? '',
+ preferred_order_number_sequence_start: Number(
+ store.preferred_order_number_sequence_start ?? 1001,
+ ),
}
}
@@ -149,6 +158,21 @@ function StoreSettingsForm({ store }: { store: Store }) {
defaultValues: { ...storeToFormValues(store), ...extensionFormValues('store', store) },
})
+ // Shows the merchant the shape their next order number will take. The
+ // sequential preview uses the configured starting value, which is only
+ // accurate for a store that has not taken an order yet — the copy under it
+ // says so rather than the preview pretending to know the live counter.
+ // Once the counter has issued its first number the starting value is inert,
+ // so the field says so rather than accepting a value that does nothing.
+ const sequenceStarted = store.order_number_sequence_started ?? false
+ const numberFormat = form.watch('preferred_document_number_format')
+ const numberPrefix = form.watch('preferred_order_number_prefix')
+ const numberSuffix = form.watch('preferred_order_number_suffix')
+ const numberStart = form.watch('preferred_order_number_sequence_start')
+ const orderNumberPreview = `${numberPrefix ?? ''}${
+ numberFormat === 'random' ? '482910375' : (numberStart ?? 1001)
+ }${numberSuffix ?? ''}`
+
// Live unit suffixes for the default-package inputs.
const weightUnit = form.watch('preferred_weight_unit')
const dimensionUnit = form.watch('preferred_unit_system') === 'metric' ? 'cm' : 'in'
@@ -196,6 +220,10 @@ function StoreSettingsForm({ store }: { store: Store }) {
preferred_track_price_history: values.preferred_track_price_history,
preferred_show_products_without_price: values.preferred_show_products_without_price,
preferred_disable_sku_validation: values.preferred_disable_sku_validation,
+ preferred_document_number_format: values.preferred_document_number_format,
+ preferred_order_number_prefix: values.preferred_order_number_prefix,
+ preferred_order_number_suffix: values.preferred_order_number_suffix,
+ preferred_order_number_sequence_start: values.preferred_order_number_sequence_start,
...extensionValues,
})
toast.success(t('admin.messages.store_settings_updated'))
@@ -253,6 +281,14 @@ function StoreSettingsForm({ store }: { store: Store }) {
})),
[t],
)
+ const documentNumberFormatOptions = useMemo(
+ () =>
+ DOCUMENT_NUMBER_FORMATS.map((value) => ({
+ value,
+ label: t(`admin.fields.store.document_number_format.options.${value}`),
+ })),
+ [t],
+ )
// Admin-UI language options come from the dashboard's own shipped locale
// bundles (getAvailableUiLocales) — the SAME canonical source the profile
// picker and top-bar switcher use, so the lists never desync. The leading
@@ -477,6 +513,76 @@ function StoreSettingsForm({ store }: { store: Store }) {
</FieldGroup>
</CardContent>
</Card>
+ <Card>
+ <CardHeader>
+ <CardTitle>{t('admin.pages.settings.store.tab_order_numbers')}</CardTitle>
+ </CardHeader>
+ <CardContent>
+ <FieldGroup>
+ <SelectField
+ id="store-document-number-format"
+ label={t('admin.fields.store.document_number_format.label')}
+ name="preferred_document_number_format"
+ control={form.control}
+ options={documentNumberFormatOptions}
+ help={t('admin.fields.store.document_number_format.help')}
+ />
+ <div className="grid gap-4 sm:grid-cols-2">
+ <Field>
+ <FieldLabel htmlFor="store-order-number-prefix">
+ {t('admin.fields.store.order_number_prefix.label')}
+ </FieldLabel>
+ <Input
+ id="store-order-number-prefix"
+ aria-invalid={!!errors.preferred_order_number_prefix || undefined}
+ {...form.register('preferred_order_number_prefix')}
+ />
+ <FieldError errors={[errors.preferred_order_number_prefix]} />
+ </Field>
+ <Field>
+ <FieldLabel htmlFor="store-order-number-suffix">
+ {t('admin.fields.store.order_number_suffix.label')}
+ </FieldLabel>
+ <Input
+ id="store-order-number-suffix"
+ aria-invalid={!!errors.preferred_order_number_suffix || undefined}
+ {...form.register('preferred_order_number_suffix')}
+ />
+ <FieldError errors={[errors.preferred_order_number_suffix]} />
+ </Field>
+ </div>
+ {numberFormat === 'sequential' && (
+ <Field>
+ <FieldLabel htmlFor="store-order-number-sequence-start">
+ {t('admin.fields.store.order_number_sequence_start.label')}
+ </FieldLabel>
+ <Input
+ id="store-order-number-sequence-start"
+ type="number"
+ min={1}
+ disabled={sequenceStarted}
+ aria-invalid={!!errors.preferred_order_number_sequence_start || undefined}
+ {...form.register('preferred_order_number_sequence_start')}
+ />
+ <FieldDescription>
+ {sequenceStarted
+ ? t('admin.fields.store.order_number_sequence_start.locked')
+ : t('admin.fields.store.order_number_sequence_start.help')}
+ </FieldDescription>
+ <FieldError errors={[errors.preferred_order_number_sequence_start]} />
+ </Field>
+ )}
+ <Field>
+ <FieldLabel>{t('admin.fields.store.order_number_preview.label')}</FieldLabel>
+ <p className="font-mono text-sm">{orderNumberPreview}</p>
+ <FieldDescription>
+ {t('admin.fields.store.order_number_preview.help')}
+ </FieldDescription>
+ </Field>
+ </FieldGroup>
+ </CardContent>
+ </Card>
+
<Card>
<CardHeader>
<CardTitle>{t('admin.pages.settings.store.tab_payments')}</CardTitle>
diff --git a/packages/dashboard/src/schemas/store.ts b/packages/dashboard/src/schemas/store.ts
index d208b7f182..459be7f2f4 100644
--- a/packages/dashboard/src/schemas/store.ts
+++ b/packages/dashboard/src/schemas/store.ts
@@ -17,6 +17,18 @@ const ALL_WEIGHT_UNITS = [...WEIGHT_UNITS.metric, ...WEIGHT_UNITS.imperial] as c
// `admin.fields.store.storefront_access.options.*`.
export const STOREFRONT_ACCESS_LEVELS = ['public', 'prices_hidden', 'login_required'] as const
+/**
+ * How document numbers are produced. `sequential` counts up from a starting
+ * value; `random` is the pre-6.0 behaviour, opted into by merchants who would
+ * rather not disclose order volume. Labels live in `en.json` under
+ * `admin.fields.store.document_number_format.options.*`.
+ */
+export const DOCUMENT_NUMBER_FORMATS = ['sequential', 'random'] as const
+
+// Prefix/suffix accept the characters that read cleanly on an invoice and
+// survive a phone call: uppercase letters, digits, dash and hash.
+const NUMBER_AFFIX_PATTERN = /^[A-Z0-9#-]*$/
+
export const storeSettingsFormSchema = z.object({
name: z.string().min(1, { error: requiredMessage('store.name') }),
preferred_admin_locale: z.string().nullable().optional(),
@@ -38,6 +50,16 @@ export const storeSettingsFormSchema = z.object({
preferred_track_price_history: z.boolean(),
preferred_show_products_without_price: z.boolean(),
preferred_disable_sku_validation: z.boolean(),
+ preferred_document_number_format: z.enum(DOCUMENT_NUMBER_FORMATS),
+ preferred_order_number_prefix: z
+ .string()
+ .max(10)
+ .regex(NUMBER_AFFIX_PATTERN, { error: 'admin.fields.store.order_number_prefix.invalid' }),
+ preferred_order_number_suffix: z
+ .string()
+ .max(10)
+ .regex(NUMBER_AFFIX_PATTERN, { error: 'admin.fields.store.order_number_suffix.invalid' }),
+ preferred_order_number_sequence_start: z.coerce.number().int().min(1),
})
export type StoreSettingsFormValues = z.infer<typeof storeSettingsFormSchema>
diff --git a/spree/api/app/controllers/spree/api/v3/admin/store_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/store_controller.rb
index 0d745a7e8a..5e4565f353 100644
--- a/spree/api/app/controllers/spree/api/v3/admin/store_controller.rb
+++ b/spree/api/app/controllers/spree/api/v3/admin/store_controller.rb
@@ -65,6 +65,10 @@ module Spree
:preferred_show_products_without_price,
:preferred_disable_sku_validation,
:preferred_order_routing_strategy,
+ :preferred_document_number_format,
+ :preferred_order_number_prefix,
+ :preferred_order_number_suffix,
+ :preferred_order_number_sequence_start,
:mail_from_address,
:customer_support_email,
:new_order_notifications_email,
diff --git a/spree/api/app/serializers/spree/api/v3/admin/store_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/store_serializer.rb
index 202810ecdd..7244f63624 100644
--- a/spree/api/app/serializers/spree/api/v3/admin/store_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/admin/store_serializer.rb
@@ -35,6 +35,11 @@ module Spree
preferred_show_products_without_price: :boolean,
preferred_disable_sku_validation: :boolean,
preferred_order_routing_strategy: :string,
+ preferred_document_number_format: :string,
+ preferred_order_number_prefix: :string,
+ preferred_order_number_suffix: :string,
+ preferred_order_number_sequence_start: :number,
+ order_number_sequence_started: :boolean,
metadata: 'Record<string, unknown>'
attributes :metadata,
@@ -67,8 +72,19 @@ module Spree
:preferred_show_products_without_price,
:preferred_disable_sku_validation,
:preferred_order_routing_strategy,
+ :preferred_document_number_format,
+ :preferred_order_number_prefix,
+ :preferred_order_number_suffix,
+ :preferred_order_number_sequence_start,
created_at: :iso8601, updated_at: :iso8601
+ # Once the counter has issued a number the starting value no longer
+ # applies, so the settings page can say that instead of accepting a
+ # value that does nothing.
+ attribute :order_number_sequence_started do |store|
+ Spree::NumberSequence.started?(store: store)
+ end
+
attribute :url, &:storefront_url
# The backend's own public URL — what a headless client sets as its
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/store_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/store_controller_spec.rb
index 0cbfba5ee5..7c4aa5d93a 100644
--- a/spree/api/spec/controllers/spree/api/v3/admin/store_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/admin/store_controller_spec.rb
@@ -198,6 +198,72 @@ RSpec.describe Spree::Api::V3::Admin::StoreController, type: :controller do
end
end
+ context 'with order-numbering params' do
+ let(:params) do
+ {
+ preferred_document_number_format: 'random',
+ preferred_order_number_prefix: 'INV',
+ preferred_order_number_suffix: '-EU',
+ preferred_order_number_sequence_start: 5001
+ }
+ end
+
+ it 'updates the numbering preferences' do
+ subject
+ expect(response).to have_http_status(:ok)
+ store.reload
+ expect(store.preferred_document_number_format).to eq('random')
+ expect(store.preferred_order_number_prefix).to eq('INV')
+ expect(store.preferred_order_number_suffix).to eq('-EU')
+ expect(store.preferred_order_number_sequence_start).to eq(5001)
+ end
+
+ it 'exposes them in the response' do
+ subject
+ expect(json_response['preferred_order_number_prefix']).to eq('INV')
+ end
+
+ it 'reports that numbering has not started yet' do
+ subject
+ expect(json_response['order_number_sequence_started']).to be(false)
+ end
+
+ context 'once the counter has issued a number' do
+ before { Spree::NumberSequence.next_value(store: store, resource_type: 'order') }
+
+ it 'reports the started flag' do
+ # Prefix stays editable after numbering starts — only the start locks.
+ patch :update, params: { preferred_order_number_prefix: 'INV' }, as: :json
+ expect(response).to have_http_status(:ok)
+ expect(json_response['order_number_sequence_started']).to be(true)
+ end
+
+ it 'rejects a changed starting value' do
+ subject
+ expect(response).to have_http_status(:unprocessable_content)
+ expect(json_response['error']['details']).to have_key('preferred_order_number_sequence_start')
+ end
+ end
+ end
+
+ context 'with an unsupported numbering format' do
+ let(:params) { { preferred_document_number_format: 'roman_numerals' } }
+
+ it 'returns a validation error' do
+ subject
+ expect(response).to have_http_status(:unprocessable_content)
+ end
+ end
+
+ context 'with a prefix containing unsupported characters' do
+ let(:params) { { preferred_order_number_prefix: 'inv/2026' } }
+
+ it 'returns a validation error' do
+ subject
+ expect(response).to have_http_status(:unprocessable_content)
+ end
+ end
+
context 'with email-section params' do
let(:params) do
{
diff --git a/spree/core/app/models/concerns/spree/derived_number.rb b/spree/core/app/models/concerns/spree/derived_number.rb
new file mode 100644
index 0000000000..7e2e0df587
--- /dev/null
+++ b/spree/core/app/models/concerns/spree/derived_number.rb
@@ -0,0 +1,66 @@
+module Spree
+ # A number derived from the parent purchase rather than generated and
+ # stored (docs/plans/6.0-document-numbers.md): `R1001-F1`, `R1001-P2`.
+ #
+ # Fulfillments and payments are children of one order, and a number that
+ # names its parent reads better everywhere it appears — a merchant reading
+ # `R1001-F2` in a support conversation knows immediately which order and
+ # which parcel, where `F0000123456` told them nothing. It also costs
+ # nothing to maintain: no counter, no collision handling, and the child
+ # automatically follows whatever format the merchant chose for orders.
+ #
+ # Rows created before 6.0 keep their stored number, so gateway references
+ # and packing slips already in the wild still resolve. New rows never write
+ # the column — it is frozen legacy data awaiting the 6.1 drop.
+ module DerivedNumber
+ extend ActiveSupport::Concern
+
+ class_methods do
+ # @param infix [String] separates the parent number from the position,
+ # e.g. 'F' for fulfillments
+ def derives_number(infix:)
+ class_attribute :number_infix, default: infix, instance_writer: false
+ end
+ end
+
+ # @return [String, nil] the stored number on legacy rows, otherwise one
+ # derived from the parent purchase and this record's position among its
+ # siblings
+ def number
+ stored = self[:number]
+ return stored if stored.present?
+
+ parent = owner
+ return if parent.nil?
+
+ "#{parent.number}-#{self.class.number_infix}#{position_among_siblings}"
+ end
+
+ private
+
+ # Position is 1-based over siblings ordered by id, counting canceled and
+ # failed rows so a label never shifts when a sibling changes status. An
+ # unsaved record sorts last, which is what a merchant watching a new row
+ # appear expects.
+ def position_among_siblings
+ scope = sibling_scope
+ return 1 if scope.nil?
+
+ earlier = id.nil? ? scope.count : scope.where(scope.arel_table[:id].lt(id)).count
+
+ earlier + 1
+ end
+
+ # The siblings sharing this record's parent. Nil when there is no parent
+ # to group by.
+ def sibling_scope
+ parent = owner
+ return if parent.nil?
+
+ association = self.class.name.demodulize.underscore.pluralize
+ return unless parent.respond_to?(association)
+
+ parent.public_send(association).unscope(:order)
+ end
+ end
+end
diff --git a/spree/core/app/models/concerns/spree/has_number.rb b/spree/core/app/models/concerns/spree/has_number.rb
new file mode 100644
index 0000000000..6fa4d0018a
--- /dev/null
+++ b/spree/core/app/models/concerns/spree/has_number.rb
@@ -0,0 +1,139 @@
+module Spree
+ # Declarative human-readable document number for models whose number is
+ # shown to a person — on an order confirmation, a supplier purchase order,
+ # a transfer slip taped to a box (docs/plans/6.0-document-numbers.md).
+ #
+ # class Spree::Order < Spree.base_class
+ # has_spree_number prefix: 'R'
+ # end
+ #
+ # Included into {Spree::Base}, so the macro is available on every model and
+ # nothing happens until one calls it — no callback, no class attributes.
+ #
+ # The concern owns the parts that never vary: assigning a number before
+ # validation, retrying on collision, and rescuing the unique-index race.
+ # Which string to try is the generator's job, and the generator is resolved
+ # per record at save time rather than frozen at class-definition time —
+ # that is what lets a merchant switch formats in settings, and an extension
+ # swap the whole strategy through {Spree.number_generators}, without
+ # reopening this class.
+ module HasNumber
+ extend ActiveSupport::Concern
+
+ # A generator that keeps colliding is a bug in the generator, not bad
+ # luck. Bail loudly rather than spinning in a save.
+ MAX_ATTEMPTS = 10
+
+ class GenerationError < StandardError; end
+
+ class_methods do
+ # @param prefix [String] leads every number for this model, e.g. 'R'
+ # @param key [Symbol] registry key; defaults to the demodulized,
+ # underscored model name (`Spree::StockTransfer` → `:stock_transfer`)
+ def has_spree_number(prefix:, key: nil)
+ class_attribute :number_prefix, default: prefix, instance_writer: false
+ class_attribute :number_key,
+ default: (key || name.demodulize.underscore).to_sym,
+ instance_writer: false
+
+ before_validation :generate_number, on: :create
+ end
+
+ # Whether this model opted into generated numbers. The concern lives on
+ # every model through {Spree::Base}, so ask rather than assuming.
+ #
+ # @return [Boolean]
+ def has_spree_number?
+ respond_to?(:number_key)
+ end
+
+ # The generator instance for this model, resolved fresh each call so a
+ # host app can swap the registry entry at runtime (and so Zeitwerk
+ # reloads pick up a redefined class in development).
+ #
+ # @param store [Spree::Store, nil] the record's store, whose format
+ # preference picks the strategy when nothing is registered
+ # @return [Spree::NumberGenerators::Base]
+ def number_generator(store: nil)
+ Spree.number_generators.for(number_key, store: store)
+ end
+ end
+
+ # Assigns a number unless one was supplied. Public so a workflow can
+ # force assignment before validation when it needs the number earlier.
+ #
+ # @return [String] the assigned number
+ def generate_number
+ return number if number.present?
+
+ generator = self.class.number_generator(store: number_store)
+
+ MAX_ATTEMPTS.times do
+ candidate = generator.generate(self)
+ next if candidate.blank?
+
+ unless number_taken?(candidate)
+ @number_generated = true
+ return self.number = candidate
+ end
+ end
+
+ raise GenerationError,
+ "#{self.class.name} could not generate a unique number after " \
+ "#{MAX_ATTEMPTS} attempts using #{generator.class.name}"
+ end
+
+ # The store whose number settings apply. Most numbered models belong to a
+ # store directly; stock transfers reach one through their destination
+ # location. Falls back to the current store so a numbered model added
+ # later works without teaching this concern about it.
+ #
+ # @return [Spree::Store, nil]
+ def number_store
+ return store if respond_to?(:store) && store.present?
+
+ Spree::Current.store
+ end
+
+ private
+
+ # Advisory only — a concurrent writer can take the number between this
+ # check and the insert, which is what the unique-index rescue below is
+ # for. Unscoped because the index is global.
+ def number_taken?(candidate)
+ self.class.unscoped.exists?(number: candidate)
+ end
+
+ # Last line of defence. The pre-check and the uniqueness validation both
+ # read committed rows, so neither can see a number another writer commits
+ # in the instant between the check and this insert — only the index can.
+ #
+ # The insert runs in a savepoint because a constraint violation poisons
+ # the surrounding PostgreSQL transaction: without one, the regenerate
+ # queries below would themselves die with PG::InFailedSqlTransaction
+ # instead of recovering. Only creates whose number this concern generated
+ # pay for the savepoint — caller-supplied numbers should surface their
+ # collision, and updates never touch the number.
+ #
+ # Regenerate and retry once; a second collision is a real problem worth
+ # surfacing rather than looping on.
+ def create_or_update(**, &block)
+ return super unless new_record? && @number_generated
+
+ begin
+ self.class.transaction(requires_new: true) { super }
+ rescue ActiveRecord::RecordNotUnique => error
+ raise error if @number_regenerated || !number_collision?(error)
+
+ @number_regenerated = true
+ self.number = nil
+ generate_number
+ retry
+ end
+ end
+
+ def number_collision?(error)
+ error.message.to_s.downcase.include?('number')
+ end
+ end
+end
diff --git a/spree/core/app/models/spree/base.rb b/spree/core/app/models/spree/base.rb
index 44dac626c1..98d0535d01 100644
--- a/spree/core/app/models/spree/base.rb
+++ b/spree/core/app/models/spree/base.rb
@@ -6,6 +6,7 @@ class Spree::Base < ApplicationRecord
include Spree::IntegrationsConcern
include Spree::Publishable
include Spree::PrefixedId
+ include Spree::HasNumber
include Spree::TypedAssociations
after_initialize do
diff --git a/spree/core/app/models/spree/claim.rb b/spree/core/app/models/spree/claim.rb
index 45273f8d66..1625bab50b 100644
--- a/spree/core/app/models/spree/claim.rb
+++ b/spree/core/app/models/spree/claim.rb
@@ -9,7 +9,7 @@ module Spree
class Claim < Spree.base_class
has_prefix_id :claim
- include Spree::Core::NumberGenerator.new(prefix: 'CLM', length: 9)
+ has_spree_number prefix: 'CLM'
include Spree::NumberIdentifier
include Spree::SingleStoreResource
include Spree::HasStatus
diff --git a/spree/core/app/models/spree/exchange.rb b/spree/core/app/models/spree/exchange.rb
index acb6a0e6a9..cc5b314246 100644
--- a/spree/core/app/models/spree/exchange.rb
+++ b/spree/core/app/models/spree/exchange.rb
@@ -10,7 +10,7 @@ module Spree
class Exchange < Spree.base_class
has_prefix_id :exch
- include Spree::Core::NumberGenerator.new(prefix: 'EX', length: 9)
+ has_spree_number prefix: 'EX'
include Spree::NumberIdentifier
include Spree::SingleStoreResource
include Spree::HasStatus
diff --git a/spree/core/app/models/spree/export.rb b/spree/core/app/models/spree/export.rb
index bb5114fd90..022d2a5b79 100644
--- a/spree/core/app/models/spree/export.rb
+++ b/spree/core/app/models/spree/export.rb
@@ -10,7 +10,7 @@ module Spree
include Spree::NumberIdentifier
include Spree::VendorConcern if defined?(Spree::VendorConcern)
- include Spree::Core::NumberGenerator.new(prefix: 'EF')
+ has_spree_number prefix: 'EF'
publishes_lifecycle_events
diff --git a/spree/core/app/models/spree/fulfillment.rb b/spree/core/app/models/spree/fulfillment.rb
index 421d08bda3..19ffad264e 100644
--- a/spree/core/app/models/spree/fulfillment.rb
+++ b/spree/core/app/models/spree/fulfillment.rb
@@ -4,8 +4,8 @@ module Spree
class Fulfillment < Spree.base_class
has_prefix_id :ful
- include Spree::Core::NumberGenerator.new(prefix: 'F', length: 11)
- include Spree::NumberIdentifier
+ include Spree::DerivedNumber
+ derives_number infix: 'F'
include Spree::HasCustomFields
include Spree::Metadata
include Spree::StorePreferences
diff --git a/spree/core/app/models/spree/import.rb b/spree/core/app/models/spree/import.rb
index 7de607691a..dbf7f541c4 100644
--- a/spree/core/app/models/spree/import.rb
+++ b/spree/core/app/models/spree/import.rb
@@ -5,7 +5,7 @@ module Spree
has_prefix_id :imp
include Spree::NumberIdentifier
- include Spree::Core::NumberGenerator.new(prefix: 'IM')
+ has_spree_number prefix: 'IM'
# Where the downloadable example CSVs are served from — see `sample_csv_url`.
#
diff --git a/spree/core/app/models/spree/number_generators/base.rb b/spree/core/app/models/spree/number_generators/base.rb
new file mode 100644
index 0000000000..282bf07a84
--- /dev/null
+++ b/spree/core/app/models/spree/number_generators/base.rb
@@ -0,0 +1,56 @@
+module Spree
+ module NumberGenerators
+ # Produces candidate document numbers for models including
+ # {Spree::HasNumber}. Uniqueness is the concern's job, not the
+ # generator's — a generator only has to propose.
+ #
+ # Subclass and register to take over numbering for one resource or all of
+ # them (docs/plans/6.0-document-numbers.md):
+ #
+ # class MyApp::BranchOrderNumbers < Spree::NumberGenerators::Base
+ # def generate(record)
+ # "#{record.number_store.code}-#{record.created_at.year}-#{...}"
+ # end
+ # end
+ #
+ # Spree.number_generators[:order] = 'MyApp::BranchOrderNumbers'
+ class Base
+ # @param record [ActiveRecord::Base] the record being numbered; reaches
+ # its store through `#number_store` and its prefix through
+ # `.number_prefix`
+ # @return [String] a candidate number
+ def generate(record)
+ raise NotImplementedError, "#{self.class.name} must implement #generate"
+ end
+
+ protected
+
+ # The prefix a merchant configured for this resource, falling back to
+ # the model's code-level default. Only orders are configurable in 6.0.
+ #
+ # @return [String]
+ def prefix_for(record)
+ return record.class.number_prefix unless record.number_key == :order
+
+ store_preference(record, :order_number_prefix) || record.class.number_prefix
+ end
+
+ # @return [String]
+ def suffix_for(record)
+ return '' unless record.number_key == :order
+
+ store_preference(record, :order_number_suffix).to_s
+ end
+
+ # @return [Object, nil] nil when there is no store to read, so callers
+ # fall back to their own defaults rather than to a store's blank
+ def store_preference(record, name)
+ store = record.number_store
+ return if store.nil?
+
+ value = store.public_send(:"preferred_#{name}")
+ value.presence
+ end
+ end
+ end
+end
diff --git a/spree/core/app/models/spree/number_generators/random.rb b/spree/core/app/models/spree/number_generators/random.rb
new file mode 100644
index 0000000000..d0e00a6e8c
--- /dev/null
+++ b/spree/core/app/models/spree/number_generators/random.rb
@@ -0,0 +1,23 @@
+module Spree
+ module NumberGenerators
+ # Pre-6.0 behaviour, kept as an opt-in: prefix + a fixed-width run of
+ # random digits. Merchants choose this when they would rather not tell a
+ # repeat customer how many orders the store took in between their two
+ # purchases, and accept numbers that are harder to read back over a
+ # phone.
+ class Random < Base
+ DEFAULT_LENGTH = 9
+
+ # @param length [Integer] digits after the prefix
+ def initialize(length: DEFAULT_LENGTH)
+ @length = length
+ end
+
+ def generate(record)
+ digits = SecureRandom.random_number(10**@length).to_s.rjust(@length, '0')
+
+ "#{prefix_for(record)}#{digits}#{suffix_for(record)}"
+ end
+ end
+ end
+end
diff --git a/spree/core/app/models/spree/number_generators/sequential.rb b/spree/core/app/models/spree/number_generators/sequential.rb
new file mode 100644
index 0000000000..5b311156be
--- /dev/null
+++ b/spree/core/app/models/spree/number_generators/sequential.rb
@@ -0,0 +1,88 @@
+module Spree
+ module NumberGenerators
+ # The 6.0 default: prefix + a counter that advances by one per document,
+ # producing the invoice-like numbers merchants expect (`R1001`, `R1002`).
+ #
+ # The counter lives in {Spree::NumberSequence} rather than being derived
+ # from the `number` column, because the column cannot answer "what comes
+ # next": upgraded stores are full of 5.x random values that poison any
+ # MAX-and-parse, string columns sort `R999` above `R1000`, concurrent
+ # writers computing MAX+1 collide by construction, and a merchant-chosen
+ # starting value is not a fact about any existing row.
+ #
+ # Numbering is mostly-gapless, never guaranteed gapless — a collision or
+ # a rolled-back transaction consumes a value. Never present this as legal
+ # invoice numbering.
+ class Sequential < Base
+ # Candidate values checked per query when jumping a stretch of numbers
+ # another store already owns.
+ SCAN_BATCH_SIZE = 100
+
+ def generate(record)
+ store = record.number_store
+ raise_missing_store(record) if store.nil?
+
+ resource_type = record.number_key.to_s
+ value = Spree::NumberSequence.next_value(
+ store: store,
+ resource_type: resource_type,
+ start_at: start_at_for(record)
+ )
+
+ candidate = compose(record, value)
+ return candidate unless taken?(record, candidate)
+
+ # The unique index is global, so a sibling store with the same format
+ # can own a whole stretch of numbers — and stepping through it one
+ # save attempt at a time would exhaust the concern's retry budget and
+ # fail the save. Find the first free value in batches and jump the
+ # counter past the stretch in one move instead.
+ free_value = next_free_value(record, value)
+ Spree::NumberSequence.advance_to(store: store, resource_type: resource_type, value: free_value)
+
+ compose(record, free_value)
+ end
+
+ private
+
+ def compose(record, value)
+ "#{prefix_for(record)}#{value}#{suffix_for(record)}"
+ end
+
+ def taken?(record, candidate)
+ record.class.unscoped.exists?(number: candidate)
+ end
+
+ def next_free_value(record, from)
+ value = from
+
+ loop do
+ candidates = (value + 1..value + SCAN_BATCH_SIZE).index_by { |v| compose(record, v) }
+ taken = record.class.unscoped.where(number: candidates.keys).pluck(:number)
+ free = (candidates.keys - taken).first
+
+ return candidates.fetch(free) if free
+
+ value += SCAN_BATCH_SIZE
+ end
+ end
+
+ # Says which setting is missing rather than letting the concern report
+ # ten failed attempts and blame collisions.
+ def raise_missing_store(record)
+ raise Spree::HasNumber::GenerationError,
+ "#{record.class.name} has no store to read numbering settings from — " \
+ 'define #number_store on the model or set Spree::Current.store'
+ end
+
+ # The starting value is part of the order-numbers settings card, so only
+ # orders honour it; every other document type counts from the default.
+ def start_at_for(record)
+ return Spree::NumberSequence::DEFAULT_START unless record.number_key == :order
+
+ store_preference(record, :order_number_sequence_start).to_i.nonzero? ||
+ Spree::NumberSequence::DEFAULT_START
+ end
+ end
+ end
+end
diff --git a/spree/core/app/models/spree/number_sequence.rb b/spree/core/app/models/spree/number_sequence.rb
new file mode 100644
index 0000000000..ab5cffb80b
--- /dev/null
+++ b/spree/core/app/models/spree/number_sequence.rb
@@ -0,0 +1,86 @@
+module Spree
+ # Per-store, per-resource counter behind sequential document numbering
+ # (docs/plans/6.0-document-numbers.md). One row per numbered resource type
+ # a store actually uses; nothing outside {Spree::NumberGenerators::Sequential}
+ # reads them.
+ #
+ # This exists because the `number` column cannot say what comes next — see
+ # the generator for why deriving it from data is not an option. Postgres
+ # has native sequences, MySQL and SQLite do not, so a locked counter row is
+ # the portable equivalent.
+ class NumberSequence < Spree.base_class
+ DEFAULT_START = 1001
+
+ belongs_to :store, class_name: 'Spree::Store'
+
+ validates :resource_type, presence: true,
+ uniqueness: { scope: :store_id, case_sensitive: false }
+ validates :value, numericality: { only_integer: true, greater_than_or_equal_to: 0 }
+
+ class << self
+ # Advances the counter and returns the value to use. The row is locked
+ # for the increment, so concurrent checkouts hand out distinct numbers
+ # instead of racing on the same one.
+ #
+ # @param store [Spree::Store]
+ # @param resource_type [String] e.g. 'order'
+ # @param start_at [Integer] first value handed out for a fresh counter
+ # @return [Integer]
+ # Whether a counter has already handed out a number, which is what makes
+ # the store's starting-value setting inert from then on. The dashboard
+ # reads this to say so rather than letting a merchant set a value that
+ # silently does nothing.
+ #
+ # @param store [Spree::Store]
+ # @param resource_type [String]
+ # @return [Boolean]
+ def started?(store:, resource_type: 'order')
+ return false if store.nil?
+
+ exists?(store: store, resource_type: resource_type)
+ end
+
+ # Moves the counter forward to +value+ — never backward — so numbering
+ # continues past a stretch of numbers that turned out to be taken.
+ #
+ # @param store [Spree::Store]
+ # @param resource_type [String]
+ # @param value [Integer] the value the counter should stand at
+ def advance_to(store:, resource_type:, value:)
+ sequence = find_or_create_sequence(store, resource_type, value)
+
+ sequence.with_lock do
+ sequence.update!(value: value) if sequence.value < value
+ end
+ end
+
+ def next_value(store:, resource_type:, start_at: DEFAULT_START)
+ sequence = find_or_create_sequence(store, resource_type, start_at)
+
+ sequence.with_lock do
+ sequence.increment!(:value)
+ sequence.value
+ end
+ end
+
+ private
+
+ # A fresh counter is seeded one below the configured start so the first
+ # increment hands out `start_at` itself.
+ #
+ # Two writers can reach the insert together — the loser sees either the
+ # unique index (RecordNotUnique) or the uniqueness validation reading
+ # the winner's committed row (RecordInvalid). Both mean the same thing:
+ # the row now exists, so read it.
+ def find_or_create_sequence(store, resource_type, start_at)
+ seed = [start_at.to_i - 1, 0].max
+
+ find_or_create_by!(store: store, resource_type: resource_type) do |sequence|
+ sequence.value = seed
+ end
+ rescue ActiveRecord::RecordNotUnique, ActiveRecord::RecordInvalid
+ find_by!(store: store, resource_type: resource_type)
+ end
+ end
+ end
+end
diff --git a/spree/core/app/models/spree/order.rb b/spree/core/app/models/spree/order.rb
index 470054e1d7..8b53702693 100644
--- a/spree/core/app/models/spree/order.rb
+++ b/spree/core/app/models/spree/order.rb
@@ -38,7 +38,7 @@ module Spree
include Spree::Purchase::Validations
include Spree::Purchase::Totals
include Spree::Purchase::Lifecycle
- include Spree::Core::NumberGenerator.new(prefix: 'R')
+ has_spree_number prefix: 'R'
include Spree::NumberIdentifier
diff --git a/spree/core/app/models/spree/payment.rb b/spree/core/app/models/spree/payment.rb
index 70a72ae50a..42046c0998 100644
--- a/spree/core/app/models/spree/payment.rb
+++ b/spree/core/app/models/spree/payment.rb
@@ -4,8 +4,8 @@ module Spree
class Payment < Spree.base_class
has_prefix_id :py # Stripe: py_
- include Spree::Core::NumberGenerator.new(prefix: 'P', letters: true, length: 7)
- include Spree::NumberIdentifier
+ include Spree::DerivedNumber
+ derives_number infix: 'P'
include Spree::HasCustomFields
include Spree::Metadata
if defined?(Spree::Security::Payments)
diff --git a/spree/core/app/models/spree/payment/gateway_options.rb b/spree/core/app/models/spree/payment/gateway_options.rb
index 91d461e7d0..c4cd2e2be0 100644
--- a/spree/core/app/models/spree/payment/gateway_options.rb
+++ b/spree/core/app/models/spree/payment/gateway_options.rb
@@ -28,16 +28,21 @@ module Spree
order.last_ip_address
end
+ # The payment number already names its order (`R1001-P1`), so this is
+ # the payment number alone rather than the two concatenated.
def order_id
- "#{order.number}-#{payment.number}"
+ payment.number
end
def payment_id
payment.number
end
+ # Built on the prefixed ID, not the number: a derived number shifts if
+ # an earlier sibling payment is destroyed, and a shifted idempotency
+ # key could collide with one already used at the gateway.
def idempotency_key
- "spree-#{payment.number}"
+ "spree-#{payment.prefixed_id}"
end
def shipping
diff --git a/spree/core/app/models/spree/return.rb b/spree/core/app/models/spree/return.rb
index 7bffc02c77..e770efe5c0 100644
--- a/spree/core/app/models/spree/return.rb
+++ b/spree/core/app/models/spree/return.rb
@@ -13,7 +13,7 @@ module Spree
class Return < Spree.base_class
has_prefix_id :ret
- include Spree::Core::NumberGenerator.new(prefix: 'RET', length: 9)
+ has_spree_number prefix: 'RET'
include Spree::NumberIdentifier
include Spree::SingleStoreResource
include Spree::HasStatus
diff --git a/spree/core/app/models/spree/stock_transfer.rb b/spree/core/app/models/spree/stock_transfer.rb
index e537ab5eec..a620bc1293 100644
--- a/spree/core/app/models/spree/stock_transfer.rb
+++ b/spree/core/app/models/spree/stock_transfer.rb
@@ -2,7 +2,7 @@ module Spree
class StockTransfer < Spree.base_class
has_prefix_id :st
- include Spree::Core::NumberGenerator.new(prefix: 'T')
+ has_spree_number prefix: 'T'
include Spree::NumberIdentifier
include Spree::HasCustomFields
include Spree::Metadata
@@ -24,6 +24,15 @@ module Spree
validate :stock_movements_not_empty
validates :destination_location, presence: true
+ # Transfers have no store of their own — they belong to the warehouses
+ # they move stock between, and those are store-scoped. Used by
+ # {Spree::HasNumber} to pick up the store's numbering settings.
+ #
+ # @return [Spree::Store, nil]
+ def number_store
+ destination_location&.store || source_location&.store || super
+ end
+
def source_movements
find_stock_location_with_location_id(source_location_id)
end
diff --git a/spree/core/app/models/spree/store.rb b/spree/core/app/models/spree/store.rb
index da8fa24033..d7f8cb6f59 100644
--- a/spree/core/app/models/spree/store.rb
+++ b/spree/core/app/models/spree/store.rb
@@ -91,6 +91,15 @@ module Spree
# decides which StockLocation fulfills which items.
preference :order_routing_strategy, :string, default: 'Spree::OrderRouting::Strategy::Rules'
+ # Document numbering (docs/plans/6.0-document-numbers.md). The format
+ # applies to every numbered document; prefix, suffix and starting value
+ # are order-only — other document types keep their code-level prefixes.
+ # Changes affect future numbers only; existing numbers are permanent.
+ preference :document_number_format, :string, default: 'sequential'
+ preference :order_number_prefix, :string, default: 'R'
+ preference :order_number_suffix, :string, default: ''
+ preference :order_number_sequence_start, :integer, default: 1001
+
#
# Associations
#
@@ -195,7 +204,16 @@ module Spree
validates :preferred_digital_asset_authorized_days, numericality: { only_integer: true, greater_than: 0 }
validates :preferred_stock_reservation_ttl_minutes, numericality: { only_integer: true, greater_than: 0 }
validates :preferred_storefront_access, inclusion: { in: Spree::Channel::Gating::STOREFRONT_ACCESS }
+ validates :preferred_document_number_format,
+ inclusion: { in: Spree::NumberGenerators::Registry::FORMATS.keys }
+ validates :preferred_order_number_sequence_start,
+ numericality: { only_integer: true, greater_than: 0 }
+ validates :preferred_order_number_prefix, :preferred_order_number_suffix,
+ length: { maximum: 10 },
+ format: { with: /\A[A-Z0-9#-]*\z/,
+ message: :invalid_document_number_affix }
validate :preferred_storefront_url_is_an_origin
+ validate :order_number_sequence_start_unchanged_after_first_number, on: :update
validates :mail_from_address, email: { allow_blank: false }
validates :customer_support_email, email: { allow_blank: true }
# FIXME: we should remove this condition in v5
@@ -501,5 +519,22 @@ module Spree
errors.add(:preferred_storefront_url, :invalid)
end
+
+ # The starting value only shapes a counter that does not exist yet — once
+ # the first number is issued the counter owns the value, so accepting a
+ # change here would persist a setting that can never apply again. The
+ # dashboard disables the field; this backs it for API clients.
+ def order_number_sequence_start_unchanged_after_first_number
+ return unless preferences_changed?
+
+ default = preference_default(:order_number_sequence_start)
+ old_value, new_value = changes['preferences'].map do |preferences_hash|
+ ((preferences_hash || {})[:order_number_sequence_start] || default).to_i
+ end
+ return if old_value == new_value
+ return unless Spree::NumberSequence.started?(store: self)
+
+ errors.add(:preferred_order_number_sequence_start, :locked_after_first_number)
+ end
end
end
diff --git a/spree/core/app/services/spree/sample_data/import_builder.rb b/spree/core/app/services/spree/sample_data/import_builder.rb
index faf8f18ff9..dd53d8fe18 100644
--- a/spree/core/app/services/spree/sample_data/import_builder.rb
+++ b/spree/core/app/services/spree/sample_data/import_builder.rb
@@ -18,7 +18,9 @@ module Spree
# have to travel with it rather than live on the instance.
import.preferred_inline = inline
import.preferred_skip_events = skip_events
- import.number = import.generate_permalink(import_class)
+ # Saved with `validate: false` below, which skips the before_validation
+ # that normally numbers the record.
+ import.generate_number
import.attachment.attach(
io: File.open(csv_path),
filename: File.basename(csv_path),
diff --git a/spree/core/config/locales/en.yml b/spree/core/config/locales/en.yml
index eae690690b..100f5ce4b6 100644
--- a/spree/core/config/locales/en.yml
+++ b/spree/core/config/locales/en.yml
@@ -546,6 +546,8 @@ en:
errors:
messages:
already_confirmed: was already confirmed
+ invalid_document_number_affix: 'can only contain uppercase letters, digits, dashes and #'
+ locked_after_first_number: cannot change once numbering has started
not_a_number: is not a number
not_found: not found
not_locked: was not locked
diff --git a/spree/core/db/migrate/20260813000001_create_spree_number_sequences.rb b/spree/core/db/migrate/20260813000001_create_spree_number_sequences.rb
new file mode 100644
index 0000000000..d01fdc571d
--- /dev/null
+++ b/spree/core/db/migrate/20260813000001_create_spree_number_sequences.rb
@@ -0,0 +1,13 @@
+class CreateSpreeNumberSequences < ActiveRecord::Migration[8.1]
+ def change
+ create_table :spree_number_sequences do |t|
+ t.references :store, null: false
+ t.string :resource_type, null: false
+ t.bigint :value, null: false, default: 0
+ t.timestamps
+ end
+
+ add_index :spree_number_sequences, [:store_id, :resource_type],
+ unique: true, name: 'index_spree_number_sequences_on_store_and_resource'
+ end
+end
diff --git a/spree/core/db/sample_data/orders.rb b/spree/core/db/sample_data/orders.rb
index 505354fa8e..5a5132db81 100644
--- a/spree/core/db/sample_data/orders.rb
+++ b/spree/core/db/sample_data/orders.rb
@@ -35,11 +35,14 @@ shipping_address = Spree::Address.find_or_create_by!(
phone: '555-0199'
)
-# Create orders
+# Create orders. Numbers are fixed rather than generated — the number is the
+# `first_or_create!` key that makes a re-run idempotent — and match the 6.0
+# sequential default so a sample store looks like a real one. Real orders
+# created afterwards skip past taken values on their own.
orders = []
orders << store.orders.where(
- number: 'R123456789',
+ number: 'R1001',
currency: 'USD'
).first_or_create! do |order|
@@ -49,7 +52,7 @@ orders << store.orders.where(
end
orders << store.orders.where(
- number: 'R987654321',
+ number: 'R1002',
currency: 'USD'
).first_or_create! do |order|
diff --git a/spree/core/lib/spree/core.rb b/spree/core/lib/spree/core.rb
index 40bbdf30b8..ceefc8e6b8 100644
--- a/spree/core/lib/spree/core.rb
+++ b/spree/core/lib/spree/core.rb
@@ -472,6 +472,17 @@ module Spree
Rails.application.config.spree.integrations = value
end
+ # Registry mapping a numbered resource to the generator that produces its
+ # document numbers. With no entry, the store's `document_number_format`
+ # preference picks between the sequential and random strategies.
+ #
+ # @return [Spree::NumberGenerators::Registry]
+ # @example Custom order numbers
+ # Spree.number_generators[:order] = 'MyApp::BranchOrderNumbers'
+ def self.number_generators
+ Rails.application.config.spree.number_generators
+ end
+
# Event subscribers that handle lifecycle and custom events
# @example Adding a custom subscriber
# Spree.subscribers << MyApp::OrderNotificationSubscriber
@@ -619,6 +630,7 @@ end
require 'spree/core/version'
require 'spree/core/number_generator'
+require 'spree/number_generators/registry'
require 'spree/migrations'
require 'spree/translation_migrations'
require 'spree/core/engine'
diff --git a/spree/core/lib/spree/core/engine.rb b/spree/core/lib/spree/core/engine.rb
index b23e0dee45..aeb4f13dcd 100644
--- a/spree/core/lib/spree/core/engine.rb
+++ b/spree/core/lib/spree/core/engine.rb
@@ -40,6 +40,7 @@ module Spree
:analytics_events,
:analytics_event_handlers,
:integrations,
+ :number_generators,
:subscribers,
:store_authentication_strategies,
:admin_authentication_strategies)
@@ -94,6 +95,12 @@ module Spree
initializer 'spree.register.calculators', before: :after_initialize do |app|
end
+ # Seeded before application initializers so a host's
+ # `config/initializers/spree.rb` can register custom generators.
+ initializer 'spree.register.number_generators', before: :load_config_initializers do |app|
+ app.config.spree.number_generators = Spree::NumberGenerators::Registry.new
+ end
+
initializer 'spree.register.stock_splitters', before: :load_config_initializers do |app|
end
diff --git a/spree/core/lib/spree/core/number_generator.rb b/spree/core/lib/spree/core/number_generator.rb
index 709a04b0b2..dd91041465 100644
--- a/spree/core/lib/spree/core/number_generator.rb
+++ b/spree/core/lib/spree/core/number_generator.rb
@@ -1,49 +1,53 @@
module Spree
module Core
+ # @deprecated Use {Spree::HasNumber} instead. Removed in Spree 6.1.
+ #
+ # # before
+ # include Spree::Core::NumberGenerator.new(prefix: 'R')
+ #
+ # # after
+ # has_spree_number prefix: 'R'
+ #
+ # Kept as a shell so existing models and extension decorators keep
+ # working for one release. Including it wires up {Spree::HasNumber} with
+ # the given prefix, which means numbers now follow the store's format
+ # preference (sequential by default) rather than always being random.
+ # Hosts that need the old random numbers should switch the store's
+ # `document_number_format` preference to `random`, or register their own
+ # generator — see docs/plans/6.0-document-numbers.md.
+ #
+ # `length:` and `letters:` are accepted and ignored: they described the
+ # random format, which is now the strategy's business rather than the
+ # model's.
class NumberGenerator < Module
- BASE = 10
DEFAULT_LENGTH = 9
attr_accessor :prefix, :length
def initialize(options)
- @prefix = options.fetch(:prefix)
- @length = options.fetch(:length, DEFAULT_LENGTH)
- @letters = options[:letters]
+ @prefix = options.fetch(:prefix)
+ @length = options.fetch(:length, DEFAULT_LENGTH)
+ @letters = options[:letters]
+
+ Spree::Deprecation.warn(
+ 'Spree::Core::NumberGenerator is deprecated and will be removed in ' \
+ "Spree 6.1. Replace `include Spree::Core::NumberGenerator.new(prefix: '#{@prefix}')` " \
+ "with `has_spree_number prefix: '#{@prefix}'`. " \
+ 'See docs/plans/6.0-document-numbers.md.'
+ )
end
def included(host)
- generator_instance = self
+ prefix = @prefix
host.class_eval do
- before_validation do |instance|
- instance.number ||= generate_permalink(host)
- end
+ # Hosts inheriting from Spree::Base already have the concern; a bare
+ # ActiveRecord model (some extensions) needs it included here.
+ include Spree::HasNumber unless respond_to?(:has_spree_number)
- define_singleton_method(:number_generator) { generator_instance }
-
- def generate_permalink(host)
- host.number_generator.generate_permalink(host)
- end
- end
- end
-
- def generate_permalink(host)
- length = @length
-
- loop do
- candidate = new_candidate(length)
- return candidate unless host.exists?(number: candidate)
-
- # If over half of all possible options are taken add another digit.
- length += 1 if host.count > Rational(BASE**length, 2)
+ has_spree_number prefix: prefix
end
end
-
- def new_candidate(length)
- characters = @letters ? 36 : 10
- @prefix + SecureRandom.random_number(characters**length).to_s(characters).rjust(length, '0').upcase
- end
- end # Permalink
- end # Core
-end # Spree
+ end
+ end
+end
diff --git a/spree/core/lib/spree/number_generators/registry.rb b/spree/core/lib/spree/number_generators/registry.rb
new file mode 100644
index 0000000000..74b266f5b0
--- /dev/null
+++ b/spree/core/lib/spree/number_generators/registry.rb
@@ -0,0 +1,80 @@
+module Spree
+ module NumberGenerators
+ # Maps a resource key (`:order`, `:return`, …) to the generator that
+ # numbers it. Empty by default: with no explicit entry, the store's
+ # `document_number_format` preference decides between the sequential and
+ # random strategies, which is what makes the dashboard switch work
+ # without any registration at all.
+ #
+ # Spree.number_generators[:order] = 'MyApp::BranchOrderNumbers'
+ # Spree.number_generators[:order] # => the class
+ # Spree.number_generators.delete(:order) # back to store settings
+ #
+ # Values are stored as strings and constantized on read so a host app can
+ # register in an initializer without eager-loading the class, and so
+ # Zeitwerk reloads resolve the current definition in development.
+ class Registry
+ FORMATS = {
+ 'sequential' => 'Spree::NumberGenerators::Sequential',
+ 'random' => 'Spree::NumberGenerators::Random'
+ }.freeze
+
+ DEFAULT_FORMAT = 'sequential'.freeze
+
+ def initialize
+ @overrides = {}
+ end
+
+ # @param key [Symbol, String] resource key
+ # @param class_name [String, Class, nil] nil clears the override
+ def []=(key, class_name)
+ if class_name.nil?
+ delete(key)
+ else
+ @overrides[key.to_sym] = class_name.to_s
+ end
+ end
+
+ # @return [Class, nil] the registered class, without falling back
+ def [](key)
+ @overrides[key.to_sym]&.constantize
+ end
+
+ def delete(key)
+ @overrides.delete(key.to_sym)
+ end
+
+ def keys
+ @overrides.keys
+ end
+
+ def clear
+ @overrides.clear
+ end
+
+ # The generator for a resource: an explicit registration if there is
+ # one, otherwise the strategy named by the format preference of the
+ # store the record belongs to.
+ #
+ # @param key [Symbol, String] resource key
+ # @param store [Spree::Store, nil] the record's store; the format
+ # preference is read from it rather than from `Spree::Current` so a
+ # background job numbering another store's document still honours
+ # that store's choice
+ # @return [Spree::NumberGenerators::Base]
+ def for(key, store: nil)
+ registered = self[key]
+ return registered.new if registered
+
+ format_class(store).new
+ end
+
+ private
+
+ def format_class(store)
+ format = (store || Spree::Current.store)&.preferred_document_number_format
+ FORMATS.fetch(format.to_s, FORMATS.fetch(DEFAULT_FORMAT)).constantize
+ end
+ end
+ end
+end
diff --git a/spree/core/lib/spree/testing_support/factories/number_sequence_factory.rb b/spree/core/lib/spree/testing_support/factories/number_sequence_factory.rb
new file mode 100644
index 0000000000..d6a26dd148
--- /dev/null
+++ b/spree/core/lib/spree/testing_support/factories/number_sequence_factory.rb
@@ -0,0 +1,7 @@
+FactoryBot.define do
+ factory :number_sequence, class: 'Spree::NumberSequence' do
+ store { Spree::Store.default }
+ resource_type { 'order' }
+ value { 1000 }
+ end
+end
diff --git a/spree/core/lib/tasks/migrate_returns.rake b/spree/core/lib/tasks/migrate_returns.rake
index 5ad27ff4f3..8e8b18eee7 100644
--- a/spree/core/lib/tasks/migrate_returns.rake
+++ b/spree/core/lib/tasks/migrate_returns.rake
@@ -171,7 +171,7 @@ module Spree
created_at: authorization.created_at,
updated_at: authorization.updated_at
)
- # Required, not an optimisation: NumberGenerator assigns the number in a
+ # Required, not an optimisation: Spree::HasNumber assigns the number in a
# before_validation hook, which save!(validate: false) below skips — so
# without this the NOT NULL constraint on `number` rejects the row. The
# legacy number is also what makes a re-run idempotent, so a generated
@@ -184,7 +184,7 @@ module Spree
if authorization.number.present?
record.number = authorization.number
else
- record.number = record.generate_permalink(klass)
+ record.generate_number
# write_attribute, not #metadata= — see migrated_numberless_ids.
record.write_attribute(:metadata, { 'legacy_return_authorization_id' => authorization.id })
end
diff --git a/spree/core/spec/lib/spree/core/number_generator_spec.rb b/spree/core/spec/lib/spree/core/number_generator_spec.rb
index aa5bf1428b..75faaafe54 100644
--- a/spree/core/spec/lib/spree/core/number_generator_spec.rb
+++ b/spree/core/spec/lib/spree/core/number_generator_spec.rb
@@ -1,158 +1,55 @@
require 'spec_helper'
+# The module factory is a deprecated shell over Spree::HasNumber (removed in
+# 6.1). What matters here is that models written against the old API still get
+# numbered — not how the number is produced, which has its own spec.
describe Spree::Core::NumberGenerator do
- let(:number_generator) { described_class.new(options) }
-
let(:model) do
- mod = number_generator
-
Class.new(ApplicationRecord) do
- self.table_name = 'spree_orders'
- include mod
- end
- end
-
- let(:options) { { prefix: 'R' } }
-
- %i[prefix length].each do |name|
- describe "##{name}" do
- let(:value) { double('Generic Value') }
-
- it 'returns attribute value from options' do
- expect(described_class.new(options.merge(name => value)).public_send(name)).to be(value)
- end
- end
+ def self.name = 'Spree::LegacyNumbered'
- describe "##{name}=" do
- let(:value_a) { double('Generic Value A') }
- let(:value_b) { double('Generic Value B') }
+ self.table_name = 'spree_orders'
- it 'writes attribute value' do
- object = described_class.new(options.merge(name => value_a))
- expect { object.public_send(:"#{name}=", value_b) }.
- to change { object.public_send(name) }.
- from(value_a).
- to(value_b)
- end
+ include Spree::Core::NumberGenerator.new(prefix: 'R')
end
end
- shared_examples_for 'duplicate without length increment' do
- it 'sets permalink field' do
- expect { subject }.to change(resource, :number).from(nil).to(String)
- expect(resource.number).to match(regex)
- end
+ before do
+ allow(Spree::Deprecation).to receive(:warn)
+ # The bare test class has no store association, so the concern falls back
+ # to the current store for its numbering settings.
+ Spree::Current.store = @default_store
end
- shared_examples_for 'generating permalink' do
- let(:resource) { model.new }
-
- context 'and generated candidate is unique' do
- before do
- expect(model).to receive(:exists?).and_return(false)
- end
-
- it 'sets permalink field' do
- expect { subject }.to change(resource, :number).from(nil).to(String)
- expect(resource.number).to match(regex)
- end
- end
-
- context 'and generated candidate is NOT unique' do
- before do
- expect(model).to receive(:exists?).and_return(true).ordered
- expect(model).to receive(:count).and_return(record_count).ordered
- expect(model).to receive(:exists?).and_return(false)
- end
-
- context 'and less than half of the value space taken' do
- let(:record_count) { 10**expected_length / 2 - 1 }
-
- include_examples 'duplicate without length increment'
- end
+ after { Spree::Current.store = nil }
- context 'and exactly half of the value space taken' do
- let(:record_count) { 10**expected_length / 2 }
+ it 'warns that the module is going away' do
+ model
- include_examples 'duplicate without length increment'
- end
-
- context 'and more than half of the value space is taken' do
- let(:record_count) { 10**expected_length / 2 + 1 }
-
- it 'sets permalink field' do
- expect { subject }.to change(resource, :number).from(nil).to(String)
- expect(resource.number).to match(regex_more_than_half)
- end
- end
- end
+ expect(Spree::Deprecation).to have_received(:warn).with(/removed in Spree 6.1/)
end
- describe '#included' do
- context 'generates .number_generator on host' do
- it 'returns number generator' do
- expect(model.number_generator).to be(number_generator)
- end
- end
-
- context 'generates validation hooks on host' do
- subject { resource.valid? }
-
- let(:expected_length) { 9 }
- let(:regex) { /R[0-9]{9}$/ }
- let(:regex_more_than_half) { /R[0-9]{10}$/ }
-
- context 'when permalink field value is nil' do
- context 'on defaults' do
- include_examples 'generating permalink'
- end
-
- context 'with length: option' do
- let(:options) { super().merge(length: 10) }
- let(:expected_length) { 10 }
- let(:regex) { /R[0-9]{10}$/ }
- let(:regex_more_than_half) { /R[0-9]{11}$/ }
-
- include_examples 'generating permalink'
- end
+ it 'points at the replacement' do
+ model
- context 'with letters option' do
- let(:options) { super().merge(letters: true) }
- let(:regex) { /R[0-9A-Z]{9}$/ }
- let(:regex_more_than_half) { /R[0-9A-Z]{10}$/ }
-
- include_examples 'generating permalink'
- end
- end
-
- context 'when permalink field value is present' do
- let(:resource) { model.new(number: 'Test') }
-
- it 'does not touch field' do
- expect { subject }.not_to change(resource, :number)
- end
- end
- end
+ expect(Spree::Deprecation).to have_received(:warn).with(/has_spree_number/)
end
- describe 'generator method redefinition' do
- let(:model) do
- mod = number_generator
+ it 'still numbers records on create' do
+ record = model.new(currency: 'USD')
+ record.validate
- Class.new(ApplicationRecord) do
- self.table_name = 'spree_orders'
- include mod
+ expect(record.number).to start_with('R')
+ end
- def generate_permalink(_host)
- '42'
- end
- end
- end
+ it 'leaves a caller-supplied number alone' do
+ record = model.new(currency: 'USD', number: 'R-KEEP-ME')
+ record.validate
- let(:resource) { model.new }
+ expect(record.number).to eq('R-KEEP-ME')
+ end
- it 'allows to override generator method' do
- expect { resource.validate }.to change { resource.number }.from(nil).to('42')
- end
+ it 'exposes the prefix it was built with' do
+ expect(described_class.new(prefix: 'R').prefix).to eq('R')
end
end
diff --git a/spree/core/spec/models/spree/concerns/derived_number_spec.rb b/spree/core/spec/models/spree/concerns/derived_number_spec.rb
new file mode 100644
index 0000000000..2909d7ad02
--- /dev/null
+++ b/spree/core/spec/models/spree/concerns/derived_number_spec.rb
@@ -0,0 +1,83 @@
+require 'spec_helper'
+
+RSpec.describe Spree::DerivedNumber do
+ let(:order) { create(:order) }
+
+ describe 'fulfillments' do
+ it 'derives the number from the order and position' do
+ first = create(:fulfillment, order: order)
+ second = create(:fulfillment, order: order)
+
+ expect([first.number, second.number]).to eq(["#{order.number}-F1", "#{order.number}-F2"])
+ end
+
+ it 'does not write the column' do
+ fulfillment = create(:fulfillment, order: order)
+
+ expect(fulfillment.reload[:number]).to be_nil
+ end
+
+ it 'keeps a stored number on legacy rows' do
+ fulfillment = create(:fulfillment, order: order)
+ fulfillment.update_column(:number, 'F00012345678')
+
+ expect(fulfillment.reload.number).to eq('F00012345678')
+ end
+
+ it 'keeps positions stable when an earlier sibling is canceled' do
+ first = create(:fulfillment, order: order)
+ second = create(:fulfillment, order: order)
+ first.update!(status: 'canceled')
+
+ expect(second.number).to eq("#{order.number}-F2")
+ end
+ end
+
+ describe 'payments' do
+ let(:paid_order) { create(:order, total: 45.75) }
+
+ it 'derives the number from the order and position' do
+ payment = create(:payment, order: paid_order)
+
+ expect(payment.number).to eq("#{paid_order.number}-P1")
+ end
+
+ it 'numbers a second payment on the same order' do
+ create(:payment, order: paid_order)
+ second = create(:payment, order: paid_order, amount: 0)
+
+ expect(second.number).to eq("#{paid_order.number}-P2")
+ end
+
+ it 'derives from the cart while checkout is still in progress' do
+ cart = create(:cart)
+ payment = create(:payment, cart: cart, order: nil, amount: 0)
+
+ expect(payment.number).to eq("#{cart.number}-P1")
+ end
+ end
+
+ describe 'gateway options' do
+ let(:payment) { create(:payment, order: create(:order, total: 45.75)) }
+
+ it 'sends the payment number as the gateway order reference' do
+ expect(payment.gateway_options[:order_id]).to eq(payment.number)
+ end
+
+ it 'builds the idempotency key from the immutable prefixed id' do
+ expect(payment.gateway_options[:idempotency_key]).to eq("spree-#{payment.prefixed_id}")
+ end
+
+ it 'keeps the idempotency key stable when an earlier sibling is destroyed' do
+ paid_order = create(:order, total: 45.75)
+ first = create(:payment, order: paid_order)
+ second = create(:payment, order: paid_order, amount: 0)
+ key_before = second.gateway_options[:idempotency_key]
+
+ first.destroy!
+
+ # The display number shifts (accepted trade-off); the gateway key must not.
+ expect(second.reload.gateway_options[:idempotency_key]).to eq(key_before)
+ end
+ end
+end
diff --git a/spree/core/spec/models/spree/concerns/has_number_race_spec.rb b/spree/core/spec/models/spree/concerns/has_number_race_spec.rb
new file mode 100644
index 0000000000..74a8e83e6a
--- /dev/null
+++ b/spree/core/spec/models/spree/concerns/has_number_race_spec.rb
@@ -0,0 +1,60 @@
+require 'spec_helper'
+
+# Three things guard number uniqueness, and each catches what the one before
+# it cannot: the generator's pre-check (cheap, advisory), the uniqueness
+# validation from Spree::NumberIdentifier, and the database's unique index —
+# the only one that holds when two writers commit at the same instant.
+RSpec.describe 'Spree::HasNumber uniqueness guards' do
+ # Created before any stubbing so it numbers itself normally.
+ let!(:taken) { create(:order).number }
+
+ def generating(*candidates)
+ generator = instance_double(Spree::NumberGenerators::Sequential)
+ allow(Spree::NumberGenerators::Sequential).to receive(:new).and_return(generator)
+ allow(generator).to receive(:generate).and_return(*candidates)
+
+ yield
+ end
+
+ it 'skips a taken candidate before it reaches the database' do
+ order = build(:order)
+
+ generating(taken, 'R-SECOND-TRY') { order.save! }
+
+ expect(order.reload.number).to eq('R-SECOND-TRY')
+ end
+
+ it 'recovers from a duplicate that slips past the pre-check' do
+ order = build(:order)
+ # Simulates another writer committing between the pre-check and the insert.
+ allow_any_instance_of(Spree::Order).to receive(:number_taken?).and_return(false)
+
+ generating(taken, 'R-AFTER-RACE') do
+ expect { order.save! }.to raise_error(ActiveRecord::RecordInvalid, /Number has already been taken/)
+ end
+ end
+
+ # With validation skipped the index is the only guard left, so this is the
+ # path a true concurrent commit takes.
+ it 'renumbers and saves when the index rejects the insert' do
+ order = build(:order)
+ allow_any_instance_of(Spree::Order).to receive(:number_taken?).and_return(false)
+
+ generating(taken, 'R-INDEX-RETRY') do
+ order.generate_number
+ order.save!(validate: false)
+ end
+
+ expect(order.reload.number).to eq('R-INDEX-RETRY')
+ end
+
+ it 'gives up when the renumber collides too' do
+ order = build(:order)
+ allow_any_instance_of(Spree::Order).to receive(:number_taken?).and_return(false)
+
+ generating(taken) do
+ order.generate_number
+ expect { order.save!(validate: false) }.to raise_error(ActiveRecord::RecordNotUnique)
+ end
+ end
+end
diff --git a/spree/core/spec/models/spree/concerns/has_number_spec.rb b/spree/core/spec/models/spree/concerns/has_number_spec.rb
new file mode 100644
index 0000000000..428a4641c7
--- /dev/null
+++ b/spree/core/spec/models/spree/concerns/has_number_spec.rb
@@ -0,0 +1,139 @@
+require 'spec_helper'
+
+RSpec.describe Spree::HasNumber do
+ after { Spree.number_generators.clear }
+
+ describe 'assigning a number' do
+ it 'numbers a record on create' do
+ order = create(:order)
+
+ expect(order.number).to be_present
+ end
+
+ it 'keeps a number supplied by the caller' do
+ order = create(:order, number: 'R-CUSTOM-1')
+
+ expect(order.number).to eq('R-CUSTOM-1')
+ end
+
+ it 'does not renumber on update' do
+ order = create(:order)
+
+ expect { order.update!(email: '[email protected]') }.not_to change(order, :number)
+ end
+ end
+
+ describe 'prefixes' do
+ it 'uses the model prefix for non-order documents' do
+ expect(create(:stock_transfer).number).to start_with('T')
+ end
+
+ it 'uses the store prefix for orders' do
+ stub_store_preferences(order_number_prefix: 'INV')
+
+ expect(create(:order).number).to start_with('INV')
+ end
+
+ it 'appends the store suffix for orders' do
+ stub_store_preferences(order_number_suffix: '-EU')
+
+ expect(create(:order).number).to end_with('-EU')
+ end
+ end
+
+ describe 'collisions' do
+ it 'skips a candidate that is already taken' do
+ taken = create(:order).number
+ generator = instance_double(Spree::NumberGenerators::Sequential)
+ allow(Spree::NumberGenerators::Sequential).to receive(:new).and_return(generator)
+ allow(generator).to receive(:generate).and_return(taken, 'R-FREE-1')
+
+ expect(create(:order).number).to eq('R-FREE-1')
+ end
+
+ it 'gives up rather than looping forever' do
+ taken = create(:order).number
+ generator = instance_double(Spree::NumberGenerators::Sequential)
+ allow(Spree::NumberGenerators::Sequential).to receive(:new).and_return(generator)
+ allow(generator).to receive(:generate) { taken }
+
+ expect { create(:order) }.to raise_error(Spree::HasNumber::GenerationError)
+ end
+ end
+
+ describe 'the registry' do
+ let(:custom_generator) do
+ Class.new(Spree::NumberGenerators::Base) do
+ def generate(record)
+ "CUSTOM-#{record.class.number_prefix}-1"
+ end
+ end
+ end
+
+ before { stub_const('MyApp::TestNumbers', custom_generator) }
+
+ it 'uses a registered generator for that resource' do
+ Spree.number_generators[:order] = 'MyApp::TestNumbers'
+
+ expect(create(:order).number).to eq('CUSTOM-R-1')
+ end
+
+ it 'leaves other resources on the store default' do
+ Spree.number_generators[:order] = 'MyApp::TestNumbers'
+
+ expect(create(:stock_transfer).number).not_to start_with('CUSTOM')
+ end
+
+ it 'falls back to the store format once the entry is removed' do
+ Spree.number_generators[:order] = 'MyApp::TestNumbers'
+ Spree.number_generators.delete(:order)
+
+ expect(create(:order).number).not_to start_with('CUSTOM')
+ end
+ end
+
+ describe 'availability on every model' do
+ it 'exposes the macro without a per-model include' do
+ expect(Spree::Product).to respond_to(:has_spree_number)
+ end
+
+ it 'leaves models that never call it alone' do
+ expect(Spree::Product.has_spree_number?).to be(false)
+ end
+
+ it 'reports models that opted in' do
+ expect(Spree::Order.has_spree_number?).to be(true)
+ end
+
+ it 'adds no numbering callback to models that never call it' do
+ callbacks = Spree::Product._validation_callbacks.map(&:filter)
+
+ expect(callbacks).not_to include(:generate_number)
+ end
+ end
+
+ describe 'when no store can be resolved' do
+ it 'names the missing store rather than blaming collisions' do
+ order = build(:order)
+ allow(order).to receive(:number_store).and_return(nil)
+
+ expect { order.generate_number }.
+ to raise_error(Spree::HasNumber::GenerationError, /no store to read numbering settings from/)
+ end
+ end
+
+ describe 'the store format preference' do
+ it 'generates sequential numbers by default' do
+ first = create(:order).number
+ second = create(:order).number
+
+ expect(second.sub(/\AR/, '').to_i).to eq(first.sub(/\AR/, '').to_i + 1)
+ end
+
+ it 'generates random numbers when the store opts in' do
+ stub_store_preferences(document_number_format: 'random')
+
+ expect(create(:order).number).to match(/\AR\d{9}\z/)
+ end
+ end
+end
diff --git a/spree/core/spec/models/spree/number_customization_scenarios_spec.rb b/spree/core/spec/models/spree/number_customization_scenarios_spec.rb
new file mode 100644
index 0000000000..872bc2a8a2
--- /dev/null
+++ b/spree/core/spec/models/spree/number_customization_scenarios_spec.rb
@@ -0,0 +1,125 @@
+require 'spec_helper'
+
+# The two customization paths a merchant or developer actually asks for. If
+# either of these breaks, the feature has not delivered what it promised.
+RSpec.describe 'document number customization scenarios' do
+ after { Spree.number_generators.clear }
+
+ describe 'a merchant starting their sequence at a chosen number' do
+ it 'issues the first order at the configured start' do
+ stub_store_preferences(order_number_sequence_start: 10_001)
+
+ expect(create(:order).number).to eq('R10001')
+ end
+
+ it 'counts up from there' do
+ stub_store_preferences(order_number_sequence_start: 10_001)
+
+ numbers = 3.times.map { create(:order).number }
+
+ expect(numbers).to eq(%w[R10001 R10002 R10003])
+ end
+
+ it 'keeps counting when the start is raised afterwards' do
+ stub_store_preferences(order_number_sequence_start: 10_001)
+ create(:order)
+
+ stub_store_preferences(order_number_sequence_start: 90_000)
+
+ expect(create(:order).number).to eq('R10002')
+ end
+
+ it 'combines the start with a custom prefix and suffix' do
+ stub_store_preferences(
+ order_number_sequence_start: 5001,
+ order_number_prefix: 'INV',
+ order_number_suffix: '-EU'
+ )
+
+ expect(create(:order).number).to eq('INV5001-EU')
+ end
+ end
+
+ describe 'a developer registering a custom generator' do
+ let(:year_scoped_generator) do
+ Class.new(Spree::NumberGenerators::Base) do
+ def generate(record)
+ sequence = Spree::NumberSequence.next_value(
+ store: record.number_store,
+ resource_type: record.number_key.to_s,
+ start_at: 1
+ )
+
+ "#{prefix_for(record)}-2026-#{sequence.to_s.rjust(5, '0')}"
+ end
+ end
+ end
+
+ before { stub_const('MyApp::YearScopedNumbers', year_scoped_generator) }
+
+ it 'produces numbers in the registered format' do
+ Spree.number_generators[:order] = 'MyApp::YearScopedNumbers'
+
+ expect(create(:order).number).to eq('R-2026-00001')
+ end
+
+ it 'honours the merchant prefix through prefix_for' do
+ Spree.number_generators[:order] = 'MyApp::YearScopedNumbers'
+ stub_store_preferences(order_number_prefix: 'ACME')
+
+ expect(create(:order).number).to eq('ACME-2026-00001')
+ end
+
+ it 'overrides the store format switch' do
+ Spree.number_generators[:order] = 'MyApp::YearScopedNumbers'
+ stub_store_preferences(document_number_format: 'random')
+
+ expect(create(:order).number).to eq('R-2026-00001')
+ end
+
+ it 'leaves other document types on the store default' do
+ Spree.number_generators[:order] = 'MyApp::YearScopedNumbers'
+
+ expect(create(:stock_transfer).number).to start_with('T')
+ end
+
+ it 'can be registered for several document types, each on its own counter' do
+ Spree.number_generators[:order] = 'MyApp::YearScopedNumbers'
+ Spree.number_generators[:stock_transfer] = 'MyApp::YearScopedNumbers'
+ create(:order)
+
+ # 00001, not 00002 — the transfer does not share the order counter.
+ expect(create(:stock_transfer).number).to eq('T-2026-00001')
+ end
+ end
+
+ describe 'the starting value is an order setting only' do
+ it 'does not leak into other document types' do
+ stub_store_preferences(order_number_sequence_start: 5001)
+
+ expect(create(:order).number).to eq('R5001')
+ expect(create(:stock_transfer).number).to eq('T1001')
+ end
+ end
+
+ describe 'two stores with identical formats' do
+ it 'jumps a new store past numbers the first store already owns' do
+ 5.times { create(:order) } # default store: R1001..R1005
+
+ other_store = create(:store)
+ order = create(:order, store: other_store)
+
+ expect(order.number).to eq('R1006')
+ end
+
+ it 'continues the new store from its own counter afterwards' do
+ 3.times { create(:order) } # R1001..R1003
+
+ other_store = create(:store)
+ first = create(:order, store: other_store) # jumps to R1004
+ second = create(:order, store: other_store)
+
+ expect([first.number, second.number]).to eq(%w[R1004 R1005])
+ end
+ end
+end
diff --git a/spree/core/spec/models/spree/number_sequence_spec.rb b/spree/core/spec/models/spree/number_sequence_spec.rb
new file mode 100644
index 0000000000..9434a989f2
--- /dev/null
+++ b/spree/core/spec/models/spree/number_sequence_spec.rb
@@ -0,0 +1,77 @@
+require 'spec_helper'
+
+RSpec.describe Spree::NumberSequence do
+ let(:store) { @default_store }
+
+ describe '.next_value' do
+ it 'starts at the requested value' do
+ value = described_class.next_value(store: store, resource_type: 'order', start_at: 1001)
+
+ expect(value).to eq(1001)
+ end
+
+ it 'advances by one per call' do
+ 3.times.map { described_class.next_value(store: store, resource_type: 'order', start_at: 1) }.
+ then { |values| expect(values).to eq([1, 2, 3]) }
+ end
+
+ it 'counts each resource type separately' do
+ described_class.next_value(store: store, resource_type: 'order', start_at: 1)
+ described_class.next_value(store: store, resource_type: 'order', start_at: 1)
+
+ expect(described_class.next_value(store: store, resource_type: 'return', start_at: 1)).to eq(1)
+ end
+
+ it 'counts each store separately' do
+ other_store = create(:store)
+ described_class.next_value(store: store, resource_type: 'order', start_at: 1)
+
+ expect(described_class.next_value(store: other_store, resource_type: 'order', start_at: 1)).to eq(1)
+ end
+
+ it 'ignores a changed starting value once the counter exists' do
+ described_class.next_value(store: store, resource_type: 'order', start_at: 1)
+
+ expect(described_class.next_value(store: store, resource_type: 'order', start_at: 500)).to eq(2)
+ end
+
+ end
+
+ describe 'concurrency' do
+ # Transactional tests pin one shared connection, and a transaction never
+ # blocks on its own FOR UPDATE — threads interleave freely and the test
+ # both proves nothing and flakes. Real parallel connections need the
+ # transaction wrapper off, so this group creates and removes its own rows.
+ self.use_transactional_tests = false
+
+ let!(:concurrent_store) { create(:store) }
+
+ after do
+ described_class.where(store: concurrent_store).delete_all
+ concurrent_store.really_destroy!
+ end
+
+ it 'never hands out the same value twice' do
+ values = Concurrent::Array.new
+
+ threads = 4.times.map do
+ Thread.new do
+ ActiveRecord::Base.connection_pool.with_connection do
+ values << described_class.next_value(store: concurrent_store, resource_type: 'order', start_at: 1)
+ end
+ end
+ end
+ threads.each(&:join)
+
+ expect(values.sort).to eq([1, 2, 3, 4])
+ end
+ end
+
+ describe 'uniqueness' do
+ it 'allows one row per store and resource type' do
+ create(:number_sequence, store: store, resource_type: 'order')
+
+ expect(build(:number_sequence, store: store, resource_type: 'order')).not_to be_valid
+ end
+ end
+end
diff --git a/spree/core/spec/models/spree/payment/gateway_options_spec.rb b/spree/core/spec/models/spree/payment/gateway_options_spec.rb
index f9caf98342..ec04a61700 100644
--- a/spree/core/spec/models/spree/payment/gateway_options_spec.rb
+++ b/spree/core/spec/models/spree/payment/gateway_options_spec.rb
@@ -8,6 +8,7 @@ RSpec.describe Spree::Payment::GatewayOptions, type: :model do
Spree::Payment,
owner: order,
number: 'P1566',
+ prefixed_id: 'py_k5nR8xLq',
currency: 'EUR',
payment_method: payment_method
)
@@ -89,13 +90,18 @@ RSpec.describe Spree::Payment::GatewayOptions, type: :model do
describe '#order_id' do
subject { options.order_id }
- it { is_expected.to eq 'R1444-P1566' }
+ # The payment number already names its order, so this is no longer the
+ # order number and the payment number concatenated.
+ it { is_expected.to eq 'P1566' }
end
describe '#idempotency_key' do
subject { options.idempotency_key }
- it { is_expected.to eq 'spree-P1566' }
+ # The prefixed ID, not the number — a derived number can shift if an
+ # earlier sibling payment is destroyed, and a shifted key could collide
+ # with one already used at the gateway.
+ it { is_expected.to eq 'spree-py_k5nR8xLq' }
end
describe '#shipping' do
@@ -149,9 +155,9 @@ RSpec.describe Spree::Payment::GatewayOptions, type: :model do
customer: '[email protected]',
customer_id: 144,
ip: '0.0.0.0',
- order_id: 'R1444-P1566',
+ order_id: 'P1566',
payment_id: 'P1566',
- idempotency_key: 'spree-P1566',
+ idempotency_key: 'spree-py_k5nR8xLq',
shipping: '1244'.to_d,
tax: '153'.to_d,
subtotal: '1511'.to_d,
diff --git a/spree/core/spec/models/spree/shipment_spec.rb b/spree/core/spec/models/spree/shipment_spec.rb
index 81d197f21e..49c07ebbad 100644
--- a/spree/core/spec/models/spree/shipment_spec.rb
+++ b/spree/core/spec/models/spree/shipment_spec.rb
@@ -102,10 +102,8 @@ describe Spree::Shipment, type: :model do
allow(order).to receive :recalculate_totals!
end
- it 'generates a number containing a letter + 11 numbers' do
- expect(shipment.number[0]).to eq('F')
- expect(/\d{11}/.match(shipment.number)).not_to be_nil
- expect(shipment.number.length).to eq(12)
+ it 'derives the number from the order it belongs to' do
+ expect(shipment.number).to eq("#{shipment.order.number}-F1")
end
end
diff --git a/spree/core/spec/models/spree/store_spec.rb b/spree/core/spec/models/spree/store_spec.rb
index f419406deb..20352a84df 100644
--- a/spree/core/spec/models/spree/store_spec.rb
+++ b/spree/core/spec/models/spree/store_spec.rb
@@ -5,6 +5,31 @@ describe Spree::Store, type: :model, without_global_store: true do
Spree::Country.find_by(iso: 'US') || create(:country_us)
end
+ describe 'order number sequence start' do
+ let(:store) { create(:store) }
+
+ it 'can change while no number has been issued' do
+ store.preferred_order_number_sequence_start = 10_001
+
+ expect(store).to be_valid
+ end
+
+ it 'locks once the counter has issued a number' do
+ Spree::NumberSequence.next_value(store: store, resource_type: 'order')
+ store.preferred_order_number_sequence_start = 10_001
+
+ expect(store).not_to be_valid
+ expect(store.errors[:preferred_order_number_sequence_start]).to be_present
+ end
+
+ it 'accepts a save that does not change the start after numbering began' do
+ Spree::NumberSequence.next_value(store: store, resource_type: 'order')
+ store.name = 'Renamed'
+
+ expect(store).to be_valid
+ end
+ end
+
context 'Associations' do
subject { create(:store) }