spree_core 5.5.2 → 5.6.0.rc1

data/app/models/spree/taxon.rb

@@ -4,6 +4,8 @@ require 'stringex'
 
 module Spree
   class Taxon < Spree.base_class
+    include Spree::SingleStoreResource
+
     has_prefix_id :ctg
 
     RULES_MATCH_POLICIES = %w[all any].freeze
@@ -37,7 +39,7 @@ module Spree
     # Associations
     #
     belongs_to :taxonomy, class_name: 'Spree::Taxonomy', inverse_of: :taxons
-    has_one :store, through: :taxonomy
+    belongs_to :store, class_name: 'Spree::Store', optional: true
     has_many :classifications, -> { order(:position) }, dependent: :destroy_async, inverse_of: :taxon
     has_many :products, through: :classifications
 
@@ -56,9 +58,16 @@ module Spree
     #
     # Validations
     #
-    validates :name, presence: true, uniqueness: { scope: %i[parent_id taxonomy_id], case_sensitive: false }
-    validates :taxonomy, presence: true
-    validates :permalink, uniqueness: { case_sensitive: false, scope: %i[parent_id taxonomy_id] }
+    validates :name, presence: true
+    validates :taxonomy, presence: true, if: :requires_taxonomy?
+    validates :store, presence: true
+    # Taxonomy-backed taxons are unique within their taxonomy; taxonomy-less
+    # categories (store-owned) are unique within their store, so two stores can
+    # each have a top-level "Shoes".
+    validates :name, uniqueness: { scope: %i[parent_id taxonomy_id], case_sensitive: false }, if: :requires_taxonomy?
+    validates :permalink, uniqueness: { scope: %i[parent_id taxonomy_id], case_sensitive: false }, if: :requires_taxonomy?
+    validates :name, uniqueness: { scope: %i[parent_id store_id], case_sensitive: false }, unless: :requires_taxonomy?
+    validates :permalink, uniqueness: { scope: %i[parent_id store_id], case_sensitive: false }, unless: :requires_taxonomy?
     validates :hide_from_nav, inclusion: { in: [true, false] }
     validate :check_for_root, on: :create
     validate :parent_belongs_to_same_taxonomy
@@ -81,13 +90,32 @@ module Spree
     after_commit :regenerate_pretty_name_and_permalink, on: :update, if: :should_regenerate_pretty_name_and_permalink?
     after_move :regenerate_pretty_name_and_permalink
     after_move :regenerate_translations_pretty_name_and_permalink
+    # Moving a subtree shifts its products under a new ancestor chain (and away
+    # from the old one), so recompute both branches' inclusive products_count.
+    # Capture the old parent before the move; recompute both chains after.
+    before_move :capture_parent_before_move
+    after_move :recalculate_products_count_after_move
+    # Destroying a taxon drops its subtree's products from every ancestor's
+    # inclusive count. Recompute the ancestors here (while the doomed subtree's
+    # rows still exist) excluding that subtree, since the Classification destroy
+    # callbacks can't help: classifications are removed via destroy_async, so
+    # they outlive this callback and their taxon may already be gone.
+    before_destroy :recalculate_ancestors_before_destroy, prepend: true
 
     #
     # Scopes
     #
-    scope :for_store, ->(store) { joins(:taxonomy).where(spree_taxonomies: { store_id: store.id }) }
-    scope :for_stores, ->(stores) { joins(:taxonomy).where(spree_taxonomies: { store_id: stores.ids }) }
+    # Prefer the direct store_id column; fall back to the taxonomy join for rows
+    # not yet backfilled (store_id IS NULL) so legacy behaviour is preserved.
+    scope :for_store, ->(store) { for_stores([store]) }
+    scope :for_stores, lambda { |stores|
+      store_ids = Array(stores).map(&:id)
+      taxonomy_ids = Spree::Taxonomy.where(store_id: store_ids).select(:id)
+      where(store_id: store_ids).or(where(store_id: nil, taxonomy_id: taxonomy_ids))
+    }
     scope :for_taxonomy, lambda { |taxonomy_name|
+      Spree::Deprecation.warn('Spree::Taxon.for_taxonomy is deprecated and will be removed in Spree 6. Please use for_store instead.')
+
       if Spree.use_translations?
         joins(:taxonomy)
           .join_translation_table(Taxonomy)
@@ -121,13 +149,14 @@ module Spree
     #
     self.whitelisted_ransackable_associations = %w[taxonomy parent]
     self.whitelisted_ransackable_attributes = %w[name permalink automatic depth is_root children_count
-                                                 classification_count hide_from_nav parent_id]
+                                                 classification_count products_count pretty_name hide_from_nav parent_id]
 
     #
     # Translations
     #
     TRANSLATABLE_FIELDS = %i[name pretty_name description permalink].freeze
-    translates(*TRANSLATABLE_FIELDS, column_fallback: !Spree.always_use_translations?)
+    RICH_TEXT_TRANSLATABLE_FIELDS = %i[description].freeze
+    translates(*TRANSLATABLE_FIELDS, column_fallback: Spree.mobility_column_fallback)
 
     #
     # Action Text
@@ -154,6 +183,18 @@ module Spree
       !automatic?
     end
 
+    # The owning store. Prefers the direct +store_id+; falls back to the
+    # taxonomy's store for legacy rows not yet backfilled.
+    def store
+      super || taxonomy&.store
+    end
+
+    # Whether a taxonomy is mandatory. Legacy +Spree::Taxon+ requires one;
+    # +Spree::Category+ overrides this to false (it is owned via +store_id+).
+    def requires_taxonomy?
+      true
+    end
+
     def manual_sort_order?
       sort_order == 'manual'
     end
@@ -169,6 +210,26 @@ module Spree
                                                  )
     end
 
+    # Recomputes the stored, descendant-inclusive +products_count+ for the given
+    # taxons AND all of their ancestors — the nodes whose inclusive count can
+    # shift when a classification changes. Counts unique products classified
+    # under each node or its descendants (a product reachable through several
+    # nodes is counted once per ancestor). Call after any classification change.
+    #
+    # @param taxon_ids [Array<Integer>] taxons whose branch counts changed
+    def self.recalculate_products_count(taxon_ids)
+      changed = unscoped.where(id: Array(taxon_ids).compact.uniq)
+
+      # The affected nodes are each changed taxon plus its ancestors.
+      affected = changed.flat_map { |taxon| taxon.self_and_ancestors.to_a }.uniq(&:id)
+
+      affected.each do |taxon|
+        count = Spree::Classification.where(taxon_id: taxon.self_and_descendants.select(:id))
+                                     .distinct.count(:product_id)
+        taxon.update_column(:products_count, count) if taxon.products_count != count
+      end
+    end
+
     def products_matching_rules(opts = {})
       return Spree::Product.none if manual? || rules.empty?
 
@@ -379,6 +440,7 @@ module Spree
     end
 
     def sync_taxonomy_name
+      return unless taxonomy.present?
       return unless saved_changes.key?(:name) && root?
       return if taxonomy.name.to_s == name.to_s
 
@@ -389,7 +451,33 @@ module Spree
       # Touches all ancestors at once to avoid recursive taxonomy touch, and reduce queries.
       ancestors.update_all(updated_at: Time.current)
       # Have taxonomy touch happen in #touch_ancestors_and_taxonomy rather than association option in order for imports to override.
-      taxonomy.try!(:touch)
+      taxonomy.touch if taxonomy.present?
+    end
+
+    def capture_parent_before_move
+      @parent_id_before_move = parent_id_in_database
+    end
+
+    # Recompute the inclusive products_count for the moved node's new ancestor
+    # chain and the previous parent's chain too (whose subtree just lost this
+    # node's products).
+    def recalculate_products_count_after_move
+      affected = [id, @parent_id_before_move].compact
+      @parent_id_before_move = nil
+      self.class.recalculate_products_count(affected)
+    end
+
+    # Recomputes each ancestor's inclusive products_count as if this subtree were
+    # already gone (its classifications are destroyed asynchronously, so they're
+    # still present here). Excludes self_and_descendants from the count.
+    def recalculate_ancestors_before_destroy
+      doomed_ids = self_and_descendants.ids
+      ancestors.each do |ancestor|
+        remaining = Spree::Classification.
+                    where(taxon_id: ancestor.self_and_descendants.where.not(id: doomed_ids).select(:id)).
+                    distinct.count(:product_id)
+        ancestor.update_column(:products_count, remaining) if ancestor.products_count != remaining
+      end
     end
 
     def check_for_root
@@ -408,6 +496,21 @@ module Spree
       self.taxonomy = parent.taxonomy if parent.present? && taxonomy.blank?
     end
 
+    def set_store
+      Spree::Deprecation.warn('Spree::Taxon#set_store is deprecated and will be removed in Spree 6.0. ensure_store instead.')
+      ensure_store
+    end
+
+    # Every taxon is store-owned. Resolve the store from the taxonomy, then the
+    # parent, finally the current store — so the direct column is always
+    # populated for new records. Guards on the raw +store_id+ column rather than
+    # +#store+, whose reader masks an unset column with the taxonomy fallback.
+    def ensure_store
+      return if store_id.present?
+
+      self.store = taxonomy&.store || parent&.store || Spree::Store.current
+    end
+
     def regenerate_translations_pretty_name_and_permalink
       translations.each(&:regenerate_pretty_name_and_permalink)
     end

data/app/models/spree/taxonomy.rb

@@ -8,7 +8,7 @@ module Spree
     include Spree::SingleStoreResource
 
     TRANSLATABLE_FIELDS = %i[name].freeze
-    translates(*TRANSLATABLE_FIELDS, column_fallback: !Spree.always_use_translations?)
+    translates(*TRANSLATABLE_FIELDS, column_fallback: Spree.mobility_column_fallback)
 
     acts_as_list
 

data/app/models/spree/translations/batch.rb

@@ -0,0 +1,104 @@
+module Spree
+  module Translations
+    # Atomically upserts translations across MANY records of (possibly)
+    # different translatable resource types in one operation — the domain
+    # behind +POST /api/v3/admin/translations/batch+.
+    #
+    # The input is a flat list of independent registry writes, each naming its
+    # own +resource_type+ + +resource_id+ (no nested parent-owns-children
+    # payload), so there's no per-model branching. Records are resolved within
+    # the current store, then upserted in a single transaction: any failure
+    # rolls back the whole batch and surfaces the offending entry's index via a
+    # typed {EntryError}.
+    #
+    # @example
+    #   Spree::Translations::Batch.new(entries).process! do |record|
+    #     authorize!(:update, record)
+    #   end
+    class Batch
+      include ActiveModel::Model
+
+      # Raised when the batch payload is empty (or not a list of entries).
+      class EmptyError < StandardError; end
+
+      # Raised when an entry can't be processed — unknown/non-translatable
+      # resource type, a record missing in the current store, or an invalid
+      # save. Carries the entry +index+ so the caller can map the error back to
+      # the offending row.
+      class EntryError < StandardError
+        attr_reader :index
+
+        def initialize(message, index)
+          @index = index
+          super(message)
+        end
+      end
+
+      # @return [Array<Spree.base_class>] records written by the last successful {#process!}
+      attr_reader :records
+
+      # @param entries [Array<Hash>] [{ resource_type:, resource_id:, values: { locale => { field => value } } }]
+      def initialize(entries)
+        @entries = Array(entries)
+        @records = []
+      end
+
+      # Distinct +write_<resource>+ scopes a caller needs to authorize this
+      # batch — one per resource type present. Lets the API layer gate an
+      # API-key request without re-deriving scope names.
+      # @return [Array<String>]
+      def required_scopes
+        @entries.map { |entry| "write_#{entry[:resource_type].to_s.pluralize}" }.uniq
+      end
+
+      # Upserts every entry in one transaction. Yields each resolved record
+      # before it is written so the caller can authorize it; a raised error in
+      # the block (or any entry failure) rolls back the whole batch.
+      #
+      # @yieldparam record [Spree.base_class] the resolved record, pre-write
+      # @raise [EmptyError] when there are no entries
+      # @raise [EntryError] when an entry can't be resolved or saved
+      # @return [Array<Spree.base_class>] the written records
+      def process!
+        raise EmptyError if @entries.empty?
+
+        @records = []
+        ActiveRecord::Base.transaction do
+          @entries.each_with_index do |entry, index|
+            record = resolve_record!(entry, index)
+            yield record if block_given?
+            upsert!(record, entry[:values], index)
+            @records << record
+          end
+        end
+        @records
+      end
+
+      private
+
+      def upsert!(record, values, index)
+        record.upsert_translations(values)
+      rescue ActiveRecord::RecordInvalid => e
+        raise EntryError.new(e.record.errors.full_messages.join(', '), index)
+      end
+
+      def resolve_record!(entry, index)
+        klass = resource_class(entry[:resource_type])
+        raise EntryError.new("Unknown translatable resource type: #{entry[:resource_type]}", index) if klass.nil?
+
+        relation = klass.respond_to?(:for_store) ? klass.for_store(Spree::Store.current) : klass
+        relation.find_by_prefix_id!(entry[:resource_id])
+      rescue ActiveRecord::RecordNotFound
+        raise EntryError.new("Resource not found: #{entry[:resource_id]}", index)
+      end
+
+      # Memoized per instance so a batch of N entries doesn't rebuild the
+      # registry map N times. A Batch is request-scoped, so dev-mode class
+      # reloads are still picked up on the next request.
+      def resource_class(token)
+        @resource_class_map ||= Hash.new { |h, t| h[t] = Spree::Translations.resource_class(t) }
+        @resource_class_map[token]
+      end
+    end
+  end
+end

data/app/models/spree/variant.rb

@@ -13,7 +13,7 @@ module Spree
 
     publishes_lifecycle_events
 
-    MEMOIZED_METHODS = %w(purchasable in_stock on_sale backorderable tax_category options_text compare_at_price)
+    MEMOIZED_METHODS = %w(in_stock on_sale backorderable tax_category options_text compare_at_price)
 
     DIMENSION_UNITS = %w[mm cm in ft]
     WEIGHT_UNITS = %w[g kg lb oz]
@@ -88,6 +88,8 @@ module Spree
     validates :dimensions_unit, inclusion: { in: DIMENSION_UNITS }, allow_blank: true
     validates :weight_unit, inclusion: { in: WEIGHT_UNITS }, allow_blank: true
 
+    validates :backorder_limit, numericality: { only_integer: true, greater_than_or_equal_to: 0, allow_nil: true }
+
     after_create :create_stock_items
     after_create :set_master_out_of_stock, unless: :is_master?
     after_commit :clear_line_items_cache, on: :update
@@ -238,6 +240,19 @@ module Spree
       !discontinued? && product.available?
     end
 
+    # Returns true if the variant is sold as a pre-order: the product is active
+    # and not deleted, the variant is flagged preorderable and not discontinued,
+    # and the "ships by" date is open-ended or still in the future.
+    # Pre-order relaxes only the publish-date embargo, not the rest of the
+    # availability rules. Like backorder, a pre-order can make the variant
+    # purchasable beyond on-hand stock; the oversell cap is +backorder_limit+
+    # (empty ⇒ unlimited), and it adds the ship-by promise.
+    # @return [Boolean] true if the variant is a pre-order
+    def preorder?
+      !discontinued? && preorderable? && product.active? && !product.deleted? &&
+        (preorder_ships_at.nil? || preorder_ships_at > Time.current)
+    end
+
     # Returns true if the variant is in stock or backorderable.
     # @return [Boolean] true if the variant is in stock or backorderable
     def in_stock_or_backorderable?
@@ -647,7 +662,19 @@ module Spree
     alias is_backorderable? backorderable?
 
     def purchasable?
-      @purchasable ||= in_stock? || backorderable?
+      in_stock? || oversellable_now?
+    end
+
+    # Whether the variant can currently be bought by overselling — via
+    # backorder or pre-order. Unlimited when +backorder_limit+ is nil (empty =
+    # no cap); with a limit, purchasable only while the oversell allowance
+    # remains.
+    #
+    # @return [Boolean]
+    def oversellable_now?
+      return false unless backorderable? || preorder?
+
+      backorder_limit.nil? || can_supply?(1)
     end
 
     # Shortcut method to determine if inventory tracking is enabled for this variant

data/app/presenters/spree/search_provider/product_presenter.rb

@@ -58,6 +58,9 @@ module Spree
           status: product.status,
           sku: product.sku,
           in_stock: product.in_stock?,
+          # True when the product has an active pre-order variant, so a
+          # scheduled (future-published) launch still surfaces in search.
+          preorder: product.preorder?,
           store_ids: Array(product.store_id).map(&:to_s),
           channel_ids: channel_ids_for_store,
           discontinue_on: product.discontinue_on&.to_i || 0,

data/app/services/spree/carts/complete.rb

@@ -10,6 +10,9 @@ module Spree
       def call(cart:)
         return success(cart) if cart.completed?
         return failure(cart, 'Order is canceled') if cart.canceled?
+        # Enforced here (not only in the controller) so every completion path —
+        # API, payment-session webhook — honors the channel's guest-checkout gate.
+        return failure(cart, Spree.t(:guest_checkout_not_allowed)) if cart.guest_checkout_disallowed?
 
         cart.with_lock do
           process_payments!(cart) if cart.payment_required?

data/app/services/spree/fulfillments/create.rb

@@ -0,0 +1,259 @@
+module Spree
+  module Fulfillments
+    # Manually creates a fulfillment (Spree::Shipment) on a completed order,
+    # bypassing order routing. Moves the requested quantities of each line
+    # item's not-yet-shipped inventory units out of their current shipments
+    # into the new fulfillment, mirroring externally-managed fulfillment
+    # (3PL, courier API, drop-shipping) back into Spree.
+    #
+    # Stock bookkeeping follows the split/transfer semantics: when the source
+    # and target stock locations differ, moved quantities are restocked at the
+    # source and unstocked at the target. Source shipments left empty are
+    # destroyed and their cost and selected delivery method carry over to the
+    # new fulfillment, unless the caller provides its own +cost+ /
+    # +delivery_method+.
+    #
+    # The resulting cost is frozen only for fulfillments registered with
+    # status: 'shipped' (rate refresh skips shipped shipments). Pending/ready
+    # fulfillments participate in the standard rate machinery — the order
+    # updater re-prices them from the delivery method calculators on the next
+    # recalculation, exactly like shipments created via split/transfer.
+    class Create
+      prepend Spree::ServiceModule::Base
+
+      # @param order [Spree::Order] completed order to fulfill
+      # @param stock_location [Spree::StockLocation] location the fulfillment ships from
+      # @param items [Array<Hash>, nil] `[{ line_item: Spree::LineItem, quantity: Integer }]`;
+      #   nil fulfills every not-yet-shipped unit on the order
+      # @param tracking [String, nil] carrier tracking number
+      # @param delivery_method [Spree::ShippingMethod, nil] carrier; stored as the selected rate.
+      #   Defaults to the delivery method of the drained source fulfillment(s)
+      # @param cost [String, Numeric, nil] explicit shipping cost (e.g. the 3PL's price).
+      #   Defaults to the summed cost of the drained source fulfillment(s), keeping the
+      #   order total unchanged; an explicit cost changes the order total and payment state.
+      #   Guaranteed to persist only with status: 'shipped' — pending fulfillments are
+      #   re-priced by the rate engine (see class docs)
+      # @param status [String, nil] pass 'shipped' to register an already-shipped fulfillment
+      # @param metadata [Hash, nil] metadata stored on the fulfillment
+      # @return [Spree::ServiceModule::Result] the created shipment on success
+      def call(order:, stock_location:, items: nil, tracking: nil, delivery_method: nil, cost: nil, status: nil, metadata: nil)
+        return failure(nil, Spree.t('fulfillments.errors.invalid_status')) unless status.nil? || status == 'shipped'
+
+        cost = parse_cost(cost)
+        return cost if cost.is_a?(Spree::ServiceModule::Result)
+
+        fulfillment = nil
+
+        # The order row is locked before reading fulfillable units so
+        # concurrent creations (e.g. duplicate carrier webhooks) validate and
+        # move units against a serialized snapshot. The API layer already
+        # serializes via with_order_lock; this covers direct service callers.
+        ActiveRecord::Base.transaction do
+          order.lock!
+
+          return failure(nil, Spree.t('fulfillments.errors.order_not_completed')) unless order.completed?
+          return failure(nil, Spree.t('fulfillments.errors.order_canceled')) if order.canceled?
+
+          units_by_line_item = fulfillable_units(order)
+
+          requested = normalize_items(order, items, units_by_line_item)
+          return requested if requested.is_a?(Spree::ServiceModule::Result)
+
+          fulfillment = order.shipments.new(
+            stock_location: stock_location,
+            address_id: order.ship_address_id,
+            tracking: tracking
+          )
+          fulfillment.metadata = metadata if metadata.present?
+          fulfillment.save!
+
+          source_shipments = move_units(order, fulfillment, requested, units_by_line_item)
+          inherited = destroy_drained_shipments(source_shipments, capture_delivery_method: delivery_method.nil?)
+          attach_cost_and_rate(fulfillment, delivery_method, cost, inherited)
+
+          if status == 'shipped'
+            mark_shipped(fulfillment)
+          else
+            fulfillment.update!(order)
+          end
+
+          order.reload.update_with_updater!
+        end
+
+        success(fulfillment.reload)
+      end
+
+      private
+
+      # Units that can still be moved into a manual fulfillment: on-hand or
+      # backordered units sitting in shipments that haven't shipped or been
+      # canceled (canceled shipments already restocked their stock). Loaded
+      # in one query, on-hand first so moved units stay shippable, grouped
+      # by line item for both validation and moving.
+      def fulfillable_units(order)
+        order.inventory_units.
+          on_hand_or_backordered.
+          joins(:shipment).
+          merge(Spree::Shipment.ready_or_pending).
+          preload(:shipment, :variant).
+          order(Arel.sql("CASE WHEN #{Spree::InventoryUnit.table_name}.state = 'on_hand' THEN 0 ELSE 1 END"), :id).
+          group_by(&:line_item_id)
+      end
+
+      def normalize_items(order, items, units_by_line_item)
+        available_for = ->(line_item) { units_by_line_item.fetch(line_item.id, []).sum(&:quantity) }
+
+        if items.nil?
+          derived = order.line_items.filter_map do |line_item|
+            quantity = available_for.call(line_item)
+            { line_item: line_item, quantity: quantity } if quantity.positive?
+          end
+          return failure(nil, Spree.t('fulfillments.errors.no_items_to_fulfill')) if derived.empty?
+
+          return derived
+        end
+
+        return failure(nil, Spree.t('fulfillments.errors.no_items_to_fulfill')) if items.empty?
+
+        # Merge duplicate line item entries, then validate quantities.
+        merged = items.group_by { |item| item[:line_item].id }.values.map do |grouped|
+          { line_item: grouped.first[:line_item], quantity: grouped.sum { |item| item[:quantity].to_i } }
+        end
+
+        merged.each do |item|
+          line_item = item[:line_item]
+          quantity = item[:quantity]
+
+          unless quantity.positive?
+            return failure(nil, Spree.t('fulfillments.errors.invalid_quantity', item: line_item.prefixed_id))
+          end
+
+          available = available_for.call(line_item)
+          if quantity > available
+            return failure(
+              nil,
+              Spree.t('fulfillments.errors.insufficient_quantity',
+                      item: line_item.prefixed_id, requested: quantity, available: available)
+            )
+          end
+        end
+
+        merged
+      end
+
+      # Moves the requested quantities into the fulfillment, on-hand units
+      # first so the new fulfillment is shippable whenever possible. Restocks
+      # the source location and unstocks the target for tracked variants when
+      # the locations differ, keeping stock levels truthful about where the
+      # goods actually leave from.
+      #
+      # @return [Array<Spree::Shipment>] the shipments units were taken from
+      def move_units(order, fulfillment, requested, units_by_line_item)
+        source_shipments = []
+        stock_moves = Hash.new(0)
+
+        requested.each do |item|
+          remaining = item[:quantity]
+
+          units_by_line_item.fetch(item[:line_item].id, []).each do |unit|
+            break if remaining.zero?
+
+            take = [unit.quantity, remaining].min
+            source_shipments << unit.shipment
+            stock_moves[[unit.shipment, unit.variant]] += take
+
+            target = fulfillment.inventory_units.find_or_initialize_by(
+              state: unit.state,
+              variant_id: unit.variant_id,
+              line_item_id: unit.line_item_id,
+              order_id: order.id
+            )
+            target.pending = unit.pending
+            # The quantity column has a database default of 1, so a fresh
+            # record must be set to the moved quantity, not incremented.
+            target.quantity = target.new_record? ? take : target.quantity + take
+            target.save!
+
+            if take == unit.quantity
+              unit.destroy!
+            else
+              unit.update!(quantity: unit.quantity - take)
+            end
+
+            remaining -= take
+          end
+        end
+
+        stock_moves.each do |(source_shipment, variant), quantity|
+          next unless variant.track_inventory?
+          next if source_shipment.stock_location_id == fulfillment.stock_location_id
+
+          source_shipment.stock_location.restock(variant, quantity, source_shipment)
+          fulfillment.stock_location.unstock(variant, quantity, fulfillment)
+        end
+
+        source_shipments.uniq
+      end
+
+      # Destroys fully drained source shipments, capturing what the new
+      # fulfillment inherits from them — the summed cost and the first
+      # selected delivery method, read before destroy since the rates are
+      # deleted along with the shipment. The delivery method lookup costs
+      # queries, so it is skipped when the caller provided its own.
+      #
+      # @return [Hash] `{ cost: BigDecimal, delivery_method: Spree::ShippingMethod or nil }`
+      def destroy_drained_shipments(source_shipments, capture_delivery_method:)
+        inherited = { cost: 0, delivery_method: nil }
+
+        source_shipments.each do |shipment|
+          next unless shipment.inventory_units.sum(:quantity).zero?
+
+          inherited[:cost] += shipment.cost
+          inherited[:delivery_method] ||= shipment.shipping_method if capture_delivery_method
+          shipment.destroy!
+        end
+
+        inherited
+      end
+
+      # The fulfillment inherits the cost and carrier of the shipments it
+      # replaced — keeping the order total (and thus payment state) unchanged —
+      # unless the caller provides its own. Frozen once shipped; see the class
+      # docs for pending-path re-pricing. The carrier rides along as a
+      # selected rate.
+      def attach_cost_and_rate(fulfillment, delivery_method, cost, inherited)
+        effective_cost = cost || inherited[:cost]
+        method = delivery_method || inherited[:delivery_method]
+
+        fulfillment.update_columns(cost: effective_cost) if effective_cost.positive?
+        fulfillment.add_shipping_method(method, true) if method
+      end
+
+      # Strict decimal parsing (same semantics as Shipment#cost=, which the
+      # update_columns freeze path bypasses) — the lenient LocalizedNumber
+      # would turn garbage into 0, and 0 is a legal cost here.
+      #
+      # @return [BigDecimal, Numeric, nil] nil when no cost was given (blank
+      #   counts as omitted); a failure Result for malformed or negative input
+      def parse_cost(cost)
+        return if cost.blank?
+
+        parsed = cost.is_a?(String) ? BigDecimal(cost.strip) : cost
+        return failure(nil, Spree.t('fulfillments.errors.invalid_cost')) if parsed.negative?
+
+        parsed
+      rescue ArgumentError
+        failure(nil, Spree.t('fulfillments.errors.invalid_cost'))
+      end
+
+      # Registers an externally-completed fulfillment: backorders are filled
+      # (the external location evidently had the goods) and the paid-order
+      # readiness gate is bypassed deliberately — the goods already left.
+      def mark_shipped(fulfillment)
+        fulfillment.inventory_units.backordered.each(&:fill_backorder!)
+        fulfillment.update_columns(state: 'ready') unless fulfillment.ready?
+        fulfillment.reload.ship!
+      end
+    end
+  end
+end

data/app/services/spree/imports/row_processors/base.rb

@@ -20,6 +20,15 @@ module Spree
 
         private
 
+        # Memoizes a shared-record lookup (including nil misses) in the import's
+        # per-job cache so repeated rows don't re-run the same query.
+        def cached_lookup(*key)
+          cache = import.row_lookup_cache
+          return cache[key] if cache.key?(key)
+
+          cache[key] = yield
+        end
+
         def build_schema_hash(row, mappings, schema_fields)
           attributes = {}
           schema_fields.each do |field|