spree_core 6.0.0.beta4 → 6.0.0.rc2

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

@@ -0,0 +1,46 @@
+module Spree
+  module Receivables
+    # Ends a purchase order or transfer whose missing units are not going to
+    # turn up. Nothing is written to any shelf: closing short keeps what was
+    # received, records why the rest never arrived, and leaves the outstanding
+    # count on each line as the record of the gap. The including workflow
+    # names the document (`receivable`).
+    module ClosingShort
+      include IncomingCounter
+
+      private
+
+      def close
+        receivable.with_lock do
+          step :ensure_closable
+          run_hooks :validate
+          step :uncount_awaited_units
+          step :close_short
+        end
+
+        run_hooks :after_close
+        receivable.publish_event("#{receivable.event_prefix}.received")
+        success(receivable.reload)
+      end
+
+      def ensure_closable
+        return if receivable.partially_received?
+
+        failure(receivable, I18n.t("spree.#{receivable.event_prefix}.errors.not_partially_received"))
+      end
+
+      # The balance is not coming, so it leaves the destination's incoming
+      # figure; each line's outstanding count keeps the record.
+      def uncount_awaited_units
+        uncount_incoming(receivable)
+      end
+
+      def close_short
+        now = Time.current
+        attributes = { status: 'received', received_at: now, closed_short_at: now, close_reason: reason.presence }
+
+        failure(receivable) unless receivable.update(attributes)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,48 @@
+module Spree
+  module Receivables
+    # Edits a draft purchase order or transfer. Past `draft` the document is a
+    # matter of record, so the edit is refused rather than quietly rewriting
+    # something a supplier or warehouse is already acting on. The including
+    # workflow names the document (`receivable`) and the line columns callers
+    # may set (`item_attributes`).
+    module DraftEditing
+      private
+
+      def edit
+        step :ensure_editable
+        run_hooks :validate
+
+        ApplicationRecord.transaction do
+          step :apply_changes
+          step :save_document
+        end
+
+        run_hooks :after_update
+        success(receivable.reload)
+      end
+
+      def ensure_editable
+        return if receivable.editable?
+
+        failure(receivable, I18n.t("spree.#{receivable.event_prefix}.errors.not_editable"))
+      end
+
+      # A whole-list replacement rather than a per-line diff: a draft's lines
+      # are what the merchant is still deciding, and sending the list they
+      # want is simpler for a client than working out which rows to delete.
+      def apply_changes
+        receivable.assign_attributes(attributes) if attributes.present?
+        return if items.nil?
+
+        receivable.items.destroy_all
+        Array(items).each do |item|
+          receivable.items.build(variant: item[:variant], **item_attributes.index_with { |key| item[key] })
+        end
+      end
+
+      def save_document
+        failure(receivable) unless receivable.save
+      end
+    end
+  end
+end

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

@@ -26,7 +26,9 @@ module Spree
       #   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)
+      # @param tax_amount [BigDecimal, Numeric] the tax inside +amount+, when
+      #   what is being refunded carried tax (see Spree::Refund#tax_amount)
+      def perform(payment:, amount: nil, reason: nil, refunder: nil, originator: nil, order: nil, tax_amount: 0)
         super
 
         step :ensure_refundable
@@ -96,7 +98,8 @@ module Spree
             order: order || payment.order,
             reason: reason || Spree::RefundReason.return_processing_reason(refund_store),
             refunder: refunder,
-            originator: originator
+            originator: originator,
+            tax_amount: tax_amount
           )
         end
       end

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

@@ -91,9 +91,12 @@ module Spree
       # @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
+      # @param tax_amount [BigDecimal] the tax inside +amount+, divided across
+      #   the rows in proportion to what each refunds
       # @return [Array<Spree::Refund>] the refunds written, in drain order
-      def refund_order_payments(order:, amount:, record:, refunder: nil)
+      def refund_order_payments(order:, amount:, record:, refunder: nil, tax_amount: 0)
         remaining = amount.to_d
+        tax_remaining = tax_amount.to_d
         refunds = []
         shares = refundable_shares(order)
         # With no payment to draw on the caller reports that instead.
@@ -109,13 +112,21 @@ module Spree
           creditable = [refundable, remaining].min
           next unless creditable.positive?
 
+          # The last row takes what is left, so the rows' tax adds up exactly.
+          row_tax = if creditable == remaining
+                      tax_remaining
+                    else
+                      Spree::Money::Rounding.to_currency(tax_amount.to_d * creditable / amount.to_d, order.currency)
+                    end
+
           result = Spree.refund_create_workflow.call(
             payment: payment,
             amount: creditable,
             order: order,
             reason: reason,
             refunder: refunder,
-            originator: record
+            originator: record,
+            tax_amount: row_tax
           )
           # `failure` raises, so this ends the drain — the caller's own error
           # vocabulary decorates the 422.
@@ -123,6 +134,7 @@ module Spree
 
           refunds << result.value
           remaining -= creditable
+          tax_remaining -= row_tax
         end
 
         refunds

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

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Spree
+  module Refunds
+    # The tax half of putting money back: asking the order's tax provider what
+    # tax goes back with it, and filing the credit once the money has moved.
+    #
+    # Shared by returns, claims and exchanges, which give back tax for the same
+    # reason they give back money (see Spree::PostSale::Taxation).
+    module TaxCredit
+      extend ActiveSupport::Concern
+
+      private
+
+      # Runs a provider calculation, refusing the step when the provider could
+      # not answer. Going on would refund tax nobody worked out — too little,
+      # and the customer is short; none, and the merchant finds out in a filing.
+      def with_tax_provider(record)
+        yield
+      rescue Spree::Tax::ProviderError => error
+        Rails.error.report(error, handled: true, context: tax_report_context(record), source: 'spree.post_sale')
+
+        # A refusal names its own problem; an outage is worth retrying, and its
+        # raw message names the endpoint rather than anything the caller can fix.
+        failure(record, error.is_a?(Spree::Tax::CalculationRefused) ? error.message.to_s : :tax_provider_unavailable)
+      end
+
+      # A record withdrawn before anything went back loses its rows — left in
+      # place they would count against what a later return of the same units
+      # may credit.
+      def clear_tax_credit(record)
+        record.clear_tax!
+      end
+
+      # Files the credit with the provider after the money has moved.
+      # Reported rather than raised: the refund has gone through and the record
+      # is already settled, so failing here would fail a refund that happened.
+      def file_tax_credit(record, lines, amount)
+        order = record.order
+        order.tax_provider.refund(order, lines, amount: amount, tax_date: order.completed_at)
+      rescue Spree::Tax::ProviderError => error
+        Rails.error.report(error, handled: true, context: tax_report_context(record), source: 'spree.post_sale')
+      end
+
+      # Divides a refund across lines in proportion to what each is worth, to
+      # the cent, so the tax given back on each line follows the money on it.
+      #
+      # @param amount [BigDecimal]
+      # @param worth [Hash{Object => BigDecimal}] line => what it is worth
+      # @param currency [String]
+      # @return [Hash{Object => BigDecimal}]
+      def allocate_refund(amount, worth, currency)
+        weights = worth.values.map { |value| Spree::Money::Rounding.to_minor_units(value, currency) }
+        return worth.transform_values { 0.to_d } if weights.sum.zero?
+
+        shares = Spree::Adjusters::LargestRemainder.largest_remainder_shares(
+          Spree::Money::Rounding.to_minor_units(amount, currency), weights
+        )
+        worth.keys.zip(shares).to_h { |line, cents| [line, Spree::Money::Rounding.from_minor_units(cents, currency)] }
+      end
+
+      def tax_report_context(record)
+        { record_type: record.class.name, record_id: record.id, order_id: record.order_id }
+      end
+    end
+  end
+end

data/app/workflows/spree/returns/approve.rb

@@ -10,38 +10,21 @@ module Spree
     # 6.0-delivery-rate-provider.md; a store needing one before then can put
     # the URL in the return's `metadata`.
     class Approve < Spree::Workflow
+      include Spree::PostSale::Approval
+
       hooks :validate, :after_approve
 
       # @param return_record [Spree::Return]
       # @param approver [Object, nil] who is approving it (see Spree.actor_classes)
       def perform(return_record:, approver: nil)
         super
-
-        step :ensure_approvable
-        run_hooks :validate
-
-        ApplicationRecord.transaction do
-          step :mark_approved
-        end
-
-        run_hooks :after_approve
-        return_record.publish_event('return.approved')
-        success(return_record.reload)
+        approve
       end
 
       private
 
-      def ensure_approvable
-        failure(return_record, :not_requested) unless return_record.requested?
-      end
-
-      def mark_approved
-        return_record.update!(
-          status: 'approved',
-          approved_at: Time.current,
-          created_by: return_record.created_by || approver
-        )
-      end
+      def post_sale_record = return_record
+      def approvable_status = 'requested'
     end
   end
 end

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

@@ -7,6 +7,8 @@ module Spree
     # holding the customer's items, and the way out is a refund, not a
     # cancellation.
     class Cancel < Spree::Workflow
+      include Spree::PostSale::Cancellation
+
       hooks :validate, :after_cancel
 
       # @param return_record [Spree::Return]
@@ -14,39 +16,20 @@ module Spree
       def perform(return_record:, reason: nil)
         super
 
-        step :ensure_cancellable
-        run_hooks :validate
-
-        ApplicationRecord.transaction do
-          step :mark_canceled
-        end
-
         # Carrier I/O, after the status is committed: a customer who abandons
         # a return must not be left holding live prepaid postage the merchant
         # is still paying for.
-        external_step :refund_prepaid_label
-
-        run_hooks :after_cancel
-        return_record.publish_event('return.canceled')
-        success(return_record.reload)
+        cancel { external_step :refund_prepaid_label }
       end
 
       private
 
-      def ensure_cancellable
-        return if return_record.requested? || return_record.approved?
-
-        failure(return_record, :not_cancellable)
-      end
+      def post_sale_record = return_record
+      def cancellable_statuses = %w[requested approved]
 
       def refund_prepaid_label
         Spree::Fulfillments::StandDownProvider.refund_labels(return_record)
       end
-
-      def mark_canceled
-        memo = [return_record.memo, reason].compact_blank.join("\n")
-        return_record.update!(status: 'canceled', canceled_at: Time.current, memo: memo.presence)
-      end
     end
   end
 end

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

@@ -8,6 +8,7 @@ module Spree
     # commerce and deliberately does not live in core.
     class Create < Spree::Workflow
       include Spree::Returns::ReturnableQuantity
+      include Spree::Refunds::TaxCredit
 
       hooks :validate, :after_create
 
@@ -32,8 +33,11 @@ module Spree
         # is written.
         run_hooks :validate
 
+        # The tax is worked out with the return rather than after it, so no
+        # return ever offers a refund whose tax nobody calculated.
         ApplicationRecord.transaction do
           step :build_return
+          step :calculate_tax
         end
 
         run_hooks :after_create
@@ -93,6 +97,10 @@ module Spree
         failure(@return_record) unless @return_record.save
       end
 
+      def calculate_tax
+        with_tax_provider(return_record) { return_record.calculate_tax! }
+      end
+
       # Where goods come back to when nobody said. Goods return where they
       # shipped from, which is right until a merchant runs a dedicated
       # returns centre — so a location that has opted out of receiving them

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

@@ -1,13 +1,9 @@
 module Spree
   module Returns
-    # Records what the warehouse actually received.
-    #
-    # Partial and damaged receipt is the normal case, not an edge case: the
-    # customer said three items were coming, two arrived, one of those is not
-    # resellable. Quantities and resellable flags therefore come from the
-    # caller rather than from the request, which is precisely what a state
-    # machine transition could not express.
+    # Records what the warehouse actually received (see Spree::PostSale::Receipt).
     class Receive < Spree::Workflow
+      include Spree::PostSale::Receipt
+
       hooks :validate, :before_restock, :after_receive
 
       # @param return_record [Spree::Return]
@@ -16,79 +12,12 @@ module Spree
       # @param received_by [Object, nil]
       def perform(return_record:, items: nil, received_by: nil)
         super
-
-        step :ensure_receivable
-        step :normalize_items
-        run_hooks :validate
-
-        ApplicationRecord.transaction do
-          step :record_receipt
-          run_hooks :before_restock
-          step :restock_resellable_items
-          step :mark_received
-        end
-
-        run_hooks :after_receive
-        return_record.publish_event('return.received')
-        success(return_record.reload)
+        receive
       end
 
       private
 
-      def ensure_receivable
-        failure(return_record, :not_approved) unless return_record.approved?
-      end
-
-      def normalize_items
-        @normalized_items =
-          if items.nil?
-            return_record.return_line_items.map do |line|
-              { return_line_item: line, quantity: line.quantity, resellable: true }
-            end
-          else
-            items.map { |item| normalize_item(item) }
-          end
-
-        failure(return_record, :no_items_received) if @normalized_items.sum { |item| item[:quantity] }.zero?
-      end
-
-      def normalize_item(item)
-        line = item[:return_line_item]
-        quantity = item[:quantity].to_i
-
-        failure(return_record, :item_not_on_return) unless line&.return_id == return_record.id
-        failure(return_record, :invalid_quantity) if quantity.negative? || quantity > line.quantity
-
-        { return_line_item: line, quantity: quantity, resellable: item.fetch(:resellable, true) }
-      end
-
-      def record_receipt
-        @normalized_items.each do |item|
-          item[:return_line_item].update!(
-            received_quantity: item[:quantity],
-            resellable: item[:resellable]
-          )
-        end
-      end
-
-      # Only resellable goods go back into sellable stock — a damaged return
-      # is received but never restocked.
-      def restock_resellable_items
-        @normalized_items.each do |item|
-          next unless item[:resellable]
-          next unless item[:quantity].positive?
-
-          return_record.stock_location.restock(
-            item[:return_line_item].variant,
-            item[:quantity],
-            return_record
-          )
-        end
-      end
-
-      def mark_received
-        return_record.update!(status: 'received', received_at: Time.current)
-      end
+      def post_sale_record = return_record
     end
   end
 end

data/app/workflows/spree/returns/refund.rb

@@ -9,6 +9,7 @@ module Spree
     # a crash leaves a refunded return with no credit issued.
     class Refund < Spree::Workflow
       include Spree::Refunds::OrderPayments
+      include Spree::Refunds::TaxCredit
 
       hooks :validate, :before_refund, :after_refund
 
@@ -30,7 +31,13 @@ module Spree
         run_hooks :validate
         run_hooks :before_refund
 
-        if internal_refund?
+        step :settle_tax unless @amount_to_refund.zero?
+
+        # Nothing is owed (a free gift sent back), so the return closes
+        # without a refund row, store credit or tax credit.
+        if @amount_to_refund.zero?
+          step :mark_refunded
+        elsif internal_refund?
           ApplicationRecord.transaction do
             step :issue_store_credit
             step :mark_refunded
@@ -40,7 +47,7 @@ module Spree
           step :mark_refunded
         end
 
-        external_step :refund_tax
+        external_step :refund_tax unless @amount_to_refund.zero?
         run_hooks :after_refund
         return_record.publish_event('return.refunded')
         success(return_record.reload)
@@ -62,8 +69,20 @@ module Spree
         received = return_record.return_line_items.select { |line| line.refund_amount.positive? }
         return if received.empty?
 
-        order = return_record.order
-        order.tax_provider.refund(order, received, amount: @amount_to_refund, tax_date: order.completed_at)
+        file_tax_credit(return_record, received, @amount_to_refund)
+      end
+
+      # Rewrites the credit rows for what actually goes back — the units that
+      # arrived, and of those only the part of their worth being refunded —
+      # before any money moves, so the refund carries exactly the tax the rows
+      # record.
+      def settle_tax
+        lines = return_record.return_line_items.to_a
+        short = @amount_to_refund < return_record.refund_total
+        amounts = allocate_refund(@amount_to_refund, lines.index_with(&:refund_amount), return_record.currency) if short
+
+        with_tax_provider(return_record) { return_record.settle_tax!(amounts: amounts) }
+        @tax_amount = return_record.credited_tax_total
       end
 
       def internal_refund?
@@ -76,7 +95,7 @@ module Spree
           # attribute, and ActiveModel raises when an error names one that
           # does not exist on the record.
           return_record.errors.add(:base, :invalid_refund_method,
-                           message: Spree.t('errors.messages.invalid_refund_method'))
+                           message: I18n.t('spree.errors.messages.invalid_refund_method'))
           failure(return_record)
         end
         failure(return_record, :not_received) unless return_record.received?
@@ -85,12 +104,15 @@ module Spree
       # Only what actually came back is refundable — a customer who sent two of
       # three items gets two items' worth. One figure serves as both the
       # default and the ceiling, so a caller naming an amount cannot ask for
-      # more than a caller who names none would get.
+      # more than a caller who names none would get. Zero is accepted only when
+      # zero is owed, so a return the customer is owed money on cannot be
+      # closed without paying them.
       def resolve_amount
         refundable = return_record.refundable_total.to_d
         @amount_to_refund = amount ? amount.to_d : refundable
 
-        failure(return_record, :nothing_to_refund) unless @amount_to_refund.positive?
+        failure(return_record, :refund_amount_negative) if @amount_to_refund.negative?
+        failure(return_record, :refund_amount_required) if @amount_to_refund.zero? && refundable.positive?
         failure(return_record, :refund_exceeds_balance) if @amount_to_refund > refundable
       end
 
@@ -111,7 +133,8 @@ module Spree
           order: return_record.order,
           amount: @amount_to_refund,
           record: return_record,
-          refunder: refunder
+          refunder: refunder,
+          tax_amount: @tax_amount
         )
 
         failure(return_record, :no_refundable_payments) if @refunds.empty?

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

@@ -82,8 +82,7 @@ module Spree
         return unless requirement.class.requires_file?
         return if submission.file.attached?
 
-        errors.add(:file, :blank, message: Spree.t('seller_requirements.file_required',
-                                                   default: 'A file is required for this requirement'))
+        errors.add(:file, :blank, message: I18n.t('spree.seller_requirements.file_required'))
         failure(submission, errors)
       end
 

data/app/workflows/spree/seller_transfers/reverse.rb

@@ -102,9 +102,17 @@ module Spree
         gross = amounts.values.sum.to_d
         return if gross <= 0
 
+        taxes = refund.refunded_line_taxes
+
         # Nil from any line means the attribution cannot be trusted whole, so
         # the blend answers for the refund rather than part of it.
-        earnings = amounts.map { |line_item_id, amount| line_earning(line_item_id, amount.to_d) }
+        earnings = amounts.map do |line_item_id, amount|
+          if taxes.key?(line_item_id)
+            line_goods_earning(line_item_id, amount.to_d, taxes[line_item_id].to_d)
+          else
+            line_earning(line_item_id, amount.to_d)
+          end
+        end
         return if earnings.any?(&:nil?)
 
         quantize(earnings.sum * (refunded.to_d.abs / gross))
@@ -124,6 +132,9 @@ module Spree
       # The commission comes from the row written against that line at
       # placement, not from today's rate: rates change, a clamped fee is not the
       # rate times the base, and a fixed rate is charged per unit.
+      #
+      # This is the reading for a refund that cannot say how much tax it gave
+      # back — a return or claim opened before they carried tax.
       def line_earning(line_item_id, amount)
         line_item = order_line_items[line_item_id]
         paid = line_item&.amount.to_d
@@ -141,6 +152,22 @@ module Spree
         earned
       end
 
+      # The same for a refund that knows the tax it gave back on the line. The
+      # goods in it are measured against the line's worth before tax, after
+      # discounts, and carry their share of the commission; the tax goes back
+      # only when the seller collected it — when the marketplace remits it, the
+      # seller never had it to return.
+      def line_goods_earning(line_item_id, amount, tax)
+        line_item = order_line_items[line_item_id]
+        worth = line_item ? [line_item.discounted_amount.to_d, 0].max - line_item.included_tax_total.to_d : 0.to_d
+        return unless worth.positive?
+
+        goods = amount - tax
+        earned = goods - (commission_totals[line_item_id].to_d * goods / worth)
+        earned += tax unless order.seller&.tax_remittance == 'platform'
+        earned
+      end
+
       def order_line_items
         @order_line_items ||= order.line_items.index_by(&:id)
       end

data/app/workflows/spree/shipping_labels/purchase.rb

@@ -51,15 +51,15 @@ module Spree
       end
 
       def ensure_purchasable
-        failure(owner, Spree.t('shipping_labels.errors.provider_has_no_labels')) unless provider.class.generates_labels?
-        failure(owner, Spree.t('shipping_labels.errors.already_purchased')) if owner.shipping_labels.active.exists?
+        failure(owner, I18n.t('spree.shipping_labels.errors.provider_has_no_labels')) unless provider.class.generates_labels?
+        failure(owner, I18n.t('spree.shipping_labels.errors.already_purchased')) if owner.shipping_labels.active.exists?
 
         case owner
         when Spree::Fulfillment
-          failure(owner, Spree.t('fulfillments.errors.cannot_purchase_label')) unless owner.unfulfilled?
-          failure(owner, Spree.t('fulfillments.errors.order_draft')) if owner.order&.draft?
+          failure(owner, I18n.t('spree.fulfillments.errors.cannot_purchase_label')) unless owner.unfulfilled?
+          failure(owner, I18n.t('spree.fulfillments.errors.order_draft')) if owner.order&.draft?
         when Spree::Return
-          failure(owner, Spree.t('shipping_labels.errors.return_closed')) if owner.received? || owner.refunded? || owner.canceled?
+          failure(owner, I18n.t('spree.shipping_labels.errors.return_closed')) if owner.received? || owner.refunded? || owner.canceled?
         end
       end
 
@@ -71,7 +71,7 @@ module Spree
       # re-read inside it.
       def claim_purchase
         owner.with_lock do
-          failure(owner, Spree.t('shipping_labels.errors.already_purchased')) if owner.shipping_labels.active.exists?
+          failure(owner, I18n.t('spree.shipping_labels.errors.already_purchased')) if owner.shipping_labels.active.exists?
 
           @shipping_label = owner.shipping_labels.create!(
             store: owner.store,
@@ -81,7 +81,7 @@ module Spree
           )
         end
       rescue ActiveRecord::RecordNotUnique
-        failure(owner, Spree.t('shipping_labels.errors.already_purchased'))
+        failure(owner, I18n.t('spree.shipping_labels.errors.already_purchased'))
       end
 
       # Undoes the claim when the carrier refuses, so a failed purchase does
@@ -105,7 +105,7 @@ module Spree
 
         return if @purchase.is_a?(Spree::LabelPurchase) && @purchase.valid?
 
-        failure(owner, Spree.t('fulfillments.errors.label_purchase_failed'))
+        failure(owner, I18n.t('spree.fulfillments.errors.label_purchase_failed'))
       rescue Spree::Core::LabelPurchaseRefused => e
         failure(owner, e.message)
       end