Skip to content

armgit / spree

Public Imported from GitHub
0

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

Order cancellation graduates to the workflow tier

Damian Legawiece417181498b8
diff --git a/CLAUDE.md b/CLAUDE.md
index 570335c0c0..4427e0412d 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -31,7 +31,7 @@ Active plans (6.0 target, work pending):
- `6.0-inventory-operations.md` — StockTransfer lifecycle (draft → ready_to_ship → in_transit → received with partial receive), new `Spree::PurchaseOrder` + `Spree::Supplier` (renamed from Vendor — `Spree::Vendor` is the marketplace seller, see decisions.md 2026-07-14) replacing today's "external receive" hack, variant + stock-location stock history panels. Consumes the typed-movement primitives from `6.0-typed-stock-movements.md`.
- `6.0-replace-taxons-with-categories.md` — Split Taxon into Category (hierarchy) + Collection (flat/rule-based). **Shipped to 6-0-dev (PR #14302):** the Category surface (5.5–5.6) plus the 6.0 core — `spree_taxons`→`spree_categories` table rename + inheritance flip (`Spree::Category < Spree.base_class`, `Spree::Taxon` alias kept), the full `Collection` stack (model + rules + DB/Meilisearch manual sort + API), the taxon→category/collection data migration, and de-ruling Category. Pending (all 6.1): channel-aware `CollectionRules::AvailableOn` (ships interim now, rides with channels) + dropping `spree_taxon_rules`/`Taxonomy`. No brand feature in 6.0 — brands are modeled as a Category/Collection; `brand_taxon`/`brand_name` removed with `Taxonomy`.
- `6.0-delivery-method-rules.md` — `Spree::DeliveryMethodRule` STI on DeliveryMethod (design finalized 2026-07-29): ItemTotal/Weight rules first (Channel/Market/CustomerGroup later in lockstep with payment-method-rules), enforced solely in `Stock::Estimator`'s method filter so calculator- AND provider-priced methods obey eligibility; replaces the FlatRate-only bound preferences (one-release bridge + data task). Phase 1 rides the 6.0 core-rewrite finishing work.
-- `6.0-service-workflows.md` — Two-tier services doctrine (2026-07-30). **Tier 1 `app/services/`:** plain `ServiceModule` classes, hand-written `def call(cart:, ...)`, Ruby kwargs as the contract — the permanent default; no DSL, no new `run`-pipelines, no hand-rolled sagas. **Tier 2 `app/workflows/`:** `Spree::Workflow` step DSL (`argument` typed contracts, `provides:`, `transaction`/`external_step`, `on_flow_failure:`, `rescue_from`, `run_hooks` + `Spree.hooks`, `emit`, bare argument readers), reserved for flows needing hooks, compensation/external I/O, replay, or durability — currently `Carts::Complete`, `Carts::AddItem`, `Carts::Recalculate`, `Carts::RecalculateTotals` (+ order twins). A service graduates to the workflow tier when it earns a hook, never speculatively. `Carts::Complete` battery must pass unmodified. **Durability = plain Rails:** long-running background work uses `ActiveJob::Continuable` directly (reference: `Spree::Imports::ProcessJob` — CSV spine with a row-number cursor; `CreateRowsJob`/`ProcessRowsJob` deprecated shells); workflows are synchronous request-cycle flows and are NOT jobs — Workflow-level durable execution ships only if the payout run proves the need.
+- `6.0-service-workflows.md` — Two-tier services doctrine (2026-07-30). **Tier 1 `app/services/`:** plain `ServiceModule` classes, hand-written `def call(cart:, ...)`, Ruby kwargs as the contract — the permanent default; no DSL, no new `run`-pipelines, no hand-rolled sagas. **Tier 2 `app/workflows/`:** `Spree::Workflow` step DSL (`argument` typed contracts, `provides:`, `transaction`/`external_step`, `on_flow_failure:`, `rescue_from`, `run_hooks` + `Spree.hooks`, `emit`, bare argument readers), reserved for flows needing hooks, compensation/external I/O, replay, or durability — currently `Carts::Complete`, `Carts::AddItem`, `Carts::Recalculate`, `Carts::RecalculateTotals` (+ order twins) and `Orders::Cancel` (absorbed `Order#after_cancel`; gateway settlement is an external_step). A service graduates to the workflow tier when it earns a hook, never speculatively. Workflow Dependencies seams use `*_workflow` keys; legacy `*_service` names stay settable/readable with warnings until 6.1 but writes are stashed, never applied (old service classes aren't workflow-contract compatible). `Carts::Complete` battery must pass unmodified. **Durability = plain Rails:** long-running background work uses `ActiveJob::Continuable` directly (reference: `Spree::Imports::ProcessJob` — CSV spine with a row-number cursor; `CreateRowsJob`/`ProcessRowsJob` deprecated shells); workflows are synchronous request-cycle flows and are NOT jobs — Workflow-level durable execution ships only if the payout run proves the need.
- `6.0-store-scoped-custom-field-definitions.md` — Add `store_id` + persisted `filter_key` to `Spree::MetafieldDefinition` (today global and computed), making uniqueness `(store_id, resource_type, filter_key)` with a DB index. Deferred from the 5.6 custom-field search/sort/filter work (schema change, not patch-safe). **Until then:** `filter_key` is a computed method — no Ransack predicates or `where`/`order` against it; definitions are global; uniqueness rests on a `CONCAT` validation with no index behind it.
Multi-version plans (some phases shipped, some pending):
diff --git a/docs/plans/6.0-service-workflows.md b/docs/plans/6.0-service-workflows.md
index b7c9fd23d7..d310b14eec 100644
--- a/docs/plans/6.0-service-workflows.md
+++ b/docs/plans/6.0-service-workflows.md
@@ -4,7 +4,7 @@
**Target:** Spree 6.0
**Depends on:** `6.0-cart-order-split.md` (Carts::Complete is the reference implementation and stress test). Coordinates with: `6.0-multi-vendor-marketplace.md` (payout runs are the first durable-flow consumer), the Rails 8.1 floor decision (decisions.md 2026-07-29 — ActiveJob Continuations are the durability primitive).
**Author:** Damian Legawiec + Claude (design session 2026-07-30)
-**Last updated:** 2026-07-30
+**Last updated:** 2026-07-31
## Summary
@@ -52,7 +52,24 @@ green and its observable semantics byte-identical.
replay/halt semantics, or a durable future. Initial set:
`Carts::Complete`, `Carts::AddItem`, `Carts::Recalculate`,
`Carts::RecalculateTotals` (+ order twins); a service graduates to the
- workflow tier the moment it earns a hook — never speculatively.
+ workflow tier the moment it earns a hook — never speculatively. First
+ graduation (2026-07-31): `Orders::Cancel`, absorbing the orchestration
+ buried in `Order#after_cancel` — the cancellation record, status flip
+ and fulfillment cancellation commit atomically with the `after_cancel`
+ hook inside the transaction, while payment settlement (gateway voids
+ and refunds, previously running inside the DB transaction) moved to an
+ `external_step` after commit. Workflow-backed `Spree::Dependencies`
+ seams are named `*_workflow` (`order_cancel_workflow`,
+ `cart_add_item_workflow`, `cart_recalculate_workflow`,
+ `carts_complete_workflow`, `cart/order_recalculate_totals_workflow`);
+ the legacy `*_service` names stay settable and readable one release
+ (reads, writes and top-level `Spree.*` resolution — no boot crashes),
+ but a legacy write is stashed, NOT applied: a class written against
+ the old service contract is not interchangeable with the workflow the
+ new call sites consume, so the warning says the override was not
+ applied and names the `*_workflow` seam to port to. Legacy reads fall
+ back to the workflow class, which accepts the old keyword vocabulary
+ through its `alias_argument` bridges. Removed in 6.1.
`Callable.call`, `Result`, `success`/`failure` stay the shared caller
contract across both tiers — callers cannot tell them apart.
2. **No engine.** No execution-state tables, no visualizer, no parallel
@@ -268,9 +285,10 @@ never hand-written (Typelizer philosophy, applied to Ruby):
along the way (`OrderUpdater#update` dissolved into
`RecalculateTotals`, single status writer, `use_shipping` fix).
Acceptance held throughout: batteries green unmodified.
-3. **Phase 1c — first hooks — shipped:** `after_item_added` (AddItem) and
- `before_finalize` (Complete) registered-hook seams. These two only; more
- hooks are added by demand, not speculation. Extension-facing docs pending.
+3. **Phase 1c — hooks — shipped:** `after_item_added` (AddItem),
+ `before_finalize` (Complete) and `after_cancel` (Orders::Cancel,
+ in-transaction) registered-hook seams. These three only; more hooks
+ are added by demand, not speculation. Extension-facing docs pending.
4. **Rolling adoption:** services migrate when meaningfully touched — never a
big-bang sweep. `ServiceModule::Base` is not deprecated in 6.0.
5. **Phase 2 — resolved:** plain `ActiveJob::Continuable` jobs are the
diff --git a/spree/api/app/controllers/spree/api/v3/store/carts/items_controller.rb b/spree/api/app/controllers/spree/api/v3/store/carts/items_controller.rb
index c23afa96ac..f8a9de3f32 100644
--- a/spree/api/app/controllers/spree/api/v3/store/carts/items_controller.rb
+++ b/spree/api/app/controllers/spree/api/v3/store/carts/items_controller.rb
@@ -12,7 +12,7 @@ module Spree
# POST /api/v3/store/carts/:cart_id/items
def create
with_order_lock do
- result = Spree.cart_add_item_service.call(
+ result = Spree.cart_add_item_workflow.call(
cart: @cart,
variant: variant,
quantity: permitted_params[:quantity] || 1,
diff --git a/spree/api/app/controllers/spree/api/v3/store/carts_controller.rb b/spree/api/app/controllers/spree/api/v3/store/carts_controller.rb
index c785b14309..9ada01bbe4 100644
--- a/spree/api/app/controllers/spree/api/v3/store/carts_controller.rb
+++ b/spree/api/app/controllers/spree/api/v3/store/carts_controller.rb
@@ -113,7 +113,7 @@ module Spree
return render_authentication_required('api.errors.guest_checkout_not_allowed', 'You must be signed in to complete checkout')
end
- result = Spree::Dependencies.carts_complete_service.constantize.call(cart: @cart)
+ result = Spree::Dependencies.carts_complete_workflow.constantize.call(cart: @cart)
if result.success?
@cart = result.value
diff --git a/spree/core/app/jobs/spree/orders/finalize_stale_drafts_job.rb b/spree/core/app/jobs/spree/orders/finalize_stale_drafts_job.rb
index c05f085580..4bc7a86781 100644
--- a/spree/core/app/jobs/spree/orders/finalize_stale_drafts_job.rb
+++ b/spree/core/app/jobs/spree/orders/finalize_stale_drafts_job.rb
@@ -18,7 +18,7 @@ module Spree
cart = order.cart
next if cart.nil? || cart.completed?
- result = Spree::Dependencies.carts_complete_service.constantize.call(cart: cart)
+ result = Spree::Dependencies.carts_complete_workflow.constantize.call(cart: cart)
Rails.logger.error("[Spree] Completion recovery failed for order #{order.number}: #{result.error&.value}") if result.failure?
rescue StandardError => e
Rails.logger.error("[Spree] Completion recovery raised for order #{order.number}: #{e.message}")
diff --git a/spree/core/app/models/spree/cart.rb b/spree/core/app/models/spree/cart.rb
index 3a5a237729..05104479b3 100644
--- a/spree/core/app/models/spree/cart.rb
+++ b/spree/core/app/models/spree/cart.rb
@@ -204,7 +204,7 @@ module Spree
# and derived item counts. Convenience for
# {Spree::Carts::RecalculateTotals}.
def recalculate_totals!
- Spree::Carts::RecalculateTotals.call(cart: self)
+ Spree.cart_recalculate_totals_workflow.call(cart: self)
end
# @deprecated Use {#recalculate_totals!}; removed in 6.1.
diff --git a/spree/core/app/models/spree/order.rb b/spree/core/app/models/spree/order.rb
index d3e488e452..a0a9441bc3 100644
--- a/spree/core/app/models/spree/order.rb
+++ b/spree/core/app/models/spree/order.rb
@@ -543,7 +543,7 @@ module Spree
# and derived item counts. Convenience for
# {Spree::Orders::RecalculateTotals}.
def recalculate_totals!
- Spree::Orders::RecalculateTotals.call(order: self)
+ Spree.order_recalculate_totals_workflow.call(order: self)
end
# @deprecated Use {#recalculate_totals!}; removed in 6.1.
@@ -974,17 +974,15 @@ module Spree
# @param canceled_at [Time, nil] the time of cancellation (defaults to current time)
# @return [Spree::ServiceModule::Result]
def canceled_by(user, canceled_at = nil)
- Spree.order_cancel_service.call(order: self, canceler: user, canceled_at: canceled_at)
+ Spree.order_cancel_workflow.call(order: self, canceler: user, canceled_at: canceled_at)
end
- # Machine-free lifecycle: cancel/resume flip +status+ and run the same
- # side effects the machine transitions ran.
+ # Machine-free lifecycle: cancellation runs through the
+ # {Spree::Orders::Cancel} workflow (which also records a
+ # Spree::OrderCancellation row); resume flips +status+ back and runs
+ # the same side effects the machine transition ran.
def cancel
- return false unless allow_cancel?
-
- update_column(:canceled_at, Time.current) if canceled_at.blank?
- after_cancel
- true
+ Spree.order_cancel_workflow.call(order: self).success?
end
def cancel!
@@ -1190,25 +1188,6 @@ module Spree
end
end
- def after_cancel
- update_column(:status, 'canceled')
-
- fulfillments.each(&:cancel!)
-
- # payments fully covered by gift card won't be refunded
- # we want to only void the payment
- if gift_card.present? && covered_by_store_credit?
- payments.completed.store_credits.each(&:void!)
- else
- payments.completed.each(&:cancel!)
- payments.incomplete.not_store_credits.each(&:void_transaction!)
- payments.store_credits.pending.each(&:void!)
- end
-
- recalculate_totals!
- send_order_canceled_webhook
- end
-
def after_resume
update_column(:status, 'placed')
diff --git a/spree/core/app/models/spree/promotion/actions/create_line_items.rb b/spree/core/app/models/spree/promotion/actions/create_line_items.rb
index 748415a852..4832f95387 100644
--- a/spree/core/app/models/spree/promotion/actions/create_line_items.rb
+++ b/spree/core/app/models/spree/promotion/actions/create_line_items.rb
@@ -58,7 +58,7 @@ module Spree
current_quantity = order.quantity_of(item.variant)
next unless current_quantity < item.quantity && item_available?(item)
- add_service = order.is_a?(Spree::Cart) ? Spree.cart_add_item_service : Spree.order_add_item_service
+ add_service = order.is_a?(Spree::Cart) ? Spree.cart_add_item_workflow : Spree.order_add_item_service
line_item = add_service.call(**{ (order.is_a?(Spree::Cart) ? :cart : :order) => order },
variant: item.variant,
quantity: item.quantity - current_quantity).value
diff --git a/spree/core/app/services/spree/carts/remove_item.rb b/spree/core/app/services/spree/carts/remove_item.rb
index c66d55562d..8786025811 100644
--- a/spree/core/app/services/spree/carts/remove_item.rb
+++ b/spree/core/app/services/spree/carts/remove_item.rb
@@ -13,7 +13,7 @@ module Spree
ActiveRecord::Base.transaction do
line_item = remove_from_line_item(cart: cart, variant: variant, quantity: quantity, options: options)
- Spree.cart_recalculate_service.call(line_item: line_item,
+ Spree.cart_recalculate_workflow.call(line_item: line_item,
cart: cart,
options: options)
success(line_item)
diff --git a/spree/core/app/services/spree/carts/remove_line_item.rb b/spree/core/app/services/spree/carts/remove_line_item.rb
index d93cd781c0..742b0aca12 100644
--- a/spree/core/app/services/spree/carts/remove_line_item.rb
+++ b/spree/core/app/services/spree/carts/remove_line_item.rb
@@ -19,7 +19,7 @@ module Spree
raise Spree::StockReservations::InsufficientStockError.new(nil, result.error.to_s) if result.failure?
end
- Spree.cart_recalculate_service.new.call(cart: cart,
+ Spree.cart_recalculate_workflow.new.call(cart: cart,
line_item: line_item,
options: options)
end
diff --git a/spree/core/app/services/spree/carts/set_quantity.rb b/spree/core/app/services/spree/carts/set_quantity.rb
index 8fc7874e23..b8cc714193 100644
--- a/spree/core/app/services/spree/carts/set_quantity.rb
+++ b/spree/core/app/services/spree/carts/set_quantity.rb
@@ -12,7 +12,7 @@ module Spree
ActiveRecord::Base.transaction do
run :change_item_quantity
run :handle_stock_reservations
- run Spree.cart_recalculate_service
+ run Spree.cart_recalculate_workflow
end
end
diff --git a/spree/core/app/services/spree/checkout/complete.rb b/spree/core/app/services/spree/checkout/complete.rb
index 63bd822928..4644212bc0 100644
--- a/spree/core/app/services/spree/checkout/complete.rb
+++ b/spree/core/app/services/spree/checkout/complete.rb
@@ -6,7 +6,7 @@ module Spree
def call(order:)
Spree::Deprecation.warn('Spree::Checkout::Complete is deprecated and will be removed in Spree 6.1. Use Spree::Carts::Complete instead.')
- Spree::Dependencies.carts_complete_service.constantize.call(cart: order)
+ Spree::Dependencies.carts_complete_workflow.constantize.call(cart: order)
end
end
end
diff --git a/spree/core/app/services/spree/orders/cancel.rb b/spree/core/app/services/spree/orders/cancel.rb
deleted file mode 100644
index 696f4bb781..0000000000
--- a/spree/core/app/services/spree/orders/cancel.rb
+++ /dev/null
@@ -1,54 +0,0 @@
-module Spree
- module Orders
- class Cancel
- prepend Spree::ServiceModule::Base
-
- DEFAULT_REASON = 'other'.freeze
-
- # Cancels an order and records a Spree::OrderCancellation history record.
- # Legacy `canceler:` and `canceled_at:` remain valid; new keywords are additive.
- #
- # @param order [Spree::Order]
- # @param canceler [Object, nil] the user/admin who initiated the cancellation
- # @param canceled_at [Time, nil] timestamp (defaults to Time.current)
- # @param reason [String] one of Spree::OrderCancellation::REASONS
- # @param note [String, nil] staff-facing note
- # @param restock_items [Boolean] whether to return inventory
- # @param refund_payments [Boolean] whether to refund captured payments
- # @param refund_amount [BigDecimal, Numeric, nil] amount to refund;
- # when refund_payments is true and this is nil, defaults to order.payment_total
- # @param notify_customer [Boolean] hint for subscribers
- # @return [Spree::ServiceModule::Result]
- def call(order:, canceler: nil, canceled_at: nil,
- reason: DEFAULT_REASON, note: nil,
- restock_items: false, refund_payments: false, refund_amount: nil,
- notify_customer: false)
- canceled_at ||= Time.current
- refund_amount ||= order.payment_total if refund_payments
-
- order.transaction do
- order.cancellations.create!(
- reason: reason,
- note: note,
- restock_items: restock_items,
- refund_payments: refund_payments,
- refund_amount: refund_amount,
- notify_customer: notify_customer,
- canceled_by: canceler,
- created_at: canceled_at
- )
-
- changes = { canceled_at: canceled_at }
- changes[:canceler_id] = canceler.id if canceler.present?
- order.update_columns(changes)
- order.cancel!
- end
-
- order.publish_event('order.canceled', order.event_payload.merge(notify_customer: notify_customer))
- success(order.reload)
- rescue ActiveRecord::RecordInvalid, StateMachines::InvalidTransition
- failure(order)
- end
- end
- end
-end
diff --git a/spree/core/app/services/spree/orders/complete.rb b/spree/core/app/services/spree/orders/complete.rb
index 006d7e539b..e0d988ee50 100644
--- a/spree/core/app/services/spree/orders/complete.rb
+++ b/spree/core/app/services/spree/orders/complete.rb
@@ -17,7 +17,7 @@ module Spree
def call(order:, payment_pending: false, notify_customer: false)
order.notify_customer = notify_customer
- Spree::Dependencies.carts_complete_service.constantize.call(
+ Spree::Dependencies.carts_complete_workflow.constantize.call(
cart: order,
payment_pending: payment_pending
)
diff --git a/spree/core/app/services/spree/payments/handle_webhook.rb b/spree/core/app/services/spree/payments/handle_webhook.rb
index 53eb6d7fa9..94a90ff707 100644
--- a/spree/core/app/services/spree/payments/handle_webhook.rb
+++ b/spree/core/app/services/spree/payments/handle_webhook.rb
@@ -44,7 +44,7 @@ module Spree
unless order.reload.completed?
completable = order.is_a?(Spree::Order) ? (order.cart || order) : order
- Spree::Dependencies.carts_complete_service.constantize.call(cart: completable)
+ Spree::Dependencies.carts_complete_workflow.constantize.call(cart: completable)
end
end
diff --git a/spree/core/app/workflows/spree/carts/add_item.rb b/spree/core/app/workflows/spree/carts/add_item.rb
index 30e753fff1..850411c730 100644
--- a/spree/core/app/workflows/spree/carts/add_item.rb
+++ b/spree/core/app/workflows/spree/carts/add_item.rb
@@ -14,7 +14,7 @@ module Spree
transaction do
step :add_to_line_item, provides: [:line_item, :line_item_created]
step :handle_stock_reservations, if: -> { cart.in_checkout? }
- step :recalculate, with: -> { Spree.cart_recalculate_service }
+ step :recalculate, with: -> { Spree.cart_recalculate_workflow }
run_hooks :after_item_added
end
diff --git a/spree/core/app/workflows/spree/carts/recalculate.rb b/spree/core/app/workflows/spree/carts/recalculate.rb
index 42a61c6e8b..1322387e4a 100644
--- a/spree/core/app/workflows/spree/carts/recalculate.rb
+++ b/spree/core/app/workflows/spree/carts/recalculate.rb
@@ -13,7 +13,7 @@ module Spree
step :rebuild_delivery_proposals
step :activate_promotions
# Typed rows (discounts + tax) are rebuilt by the full recalculation.
- step :final_recalculation, with: -> { Spree::Carts::RecalculateTotals }
+ step :final_recalculation, with: -> { Spree.cart_recalculate_totals_workflow }
private
diff --git a/spree/core/app/workflows/spree/orders/cancel.rb b/spree/core/app/workflows/spree/orders/cancel.rb
new file mode 100644
index 0000000000..b0709ff804
--- /dev/null
+++ b/spree/core/app/workflows/spree/orders/cancel.rb
@@ -0,0 +1,103 @@
+module Spree
+ module Orders
+ # Cancels an order — the orchestration that used to hide inside
+ # Order#after_cancel, as declared steps: the cancellation record, the
+ # status flip and fulfillment cancellation commit atomically (with the
+ # after_cancel hook inside the transaction), then payment settlement
+ # runs as external I/O — voids and refunds are gateway calls and must
+ # never share a database transaction — followed by money and status
+ # recomputation and the order.canceled event after commit.
+ #
+ # Legacy `canceler:` and `canceled_at:` remain valid; new keywords are
+ # additive and stored on the Spree::OrderCancellation record.
+ class Cancel < Spree::Workflow
+ DEFAULT_REASON = 'other'.freeze
+
+ argument :order, Spree::Order
+ argument :canceler, default: nil
+ argument :canceled_at, default: nil
+ argument :reason, String, default: DEFAULT_REASON
+ argument :note, default: nil
+ argument :restock_items, :boolean, default: false
+ argument :refund_payments, :boolean, default: false
+ argument :refund_amount, default: nil
+ argument :notify_customer, :boolean, default: false
+ returns -> { order.reload }
+
+ rescue_from ActiveRecord::RecordInvalid, StateMachines::InvalidTransition do |_error|
+ failure(order)
+ end
+
+ step :ensure_cancellable
+ step :normalize, provides: [:decided_at, :amount_to_refund]
+ transaction do
+ step :record_cancellation, provides: [:cancellation]
+ step :mark_canceled
+ step :cancel_fulfillments
+ run_hooks :after_cancel
+ end
+ external_step :settle_payments
+ step :recalculate_totals, with: -> { Spree::Orders::RecalculateTotals }
+ step :recompute_statuses, with: -> { Spree::Orders::RecomputeStatuses }
+ step :send_legacy_webhook
+ emit 'order.canceled', payload: -> { order.event_payload.merge(notify_customer: notify_customer) }
+
+ private
+
+ def ensure_cancellable
+ failure(order) unless order.allow_cancel?
+ end
+
+ def normalize
+ amount = refund_amount
+ amount ||= order.payment_total if refund_payments
+ { decided_at: canceled_at || Time.current, amount_to_refund: amount }
+ end
+
+ def record_cancellation
+ {
+ cancellation: order.cancellations.create!(
+ reason: reason,
+ note: note,
+ restock_items: restock_items,
+ refund_payments: refund_payments,
+ refund_amount: amount_to_refund,
+ notify_customer: notify_customer,
+ canceled_by: canceler,
+ created_at: decided_at
+ )
+ }
+ end
+
+ def mark_canceled
+ changes = { status: 'canceled', canceled_at: decided_at }
+ changes[:canceler_id] = canceler.id if canceler.present?
+ order.update_columns(changes)
+ end
+
+ # Canceling a fulfillment restocks its inventory (Spree::Fulfillment's
+ # own cancel semantics); allow_cancel? already excluded orders with
+ # shipped fulfillments.
+ def cancel_fulfillments
+ order.fulfillments.each(&:cancel!)
+ end
+
+ # Gateway I/O. Payments fully covered by a gift card are only voided,
+ # never refunded; everything else cancels captured payments (void or
+ # refund at the gateway's discretion) and voids what never completed.
+ def settle_payments
+ if order.gift_card.present? && order.covered_by_store_credit?
+ order.payments.completed.store_credits.each(&:void!)
+ else
+ order.payments.completed.each(&:cancel!)
+ order.payments.incomplete.not_store_credits.each(&:void_transaction!)
+ order.payments.store_credits.pending.each(&:void!)
+ end
+ end
+
+ def send_legacy_webhook
+ order.send_order_canceled_webhook
+ end
+ end
+ end
+end
diff --git a/spree/core/lib/spree/core.rb b/spree/core/lib/spree/core.rb
index 2a6ccda338..e8f05cfe33 100644
--- a/spree/core/lib/spree/core.rb
+++ b/spree/core/lib/spree/core.rb
@@ -556,8 +556,10 @@ module Spree
private
def core_dependency?(name)
- defined?(Spree::Dependencies) &&
- Spree::Dependencies.class::INJECTION_POINTS.include?(name)
+ return false unless defined?(Spree::Dependencies)
+
+ Spree::Dependencies.class::INJECTION_POINTS.include?(name) ||
+ Spree::Dependencies.class::LEGACY_WORKFLOW_KEYS.key?(name)
end
end
diff --git a/spree/core/lib/spree/core/dependencies.rb b/spree/core/lib/spree/core/dependencies.rb
index 1e9c8c9414..adbf351d23 100644
--- a/spree/core/lib/spree/core/dependencies.rb
+++ b/spree/core/lib/spree/core/dependencies.rb
@@ -12,8 +12,10 @@ module Spree
# cart_create/update/estimate_shipping_rates/change_currency service
# registrations were removed with their dead implementations.
cart_compare_line_items_service: 'Spree::CompareLineItems',
- cart_add_item_service: 'Spree::Carts::AddItem',
- cart_recalculate_service: 'Spree::Carts::Recalculate',
+ cart_add_item_workflow: 'Spree::Carts::AddItem',
+ cart_recalculate_workflow: 'Spree::Carts::Recalculate',
+ cart_recalculate_totals_workflow: 'Spree::Carts::RecalculateTotals',
+ order_recalculate_totals_workflow: 'Spree::Orders::RecalculateTotals',
cart_remove_item_service: 'Spree::Carts::RemoveItem',
cart_remove_line_item_service: 'Spree::Carts::RemoveLineItem',
cart_set_item_quantity_service: 'Spree::Carts::SetQuantity',
@@ -30,7 +32,7 @@ module Spree
cart_remove_out_of_stock_items_service: 'Spree::Carts::RemoveOutOfStockItems',
# carts
- carts_complete_service: 'Spree::Carts::Complete',
+ carts_complete_workflow: 'Spree::Carts::Complete',
carts_create_service: 'Spree::Carts::Create',
carts_update_service: 'Spree::Carts::Update',
carts_upsert_items_service: 'Spree::Carts::UpsertItems',
@@ -52,7 +54,7 @@ module Spree
# order
order_approve_service: 'Spree::Orders::Approve',
- order_cancel_service: 'Spree::Orders::Cancel',
+ order_cancel_workflow: 'Spree::Orders::Cancel',
order_complete_service: 'Spree::Orders::Complete',
order_add_manual_discount_service: 'Spree::Orders::AddManualDiscount',
order_create_service: 'Spree::Orders::Create',
@@ -119,6 +121,52 @@ module Spree
}.freeze
include Spree::DependenciesHelper
+
+ # 6.0 tier rename: these seams resolve Spree::Workflow classes now.
+ # The old *_service names stay settable and readable one release so
+ # applications don't crash at boot — but a legacy write is stashed,
+ # NOT applied to the workflow seam: a class written against the old
+ # service contract is not interchangeable with the workflow the new
+ # call sites consume. Reads return the stashed value (legacy code
+ # calling its own class keeps working), falling back to the workflow
+ # class — safe for legacy callers, whose old keyword vocabulary the
+ # workflows accept through alias_argument bridges. Removed in 6.1.
+ LEGACY_WORKFLOW_KEYS = {
+ cart_add_item_service: :cart_add_item_workflow,
+ cart_recalculate_service: :cart_recalculate_workflow,
+ carts_complete_service: :carts_complete_workflow,
+ order_cancel_service: :order_cancel_workflow
+ }.freeze
+
+ def legacy_workflow_overrides
+ @legacy_workflow_overrides ||= {}
+ end
+
+ LEGACY_WORKFLOW_KEYS.each do |legacy, current|
+ define_method("#{legacy}=") do |value|
+ Spree::Deprecation.warn(
+ "Spree::Dependencies##{legacy}= is deprecated and NO LONGER CONSULTED by Spree — " \
+ "the override was not applied. Port the class to the Spree::Workflow contract and " \
+ "set #{current}= instead. The #{legacy} name is removed in Spree 6.1."
+ )
+ legacy_workflow_overrides[legacy] = value
+ end
+
+ define_method(legacy) do
+ Spree::Deprecation.warn("Spree::Dependencies##{legacy} is deprecated and will be removed in Spree 6.1. Use #{current} instead.")
+ legacy_workflow_overrides.fetch(legacy) { send(current) }
+ end
+
+ define_method("#{legacy}_class") do
+ Spree::Deprecation.warn("Spree::Dependencies##{legacy} is deprecated and will be removed in Spree 6.1. Use #{current} instead.")
+ if legacy_workflow_overrides.key?(legacy)
+ value = legacy_workflow_overrides[legacy]
+ value.is_a?(String) ? value.constantize : value
+ else
+ send("#{current}_class")
+ end
+ end
+ end
end
end
end
diff --git a/spree/core/spec/models/spree/app_dependencies_spec.rb b/spree/core/spec/models/spree/app_dependencies_spec.rb
index b1daed6210..0709c2f505 100644
--- a/spree/core/spec/models/spree/app_dependencies_spec.rb
+++ b/spree/core/spec/models/spree/app_dependencies_spec.rb
@@ -11,43 +11,43 @@ describe Spree::Core::Dependencies, type: :model do
describe 'backwards compatibility' do
it 'returns the default value as string' do
- expect(deps.cart_add_item_service).to eq('Spree::Carts::AddItem')
+ expect(deps.cart_add_item_workflow).to eq('Spree::Carts::AddItem')
end
it 'allows to overwrite the value with a class' do
- deps.cart_add_item_service = MyCustomAddItemService
- expect(deps.cart_add_item_service).to eq MyCustomAddItemService
+ deps.cart_add_item_workflow = MyCustomAddItemService
+ expect(deps.cart_add_item_workflow).to eq MyCustomAddItemService
end
it 'allows to overwrite the value with a string' do
- deps.cart_add_item_service = 'MyCustomAddItemService'
- expect(deps.cart_add_item_service).to eq 'MyCustomAddItemService'
+ deps.cart_add_item_workflow = 'MyCustomAddItemService'
+ expect(deps.cart_add_item_workflow).to eq 'MyCustomAddItemService'
end
it 'works with constantize for string values' do
- expect(deps.cart_add_item_service.constantize).to eq Spree::Carts::AddItem
+ expect(deps.cart_add_item_workflow.constantize).to eq Spree::Carts::AddItem
end
end
describe '#<dependency>_class' do
it 'returns the constantized class for string values' do
- expect(deps.cart_add_item_service_class).to eq Spree::Carts::AddItem
+ expect(deps.cart_add_item_workflow_class).to eq Spree::Carts::AddItem
end
it 'returns the class directly when set as class' do
- deps.cart_add_item_service = MyCustomAddItemService
- expect(deps.cart_add_item_service_class).to eq MyCustomAddItemService
+ deps.cart_add_item_workflow = MyCustomAddItemService
+ expect(deps.cart_add_item_workflow_class).to eq MyCustomAddItemService
end
it 'memoizes the resolved class' do
- deps.cart_add_item_service_class
- expect(deps.instance_variable_get(:@cart_add_item_service_resolved)).to eq Spree::Carts::AddItem
+ deps.cart_add_item_workflow_class
+ expect(deps.instance_variable_get(:@cart_add_item_workflow_resolved)).to eq Spree::Carts::AddItem
end
it 'clears memoization when value changes' do
- deps.cart_add_item_service_class
- deps.cart_add_item_service = MyCustomAddItemService
- expect(deps.instance_variable_defined?(:@cart_add_item_service_resolved)).to be false
+ deps.cart_add_item_workflow_class
+ deps.cart_add_item_workflow = MyCustomAddItemService
+ expect(deps.instance_variable_defined?(:@cart_add_item_workflow_resolved)).to be false
end
end
@@ -57,13 +57,13 @@ describe Spree::Core::Dependencies, type: :model do
end
it 'tracks overridden dependencies' do
- deps.cart_add_item_service = MyCustomAddItemService
- expect(deps.overrides).to have_key(:cart_add_item_service)
+ deps.cart_add_item_workflow = MyCustomAddItemService
+ expect(deps.overrides).to have_key(:cart_add_item_workflow)
end
it 'includes override metadata' do
- deps.cart_add_item_service = MyCustomAddItemService
- override = deps.overrides[:cart_add_item_service]
+ deps.cart_add_item_workflow = MyCustomAddItemService
+ override = deps.overrides[:cart_add_item_workflow]
expect(override[:value]).to eq MyCustomAddItemService
expect(override[:source]).to be_a(String)
@@ -71,30 +71,60 @@ describe Spree::Core::Dependencies, type: :model do
end
end
+ describe 'legacy *_service workflow keys' do
+ it 'stashes writes without touching the workflow seam and reads them back' do
+ expect(Spree::Deprecation).to receive(:warn).with(/NO LONGER CONSULTED/).ordered
+ expect(Spree::Deprecation).to receive(:warn).with(/cart_add_item_service is deprecated/).ordered
+
+ deps.cart_add_item_service = 'MyCustomAddItemService'
+ expect(deps.cart_add_item_service).to eq('MyCustomAddItemService')
+ expect(deps.cart_add_item_workflow).to eq('Spree::Carts::AddItem')
+ end
+
+ it 'falls back to the workflow class for legacy reads with no stash' do
+ allow(Spree::Deprecation).to receive(:warn)
+ expect(deps.cart_add_item_service).to eq('Spree::Carts::AddItem')
+ end
+ end
+
+ describe 'legacy keys through the Spree top-level resolver' do
+ it 'sets and resolves without raising, leaving the workflow seam untouched' do
+ allow(Spree::Deprecation).to receive(:warn)
+ stub_const('MyBootTimeAddItem', Class.new)
+
+ expect { Spree.cart_add_item_service = 'MyBootTimeAddItem' }.not_to raise_error
+ expect(Spree.cart_add_item_service).to eq(MyBootTimeAddItem)
+ expect(Spree.cart_add_item_workflow).to eq(Spree::Carts::AddItem)
+ expect(Spree::Deprecation).to have_received(:warn).at_least(:twice)
+ ensure
+ Spree::Dependencies.instance_variable_set(:@legacy_workflow_overrides, nil)
+ end
+ end
+
describe '#overridden?' do
it 'returns false for non-overridden dependencies' do
- expect(deps.overridden?(:cart_add_item_service)).to be false
+ expect(deps.overridden?(:cart_add_item_workflow)).to be false
end
it 'returns true for overridden dependencies' do
- deps.cart_add_item_service = MyCustomAddItemService
- expect(deps.overridden?(:cart_add_item_service)).to be true
+ deps.cart_add_item_workflow = MyCustomAddItemService
+ expect(deps.overridden?(:cart_add_item_workflow)).to be true
end
it 'works with string argument' do
- deps.cart_add_item_service = MyCustomAddItemService
- expect(deps.overridden?('cart_add_item_service')).to be true
+ deps.cart_add_item_workflow = MyCustomAddItemService
+ expect(deps.overridden?('cart_add_item_workflow')).to be true
end
end
describe '#override_info' do
it 'returns nil for non-overridden dependencies' do
- expect(deps.override_info(:cart_add_item_service)).to be_nil
+ expect(deps.override_info(:cart_add_item_workflow)).to be_nil
end
it 'returns override info for overridden dependencies' do
- deps.cart_add_item_service = MyCustomAddItemService
- info = deps.override_info(:cart_add_item_service)
+ deps.cart_add_item_workflow = MyCustomAddItemService
+ info = deps.override_info(:cart_add_item_workflow)
expect(info[:value]).to eq MyCustomAddItemService
expect(info[:source]).to include('app_dependencies_spec.rb')
@@ -109,14 +139,14 @@ describe Spree::Core::Dependencies, type: :model do
end
it 'marks non-overridden dependencies correctly' do
- cart_create = deps.current_values.find { |v| v[:name] == :cart_add_item_service }
+ cart_create = deps.current_values.find { |v| v[:name] == :cart_add_item_workflow }
expect(cart_create[:overridden]).to be false
expect(cart_create[:current]).to eq cart_create[:default]
end
it 'marks overridden dependencies correctly' do
- deps.cart_add_item_service = MyCustomAddItemService
- cart_create = deps.current_values.find { |v| v[:name] == :cart_add_item_service }
+ deps.cart_add_item_workflow = MyCustomAddItemService
+ cart_create = deps.current_values.find { |v| v[:name] == :cart_add_item_workflow }
expect(cart_create[:overridden]).to be true
expect(cart_create[:current]).to eq MyCustomAddItemService
@@ -126,14 +156,14 @@ describe Spree::Core::Dependencies, type: :model do
describe '#validate!' do
it 'raises Spree::DependencyError for invalid dependencies' do
- deps.cart_add_item_service = 'NonExistentClass'
+ deps.cart_add_item_workflow = 'NonExistentClass'
expect { deps.validate! }.to raise_error(Spree::DependencyError)
end
it 'includes dependency names in error message' do
- deps.cart_add_item_service = 'NonExistentClass'
- deps.cart_add_item_service = 'AnotherNonExistentClass'
- expect { deps.validate! }.to raise_error(Spree::DependencyError, /cart_add_item_service/)
+ deps.cart_add_item_workflow = 'NonExistentClass'
+ deps.cart_add_item_workflow = 'AnotherNonExistentClass'
+ expect { deps.validate! }.to raise_error(Spree::DependencyError, /cart_add_item_workflow/)
end
end
end
@@ -144,12 +174,12 @@ describe 'Spree module dependency accessors' do
describe 'Spree.<dependency>' do
it 'returns the resolved class' do
- expect(Spree.cart_add_item_service).to eq Spree::Carts::AddItem
+ expect(Spree.cart_add_item_workflow).to eq Spree::Carts::AddItem
end
it 'responds to dependency methods' do
- expect(Spree.respond_to?(:cart_add_item_service)).to be true
- expect(Spree.respond_to?(:cart_add_item_service=)).to be true
+ expect(Spree.respond_to?(:cart_add_item_workflow)).to be true
+ expect(Spree.respond_to?(:cart_add_item_workflow=)).to be true
end
it 'does not respond to non-dependency methods' do
@@ -160,28 +190,28 @@ describe 'Spree module dependency accessors' do
describe 'Spree.<dependency>=' do
# Use around hook with ensure to guarantee cleanup even if test fails
around do |example|
- original_value = Spree::Dependencies.cart_add_item_service
+ original_value = Spree::Dependencies.cart_add_item_workflow
example.run
ensure
# Restore original value using setter (which clears memoization)
- Spree::Dependencies.cart_add_item_service = original_value
+ Spree::Dependencies.cart_add_item_workflow = original_value
# Clear override tracking for this test
- Spree::Dependencies.instance_variable_get(:@overrides)&.delete(:cart_add_item_service)
+ Spree::Dependencies.instance_variable_get(:@overrides)&.delete(:cart_add_item_workflow)
end
it 'sets the dependency via Spree module' do
- Spree.cart_add_item_service = MyCustomAddItemService
- expect(Spree::Dependencies.cart_add_item_service).to eq MyCustomAddItemService
+ Spree.cart_add_item_workflow = MyCustomAddItemService
+ expect(Spree::Dependencies.cart_add_item_workflow).to eq MyCustomAddItemService
end
it 'returns the new class via Spree module' do
- Spree.cart_add_item_service = MyCustomAddItemService
- expect(Spree.cart_add_item_service).to eq MyCustomAddItemService
+ Spree.cart_add_item_workflow = MyCustomAddItemService
+ expect(Spree.cart_add_item_workflow).to eq MyCustomAddItemService
end
it 'tracks override source correctly (not internal routing code)' do
- Spree.cart_add_item_service = MyCustomAddItemService
- info = Spree::Dependencies.override_info(:cart_add_item_service)
+ Spree.cart_add_item_workflow = MyCustomAddItemService
+ info = Spree::Dependencies.override_info(:cart_add_item_workflow)
# Should point to this spec file, not core.rb method_missing
expect(info[:source]).to include('app_dependencies_spec.rb')
diff --git a/spree/core/spec/models/spree/order_spec.rb b/spree/core/spec/models/spree/order_spec.rb
index 69720fda1c..810a9a6e55 100644
--- a/spree/core/spec/models/spree/order_spec.rb
+++ b/spree/core/spec/models/spree/order_spec.rb
@@ -315,15 +315,10 @@ describe Spree::Order, type: :model do
subject { order.canceled_by(admin_user) }
let(:admin_user) { create :admin_user }
- let(:order) { create :order }
-
- before do
- allow(order).to receive(:cancel!)
- end
+ let(:order) { create(:completed_order_with_totals) }
it 'cancels the order' do
- expect(order).to receive(:cancel!)
- subject
+ expect { subject }.to change { order.reload.status }.to('canceled')
end
it 'saves canceler_id' do
diff --git a/spree/core/spec/services/spree/orders/cancel_spec.rb b/spree/core/spec/workflows/spree/orders/cancel_spec.rb
similarity index 100%
rename from spree/core/spec/services/spree/orders/cancel_spec.rb
rename to spree/core/spec/workflows/spree/orders/cancel_spec.rb