spree_core 5.6.1 → 6.0.0.beta2

data/app/models/spree/stock_level.rb

@@ -0,0 +1,305 @@
+module Spree
+  class StockLevel < Spree.base_class
+    has_prefix_id :sl
+
+    acts_as_paranoid
+
+    include Spree::HasCustomFields
+    include Spree::Metadata
+    include Spree::HasExternalReferences
+    # Dual-emits the pre-rename `stock_item.*` names for one release.
+    include Spree::StockLevel::CustomEvents
+
+    publishes_lifecycle_events
+
+    with_options inverse_of: :stock_levels do
+      belongs_to :stock_location, class_name: 'Spree::StockLocation'
+      belongs_to :variant, -> { with_deleted }, class_name: 'Spree::Variant'
+    end
+    has_many :stock_movements, inverse_of: :stock_level
+    has_many :stock_reservations, class_name: 'Spree::StockReservation', inverse_of: :stock_level, dependent: :destroy
+    has_many :active_stock_reservations, -> { active }, class_name: 'Spree::StockReservation', inverse_of: :stock_level
+
+    validates :variant_id, uniqueness: { scope: :stock_location_id }, unless: :deleted_at
+
+    validates :count_on_hand, numericality: {
+      greater_than_or_equal_to: 0,
+      less_than_or_equal_to: 2**31 - 1,
+      only_integer: true
+    }, if: :verify_count_on_hand?
+
+    delegate :weight, :should_track_inventory?, :thumbnail, to: :variant
+    delegate :name, :sku, to: :variant, prefix: true
+    delegate :product, to: :variant
+
+    after_save(if: :saved_changes?) { variant.touch }
+    after_touch { variant.touch }
+    after_destroy { variant.touch }
+
+    self.whitelisted_ransackable_attributes = %w[count_on_hand allocated_count reserved_count incoming_count
+                                                 stock_location_id variant_id]
+    self.whitelisted_ransackable_scopes = %w[with_stock_status]
+    self.whitelisted_ransackable_associations = %w[variant stock_location]
+
+    scope :with_active_stock_location, -> { joins(:stock_location).merge(Spree::StockLocation.active) }
+
+    # What a customer could still buy from this shelf, as an Arel expression:
+    # the same subtraction {#purchasable_count} makes in Ruby. A list filters
+    # on it, so it cannot be a Ruby method. Built through Arel rather than
+    # interpolated into a string so the column names are quoted by the adapter
+    # and nothing here can carry a fragment.
+    #
+    # @return [Arel::Nodes::Node]
+    def self.purchasable_arel
+      arel_table[:count_on_hand] - arel_table[:allocated_count] - arel_table[:reserved_count]
+    end
+
+    scope :in_stock, -> { where(purchasable_arel.gt(0)) }
+    scope :out_of_stock, -> { where(purchasable_arel.lteq(0)) }
+
+    # Running low but not yet out. Reads the store's `low_stock_threshold`
+    # when none is passed, so the Inventory page's filter and the home
+    # screen's counter ask the same question. A threshold of 0 turns the
+    # warning off, which falls out of the bounds rather than needing a branch.
+    scope :low_stock, ->(threshold = nil) {
+      ceiling = threshold || Spree::Current.store&.preferred_low_stock_threshold || 0
+      where(purchasable_arel.gt(0)).where(purchasable_arel.lteq(ceiling))
+    }
+    scope :with_incoming, -> { where(arel_table[:incoming_count].gt(0)) }
+    scope :with_reserved, -> { where(arel_table[:reserved_count].gt(0)) }
+
+    # What the Inventory page's stock-status filter can ask for. Each names a
+    # scope above; `STOCK_STATUS_SCOPES` is the allowlist that keeps a request
+    # from naming any other method.
+    STOCK_STATUS_SCOPES = %w[in_stock low_stock out_of_stock with_incoming with_reserved].freeze
+
+    # Rows in any of the named states — "out of stock, or with units on the
+    # way" is one question a merchant asks, not two filters they combine.
+    #
+    # Splatted rather than taking one array: Ransack passes a multi-value
+    # `q[with_stock_status][]` as one argument per value, so a single-parameter
+    # lambda raises on the second. Unknown names are ignored rather than
+    # refused — a stale bookmark should show a list, not an error — and the
+    # allowlist is what keeps a request from naming any other method.
+    scope :with_stock_status, ->(*statuses) {
+      wanted = statuses.flatten.map(&:to_s) & STOCK_STATUS_SCOPES
+      next all if wanted.empty?
+
+      wanted.map { |status| public_send(status) }.reduce(:or)
+    }
+
+    # Stock levels for products assigned to `store`, walking
+    # `variant → product → store`.
+    #
+    # Used by the admin API as the base scope so the controller can filter
+    # directly by stock_location/variant without inheriting
+    # `Spree::Store#stock_levels`'s extra joins or the variant default
+    # ordering.
+    scope :for_store, ->(store) {
+      joins(variant: :product).where(spree_products: { store_id: store.id })
+    }
+
+    def backordered_inventory_units
+      Spree::InventoryUnit.backordered_for_stock_level(self)
+    end
+
+    # @api private
+    # Physical stock changes through movements only — call a
+    # {Spree::StockLocation} verb rather than this, so the change leaves an
+    # audit row. Keeps the locked read-modify-write that
+    # {#process_backorders} needs the delta for.
+    #
+    # @param force [Boolean] let the write leave the shelf below zero. Only a
+    #   forced dispatch asks for this: the merchant has decided the parcel
+    #   left whatever the ledger claims.
+    def adjust_count_on_hand(value, force: false)
+      with_lock do
+        set_count_on_hand(count_on_hand + value, force: force)
+      end
+    end
+
+    # @param force [Boolean] see {#adjust_count_on_hand}
+    def set_count_on_hand(value, force: false)
+      @forced_count_on_hand = force
+      self.count_on_hand = value
+      process_backorders(count_on_hand - count_on_hand_was)
+
+      save!
+    ensure
+      # Scoped to this write: the exemption must not outlive the call that
+      # asked for it.
+      @forced_count_on_hand = false
+    end
+
+    # Units that are physically here and not already promised to a placed
+    # order — what a customer can still buy from this level.
+    def in_stock?
+      available_count.positive?
+    end
+
+    # Tells whether it's available to be included in a shipment
+    def available?
+      in_stock? || backorderable?
+    end
+
+    # Promised units go up and down atomically: two fulfillments allocating
+    # the same level concurrently must not read each other's value first, and
+    # neither counter update needs the delta that count_on_hand's locked path
+    # exists for.
+    #
+    # Touched afterwards because the counter write is a bare SQL update: it
+    # runs no callbacks, so without this a placement taking the last unit would
+    # leave the variant's cache keys and the search index claiming it is still
+    # for sale, and would publish no stock_level.updated. Under the old model
+    # the same change went through `save`, and this is what restores it.
+    #
+    # @param value [Integer] signed change
+    # @return [void]
+    def adjust_allocated_count(value)
+      value.negative? ? decrement!(:allocated_count, value.abs) : increment!(:allocated_count, value)
+      touch
+    end
+
+    # Withdraws up to +units+ of promise. Only a promise that exists can be
+    # withdrawn — stock that leaves without ever having been allocated (a
+    # stock transfer, or a fulfillment created before typed movements) must
+    # not drive the counter below zero, which would make the level look more
+    # available than it is.
+    #
+    # Locked, unlike its counterpart {#adjust_allocated_count}: the cap is read
+    # from the same counter the write then moves, so two concurrent releases
+    # reading before either writes would both pass a cap that only covered one
+    # of them.
+    #
+    # @param units [Integer]
+    # @return [void]
+    def release_allocated_count(units)
+      with_lock do
+        withdrawn = [units.abs, allocated_count].min
+        next if withdrawn.zero?
+
+        adjust_allocated_count(-withdrawn)
+      end
+    end
+
+    # Physical stock minus allocated units at this stock level. Distinct from
+    # {Spree::Stock::Quantifier#available_stock}, which sums this across all
+    # stock levels belonging to a variant.
+    #
+    # @return [Integer]
+    def available_count
+      count_on_hand - allocated_count
+    end
+
+    # Units a customer could still buy from this shelf: what is here, minus
+    # what placed orders have taken, minus what checkouts in progress are
+    # holding. The figure the Inventory page calls *Available*, and the Ruby
+    # twin of {.purchasable_arel}, which the `in_stock` scopes filter on.
+    #
+    # @return [Integer]
+    def purchasable_count
+      available_count - reserved_count
+    end
+
+    # Units held by checkouts in progress. The counter follows the
+    # reservation rows: each row adds itself on create, moves the figure on
+    # a quantity change and gives it back on destroy, and
+    # {Spree::StockReservation.withdraw} does the same for a batch delete.
+    # Nothing else writes it; the `spree:stock:recount_levels` task repairs
+    # drift, but another writer is the bug.
+    #
+    # @param value [Integer] signed change
+    # @return [void]
+    def adjust_reserved_count(value)
+      adjust_clamped_counter(:reserved_count, value)
+    end
+
+    # Units on their way here on an open purchase order or an in-flight
+    # transfer. Written only by the workflows that move those documents in
+    # and out of that state and by the receipt recorder that lands the units.
+    #
+    # @param value [Integer] signed change
+    # @return [void]
+    def adjust_incoming_count(value)
+      adjust_clamped_counter(:incoming_count, value)
+    end
+
+    def reduce_count_on_hand_to_zero
+      set_count_on_hand(0) if count_on_hand > 0
+    end
+
+    private
+
+    # One atomic UPDATE, clamped at zero in the statement itself so a
+    # withdrawal larger than the counter — a level whose figure was already
+    # repaired underneath a writer — stops at zero instead of eating into
+    # what something else holds. No row lock is needed: the database
+    # applies the arithmetic to the value it holds at that moment, and the
+    # same statement stamps `updated_at`.
+    #
+    # The variant is touched for the reason {#adjust_allocated_count} gives:
+    # a bare UPDATE runs no callbacks, and both figures change what the
+    # variant's cache keys and search index say about it.
+    def adjust_clamped_counter(column, value)
+      return if value.zero?
+
+      counter = self.class.arel_table[column]
+      next_value =
+        if value.positive?
+          counter + value
+        else
+          Arel::Nodes::Case.new.when(counter.gt(value.abs)).then(counter - value.abs).else(0)
+        end
+      now = Time.current
+      self.class.where(id: id).update_all(column => next_value, updated_at: now)
+      self[column] = [self[column] + value, 0].max
+      self.updated_at = now
+      variant.touch
+    end
+
+    # A shelf can only be driven below zero by a write that asked to, and then
+    # it means Spree never saw those goods arrive — a receiving gap that heals
+    # itself when the missing `received` movement lands. Every other writer, a
+    # correction above all, is stopped: a hand-typed count below zero is a
+    # typo, not a fact.
+    def verify_count_on_hand?
+      count_on_hand_changed? && count_on_hand.negative? &&
+        count_on_hand < count_on_hand_was && !@forced_count_on_hand
+    end
+
+    # Process backorders based on amount of stock received
+    # If stock was -20 and is now -15 (increase of 5 units), then we can process atmost 5 inventory orders.
+    # If stock was -20 but then was -25 (decrease of 5 units), do nothing.
+    def process_backorders(number)
+      return unless number.positive?
+
+      units = backordered_inventory_units.first(number) # We can process atmost n backorders
+      filled_units = []
+
+      units.each do |unit|
+        break unless number.positive?
+
+        # What this unit takes of the arriving stock — the whole unit, or the
+        # part of it the arrival covers. Read before the split, because the
+        # split leaves `unit.quantity` holding the *remainder*, and subtracting
+        # that would let the next unit be filled from stock already spoken for.
+        filled = [unit.quantity, number].min
+
+        if unit.quantity > number
+          # if required quantity is greater than available
+          # split off and fulfill that
+          split = unit.split_inventory!(number)
+          filled_units << split if split.fill_backorder!
+        else
+          filled_units << unit if unit.fill_backorder!
+        end
+        number -= filled
+      end
+
+      # One recalculation per affected order, after the whole arrival is
+      # allocated — filling five backorders on one order is one order update,
+      # not five.
+      filled_units.filter_map(&:order).uniq.each(&:fulfill!)
+    end
+  end
+end

data/app/models/spree/stock_location.rb

@@ -11,23 +11,33 @@ module Spree
     # (ship-to-store). See docs/plans/6.0-fulfillment-and-delivery.md.
     PICKUP_STOCK_POLICIES = %w[local any].freeze
 
-    include Spree::UniqueName
+    include Spree::SingleStoreResource
+    include Spree::HasExternalReferences
     if defined?(Spree::Security::StockLocations)
       include Spree::Security::StockLocations
     end
-    if defined?(Spree::VendorConcern)
-      include Spree::VendorConcern
-    end
 
     acts_as_paranoid
 
-    has_many :shipments
-    has_many :stock_items, dependent: :delete_all, inverse_of: :stock_location
-    has_many :variants, through: :stock_items
-    has_many :stock_movements, through: :stock_items
+    has_many :fulfillments, class_name: 'Spree::Fulfillment'
+    has_many :shipments, class_name: 'Spree::Fulfillment', foreign_key: :stock_location_id, deprecated: true
+    has_many :stock_levels, class_name: 'Spree::StockLevel', dependent: :delete_all, inverse_of: :stock_location
+    has_many :variants, through: :stock_levels
+    has_many :stock_movements, through: :stock_levels
+
+    has_iso_geography
+
+    # Whose shelf this is. Nil is the operator's own — the only case in a store
+    # that is not a marketplace.
+    belongs_to :seller, class_name: 'Spree::Seller', optional: true, inverse_of: :stock_locations
 
-    belongs_to :state, class_name: 'Spree::State', optional: true
-    belongs_to :country, class_name: 'Spree::Country'
+    # Per owner rather than per store, which is why validates_store_uniqueness is not used
+    # here: an operator and each of their sellers may each have a "Warehouse",
+    # which is what a marketplace looks like.
+    normalizes :name, with: ->(value) { value&.to_s&.squish&.presence }
+    validates :name, presence: true,
+                     uniqueness: { case_sensitive: false, allow_blank: true,
+                                   scope: [*spree_base_uniqueness_scope, :store_id, :seller_id] }
 
     validates :kind, presence: true
     validates :pickup_stock_policy, inclusion: { in: PICKUP_STOCK_POLICIES }
@@ -36,70 +46,85 @@ module Spree
               allow_nil: true
 
     self.whitelisted_ransackable_attributes = %w[
-      name active default kind pickup_enabled
-      country_id state_id created_at updated_at
+      name active default kind pickup_enabled returns_enabled
+      country_code state_code created_at updated_at
+      seller_id
     ]
+    self.whitelisted_ransackable_associations = %w[seller]
 
     scope :active, -> { where(active: true) }
     scope :pickup_enabled, -> { where(pickup_enabled: true) }
+    scope :returns_enabled, -> { where(returns_enabled: true) }
     scope :order_default, -> { order(default: :desc, name: :asc) }
+    # The operator's own locations — a marketplace's first-party stock.
+    scope :first_party, -> { where(seller_id: nil) }
+    scope :owned_by, ->(store_id:, seller_id:) { where(store_id: store_id, seller_id: seller_id) }
 
-    before_validation :normalize_country
-    before_validation :normalize_state
-
-    after_create :create_stock_items, if: :propagate_all_variants?
+    after_create :create_stock_levels, if: :propagate_all_variants?
     after_save :ensure_one_default
     after_update :conditional_touch_records
 
-    delegate :name, :iso3, :iso, :iso_name, to: :country, prefix: true, allow_nil: true
-    delegate :abbr, to: :state, prefix: true, allow_nil: true
-
-    # Writer methods for API convenience — accept ISO/abbr codes instead of FK IDs.
-    # Mirrors Spree::Address: SDK clients use country_iso/state_abbr because
-    # Country/State don't expose prefixed IDs (their `iso` is the public handle).
-    def country_iso=(value)
-      @country_iso_input = value
-    end
-
-    def state_abbr=(value)
-      @state_abbr_input = value
-    end
+    delegate :name, :iso3, :iso_name, to: :country, prefix: true, allow_nil: true
 
     def state_text
-      state.try(:abbr) || state.try(:name) || state_name
+      state_code.presence || state.try(:name) || state_name
     end
 
     # Wrapper for creating a new stock item respecting the backorderable config
     def propagate_variant(variant)
-      stock_items.create!(variant: variant, backorderable: backorderable_default)
+      stock_levels.create!(variant: variant, backorderable: backorderable_default)
     end
 
     # Return either an existing stock item or create a new one. Useful in
     # scenarios where the user might not know whether there is already a stock
     # item for a given variant
-    def set_up_stock_item(variant)
-      stock_item(variant) || propagate_variant(variant)
+    def set_up_stock_level(variant)
+      stock_level(variant) || propagate_variant(variant)
     end
 
-    # Returns an instance of StockItem for the variant id.
+    # Returns an instance of StockLevel for the variant id.
     #
     # @param variant_id [String] The id of a variant.
     #
-    # @return [StockItem] Corresponding StockItem for the StockLocation's variant.
-    def stock_item(variant_id)
-      stock_items.where(variant_id: variant_id).order(:id).first
+    # @return [StockLevel] Corresponding StockLevel for the StockLocation's variant.
+    def stock_level(variant_id)
+      stock_levels.where(variant_id: variant_id).order(:id).first
     end
 
     def stocks?(variant)
-      stock_items.exists?(variant: variant)
+      stock_levels.exists?(variant: variant)
+    end
+
+    # @deprecated Use {#stock_levels}; removed in 6.1.
+    def stock_items
+      Spree::Deprecation.warn('Spree::StockLocation#stock_items is deprecated and will be removed in Spree 6.1. Use #stock_levels instead.')
+      stock_levels
     end
 
-    # Attempts to look up StockItem for the variant, and creates one if not found.
+    # @deprecated Use {#stock_level}; removed in 6.1.
+    def stock_item(variant_id)
+      Spree::Deprecation.warn('Spree::StockLocation#stock_item is deprecated and will be removed in Spree 6.1. Use #stock_level instead.')
+      stock_level(variant_id)
+    end
+
+    # @deprecated Use {#set_up_stock_level}; removed in 6.1.
+    def set_up_stock_item(variant)
+      Spree::Deprecation.warn('Spree::StockLocation#set_up_stock_item is deprecated and will be removed in Spree 6.1. Use #set_up_stock_level instead.')
+      set_up_stock_level(variant)
+    end
+
+    # @deprecated Use {#stock_level_or_create}; removed in 6.1.
+    def stock_item_or_create(variant_or_variant_id)
+      Spree::Deprecation.warn('Spree::StockLocation#stock_item_or_create is deprecated and will be removed in Spree 6.1. Use #stock_level_or_create instead.')
+      stock_level_or_create(variant_or_variant_id)
+    end
+
+    # Attempts to look up StockLevel for the variant, and creates one if not found.
     #
     # @param variant Variant instance or Variant ID
     #
-    # @return [StockItem] Corresponding StockItem for the StockLocation's variant.
-    def stock_item_or_create(variant_or_variant_id)
+    # @return [StockLevel] Corresponding StockLevel for the StockLocation's variant.
+    def stock_level_or_create(variant_or_variant_id)
       if variant_or_variant_id.is_a?(Spree::Variant)
         variant_id = variant_or_variant_id.id
         variant = variant_or_variant_id
@@ -107,7 +132,7 @@ module Spree
         variant_id = variant_or_variant_id
         variant = Spree::Variant.find(variant_or_variant_id)
       end
-      stock_item(variant_id) || propagate_variant(variant)
+      stock_level(variant_id) || propagate_variant(variant)
     end
 
     # Returns the count on hand number for the variant
@@ -116,46 +141,83 @@ module Spree
     #
     # @return [Integer]
     def count_on_hand(variant)
-      stock_item(variant).try(:count_on_hand)
+      stock_level(variant).try(:count_on_hand)
     end
 
     def backorderable?(variant)
-      stock_item(variant).try(:backorderable?)
+      stock_level(variant).try(:backorderable?)
     end
 
-    def restock(variant, quantity, originator = nil, persist: true)
-      move(variant, quantity, originator, persist: persist)
+    # The five stock verbs are the public surface — extensions call these
+    # rather than creating movements themselves, so every row comes out typed
+    # and carrying its cause.
+
+    # Goods arrived: a purchase order, a transfer receipt, a return.
+    #
+    # @param variant [Spree::Variant]
+    # @param quantity [Integer]
+    # @param cause [ApplicationRecord, nil] the record this is happening for
+    # @return [Spree::StockMovement]
+    # @param unit_cost [BigDecimal, nil] what each unit landed at, when the
+    #   goods were bought. Recorded on the movement so a rolling average cost
+    #   has a ledger to read; null for stock the merchant already owned.
+    def restock(variant, quantity, cause = nil, unit_cost: nil)
+      move(variant, quantity, kind: 'received', cause: cause, unit_cost: unit_cost)
     end
 
-    def restock_backordered(variant, quantity, _originator = nil)
-      item = stock_item_or_create(variant)
-      item.update_columns(
-        count_on_hand: item.count_on_hand + quantity,
-        updated_at: Time.current
-      )
+    # Goods left.
+    #
+    # @param force [Boolean] record the departure even if it leaves the shelf
+    #   below zero. A merchant forcing a dispatch has decided the parcel left
+    #   whatever the ledger claims.
+    # @return [Spree::StockMovement]
+    def unstock(variant, quantity, cause = nil, force: false)
+      move(variant, quantity, kind: 'shipped', cause: cause, force: force)
     end
 
-    def unstock(variant, quantity, originator = nil, persist: true)
-      move(variant, -quantity, originator, persist: persist)
+    # Promises stock to a placed order. The cause is the fulfillment, never
+    # the order: it owns the origin location and the unit split, and the order
+    # comes along with it.
+    #
+    # @param fulfillment [Spree::Fulfillment]
+    # @return [Spree::StockMovement]
+    def allocate(variant, quantity, fulfillment)
+      move(variant, quantity, kind: 'allocated', cause: fulfillment)
     end
 
-    def move(variant, quantity, originator = nil, persist: true)
-      stock_item = stock_item_or_create(variant)
+    # Withdraws a promise — a canceled, relocated or shrunk fulfillment.
+    # Nothing physical moves.
+    #
+    # @param fulfillment [Spree::Fulfillment]
+    # @return [Spree::StockMovement]
+    def release(variant, quantity, fulfillment)
+      move(variant, quantity, kind: 'released', cause: fulfillment)
+    end
 
-      if persist
-        stock_item.stock_movements.create!(quantity: quantity, originator: originator)
-      else
-        originator.stock_movements << stock_item.stock_movements.build(quantity: quantity)
-      end
+    # A manual correction — an inventory count, shrinkage, damage. Signed, so
+    # a negative quantity writes stock off.
+    #
+    # @param reason [String] audit text, required
+    # @return [Spree::StockMovement]
+    def adjust(variant, quantity, reason:)
+      move(variant, quantity, kind: 'adjusted', reason: reason)
+    end
+
+    def move(variant, quantity, kind:, cause: nil, reason: nil, force: false, unit_cost: nil)
+      stock_level = stock_level_or_create(variant)
+      attributes = { quantity: quantity, kind: kind, reason: reason, unit_cost: unit_cost,
+                     **cause_attributes(cause) }
+
+      stock_level.stock_movements.create!(attributes) { |movement| movement.force = force }
     end
 
     def fill_status(variant, quantity)
-      if item = stock_item_or_create(variant)
-        if item.count_on_hand >= quantity
+      if item = stock_level_or_create(variant)
+        if item.available_count >= quantity
           on_hand = quantity
           backordered = 0
         else
-          on_hand = item.count_on_hand
+          on_hand = item.available_count
           on_hand = 0 if on_hand < 0
           # A pre-order oversells like a backorder: the shortfall becomes
           # backordered inventory units (the backorder_limit cap is enforced
@@ -169,15 +231,25 @@ module Spree
       end
     end
 
+    # Enough of an address to post a parcel to and for a carrier to rate
+    # against. `#address` below builds an unsaved record from these columns
+    # whatever their state, so a blank location answers with a blank address
+    # that reads as configured — every caller needs this guard first.
+    #
+    # @return [Boolean]
+    def postable?
+      address1.present? && city.present? && country_code.present?
+    end
+
     def address
       Spree::Address.new(
         address1: address1,
         address2: address2,
         company: company,
         city: city,
-        state: state,
+        state_code: state_code,
         state_name: state_name,
-        country: country,
+        country_code: country_code,
         zipcode: zipcode,
         phone: phone
       )
@@ -207,37 +279,43 @@ module Spree
 
     private
 
-    def normalize_country
-      iso = @country_iso_input
-      return if iso.blank?
-
-      self.country = Spree::Country.by_iso(iso)
-      @country_iso_input = nil
-    end
-
-    def normalize_state
-      abbr = @state_abbr_input
-      return if abbr.blank? || country.blank?
-
-      self.state = country.states.find_by(abbr: abbr)
-      @state_abbr_input = nil
+    # One cause in, the foreign keys it implies out. A fulfillment brings its
+    # order with it because "which order was this for?" must not cost a join.
+    # The set is closed and core-owned — extensions register causes by adding
+    # a branch here, never by inventing a movement column.
+    def cause_attributes(cause)
+      case cause
+      when Spree::Fulfillment   then { fulfillment: cause, order: cause.order }
+      when Spree::Return        then { return: cause, order: cause.order }
+      when Spree::Exchange      then { exchange: cause, order: cause.order }
+      when Spree::StockTransfer then { stock_transfer: cause }
+      when Spree::PurchaseOrder then { purchase_order: cause }
+      # A delivery names the document it was against as well as itself.
+      when Spree::StockReceipt  then { stock_receipt: cause, **cause_attributes(cause.receivable) }
+      when Spree::Order         then { order: cause }
+      else {}
+      end
     end
 
-    def create_stock_items
-      Spree::StockLocations::StockItems::CreateJob.perform_later(self)
+    def create_stock_levels
+      Spree::StockLocations::StockLevels::CreateJob.perform_later(self)
     end
 
+    # One default per OWNER, not per store: on a marketplace the operator has a
+    # default and so does every seller, so scoping this to the store would let
+    # a seller saving their own default silently demote the operator's.
     def ensure_one_default
-      if default
-        StockLocation.where(default: true).where.not(id: id).update_all(default: false)
-        StockLocation.where.not(id: id).update_all(updated_at: Time.current)
-      end
+      return unless default
+
+      siblings = self.class.owned_by(store_id: store_id, seller_id: seller_id).where.not(id: id)
+      siblings.where(default: true).update_all(default: false)
+      siblings.update_all(updated_at: Time.current)
     end
 
     def conditional_touch_records
       return unless active_changed?
 
-      stock_items.update_all(updated_at: Time.current)
+      stock_levels.update_all(updated_at: Time.current)
       variants.update_all(updated_at: Time.current)
     end
   end

data/app/models/spree/stock_movement/custom_events.rb

@@ -37,7 +37,7 @@ module Spree
       end
 
       def product
-        stock_item.variant.product
+        stock_level.variant.product
       end
     end
   end