spree_core 5.6.1 → 6.0.0.beta2

data/app/workflows/spree/purchase_orders/close.rb

@@ -0,0 +1,57 @@
+module Spree
+  module PurchaseOrders
+    # Ends an order the supplier will not complete.
+    #
+    # Eight of ten arrived and the last two are not coming. Cancelling would
+    # deny the eight, and waiting leaves the order open forever; closing short
+    # keeps what was received, records that the rest never came and why, and
+    # lets the outstanding count stand on each line as the record of the gap.
+    # No stock moves — the units were never here.
+    class Close < Spree::Workflow
+      include Spree::Receivables::IncomingCounter
+
+      hooks :validate, :after_close
+
+      attr_reader :purchase_order, :reason
+
+      # @param purchase_order [Spree::PurchaseOrder]
+      # @param reason [String, nil] why the balance is not expected
+      def perform(purchase_order:, reason: nil)
+        super
+
+        purchase_order.with_lock do
+          step :ensure_closable
+          run_hooks :validate
+          step :uncount_awaited_units
+          step :close_short
+        end
+
+        run_hooks :after_close
+        purchase_order.publish_event('purchase_order.received')
+        success(purchase_order.reload)
+      end
+
+      private
+
+      def ensure_closable
+        return if purchase_order.partially_received?
+
+        failure(purchase_order, Spree.t('purchase_order.errors.not_partially_received'))
+      end
+
+      # The merchant has just said the balance is not coming, so it leaves
+      # the destination's incoming figure; the outstanding count on each line
+      # keeps the record of what never arrived.
+      def uncount_awaited_units
+        uncount_incoming(purchase_order)
+      end
+
+      def close_short
+        now = Time.current
+        attributes = { status: 'received', received_at: now, closed_short_at: now, close_reason: reason.presence }
+
+        failure(purchase_order) unless purchase_order.update(attributes)
+      end
+    end
+  end
+end

data/app/workflows/spree/purchase_orders/create.rb

@@ -0,0 +1,68 @@
+module Spree
+  module PurchaseOrders
+    # Drafts an order to a supplier. Nothing is on order yet and nothing
+    # touches availability — a draft is what the merchant is still deciding to
+    # buy.
+    class Create < Spree::Workflow
+      hooks :validate, :after_create
+
+      # The created order — hook handlers read it (nil while :validate runs).
+      attr_reader :purchase_order
+
+      # @param store [Spree::Store]
+      # @param supplier [Spree::Supplier]
+      # @param destination_location [Spree::StockLocation] where the goods are
+      #   expected
+      # @param items [Array<Hash>] `[{ variant:, quantity_ordered:, unit_cost: }]`
+      # @param currency [String, nil] defaults to the store's; set it for a
+      #   foreign-currency order
+      # @param expected_at [Date, nil]
+      # @param reference [String, nil] the supplier's own order number
+      # @param notes [String, nil]
+      # @param created_by [Object, nil]
+      def perform(store:, supplier:, destination_location:, items: [], currency: nil,
+                  expected_at: nil, cancel_by: nil, reference: nil, notes: nil, created_by: nil)
+        super
+
+        step :build_purchase_order
+        run_hooks :validate
+
+        ApplicationRecord.transaction do
+          step :save_purchase_order
+        end
+
+        run_hooks :after_create
+        # The model's lifecycle events already emit `purchase_order.created`.
+        success(purchase_order.reload)
+      end
+
+      private
+
+      def build_purchase_order
+        @purchase_order = store.purchase_orders.new(
+          supplier: supplier,
+          destination_location: destination_location,
+          currency: currency,
+          expected_at: expected_at,
+          cancel_by: cancel_by,
+          reference: reference,
+          notes: notes,
+          created_by: created_by,
+          status: Spree::PurchaseOrder.default_status
+        )
+
+        Array(items).each do |item|
+          @purchase_order.items.build(
+            variant: item[:variant],
+            quantity_ordered: item[:quantity_ordered],
+            unit_cost: item[:unit_cost]
+          )
+        end
+      end
+
+      def save_purchase_order
+        failure(purchase_order) unless purchase_order.save
+      end
+    end
+  end
+end

data/app/workflows/spree/purchase_orders/mark_draft.rb

@@ -0,0 +1,49 @@
+module Spree
+  module PurchaseOrders
+    # Takes a placed order back to the drawing board.
+    #
+    # Only while nothing has arrived: once a delivery has been booked the
+    # lines are a record of what was received against, and can no longer be
+    # rewritten. The order's `ordered_at` is cleared, because it is no longer
+    # ordered.
+    class MarkDraft < Spree::Workflow
+      include Spree::Receivables::IncomingCounter
+
+      hooks :validate, :after_mark_draft
+
+      attr_reader :purchase_order
+
+      # @param purchase_order [Spree::PurchaseOrder]
+      def perform(purchase_order:)
+        super
+
+        purchase_order.with_lock do
+          step :ensure_returnable
+          run_hooks :validate
+          step :uncount_ordered_units
+          step :return_to_draft
+        end
+
+        run_hooks :after_mark_draft
+        purchase_order.publish_event('purchase_order.draft')
+        success(purchase_order.reload)
+      end
+
+      private
+
+      def ensure_returnable
+        failure(purchase_order, Spree.t('purchase_order.errors.already_receiving')) if purchase_order.stock_receipts.exists?
+        failure(purchase_order, Spree.t('purchase_order.errors.not_ordered_for_draft')) unless purchase_order.ordered?
+      end
+
+      # Nothing has been received, so this is every unit the order placed.
+      def uncount_ordered_units
+        uncount_incoming(purchase_order)
+      end
+
+      def return_to_draft
+        failure(purchase_order) unless purchase_order.update(status: 'draft', ordered_at: nil)
+      end
+    end
+  end
+end

data/app/workflows/spree/purchase_orders/mark_ordered.rb

@@ -0,0 +1,50 @@
+module Spree
+  module PurchaseOrders
+    # The order has gone to the supplier. Freezes the lines and starts the
+    # clock on the expected date; the goods are now "on order", which the
+    # merchant can see but availability never counts.
+    class MarkOrdered < Spree::Workflow
+      include Spree::Receivables::IncomingCounter
+
+      hooks :validate, :after_mark_ordered
+
+      # @param purchase_order [Spree::PurchaseOrder]
+      def perform(purchase_order:)
+        super
+
+        # One placement at a time per document: the draft check is what stops
+        # an order being placed twice, and two callers reading it outside the
+        # lock would both count the order's units as incoming — a surplus no
+        # receipt could ever withdraw.
+        purchase_order.with_lock do
+          step :ensure_draft
+          run_hooks :validate
+
+          step :mark_ordered
+          step :count_ordered_units
+        end
+
+        run_hooks :after_mark_ordered
+        purchase_order.publish_event('purchase_order.ordered')
+        success(purchase_order.reload)
+      end
+
+      private
+
+      def ensure_draft
+        failure(purchase_order, Spree.t('purchase_order.errors.not_draft')) unless purchase_order.draft?
+        failure(purchase_order, Spree.t('purchase_order.errors.must_have_variant')) if purchase_order.items.empty?
+      end
+
+      def mark_ordered
+        failure(purchase_order) unless purchase_order.update(status: 'ordered', ordered_at: Time.current)
+      end
+
+      # From this moment the goods are on their way as far as the Inventory
+      # page is concerned — still never as far as availability is.
+      def count_ordered_units
+        count_incoming(purchase_order)
+      end
+    end
+  end
+end

data/app/workflows/spree/purchase_orders/receive.rb

@@ -0,0 +1,65 @@
+module Spree
+  module PurchaseOrders
+    # Books in one delivery from the supplier, as a stock receipt.
+    #
+    # This is the moment purchased goods first exist as far as availability is
+    # concerned: nothing before it touched `count_on_hand`, because a merchant
+    # who has ordered stock does not have it. Suppliers under-ship and
+    # back-order routinely, so a delivery is booked as its own receipt and adds
+    # to the line's running total; over-shipments are booked as they come and
+    # close the order as `over_received`.
+    #
+    # Each `received` movement carries the line's `unit_cost`, which is what a
+    # rolling average cost is computed from — including across two deliveries
+    # agreed at different prices.
+    class Receive < Spree::Workflow
+      include Spree::StockReceipts::Recording
+
+      hooks :validate, :before_restock, :after_receive
+
+      attr_reader :purchase_order, :items, :received_at, :reference, :notes, :received_by,
+                  :stock_receipt
+
+      # @param purchase_order [Spree::PurchaseOrder]
+      # @param items [Array<Hash>, nil] `[{ item:, quantity_accepted:,
+      #   quantity_rejected:, rejection_reason:, notes: }]` — this delivery's
+      #   counts; nil books everything still outstanding, intact
+      # @param received_at [Time, nil] defaults to now
+      # @param reference [String, nil] the supplier's delivery note
+      # @param notes [String, nil]
+      # @param received_by [Object, nil]
+      def perform(purchase_order:, items: nil, received_at: nil, reference: nil, notes: nil, received_by: nil)
+        super
+        record_delivery
+      end
+
+      private
+
+      def receivable
+        purchase_order
+      end
+
+      def event_prefix
+        'purchase_order'
+      end
+
+      def error_scope
+        'purchase_order'
+      end
+
+      def ensure_receivable
+        return if purchase_order.ordered? || purchase_order.partially_received?
+
+        failure(purchase_order, Spree.t('purchase_order.errors.not_ordered'))
+      end
+
+      def line_belongs?(line)
+        line&.purchase_order_id == purchase_order.id
+      end
+
+      def unit_cost_for(line)
+        line.unit_cost
+      end
+    end
+  end
+end

data/app/workflows/spree/purchase_orders/update.rb

@@ -0,0 +1,56 @@
+module Spree
+  module PurchaseOrders
+    # Edits a draft order. Once it has been placed with the supplier, what was
+    # ordered is a matter of record between two businesses — so this refuses
+    # anything past `draft`.
+    class Update < Spree::Workflow
+      hooks :validate, :after_update
+
+      # @param purchase_order [Spree::PurchaseOrder]
+      # @param attributes [Hash] editable columns — supplier, destination,
+      #   currency, expected date, reference, notes, metadata
+      # @param items [Array<Hash>, nil] `[{ variant:, quantity_ordered:,
+      #   unit_cost: }]` replacing the current lines; nil leaves them alone
+      def perform(purchase_order:, attributes: {}, items: nil)
+        super
+
+        step :ensure_editable
+        run_hooks :validate
+
+        ApplicationRecord.transaction do
+          step :apply_changes
+          step :save_purchase_order
+        end
+
+        run_hooks :after_update
+        success(purchase_order.reload)
+      end
+
+      private
+
+      def ensure_editable
+        return if purchase_order.editable?
+
+        failure(purchase_order, Spree.t('purchase_order.errors.not_editable'))
+      end
+
+      def apply_changes
+        purchase_order.assign_attributes(attributes) if attributes.present?
+        return if items.nil?
+
+        purchase_order.items.destroy_all
+        Array(items).each do |item|
+          purchase_order.items.build(
+            variant: item[:variant],
+            quantity_ordered: item[:quantity_ordered],
+            unit_cost: item[:unit_cost]
+          )
+        end
+      end
+
+      def save_purchase_order
+        failure(purchase_order) unless purchase_order.save
+      end
+    end
+  end
+end

data/app/workflows/spree/receivables/incoming_counter.rb

@@ -0,0 +1,50 @@
+module Spree
+  module Receivables
+    # The one path that moves a document's awaited units on and off the
+    # destination's `incoming_count`. A purchase order or transfer counts
+    # toward incoming exactly while it is `incoming?` — `ordered`,
+    # `in_transit`, `partially_received` — so the workflow that takes it into
+    # that set adds every line's units, and the one that takes it out
+    # withdraws whatever is still awaited. Nothing else writes the counter.
+    module IncomingCounter
+      private
+
+      def count_incoming(receivable)
+        move_incoming(receivable, 1)
+      end
+
+      # Only a document that was counted can be uncounted: a cancelled draft
+      # never put anything on its way.
+      def uncount_incoming(receivable)
+        return unless receivable.incoming?
+
+        move_incoming(receivable, -1)
+      end
+
+      # The lines are read afresh here rather than from whatever the caller
+      # loaded before taking the document lock, since a delivery committed in
+      # between changes what is still awaited. The destination level is
+      # created when the warehouse has never held the SKU: a merchant who has
+      # ordered twenty of something new should see them on their way.
+      #
+      # Worked in variant order, not document order: these writes hold their
+      # row locks until the surrounding transaction ends, so two documents
+      # listing the same two variants the other way round would each wait on
+      # the row the other holds. Every path that touches several levels in one
+      # transaction takes them in this order.
+      def move_incoming(receivable, sign)
+        destination = receivable.destination_location
+        lines = receivable.items.includes(:variant).sort_by(&:variant_id)
+        levels = destination.stock_levels.where(variant_id: lines.map(&:variant_id)).index_by(&:variant_id)
+
+        lines.each do |item|
+          units = item.incoming
+          next if units.zero?
+
+          level = levels[item.variant_id] || destination.stock_level_or_create(item.variant)
+          level.adjust_incoming_count(sign * units)
+        end
+      end
+    end
+  end
+end

data/app/workflows/spree/refunds/create.rb

@@ -0,0 +1,136 @@
+module Spree
+  module Refunds
+    # Creates a refund and credits it back at the gateway.
+    #
+    # In the workflow tier because the credit is network I/O. The refund row
+    # commits first, then the gateway is called from an external_step — a row
+    # with no transaction_id is recoverable, a gateway credit with no record
+    # is not. On a clean gateway failure the uncredited row is destroyed
+    # (credit_allowed sums every refund row, so a dangling one would block the
+    # retry); a crash between the two leaves the row for reconciliation.
+    class Create < Spree::Workflow
+      hooks :validate, :before_refund, :after_refund
+
+      # The created refund — hook handlers read it (nil during :validate).
+      attr_reader :refund
+
+      # @param payment [Spree::Payment] the captured payment to reverse
+      # @param amount [BigDecimal, Numeric, nil] defaults to the full
+      #   creditable balance
+      # @param reason [Spree::RefundReason, nil] defaults to the store's
+      #   return-processing reason
+      # @param refunder [Object, nil] who is issuing it (see Spree.actor_classes)
+      # @param originator [Object, nil] what triggered the refund — a
+      #   Spree::Return, Exchange or Claim; nil for a manual refund
+      # @param order [Spree::Order, nil] which order is being put right.
+      #   Required only when the payment is shared by a split checkout, where
+      #   it covers several orders and the payment cannot say which one this
+      #   refund is for; otherwise the payment's own order is taken.
+      def perform(payment:, amount: nil, reason: nil, refunder: nil, originator: nil, order: nil)
+        super
+
+        step :ensure_refundable
+        @amount_to_refund = amount || payment.credit_allowed
+        step :ensure_amount_within_balance
+
+        # Veto point — before the refund record exists and before any money
+        # moves back.
+        run_hooks :validate
+        run_hooks :before_refund
+
+        step :create_refund, on_flow_failure: :destroy_uncredited_refund
+        external_step :credit_at_gateway
+
+        run_hooks :after_refund
+        payment.publish_event('payment.refunded')
+        success(refund)
+      end
+
+      private
+
+      def ensure_refundable
+        failure(payment, :payment_not_refundable) unless payment.completed?
+      end
+
+      def ensure_amount_within_balance
+        amount = @amount_to_refund.to_d
+        return if amount.positive? && amount <= payment.credit_allowed.to_d && amount <= refundable_share
+
+        failure(payment, :refund_amount_exceeds_balance)
+      end
+
+      # What the named order may take back from this payment.
+      #
+      # A payment shared by a split checkout holds several orders' money, and
+      # the whole-payment balance says nothing about whose. Without this bound,
+      # refunding one seller's order for more than it was paid would quietly
+      # spend a sibling's captured share — the money would go back to the
+      # customer, and the other seller would find nothing left to draw.
+      #
+      # @return [BigDecimal] the payment's own balance when it is not shared
+      def refundable_share
+        return payment.credit_allowed.to_d unless payment.grouped?
+
+        split = order && payment.payment_splits.find_by(order_id: order.id)
+        return 0 if split.nil?
+
+        split.refundable_amount
+      end
+
+      # The row is what reserves the balance — credit_allowed sums refund rows —
+      # so creation serializes on the payment's row lock. Without it the
+      # balance validation is check-then-act, and two concurrent refunds would
+      # both validate against the pre-refund balance and both credit.
+      #
+      # The per-order share is re-read inside the lock for the same reason.
+      # `Spree::Refund` validates against `credit_allowed`, which is the whole
+      # payment's balance and says nothing about whose money it is — so on a
+      # shared payment the model cannot catch two refunds that each fit the
+      # payment but together overdraw one child's share.
+      def create_refund
+        payment.with_lock do
+          ensure_share_still_available
+
+          @refund = payment.refunds.create!(
+            amount: @amount_to_refund,
+            order: order || payment.order,
+            reason: reason || Spree::RefundReason.return_processing_reason(refund_store),
+            refunder: refunder,
+            originator: originator
+          )
+        end
+      end
+
+      # Re-reads the named order's remaining share now that the payment's row
+      # is locked, so a sibling refund that landed since the pre-flight check
+      # is counted.
+      def ensure_share_still_available
+        return unless payment.grouped?
+
+        payment.payment_splits.reload
+        failure(payment, :refund_amount_exceeds_balance) if @amount_to_refund.to_d > refundable_share
+      end
+
+      # The store the default reason belongs to. A payment shared by a split
+      # checkout has no order of its own, so it is asked through whichever
+      # order is being refunded — and failing that the current store, since a
+      # store-less reason would be created global and reused everywhere.
+      def refund_store
+        (order || payment.order)&.store || payment.owner&.store || Spree::Current.store
+      end
+
+      def credit_at_gateway
+        refund.perform!
+      rescue Spree::Core::GatewayError => error
+        failure(refund, error.message)
+      end
+
+      # Runs when a step after create_refund fails. Only an uncredited row is
+      # destroyed — a present transaction_id means the money moved, and the
+      # record must survive whatever failed afterwards.
+      def destroy_uncredited_refund
+        refund.destroy! if refund&.transaction_id.blank?
+      end
+    end
+  end
+end

data/app/workflows/spree/refunds/order_payments.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Spree
+  module Refunds
+    # Gives a post-sale workflow one way to put money back on an order.
+    #
+    # Returns, claims and exchanges all owe the customer money for the same
+    # reason — goods that are going back, or were never right — and all three
+    # drained `order.payments` to pay it. That reads nothing on a marketplace
+    # order: a split checkout takes one charge against the
+    # {Spree::OrderGroup}, so a child order holds no payments of its own and
+    # every one of the three failed with "no refundable payments" on the
+    # orders a seller is most likely to be refunding.
+    #
+    # What a child order holds instead is a {Spree::PaymentSplit} per group
+    # payment — its own authorised, captured and refunded share. Refunding
+    # through the share is what keeps one seller's refund from spending a
+    # sibling's captured money, and it is the same shape
+    # {Spree::Orders::Cancel} already settles a canceled child order with.
+    module OrderPayments
+      extend ActiveSupport::Concern
+
+      private
+
+      # Puts `amount` back on `order`, oldest payment first, until it is
+      # covered.
+      #
+      # A split-tender order needs more than one refund, so this drains rather
+      # than picking one payment; oldest first, which is the order the customer
+      # paid in and the order both branches below read in.
+      #
+      # Every row goes through {Spree::Refunds::Create}, which owns the
+      # row-locked balance check, the gateway credit, the declined-row
+      # compensation, the refund hooks and the `payment.refunded` event — so
+      # nothing here talks to a gateway itself.
+      #
+      # @param order [Spree::Order] the order being put right
+      # @param amount [BigDecimal] how much to give back
+      # @param record [Spree::Return, Spree::Claim, Spree::Exchange] what asked
+      #   for the refund; it originates the rows and carries any failure
+      # @param refunder [Object, nil] whoever is issuing it
+      # @return [Array<Spree::Refund>] the refunds written, in drain order
+      def refund_order_payments(order:, amount:, record:, refunder: nil)
+        remaining = amount.to_d
+        refunds = []
+        shares = refundable_shares(order)
+        # Resolved once rather than per payment — but only once there is
+        # something to refund, since it is a find_or_create_by and a run that
+        # refunds nothing should leave no reason row behind.
+        reason = Spree::RefundReason.return_processing_reason(record.store) if shares.any?
+
+        shares.each do |payment, refundable|
+          break unless remaining.positive?
+
+          creditable = [refundable, remaining].min
+          next unless creditable.positive?
+
+          result = Spree.refund_create_workflow.call(
+            payment: payment,
+            amount: creditable,
+            order: order,
+            reason: reason,
+            refunder: refunder,
+            originator: record
+          )
+          # `failure` raises, so this ends the drain — the caller's own error
+          # vocabulary decorates the 422.
+          failure(record, result.error.value) if result.failure?
+
+          refunds << result.value
+          remaining -= creditable
+        end
+
+        refunds
+      end
+
+      # What each of the order's completed payments can still give back to
+      # *this* order.
+      #
+      # On an ordinary order that is the payment's own balance. On a child of
+      # a split checkout it is that child's share: `credit_allowed` sums the
+      # refunds of every child against the whole charge, so measuring one
+      # seller's refund by it would let them draw on headroom their sibling's
+      # sale is holding.
+      #
+      # @param order [Spree::Order]
+      # @return [Hash{Spree::Payment => BigDecimal}]
+      def refundable_shares(order)
+        unless order.grouped?
+          return order.payments.completed.order(:created_at).
+                 to_h { |payment| [payment, payment.credit_allowed.to_d] }
+        end
+
+        # One query for the whole run rather than one per share — this runs
+        # ahead of a gateway round trip per payment, and there is no reason to
+        # add N more of its own.
+        refunded = Spree::Refund.where(order_id: order.id).group(:payment_id).sum(:amount)
+
+        order.payment_splits.includes(:payment).order(:created_at).each_with_object({}) do |split, found|
+          next unless split.payment&.completed?
+          next if capture_in_flight?(order, split)
+
+          found[split.payment] = split.captured_amount - refunded.fetch(split.payment_id, 0)
+        end
+      end
+
+      # Whether a charge against this share is still in flight.
+      #
+      # A parcel reserves what it is about to draw before asking the gateway,
+      # so a share can read captured while the charge is still landing.
+      # Refunding through it would hand back money nobody has taken yet, so it
+      # is reported for the operator rather than guessed at — the same call
+      # {Spree::Orders::Cancel} makes when it meets one.
+      #
+      # @return [Boolean]
+      def capture_in_flight?(order, split)
+        return false unless split.capture_in_flight?
+
+        Rails.error.report(
+          Spree::Core::GatewayError.new('Payment share is mid-capture; refund left it for manual settlement'),
+          handled: true,
+          context: { order_id: order.id, payment_split_id: split.id },
+          source: 'spree.core'
+        )
+        true
+      end
+    end
+  end
+end