spree_core 5.6.1 → 6.0.0.beta1

data/app/models/spree/stock_movement.rb

@@ -2,54 +2,198 @@ module Spree
   class StockMovement < Spree.base_class
     has_prefix_id :sm
 
+    # What happened to stock. The kind carries the direction, so the three
+    # order-driven kinds are written positive; `received` and `adjusted` keep
+    # the signed meaning of quantity.
+    KINDS = %w[received allocated shipped released adjusted].freeze
+
     QUANTITY_LIMITS = {
       max: 2**31 - 1,
       min: -2**31
     }.freeze
 
-    include Spree::StockMovement::Webhooks
     include Spree::StockMovement::CustomEvents
 
     publishes_lifecycle_events
 
-    belongs_to :stock_item, class_name: 'Spree::StockItem', inverse_of: :stock_movements
-    belongs_to :originator, polymorphic: true
+    # `with_deleted` because the ledger outlives what it describes: a level is
+    # soft-deleted whenever a product save stops listing its location, and
+    # without this the default scope propagates into every join — taking the
+    # history of those units out of `for_store` and out of the API with it.
+    belongs_to :stock_level, -> { with_deleted }, class_name: 'Spree::StockLevel', inverse_of: :stock_movements
+    # @deprecated Replaced by the concrete cause keys below; dropped in 6.1.
+    belongs_to :originator, polymorphic: true, optional: true
 
-    after_create :update_stock_item_quantity
+    # The cause. A fulfillment-driven row carries its order too, so "which
+    # order was this for?" costs no join.
+    belongs_to :order, class_name: 'Spree::Order', optional: true
+    belongs_to :fulfillment, class_name: 'Spree::Fulfillment', optional: true
+    belongs_to :return, class_name: 'Spree::Return', optional: true
+    belongs_to :exchange, class_name: 'Spree::Exchange', optional: true
+    belongs_to :stock_transfer, class_name: 'Spree::StockTransfer', optional: true
+    belongs_to :purchase_order, class_name: 'Spree::PurchaseOrder', optional: true
+    belongs_to :stock_receipt, class_name: 'Spree::StockReceipt', optional: true, inverse_of: :stock_movements
 
-    with_options presence: true do
-      validates :stock_item
-      validates :quantity, numericality: {
-        greater_than_or_equal_to: :min_quantity,
-        less_than_or_equal_to: QUANTITY_LIMITS[:max],
-        only_integer: true
-      }
-    end
+    alias_attribute :stock_item_id, :stock_level_id
+
+    # Whether this write may leave the shelf below zero. An instruction about
+    # this one movement rather than a property of it, so it is never
+    # persisted — the same shape as {Spree::Fulfillment#notify_customer}.
+    attr_accessor :force
+
+    after_create :apply_to_stock_level
+
+    validates :quantity, :kind, presence: true
+    validates :kind, inclusion: { in: KINDS }, allow_blank: true
+    validates :quantity, numericality: {
+      other_than: 0,
+      greater_than_or_equal_to: QUANTITY_LIMITS[:min],
+      less_than_or_equal_to: QUANTITY_LIMITS[:max],
+      only_integer: true
+    }, allow_nil: true
+    # The three order-driven kinds carry their direction in the kind, so they
+    # are written positive and read through `abs`. Accepting a negative would
+    # store a row whose sign contradicts the change it caused — the ledger
+    # would say one thing and the shelf another.
+    validates :quantity, numericality: { greater_than: 0 }, allow_nil: true,
+                         if: -> { allocated? || released? || shipped? }
+    validates :reason, presence: true, if: :adjusted?
 
     scope :recent, -> { order(created_at: :desc) }
+    KINDS.each do |movement_kind|
+      scope movement_kind, -> { where(kind: movement_kind) }
+      define_method("#{movement_kind}?") { kind == movement_kind }
+    end
 
-    delegate :variant, :variant_id, to: :stock_item, allow_nil: true
+    # Movements for products assigned to `store`, walking
+    # `stock level → variant → product → store`. The table carries no store of
+    # its own, so this walk is the only tenancy path there is.
+    scope :for_store, ->(store) {
+      joins(stock_level: { variant: :product }).where(spree_products: { store_id: store.id })
+    }
+
+    delegate :variant, :variant_id, to: :stock_level, allow_nil: true
     delegate :product, to: :variant
 
-    self.whitelisted_ransackable_attributes = %w[quantity action created_at stock_item_id originator_type]
-    self.whitelisted_ransackable_associations = %w[stock_item]
+    # `stock_item_id` rides along for one release beside the name that replaced
+    # it: Ransack resolves attribute aliases, and dropping the old filter would
+    # hand a client still sending it the whole collection rather than an error.
+    self.whitelisted_ransackable_attributes = %w[quantity kind reason created_at stock_level_id
+                                                 stock_item_id order_id fulfillment_id return_id
+                                                 exchange_id stock_transfer_id purchase_order_id
+                                                 stock_receipt_id unit_cost]
+    self.whitelisted_ransackable_associations = %w[stock_level]
+
+    # The corrections a merchant reaches for, as codes a client can send
+    # instead of typing the text itself. Free text is still accepted — an
+    # integration's own wording is not Spree's to police — but a dashboard
+    # that sends `damaged` gets one stored string whatever language its
+    # operator works in.
+    ADJUSTMENT_REASONS = %w[
+      manual_adjustment correction count received return_restock damaged theft_or_loss
+      promotion_or_donation inventory_feed
+    ].freeze
+
+    # Stored audit text for a correction nobody labelled.
+    #
+    # @return [String]
+    def self.default_adjustment_reason
+      adjustment_reason_text(:manual_adjustment)
+    end
+
+    # What to store against a correction. A known code becomes its English
+    # text; anything else is the caller's own wording, kept as sent.
+    #
+    # Deliberately resolved in English rather than the operator's locale: the
+    # column is read by every admin afterwards and filtered across the whole
+    # history, so one cause has to be one string.
+    #
+    # @param reason [String, Symbol, nil]
+    # @return [String]
+    def self.adjustment_reason_text(reason)
+      return default_adjustment_reason if reason.blank?
+      return reason.to_s unless ADJUSTMENT_REASONS.include?(reason.to_s)
 
+      Spree.t("stock_movement.reasons.#{reason}", locale: :en)
+    end
+
+    # A movement is an immutable audit row: once written, nothing may rewrite
+    # it. The guard is against an *update*, so it reads `persisted?` at the
+    # moment the save begins rather than afterwards — a parent's autosave can
+    # insert this row while its own save is still in flight (the stock level
+    # holds it through `inverse_of`), which leaves it persisted mid-insert. That
+    # row is being created, not updated, so it must still be allowed to finish.
     def readonly?
-      persisted?
+      persisted? && !being_created?
+    end
+
+    # What the units on this row cost, when the movement was a purchase. Null
+    # on everything else: moving stock a merchant already owns is not a
+    # purchase, so a transfer or a return has no cost to record.
+    #
+    # @return [Spree::Money, nil]
+    def display_unit_cost
+      return nil if unit_cost.nil?
+
+      Spree::Money.new(unit_cost, currency: purchase_order&.currency)
+    end
+
+    # @deprecated Use {#stock_level}; removed in 6.1.
+    def stock_item
+      Spree::Deprecation.warn('Spree::StockMovement#stock_item is deprecated and will be removed in Spree 6.1. Use #stock_level instead.')
+      stock_level
+    end
+
+    # @deprecated Use {#stock_level=}; removed in 6.1.
+    def stock_item=(record)
+      Spree::Deprecation.warn('Spree::StockMovement#stock_item= is deprecated and will be removed in Spree 6.1. Use #stock_level= instead.')
+      self.stock_level = record
     end
 
     private
 
-    def update_stock_item_quantity
-      return unless stock_item.should_track_inventory?
+    # Re-entrant: a parent's autosave can call this again from inside the outer
+    # save, and the inner call must not clear the outer one's guard.
+    def create_or_update(...)
+      @create_depth = @create_depth.to_i + 1
+      @being_created = true if new_record?
+      super
+    ensure
+      @create_depth -= 1
+      @being_created = false if @create_depth.zero?
+    end
 
-      stock_item.adjust_count_on_hand quantity
+    def being_created?
+      @being_created.present?
     end
 
-    def min_quantity
-      return QUANTITY_LIMITS[:min] if stock_item.nil? || stock_item.backorderable?
+    # The single place count_on_hand and allocated_count change.
+    #
+    # A correction applies even to a variant that stopped tracking inventory —
+    # that is how turning tracking off writes its stock away, and a correction
+    # is a deliberate statement about the shelf either way.
+    def apply_to_stock_level
+      return unless adjusted? || stock_level.should_track_inventory?
+
+      case kind
+      when 'received', 'adjusted' then stock_level.adjust_count_on_hand(quantity)
+      when 'allocated'            then stock_level.adjust_allocated_count(quantity.abs)
+      when 'released'             then stock_level.release_allocated_count(quantity.abs)
+      when 'shipped'              then apply_departure
+      end
+    end
 
-      -stock_item.count_on_hand
+    # The shelf may only be driven below zero when the caller said so: a
+    # merchant forcing a dispatch has decided the parcel left whatever the
+    # ledger claims. Nothing else — a transfer least of all — may send goods a
+    # warehouse does not have.
+    #
+    # Retiring the promise keys off the cause instead, because only a dispatch
+    # has one to retire: consuming an allocation on a transfer would take a
+    # different order's units.
+    def apply_departure
+      stock_level.adjust_count_on_hand(-quantity.abs, force: force.present?)
+      stock_level.release_allocated_count(quantity.abs) if fulfillment_id.present?
     end
   end
 end

data/app/models/spree/stock_receipt.rb

@@ -0,0 +1,56 @@
+module Spree
+  # One delivery against a purchase order or a stock transfer: what the dock
+  # counted in on one day, under one packing slip. Lines on the document keep
+  # the running totals; the receipt is the record of each arrival, and every
+  # `received` movement it caused names it.
+  #
+  # A *stock* receipt on purpose — a customer-facing sales receipt will want
+  # the plain word.
+  class StockReceipt < Spree.base_class
+    has_prefix_id :sr
+
+    include Spree::SingleStoreResource
+    has_spree_number prefix: 'SR'
+    include Spree::NumberIdentifier
+    include Spree::Metadata
+
+    publishes_lifecycle_events
+
+    belongs_to :receivable, polymorphic: true, inverse_of: :stock_receipts
+    belongs_to :received_by, class_name: Spree.admin_user_class.to_s, optional: true
+
+    has_many :items, class_name: 'Spree::StockReceiptItem', inverse_of: :stock_receipt,
+                     dependent: :destroy
+    has_many :stock_movements, class_name: 'Spree::StockMovement', inverse_of: :stock_receipt,
+                               dependent: :nullify
+
+    validates :received_at, presence: true
+    validates :items, presence: true
+
+    normalizes :reference, with: ->(value) { value.strip.presence }
+
+    self.whitelisted_ransackable_attributes = %w[number reference received_at receivable_type
+                                                 receivable_id received_by_id created_at]
+
+    # @return [Integer] units this delivery put on the shelf
+    def quantity_accepted_total
+      items.sum { |item| item.quantity_accepted.to_i }
+    end
+
+    # @return [Integer] units this delivery refused
+    def quantity_rejected_total
+      items.sum { |item| item.quantity_rejected.to_i }
+    end
+
+    def event_serializer_class
+      'Spree::Api::V3::StockReceiptEventSerializer'.safe_constantize
+    end
+
+    private
+
+    def ensure_store
+      self.store ||= receivable&.store
+      super
+    end
+  end
+end

data/app/models/spree/stock_receipt_item.rb

@@ -0,0 +1,35 @@
+module Spree
+  # One line of a delivery: how many of a document's line arrived, how many of
+  # those were refused, and why. Accepted units reach the shelf; rejected ones
+  # exist only here.
+  class StockReceiptItem < Spree.base_class
+    has_prefix_id :sri
+
+    REJECTION_REASONS = %w[damaged wrong_item expired other].freeze
+
+    belongs_to :stock_receipt, class_name: 'Spree::StockReceipt', inverse_of: :items
+    # A purchase order item or a stock transfer item.
+    belongs_to :line, polymorphic: true, inverse_of: :stock_receipt_items
+
+    validates :quantity_accepted, :quantity_rejected,
+              numericality: { greater_than_or_equal_to: 0, only_integer: true }
+    validates :rejection_reason, inclusion: { in: REJECTION_REASONS },
+                                 if: -> { quantity_rejected.to_i.positive? }
+    validate :counts_something
+
+    delegate :variant, :variant_name, :variant_sku, to: :line, allow_nil: true
+
+    # @return [Integer] everything the dock counted, accepted or not
+    def quantity_counted
+      quantity_accepted.to_i + quantity_rejected.to_i
+    end
+
+    private
+
+    def counts_something
+      return if quantity_counted.positive?
+
+      errors.add(:base, :nothing_counted, message: Spree.t('stock_receipt.errors.nothing_counted'))
+    end
+  end
+end

data/app/models/spree/stock_reservation.rb

@@ -4,35 +4,138 @@ module Spree
 
     publishes_lifecycle_events
 
-    belongs_to :stock_item, class_name: 'Spree::StockItem', inverse_of: :stock_reservations
+    belongs_to :stock_level, class_name: 'Spree::StockLevel', inverse_of: :stock_reservations
     belongs_to :line_item, class_name: 'Spree::LineItem', inverse_of: :stock_reservations
-    belongs_to :order, class_name: 'Spree::Order', inverse_of: :stock_reservations
+    belongs_to :order, class_name: 'Spree::Order', inverse_of: :stock_reservations, optional: true
+    belongs_to :cart, class_name: 'Spree::Cart', inverse_of: :stock_reservations, optional: true
 
-    validates :stock_item, :line_item, :order, :quantity, :expires_at, presence: true
+    alias_attribute :stock_item_id, :stock_level_id
+
+    after_create :hold_units
+    after_update :move_held_units, if: :saved_change_to_quantity?
+    after_destroy :release_units
+
+    validates :quantity, :expires_at, presence: true
+    validate :exactly_one_owner
+    validate :stock_level_unchanged, on: :update
     validates :quantity, numericality: { greater_than: 0, only_integer: true }, presence: true
-    validates :line_item_id, uniqueness: { scope: :stock_item_id }, presence: true
+    validates :line_item_id, uniqueness: { scope: :stock_level_id }, presence: true
 
     scope :active, -> { where('spree_stock_reservations.expires_at > ?', Time.current) }
     scope :expired, -> { where('spree_stock_reservations.expires_at <= ?', Time.current) }
-    scope :for_order, ->(order) { where(order_id: order.id) }
+    scope :for_order, ->(owner) { owner.is_a?(Spree::Cart) ? where(cart_id: owner.id) : where(order_id: owner.id) }
     scope :for_store, ->(store) {
       joins(:order).where(spree_orders: { store_id: store.id })
     }
 
-    self.whitelisted_ransackable_attributes = %w[stock_item_id line_item_id order_id quantity expires_at]
-    self.whitelisted_ransackable_associations = %w[stock_item line_item order]
+    # `stock_item_id` rides along for one release beside the name that replaced
+    # it — see the same allowlist on Spree::StockMovement.
+    self.whitelisted_ransackable_attributes = %w[stock_level_id stock_item_id line_item_id order_id
+                                                 quantity expires_at]
+    self.whitelisted_ransackable_associations = %w[stock_level line_item order]
+
+    # Deletes these reservations in one statement and hands their units back
+    # to each level's reserved counter in the same transaction — the batch
+    # twin of the per-row callbacks, for a sweep or a release that would
+    # otherwise destroy rows one by one.
+    #
+    # The levels are locked first, then the rows read and deleted: the order
+    # {Spree::StockReservations::Reserve} takes, so a checkout re-reserving
+    # one of these rows waits at the level rather than the two of them
+    # locking each other out, and its new quantity cannot land between the
+    # read and the delete.
+    #
+    # @param reservations [ActiveRecord::Relation<Spree::StockReservation>]
+    # @return [Integer] how many reservations were deleted
+    def self.withdraw(reservations)
+      transaction do
+        levels = Spree::StockLevel.where(id: reservations.select(:stock_level_id)).order(:id).lock.to_a
+        held = reservations.group(:stock_level_id).sum(:quantity)
+        deleted = reservations.delete_all
+
+        levels.each { |stock_level| stock_level.adjust_reserved_count(-held.fetch(stock_level.id, 0)) }
+
+        deleted
+      end
+    end
+
+    # Removes every hold whose time is up, giving the units back to their
+    # levels. Run by {Spree::StockReservations::ExpireJob} on a schedule and
+    # by the stock recount before it measures anything.
+    #
+    # @return [void]
+    def self.sweep_expired
+      expired.in_batches(of: 1_000) { |batch| withdraw(batch) }
+    end
+
+    # @return [Spree::Cart, Spree::Order, nil]
+    def owner
+      order || cart
+    end
+
+    # @deprecated Use {#stock_level}; removed in 6.1.
+    def stock_item
+      Spree::Deprecation.warn('Spree::StockReservation#stock_item is deprecated and will be removed in Spree 6.1. Use #stock_level instead.')
+      stock_level
+    end
+
+    # @deprecated Use {#stock_level=}; removed in 6.1.
+    def stock_item=(record)
+      Spree::Deprecation.warn('Spree::StockReservation#stock_item= is deprecated and will be removed in Spree 6.1. Use #stock_level= instead.')
+      self.stock_level = record
+    end
+
+    # Bridge for legacy callers assigning +current_order+ (now a Spree::Cart)
+    # to the order association — routes carts to the cart FK instead.
+    def order=(record)
+      if record.is_a?(Spree::Cart)
+        self.cart = record
+        super(nil)
+      else
+        super
+      end
+    end
 
     def active?
       expires_at > Time.current
     end
 
-    # Resolves the reservation TTL: per-Store preference if set, otherwise
-    # the global Spree::Config[:default_stock_reservation_ttl_minutes]. Falls
-    # back to 10 minutes if both are unset (e.g. early-boot / fixture state).
+    # Resolves the reservation TTL from the store, falling back to 10 minutes
+    # when there is no store to ask (early-boot / fixture state).
     def self.ttl_for(order)
       minutes = order&.store&.preferred_stock_reservation_ttl_minutes
-      minutes = Spree::Config[:default_stock_reservation_ttl_minutes] if minutes.blank?
       minutes.to_i.then { |m| m > 0 ? m : 10 }.minutes
     end
+
+    private
+
+    # The counter follows the row wherever the row goes: a checkout that
+    # reserves, a cart that is emptied, a line item that is removed, a level
+    # that is destroyed — every path that creates, resizes or destroys a
+    # reservation moves the level's figure by exactly that row.
+    def hold_units
+      stock_level.adjust_reserved_count(quantity)
+    end
+
+    def move_held_units
+      before, after = saved_change_to_quantity
+      stock_level.adjust_reserved_count(after - before.to_i)
+    end
+
+    def release_units
+      stock_level&.adjust_reserved_count(-quantity)
+    end
+
+    def exactly_one_owner
+      errors.add(:base, :exactly_one_of_cart_or_order, message: Spree.t('errors.messages.exactly_one_of_cart_or_order')) unless [order, cart].compact.one?
+    end
+
+    # Only a quantity change moves units between counters, so re-pointing a
+    # hold at another level would leave its units counted on the old one and
+    # missing from the new. A hold that belongs elsewhere is released and
+    # taken again, never moved.
+    def stock_level_unchanged
+      errors.add(:stock_level_id, :immutable, message: Spree.t('errors.messages.stock_level_immutable')) if stock_level_id_changed?
+    end
   end
 end

data/app/models/spree/stock_transfer.rb

@@ -1,89 +1,114 @@
 module Spree
+  # Stock moving between two of the merchant's own warehouses
+  # (docs/plans/6.0-inventory-operations.md).
+  #
+  # A transfer is a trip, not an instant. Units leave the source when
+  # {Spree::StockTransfers::MarkInTransit} runs and land at the destination
+  # when {Spree::StockTransfers::Receive} does — in between they are in flight,
+  # physically gone from one shelf and not yet on the other. The 5.x model
+  # collapsed both into one transaction, which made the destination's
+  # availability wrong for the whole journey.
+  #
+  # Every status change is a workflow, never `transfer.receive!`, so receiving
+  # can carry the quantities the warehouse actually counted and cancelling can
+  # carry the merchant's restock-or-write-off choice.
+  #
+  # Receiving from a supplier is a {Spree::PurchaseOrder}, not a transfer with
+  # no source: a purchase has a cost, a supplier and an expected date, and none
+  # of those belong on internal logistics.
   class StockTransfer < Spree.base_class
     has_prefix_id :st
 
-    include Spree::Core::NumberGenerator.new(prefix: 'T')
+    # Before `has_spree_number`, deliberately: both register a
+    # `before_validation`, and numbering reads the store to pick up its
+    # sequence. Registered the other way round, a transfer built without an
+    # explicit store would draw its number from the default store's counter.
+    include Spree::SingleStoreResource
+    has_spree_number prefix: 'T'
     include Spree::NumberIdentifier
-    include Spree::Metafields
+    include Spree::HasStatus
+    include Spree::Receivable
+    include Spree::HasCustomFields
     include Spree::Metadata
 
+    # The upgrade task keeps a converted external receive's number readable by
+    # stamping the row rather than deleting it.
+    acts_as_paranoid
+
     publishes_lifecycle_events
 
-    has_many :stock_movements, as: :originator
-    accepts_nested_attributes_for :stock_movements, reject_if: proc { |attributes|
-      attributes[:quantity] = attributes[:quantity].to_i
-      attributes[:quantity].blank? || attributes[:quantity].zero? || attributes[:stock_item_id].blank?
-    }
+    has_status :draft, :ready_to_ship, :in_transit, :partially_received, :received, :over_received, :canceled,
+               default: :draft
 
-    belongs_to :source_location, class_name: 'StockLocation', optional: true
-    belongs_to :destination_location, class_name: 'StockLocation'
+    belongs_to :source_location, class_name: 'Spree::StockLocation'
+    belongs_to :destination_location, class_name: 'Spree::StockLocation'
+    belongs_to :created_by, class_name: Spree.admin_user_class.to_s, optional: true
 
-    self.whitelisted_ransackable_attributes = %w[reference source_location_id destination_location_id number]
+    has_many :items, class_name: 'Spree::StockTransferItem',
+                     inverse_of: :stock_transfer, dependent: :destroy
+    # No `dependent:`, for the reason given on Spree::Fulfillment's own
+    # movements: the ledger outlives the record that caused it.
+    has_many :stock_movements, class_name: 'Spree::StockMovement', inverse_of: :stock_transfer
 
-    validate :source_location_is_not_destination_location
-    validate :stock_movements_not_empty
-    validates :destination_location, presence: true
+    accepts_nested_attributes_for :items, allow_destroy: true
 
-    def source_movements
-      find_stock_location_with_location_id(source_location_id)
-    end
-
-    def destination_movements
-      find_stock_location_with_location_id(destination_location_id)
-    end
-
-    def transfer(source_location, destination_location, variants)
-      if variants.nil? || variants.empty?
-        errors.add(:base, Spree.t('stock_transfer.errors.must_have_variant'))
-        return false
-      end
-
-      unless variants_available_in_source_location?(source_location, variants)
-        errors.add(:base, Spree.t('stock_transfer.errors.variants_unavailable'))
-        return false
-      end
-
-      transaction do
-        variants.each_pair do |variant, quantity|
-          source_location&.unstock(variant, quantity, self, persist: false)
-          destination_location.restock(variant, quantity, self, persist: false)
-
-          self.source_location = source_location
-          self.destination_location = destination_location
-          save!
-        end
-      end
-
-      true
+    validates :source_location, :destination_location, presence: true
+    # A document that has left draft describes a box that physically exists —
+    # except a cancelled one, which describes a trip that never happened. The
+    # guard covers both because `update` assigns the status before validating,
+    # so cancelling an empty draft would otherwise be refused.
+    validates :items, presence: true, unless: -> { draft? || canceled? }
+    validate :source_location_is_not_destination_location
+    validate :locations_belong_to_the_same_store
+
+    self.whitelisted_ransackable_attributes = %w[number status reference source_location_id
+                                                 destination_location_id shipped_at received_at
+                                                 closed_short_at created_at]
+    self.whitelisted_ransackable_scopes = %w[open closed]
+    self.whitelisted_ransackable_associations = %w[source_location destination_location items]
+
+    # Whether the merchant may still edit the lines. Once the box is sealed and
+    # marked ready, what is in it is a matter of record.
+    #
+    # @return [Boolean]
+    def editable?
+      draft?
     end
 
-    # receive inventory from external vendor
-    def receive(destination_location, variants)
-      transfer(nil, destination_location, variants)
+    # Whether the units are somewhere between the two warehouses — gone from
+    # the source, not yet counted at the destination.
+    #
+    # @return [Boolean]
+    def in_flight?
+      in_transit? || partially_received?
     end
 
     private
 
-    def find_stock_location_with_location_id(location_id)
-      stock_movements.joins(:stock_item).where('spree_stock_items.stock_location_id' => location_id)
+    # The warehouse the goods are going to decides whose transfer this is,
+    # which is a fact about the record rather than about the request that
+    # created it. `Spree::Current.store` stays the fallback.
+    def ensure_store
+      self.store ||= destination_location&.store
+      super
     end
 
     def source_location_is_not_destination_location
-      return unless source_location_id.present?
-      return unless destination_location_id.present?
+      return if source_location_id.blank? || destination_location_id.blank?
       return if source_location_id != destination_location_id
 
-      errors.add(:source_location, Spree.t('stock_transfer.errors.same_location'))
-    end
-
-    def stock_movements_not_empty
-      errors.add(:base, Spree.t('stock_transfer.errors.must_have_variant')) if stock_movements.empty?
+      errors.add(:source_location, :same_location, message: Spree.t('stock_transfer.errors.same_location'))
     end
 
-    def variants_available_in_source_location?(source_location, variants)
-      return true if source_location.nil?
+    # A transfer moves a merchant's own stock between their own warehouses. Two
+    # locations from different stores would take units out of one tenant's
+    # inventory and put them into another's.
+    def locations_belong_to_the_same_store
+      return if source_location.blank? || destination_location.blank?
+      return if source_location.store_id == destination_location.store_id
 
-      source_location.stock_items.where(variant: variants.keys).where(Spree::StockItem.arel_table[:count_on_hand].gt(0)).size == variants.keys.size
+      errors.add(:destination_location, :must_belong_to_same_store,
+                 message: Spree.t('stock_transfer.errors.locations_in_different_stores'))
     end
   end
 end

data/app/models/spree/stock_transfer_item.rb

@@ -0,0 +1,25 @@
+module Spree
+  # One SKU on a stock transfer: how many left the source warehouse, and how
+  # many the destination counted in.
+  class StockTransferItem < Spree.base_class
+    has_prefix_id :sti
+
+    include Spree::ReceivableItem
+
+    expects_quantity_in :quantity_shipped
+
+    belongs_to :stock_transfer, class_name: 'Spree::StockTransfer', inverse_of: :items, touch: true
+
+    validates :quantity_shipped, numericality: { greater_than: 0, only_integer: true }
+    validates :variant_id, uniqueness: { scope: :stock_transfer_id }
+
+    self.whitelisted_ransackable_attributes = %w[variant_id quantity_shipped quantity_received quantity_rejected]
+
+    # Everything that arrived, whatever state it was in: a crushed unit is
+    # not still on the road.
+    def quantity_settled
+      quantity_received.to_i + quantity_rejected.to_i
+    end
+    self.whitelisted_ransackable_associations = %w[variant]
+  end
+end