spree_core 5.6.1 → 6.0.0.beta2

data/app/workflows/spree/orders/add_item.rb

@@ -0,0 +1,12 @@
+module Spree
+  module Orders
+    # Draft-order twin of the cart workflow — order: is the canonical
+    # keyword on this side, mapped onto the shared pipeline so cart-only
+    # behavior can diverge without branching one implementation.
+    class AddItem < Spree::Carts::AddItem
+      def perform(order:, **rest)
+        super(cart: order, **rest)
+      end
+    end
+  end
+end

data/app/workflows/spree/orders/cancel.rb

@@ -0,0 +1,261 @@
+module Spree
+  module Orders
+    # Cancels an order — the orchestration that used to hide inside
+    # Order#after_cancel: the status flip (stamping the reason and note on
+    # the order) 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.
+    class Cancel < Spree::Workflow
+      hooks :before_cancel, :after_cancel
+
+      # @param order [Spree::Order]
+      # @param canceler [Object, nil] who initiated it — an admin user or an
+      #   API key (see Spree.actor_classes)
+      # @param canceled_at [Time, nil] timestamp (defaults to Time.current)
+      # @param reason [Spree::OrderCancellationReason, nil] the merchant's own
+      #   vocabulary; must belong to the order's store
+      # @param note [String, nil] staff-facing note
+      # @param refund_payments [Boolean] whether captured money is handed back.
+      #   False by default: an authorization is always released, but returning
+      #   money already taken is its own decision — the shape Shopify, Vendure,
+      #   Saleor and WooCommerce all settled on.
+      # @param refund_amount [BigDecimal, Numeric, nil] defaults to
+      #   order.payment_total when refund_payments is true
+      # @param notify_customer [Boolean] hint for subscribers
+      # @param restock_items [Boolean, nil] deprecated and ignored — items
+      #   always return to stock when their fulfillment is canceled
+      def perform(order:, canceler: nil, canceled_at: nil,
+                  reason: nil, note: nil,
+                  refund_payments: false, refund_amount: nil,
+                  notify_customer: false, restock_items: nil)
+        super
+
+        unless restock_items.nil?
+          Spree::Deprecation.warn('Spree::Orders::Cancel no longer accepts restock_items — it never changed behavior and will be removed in Spree 6.1.')
+        end
+
+        step :ensure_cancellable
+        step :ensure_reason_belongs_to_store
+        step :ensure_refund_amount_is_settleable
+
+        # Veto point — seller policy, already-dispatched guards. Before the
+        # transaction: nothing is written yet, and payment settlement has
+        # not run.
+        run_hooks :before_cancel
+
+        @decided_at = canceled_at || Time.current
+        # Coerced because the amount arrives from JSON as a string, and it is
+        # compared against money further down — `[amount, remaining].min`
+        # raises on a String.
+        @amount_to_refund = refund_amount&.to_d
+        @amount_to_refund ||= amount_paid if refund_payments
+
+        ApplicationRecord.transaction do
+          step :mark_canceled
+          step :cancel_fulfillments
+          run_hooks :after_cancel
+        end
+
+        external_step :notify_fulfillment_providers
+        external_step :settle_payments
+        external_step :void_tax
+        step :recompute_totals, with: -> { Spree.order_recalculate_totals_workflow }
+        step :update_statuses, with: -> { Spree.order_update_statuses_service }
+        order.publish_event('order.canceled', order.event_payload.merge(notify_customer: notify_customer))
+        success(order.reload)
+      rescue ActiveRecord::RecordInvalid
+        failure(order)
+      end
+
+      private
+
+      def ensure_cancellable
+        return if order.allow_cancel?
+
+        order.errors.add(:base, :not_cancellable, message: Spree.t('errors.messages.not_cancellable'))
+        failure(order)
+      end
+
+      # An ordinary order settles at the gateway, which returns the whole
+      # captured payment — there is nowhere to apply a cap. Honouring the
+      # request halfway would refund everything while the caller believed
+      # they had held part back, so it is refused instead. A shared payment
+      # is the case the amount exists for: there it names this order's share.
+      def ensure_refund_amount_is_settleable
+        return if refund_amount.blank? || order.grouped?
+
+        order.errors.add(:base, :refund_amount_requires_shared_payment, message: Spree.t('errors.messages.refund_amount_requires_shared_payment'))
+        failure(order)
+      end
+
+      # A reason from another store would label this order with a vocabulary
+      # its merchant never wrote — the same scoping rule the controllers apply
+      # to every incidental id, enforced here so console and extension callers
+      # get it too.
+      def ensure_reason_belongs_to_store
+        return if reason.nil? || reason.store_id == order.store_id
+
+        order.errors.add(:cancel_reason, :invalid)
+        failure(order)
+      end
+
+      def mark_canceled
+        changes = { status: 'canceled', canceled_at: @decided_at, cancel_reason_id: reason&.id, cancel_note: note }
+        changes.merge!(Spree::ActedBy.columns_for(:canceler, canceler)) if canceler.present?
+        order.update_columns(changes)
+      end
+
+      # Restocks each fulfillment's units and cancels it. allow_cancel? already
+      # excluded orders with shipped fulfillments.
+      #
+      # Deliberately not delegated to Spree::Fulfillments::Cancel: that workflow
+      # ends with an external_step telling the carrier, which refuses to run
+      # inside a transaction — and this runs inside the order's. The carriers
+      # are notified in #notify_fulfillment_providers once the transaction has
+      # committed, which is the same ordering the fulfillment workflow uses.
+      def cancel_fulfillments
+        order.fulfillments.each do |fulfillment|
+          result = Spree.fulfillment_cancel_workflow.call(
+            fulfillment: fulfillment,
+            # Carrier I/O cannot run inside this transaction; the providers are
+            # told in #notify_fulfillment_providers once it has committed.
+            notify_provider: false
+          )
+
+          failure(order, result.error) unless result.success?
+        end
+      end
+
+      # The provider half of cancelling each fulfillment — network I/O, so it
+      # runs after the transaction commits. A carrier that rejects the
+      # cancellation does not undo the order cancellation; the goods are not
+      # going out either way, and the failure surfaces through the provider.
+      def notify_fulfillment_providers
+        order.fulfillments.each do |fulfillment|
+          Spree.fulfillment_stand_down_service.call(fulfillment: fulfillment)
+        end
+      end
+
+      # Gateway I/O. Payments fully covered by a gift card are only voided,
+      # never refunded; everything else releases what was never drawn and,
+      # when the caller asked for it, gives back what was.
+      def settle_payments
+        return settle_grouped_payments if order.grouped?
+
+        if order.gift_card.present? && order.covered_by_store_credit?
+          order.payments.completed.store_credits.each(&:void!)
+        else
+          settle_completed_payments
+          order.payments.incomplete.not_store_credits.each do |payment|
+            # Failed and invalid payments hold nothing to release.
+            next unless payment.can_void?
+
+            result = Spree.payment_void_workflow.call(payment: payment)
+            raise Spree::Core::GatewayError, result.error.value.to_s if result.failure?
+          end
+          order.payments.store_credits.pending.each(&:void!)
+        end
+      end
+
+      # Every completed payment goes through the gateway's own settle verb, so
+      # a hold is always released. What happens to money already drawn is the
+      # caller's decision, carried to the adapter: one that can void the charge
+      # does so regardless, and one that cannot — Stripe, on a captured
+      # PaymentIntent — refunds only when `refund_payments` allows it.
+      def settle_completed_payments
+        order.payments.completed.each { |payment| payment.cancel!(refund: refund_payments) }
+      end
+
+      # What this order has actually been paid. An order placed in a split
+      # checkout holds no payments of its own — the customer paid once, against
+      # the group — so its position is the sum of its shares.
+      #
+      # @return [BigDecimal]
+      def amount_paid
+        return order.payment_total unless order.grouped?
+
+        order.payment_splits.sum(&:net_captured_amount)
+      end
+
+      # Canceling one order of a split checkout gives back that order's money
+      # and nothing else: the payment is shared, so voiding it would release
+      # the siblings' authorization too and un-pay sellers who are still
+      # shipping. What comes back is this order's own share — refunded where it
+      # has been captured, and simply written down where it has not, since
+      # there is nothing to give back until it is drawn.
+      #
+      # Deliberately not "void the payment when every sibling is canceled too":
+      # that reads the siblings' state to decide what to do with shared money,
+      # and being wrong about it releases an authorization a seller is still
+      # relying on. Writing the share down leaves the payment voidable by
+      # whoever cancels last, which reaches the same end without the risk.
+      #
+      # Store credit and gift cards are refunded like any other share rather
+      # than voided: a void releases a whole payment, which on a shared one is
+      # the siblings' money too. The credit comes back to the customer either
+      # way, and the refund path is the one that can return a part.
+      def settle_grouped_payments
+        remaining = @amount_to_refund
+
+        order.payment_splits.includes(:payment).each do |split|
+          # A parcel dispatching marks its share taken *before* asking the
+          # gateway, so a share can read captured while the charge is still in
+          # flight. Settling against that would release an authorization the
+          # gateway is about to draw on, or hand back money it never took —
+          # so a payment mid-capture is left for the operator rather than
+          # guessed at.
+          next if capture_in_flight?(split)
+
+          # Release what this order had reserved but never drew — the
+          # authorization is no longer for anything. Under the row's lock, so
+          # a dispatch claiming the same share concurrently either draws before
+          # the release or finds nothing left.
+          split.with_lock { split.update!(authorized_amount: split.captured_amount) }
+
+          # Give money back only when the caller asked for it, and only up to
+          # what they asked for, exactly as the ungrouped path does.
+          next unless refund_payments
+
+          refundable = [split.net_captured_amount, remaining].compact.min
+          next if refundable <= 0
+
+          result = Spree.refund_create_workflow.call(
+            payment: split.payment, amount: refundable, order: order, refunder: canceler
+          )
+          raise Spree::Core::GatewayError, result.error.value.to_s if result.failure?
+
+          remaining -= refundable if remaining
+        end
+      end
+
+      # Whether a charge against this share is still in flight.
+      #
+      # The share itself knows: a parcel reserves what it is about to draw
+      # before asking the gateway, and that reservation only becomes captured
+      # money once the charge lands. Settling through it would either release
+      # an authorization about to be drawn or refund money nobody took, so it
+      # is reported for the operator rather than guessed at.
+      #
+      # @return [Boolean]
+      def capture_in_flight?(split)
+        return false unless split.capture_in_flight?
+
+        Rails.error.report(
+          Spree::Core::GatewayError.new('Payment share is mid-capture; cancellation left it for manual settlement'),
+          handled: true,
+          context: { order_id: order.id, payment_split_id: split.id },
+          source: 'spree.core'
+        )
+        true
+      end
+
+      # Reverses the filed tax document. The canceled sale must stop appearing
+      # in the merchant's tax liability.
+      def void_tax
+        order.tax_provider.void(order)
+      end
+    end
+  end
+end

data/app/workflows/spree/orders/complete.rb

@@ -0,0 +1,169 @@
+module Spree
+  module Orders
+    # The order-side completion workflow — the ONE home for everything that
+    # happens when an order becomes placed. Serves both entry points:
+    # checkout ({Spree::Carts::Complete} delegates its FINALIZE phase here
+    # with payments already captured) and admin/B2B draft completion (which
+    # may still need to process payments). Idempotent: an already-placed
+    # order halts successfully, so interrupted completions replay safely.
+    class Complete < Spree::Workflow
+      # @param order [Spree::Order]
+      # @param payment_pending [Boolean] when true the order places without
+      #   processing payments (B2B / invoice-later). With no payment rows the
+      #   status rollup yields payment_status: 'none' — whether an unpaid
+      #   placed order deserves a distinct value is the wholesale-deposit
+      #   rollup work's call (docs/plans/6.0-b2b-wholesale-shipping.md phase 7)
+      # @param notify_customer [Boolean, nil] admin drafts pass false to
+      #   complete silently; nil (checkout) leaves customer notification on
+      def perform(order:, payment_pending: false, notify_customer: nil)
+        super
+
+        order.notify_customer = notify_customer unless notify_customer.nil?
+
+        halt!(order) if order.completed?
+        step :ensure_not_canceled
+
+        order.with_lock do
+          unless order.reload.placed?
+            step :process_payments unless payment_pending || !order.payment_required?
+            step :finalize_fulfillments
+            step :place_order
+            step :use_coupon_codes
+            step :redeem_gift_card
+            step :fulfill_auto_fulfillments
+            step :ensure_digital_links
+          end
+        end
+
+        step :ensure_placed_status
+        step :release_stock_reservations
+        step :update_statuses
+        step :publish_order_placed
+
+        success(order)
+      end
+
+      private
+
+      def ensure_not_canceled
+        failure(order, 'Order is canceled') if order.canceled?
+      end
+
+      def process_payments
+        order.process_payments! unless payment_covered?
+
+        failure(order, order.errors.full_messages.to_sentence) if order.errors.any?
+        failure(order, Spree.t(:payment_processing_failed)) unless payment_covered?
+      end
+
+      # Typed adjustment rows are frozen once completed — the totals
+      # recalculation only re-sums them, never regenerates (see
+      # Spree::Carts::RecalculateTotals) — so no per-row locking is needed.
+      #
+      # Placement promises stock rather than moving it: an `allocated`
+      # movement per fulfillment raises the level's allocated count and leaves
+      # the shelf alone until the parcel actually leaves. Draft orders enter
+      # here directly, which is why the write lives in this workflow.
+      def finalize_fulfillments
+        order.fulfillments.each do |fulfillment|
+          fulfillment.finalize!
+          allocate_fulfillment_stock(fulfillment)
+        end
+      end
+
+      def allocate_fulfillment_stock(fulfillment)
+        fulfillment.manifest.each do |item|
+          next unless item.variant.track_inventory?
+          next unless item.quantity.positive?
+
+          fulfillment.stock_location.allocate(item.variant, item.quantity, fulfillment)
+        end
+      end
+
+      def place_order
+        order.update!(status: 'placed', completed_at: Time.current)
+      end
+
+      def use_coupon_codes
+        Spree::CouponCodes::CouponCodesHandler.new(order: order).use_all_codes
+      end
+
+      # A refused redemption does not fail the order: the card was already
+      # drawn down when it was applied, and the customer's order is placed.
+      # It is reported rather than swallowed, because a card that cannot be
+      # marked spent is a discrepancy someone has to look at.
+      def redeem_gift_card
+        return if order.gift_card.nil?
+
+        result = Spree.gift_card_redeem_workflow.call(gift_card: order.gift_card)
+        return if result.success?
+
+        Rails.error.report(
+          Spree::Core::GatewayError.new("Gift card #{order.gift_card.id} could not be redeemed: #{result.error}"),
+          handled: true,
+          context: { order_id: order.id, gift_card_id: order.gift_card.id },
+          source: 'spree.core'
+        )
+      end
+
+      # Providers that opt into auto_fulfill? (digital delivery today) get
+      # forced to ready and fulfilled through the machine so all hooks
+      # (links, events, webhooks) run.
+      def fulfill_auto_fulfillments
+        @auto_fulfilled_line_item_ids = []
+
+        order.fulfillments.reload.each do |fulfillment|
+          next unless fulfillment.provider.auto_fulfill?
+          next if fulfillment.fulfilled? || fulfillment.canceled?
+
+          # Digital goods go out the moment the order is placed; the payment
+          # gate does not apply, hence force.
+          Spree.fulfillment_fulfill_workflow.call(fulfillment: fulfillment, force: true)
+          @auto_fulfilled_line_item_ids.concat(fulfillment.line_items.map(&:id))
+        end
+      end
+
+      # Digital links for items delivered by non-digital providers (physical
+      # + download combos) — links are a digital-domain concern regardless of
+      # the carrier; idempotent per quantity. Runs before the confirmation
+      # email subscriber reads the links.
+      def ensure_digital_links
+        return unless order.with_digital_assets?
+
+        provider = Spree::FulfillmentProvider::Digital.new
+        order.digital_line_items.where.not(id: @auto_fulfilled_line_item_ids).includes(variant: :digital_assets).each do |line_item|
+          provider.ensure_links_for(line_item)
+        end
+      end
+
+      # Belt-and-braces for a completion interrupted between save and commit
+      # in an earlier attempt.
+      def ensure_placed_status
+        order.update_columns(status: 'placed') unless order.reload.placed?
+      end
+
+      def release_stock_reservations
+        Spree::StockReservations::Release.call(owner: order)
+      end
+
+      def update_statuses
+        Spree::Orders::UpdateStatuses.call(order: order)
+      end
+
+      # The customer-facing side effects (newsletter, account creation, risk)
+      # live in Spree::OrderPlacedSubscriber, triggered by this event.
+      # order.completed is a one-release alias for 5.x webhook consumers;
+      # wildcard subscribers dedupe on the metadata marker.
+      def publish_order_placed
+        payload = order.event_payload.merge(notify_customer: order.notify_customer)
+        order.publish_event('order.placed', payload)
+        order.publish_event('order.completed', payload, { deprecated_alias_of: 'order.placed' })
+      end
+
+      def payment_covered?
+        order.payments.reset
+        order.payments.valid.where(status: %w[pending processing completed]).sum(:amount) >= order.amount_due_at_checkout
+      end
+    end
+  end
+end

data/app/workflows/spree/orders/recalculate.rb

@@ -0,0 +1,11 @@
+module Spree
+  module Orders
+    # Draft-order twin of the cart workflow — order: is the canonical
+    # keyword on this side, mapped onto the shared pipeline.
+    class Recalculate < Spree::Carts::Recalculate
+      def perform(order:, **rest)
+        super(cart: order, **rest)
+      end
+    end
+  end
+end

data/app/workflows/spree/orders/recalculate_totals.rb

@@ -0,0 +1,12 @@
+module Spree
+  module Orders
+    # Order twin of the cart workflow — order: is the canonical keyword on
+    # this side (the calculator resolves polymorphically through the
+    # model's #updater).
+    class RecalculateTotals < Spree::Carts::RecalculateTotals
+      def perform(order:, resum_only: false)
+        super(cart: order, resum_only: resum_only)
+      end
+    end
+  end
+end

data/app/workflows/spree/orders/upsert_items.rb

@@ -0,0 +1,28 @@
+module Spree
+  module Orders
+    # Draft-order twin of the cart workflow — order: is the canonical keyword
+    # on this side, and hooks dispatch under 'orders.upsert_items.*' so an
+    # extension can hold admin edits to different rules than storefront ones.
+    #
+    # Totals are NOT recalculated here: Spree::Orders::Create and
+    # Spree::Orders::Update run items, fulfillments and coupons as one
+    # pipeline and recalculate once at the end of it.
+    class UpsertItems < Spree::Carts::UpsertItems
+      def perform(order:, **rest)
+        super(cart: order, **rest)
+      end
+
+      private
+
+      def recalculate?
+        false
+      end
+
+      # A merchant's edit applies whole or not at all — a line silently
+      # skipped is worse here than a failed request.
+      def partial_success?
+        false
+      end
+    end
+  end
+end

data/app/workflows/spree/payment_sessions/complete.rb

@@ -0,0 +1,44 @@
+module Spree
+  module PaymentSessions
+    # Completes a payment session when the customer returns from the gateway —
+    # the synchronous twin of Spree::Payments::HandleWebhook, which settles the
+    # same session when the gateway reports out of band. Either can arrive
+    # first; both settle through PaymentSession#settle_payment!.
+    #
+    # In the workflow tier because completion is network I/O (the gateway
+    # verifies the session before settling), and because this is the one
+    # moment a host can veto settlement on the synchronous path — the webhook
+    # path deliberately has no veto, since money that already moved cannot be
+    # rejected.
+    class Complete < Spree::Workflow
+      hooks :validate, :after_complete
+
+      # @param payment_session [Spree::PaymentSession]
+      # @param params [Hash] gateway-specific completion params from the client
+      def perform(payment_session:, params: {})
+        super
+
+        # A replayed confirm on a settled session is idempotent, not an error.
+        halt!(payment_session) if payment_session.completed?
+
+        run_hooks :validate
+
+        external_step :complete_at_gateway
+
+        run_hooks :after_complete
+        success(payment_session.reload)
+      end
+
+      private
+
+      def complete_at_gateway
+        payment_session.payment_method.complete_payment_session(
+          payment_session: payment_session,
+          params: params
+        )
+      rescue Spree::Core::GatewayError => error
+        failure(payment_session, error.message)
+      end
+    end
+  end
+end

data/app/workflows/spree/payments/capture.rb

@@ -0,0 +1,109 @@
+module Spree
+  module Payments
+    # Captures an authorized payment at the gateway.
+    #
+    # Owns the flow end to end: the atomic claim, the gateway round trip
+    # (an external_step, so it can never share a workflow-opened
+    # transaction), the locked bookkeeping with its settled-concurrently
+    # recheck, the partial-capture split, and the remainder's
+    # re-authorization. Spree::Payment keeps only gateway mechanics —
+    # gateway_options, handle_response, error translation.
+    class Capture < Spree::Workflow
+      include Spree::InstrumentsGatewayCalls
+
+      hooks :validate, :before_capture, :after_capture
+
+      # @param payment [Spree::Payment] a completed payment is a no-op
+      # @param amount [Integer, nil] amount in cents; nil captures in full,
+      #   a smaller amount splits the remainder into a new pending payment
+      def perform(payment:, amount: nil)
+        super
+        @amount = amount || payment.money.amount_in_cents
+
+        step :ensure_capturable
+        # Veto point — fraud holds, manual review. Before any money moves.
+        run_hooks :validate
+        run_hooks :before_capture
+
+        # Claiming before the gateway call is what makes a stale instance
+        # harmless: a payment another writer already settled refuses the
+        # claim, and the capture reports success without touching the
+        # gateway or recording a second capture event.
+        step :claim
+
+        external_step :capture_at_gateway
+        step :record_capture
+        external_step :authorize_remainder
+
+        run_hooks :after_capture
+        payment.publish_event('payment.captured')
+        success(payment.reload)
+      end
+
+      private
+
+      attr_reader :response, :remainder
+
+      # An already-captured payment returns success rather than failing:
+      # capture is naturally idempotent and double-submitted admin actions
+      # must not surface as errors. A failed payment is capturable — the
+      # failure may have been a gateway outage, and retrying is running
+      # this workflow again.
+      def ensure_capturable
+        halt!(payment) if payment.completed?
+        return if payment.pending? || payment.checkout? || payment.processing? || payment.failed?
+
+        failure(payment, :payment_not_capturable)
+      end
+
+      def claim
+        halt!(payment) unless payment.started_processing!
+      rescue Spree::Core::GatewayError => error
+        failure(payment, error.message)
+      end
+
+      def capture_at_gateway
+        @response = payment.protect_from_connection_error do
+          instrument_gateway_call(:capture, payment.payment_method) do
+            payment.payment_method.capture(@amount, payment.response_code, payment.gateway_options)
+          end
+        end
+
+        # A failed response writes no money records, so it needs no lock —
+        # handle_response records the failure and raises.
+        payment.handle_response(@response, :complete) unless @response.success?
+      rescue Spree::Core::GatewayError => error
+        failure(payment, error.message)
+      end
+
+      # Locked because the webhook settling the same payment races this
+      # request. The DB recheck — deliberately not a reload, which would
+      # discard the in-memory source (card numbers never persist) — makes
+      # the capture event exactly-once.
+      def record_capture
+        already_captured = false
+        payment.owner.with_lock do
+          if Spree::Payment.where(id: payment.id, status: 'completed').exists?
+            already_captured = true
+          else
+            payment.capture_events.create!(amount: ::Money.new(@amount, payment.currency).to_f)
+            # Split before completing, so payment.completed publishes with
+            # the captured amount and the order recomputes from correct rows.
+            @remainder = payment.split_uncaptured_amount
+            payment.handle_response(@response, :complete)
+          end
+        end
+        halt!(payment) if already_captured
+      end
+
+      # The remainder's authorization is its own network call, so it stays
+      # outside the lock.
+      def authorize_remainder
+        return if remainder.blank?
+
+        result = Spree.payment_process_workflow.call(payment: remainder, action: :authorize)
+        failure(remainder, result.error.value.to_s) if result.failure?
+      end
+    end
+  end
+end