Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Add ability for merchants to customize order number format (#14430)
Damian Legawiec9a4eb466c269
diff --git a/.changeset/document-number-customization.md b/.changeset/document-number-customization.mdnew file mode 100644index 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.mdindex 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.jsonindex 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.mdnew file mode 100644index 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 referencesdiff --git a/docs/plans/6.0-inventory-operations.md b/docs/plans/6.0-inventory-operations.mdindex 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```rubyclass Spree::StockTransfer < Spree.base_classhas_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::NumberIdentifierinclude Spree::Metafieldsinclude Spree::Metadata@@ -179,7 +181,7 @@ end```rubyclass Spree::PurchaseOrder < Spree.base_classhas_prefix_id :po- include Spree::Core::NumberGenerator.new(prefix: 'PO')+ has_spree_number prefix: 'PO' # see 6.0-document-numbers.mdinclude Spree::NumberIdentifierinclude Spree::SingleStoreResourceinclude Spree::Metafieldsdiff --git a/docs/plans/decisions.md b/docs/plans/decisions.mdindex 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 adminEvery v3 API request resolved to `Spree::Store.default`: the configured finderdiff --git a/docs/v6/developer/core-concepts/orders.mdx b/docs/v6/developer/core-concepts/orders.mdxindex 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.mdxnew file mode 100644index 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.tsindex 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.tsindex 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.jsonindex 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.jsonindex 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.jsonindex 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.jsonindex 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.jsonindex 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.jsonindex 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.tsxindex 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.tsindex 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.rbindex 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.rbindex 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 Spreepreferred_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 itsdiff --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.rbindex 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 doendend+ 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' dolet(:params) do{diff --git a/spree/core/app/models/concerns/spree/derived_number.rb b/spree/core/app/models/concerns/spree/derived_number.rbnew file mode 100644index 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+enddiff --git a/spree/core/app/models/concerns/spree/has_number.rb b/spree/core/app/models/concerns/spree/has_number.rbnew file mode 100644index 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+enddiff --git a/spree/core/app/models/spree/base.rb b/spree/core/app/models/spree/base.rbindex 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 < ApplicationRecordinclude Spree::IntegrationsConcerninclude Spree::Publishableinclude Spree::PrefixedId+ include Spree::HasNumberinclude Spree::TypedAssociationsafter_initialize dodiff --git a/spree/core/app/models/spree/claim.rb b/spree/core/app/models/spree/claim.rbindex 45273f8d66..1625bab50b 100644--- a/spree/core/app/models/spree/claim.rb+++ b/spree/core/app/models/spree/claim.rb@@ -9,7 +9,7 @@ module Spreeclass Claim < Spree.base_classhas_prefix_id :claim- include Spree::Core::NumberGenerator.new(prefix: 'CLM', length: 9)+ has_spree_number prefix: 'CLM'include Spree::NumberIdentifierinclude Spree::SingleStoreResourceinclude Spree::HasStatusdiff --git a/spree/core/app/models/spree/exchange.rb b/spree/core/app/models/spree/exchange.rbindex acb6a0e6a9..cc5b314246 100644--- a/spree/core/app/models/spree/exchange.rb+++ b/spree/core/app/models/spree/exchange.rb@@ -10,7 +10,7 @@ module Spreeclass Exchange < Spree.base_classhas_prefix_id :exch- include Spree::Core::NumberGenerator.new(prefix: 'EX', length: 9)+ has_spree_number prefix: 'EX'include Spree::NumberIdentifierinclude Spree::SingleStoreResourceinclude Spree::HasStatusdiff --git a/spree/core/app/models/spree/export.rb b/spree/core/app/models/spree/export.rbindex bb5114fd90..022d2a5b79 100644--- a/spree/core/app/models/spree/export.rb+++ b/spree/core/app/models/spree/export.rb@@ -10,7 +10,7 @@ module Spreeinclude Spree::NumberIdentifierinclude Spree::VendorConcern if defined?(Spree::VendorConcern)- include Spree::Core::NumberGenerator.new(prefix: 'EF')+ has_spree_number prefix: 'EF'publishes_lifecycle_eventsdiff --git a/spree/core/app/models/spree/fulfillment.rb b/spree/core/app/models/spree/fulfillment.rbindex 421d08bda3..19ffad264e 100644--- a/spree/core/app/models/spree/fulfillment.rb+++ b/spree/core/app/models/spree/fulfillment.rb@@ -4,8 +4,8 @@ module Spreeclass Fulfillment < Spree.base_classhas_prefix_id :ful- include Spree::Core::NumberGenerator.new(prefix: 'F', length: 11)- include Spree::NumberIdentifier+ include Spree::DerivedNumber+ derives_number infix: 'F'include Spree::HasCustomFieldsinclude Spree::Metadatainclude Spree::StorePreferencesdiff --git a/spree/core/app/models/spree/import.rb b/spree/core/app/models/spree/import.rbindex 7de607691a..dbf7f541c4 100644--- a/spree/core/app/models/spree/import.rb+++ b/spree/core/app/models/spree/import.rb@@ -5,7 +5,7 @@ module Spreehas_prefix_id :impinclude 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.rbnew file mode 100644index 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+enddiff --git a/spree/core/app/models/spree/number_generators/random.rb b/spree/core/app/models/spree/number_generators/random.rbnew file mode 100644index 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+enddiff --git a/spree/core/app/models/spree/number_generators/sequential.rb b/spree/core/app/models/spree/number_generators/sequential.rbnew file mode 100644index 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+enddiff --git a/spree/core/app/models/spree/number_sequence.rb b/spree/core/app/models/spree/number_sequence.rbnew file mode 100644index 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+enddiff --git a/spree/core/app/models/spree/order.rb b/spree/core/app/models/spree/order.rbindex 470054e1d7..8b53702693 100644--- a/spree/core/app/models/spree/order.rb+++ b/spree/core/app/models/spree/order.rb@@ -38,7 +38,7 @@ module Spreeinclude Spree::Purchase::Validationsinclude Spree::Purchase::Totalsinclude Spree::Purchase::Lifecycle- include Spree::Core::NumberGenerator.new(prefix: 'R')+ has_spree_number prefix: 'R'include Spree::NumberIdentifierdiff --git a/spree/core/app/models/spree/payment.rb b/spree/core/app/models/spree/payment.rbindex 70a72ae50a..42046c0998 100644--- a/spree/core/app/models/spree/payment.rb+++ b/spree/core/app/models/spree/payment.rb@@ -4,8 +4,8 @@ module Spreeclass Payment < Spree.base_classhas_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::HasCustomFieldsinclude Spree::Metadataif 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.rbindex 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 Spreeorder.last_ip_addressend+ # 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.numberenddef payment_idpayment.numberend+ # 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}"enddef shippingdiff --git a/spree/core/app/models/spree/return.rb b/spree/core/app/models/spree/return.rbindex 7bffc02c77..e770efe5c0 100644--- a/spree/core/app/models/spree/return.rb+++ b/spree/core/app/models/spree/return.rb@@ -13,7 +13,7 @@ module Spreeclass Return < Spree.base_classhas_prefix_id :ret- include Spree::Core::NumberGenerator.new(prefix: 'RET', length: 9)+ has_spree_number prefix: 'RET'include Spree::NumberIdentifierinclude Spree::SingleStoreResourceinclude Spree::HasStatusdiff --git a/spree/core/app/models/spree/stock_transfer.rb b/spree/core/app/models/spree/stock_transfer.rbindex 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 Spreeclass StockTransfer < Spree.base_classhas_prefix_id :st- include Spree::Core::NumberGenerator.new(prefix: 'T')+ has_spree_number prefix: 'T'include Spree::NumberIdentifierinclude Spree::HasCustomFieldsinclude Spree::Metadata@@ -24,6 +24,15 @@ module Spreevalidate :stock_movements_not_emptyvalidates :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_movementsfind_stock_location_with_location_id(source_location_id)enddiff --git a/spree/core/app/models/spree/store.rb b/spree/core/app/models/spree/store.rbindex 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 Spreevalidates :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: :updatevalidates :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 Spreeerrors.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)+ endendenddiff --git a/spree/core/app/services/spree/sample_data/import_builder.rb b/spree/core/app/services/spree/sample_data/import_builder.rbindex 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 = inlineimport.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_numberimport.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.ymlindex 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 startednot_a_number: is not a numbernot_found: not foundnot_locked: was not lockeddiff --git a/spree/core/db/migrate/20260813000001_create_spree_number_sequences.rb b/spree/core/db/migrate/20260813000001_create_spree_number_sequences.rbnew file mode 100644index 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+enddiff --git a/spree/core/db/sample_data/orders.rb b/spree/core/db/sample_data/orders.rbindex 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',email: '[email protected]',currency: 'USD').first_or_create! do |order|@@ -49,7 +52,7 @@ orders << store.orders.where(endorders << store.orders.where(- number: 'R987654321',+ number: 'R1002',email: '[email protected]',currency: 'USD').first_or_create! do |order|diff --git a/spree/core/lib/spree/core.rb b/spree/core/lib/spree/core.rbindex 40bbdf30b8..ceefc8e6b8 100644--- a/spree/core/lib/spree/core.rb+++ b/spree/core/lib/spree/core.rb@@ -472,6 +472,17 @@ module SpreeRails.application.config.spree.integrations = valueend+ # 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 @@ endrequire '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.rbindex 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 Spreeinitializer '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|enddiff --git a/spree/core/lib/spree/core/number_generator.rb b/spree/core/lib/spree/core/number_generator.rbindex 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 Spreemodule 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 = 10DEFAULT_LENGTH = 9attr_accessor :prefix, :lengthdef 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.'+ )enddef included(host)- generator_instance = self+ prefix = @prefixhost.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: prefixendend-- 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+enddiff --git a/spree/core/lib/spree/number_generators/registry.rb b/spree/core/lib/spree/number_generators/registry.rbnew file mode 100644index 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+enddiff --git a/spree/core/lib/spree/testing_support/factories/number_sequence_factory.rb b/spree/core/lib/spree/testing_support/factories/number_sequence_factory.rbnew file mode 100644index 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+enddiff --git a/spree/core/lib/tasks/migrate_returns.rake b/spree/core/lib/tasks/migrate_returns.rakeindex 5ad27ff4f3..8e8b18eee7 100644--- a/spree/core/lib/tasks/migrate_returns.rake+++ b/spree/core/lib/tasks/migrate_returns.rake@@ -171,7 +171,7 @@ module Spreecreated_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 Spreeif authorization.number.present?record.number = authorization.numberelse- 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 })enddiff --git a/spree/core/spec/lib/spree/core/number_generator_spec.rb b/spree/core/spec/lib/spree/core/number_generator_spec.rbindex 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')endend- 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_storeend- 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')endenddiff --git a/spree/core/spec/models/spree/concerns/derived_number_spec.rb b/spree/core/spec/models/spree/concerns/derived_number_spec.rbnew file mode 100644index 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+enddiff --git a/spree/core/spec/models/spree/concerns/has_number_race_spec.rb b/spree/core/spec/models/spree/concerns/has_number_race_spec.rbnew file mode 100644index 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+enddiff --git a/spree/core/spec/models/spree/concerns/has_number_spec.rb b/spree/core/spec/models/spree/concerns/has_number_spec.rbnew file mode 100644index 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+enddiff --git a/spree/core/spec/models/spree/number_customization_scenarios_spec.rb b/spree/core/spec/models/spree/number_customization_scenarios_spec.rbnew file mode 100644index 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+enddiff --git a/spree/core/spec/models/spree/number_sequence_spec.rb b/spree/core/spec/models/spree/number_sequence_spec.rbnew file mode 100644index 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+enddiff --git a/spree/core/spec/models/spree/payment/gateway_options_spec.rb b/spree/core/spec/models/spree/payment/gateway_options_spec.rbindex 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 doSpree::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 dodescribe '#order_id' dosubject { 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' }enddescribe '#idempotency_key' dosubject { 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' }enddescribe '#shipping' do@@ -149,9 +155,9 @@ RSpec.describe Spree::Payment::GatewayOptions, type: :model docustomer: '[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.rbindex 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 doallow(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")endenddiff --git a/spree/core/spec/models/spree/store_spec.rb b/spree/core/spec/models/spree/store_spec.rbindex 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 doSpree::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' dosubject { create(:store) }