spree_core 5.6.1 → 6.0.0.beta2

data/app/models/spree/variant.rb

@@ -6,42 +6,65 @@ module Spree
     acts_as_list scope: :product
 
     include Spree::MemoizedData
-    include Spree::Metafields
+    include Spree::HasCustomFields
     include Spree::Metadata
+    include Spree::HasExternalReferences
     include Spree::Searchable
-    include Spree::Variant::Webhooks
+    include Spree::StorePreferences
 
     publishes_lifecycle_events
 
-    MEMOIZED_METHODS = %w(in_stock on_sale backorderable tax_category options_text compare_at_price)
+    MEMOIZED_METHODS = %w(in_stock on_sale backorderable tax_category tax_category_id options_text compare_at_price)
 
     DIMENSION_UNITS = %w[mm cm in ft]
     WEIGHT_UNITS = %w[g kg lb oz]
 
+    # What a buyer is quoted in. Stored quantities are units at every level;
+    # this only changes the vocabulary a storefront presents.
+    PURCHASE_UNITS = %w[unit carton]
+
     belongs_to :product, -> { with_deleted }, touch: true, class_name: 'Spree::Product', inverse_of: :variants
     belongs_to :tax_category, class_name: 'Spree::TaxCategory', optional: true
-
-    delegate :name, :name=, :description, :slug, :available_on, :make_active_at, :shipping_category_id,
-             :meta_description, :meta_keywords, :shipping_category, to: :product
+    # The carton this variant is packed into. Geometry lives on the shared
+    # row; how many units fit and what a packed carton weighs stay here.
+    belongs_to :carton_package_type, class_name: 'Spree::PackageType', optional: true,
+               inverse_of: :variants
+    # Which seller sells this variant. Nil is the operator's own listing, and
+    # on a product whose seller owns every variant the product answers instead
+    # — see #resolved_seller_id. Several sellers on one product is the whole point: two
+    # of them are two variant rows, so their stock, prices and line-item
+    # attribution are separate by construction.
+    belongs_to :seller, class_name: 'Spree::Seller', optional: true
+    # Nil defers to the product, exactly as tax_category does.
+    belongs_to :delivery_profile, class_name: 'Spree::DeliveryProfile', optional: true
+
+    delegate :name, :name=, :description, :slug, :available_on, :make_active_at, :product_type_id,
+             :meta_description, :meta_keywords, :product_type, :store_id, to: :product
 
     normalizes :sku, with: ->(value) { value&.to_s&.strip }
+    normalizes :hs_code, with: ->(value) { value&.to_s&.gsub(/[^0-9]/, '') }
+    normalizes :country_of_origin, with: ->(value) { value&.to_s&.strip&.upcase }
 
     # we need to have this callback before any dependent: :destroy associations
     # https://github.com/rails/rails/issues/3458
     before_destroy :ensure_not_in_complete_orders
     after_destroy :remove_line_items_from_incomplete_orders
 
-    # must include this after ensure_not_in_complete_orders to make sure price won't be deleted before validation
-    include Spree::DefaultPrice
+    # Terms stated for this variant go with it. Nothing below the cart layer
+    # reads them, but a row pointing at a destroyed variant would resolve for
+    # nobody and count against the agreement's overrides forever.
+    has_many :catalog_quantity_rules, class_name: 'Spree::CatalogQuantityRule',
+                                      dependent: :destroy, inverse_of: :variant
 
     with_options inverse_of: :variant do
-      has_many :inventory_units
+      has_many :fulfillment_items, class_name: 'Spree::FulfillmentItem'
       has_many :line_items
-      has_many :stock_items, dependent: :destroy, autosave: true
+      has_many :stock_levels, class_name: 'Spree::StockLevel', dependent: :destroy, autosave: true
     end
+    has_many :inventory_units, class_name: 'Spree::FulfillmentItem', inverse_of: :variant, deprecated: true
 
     has_many :orders, through: :line_items
-    with_options through: :stock_items do
+    with_options through: :stock_levels do
       has_many :stock_locations
       has_many :stock_movements
       has_many :stock_reservations
@@ -50,17 +73,25 @@ module Spree
     has_many :option_value_variants, class_name: 'Spree::OptionValueVariant'
     has_many :option_values, through: :option_value_variants, dependent: :destroy, class_name: 'Spree::OptionValue'
 
-    has_many :images, -> { order(:position) }, as: :viewable, dependent: :destroy, class_name: 'Spree::Asset'
+    has_many :images, -> { order(:position) }, as: :viewable, dependent: :destroy, class_name: 'Spree::Media'
 
     has_many :variant_media, class_name: 'Spree::VariantMedia', dependent: :destroy
     # Order through the asset's product-level position so a variant's gallery
     # follows whatever ordering the merchant set on the product. There's no
     # per-variant reordering — link/unlink only.
     has_many :associated_media,
-             -> { order(Spree::Asset.arel_table[:position].asc) },
-             through: :variant_media, source: :asset, class_name: 'Spree::Asset'
+             -> { order(Spree::Media.arel_table[:position].asc) },
+             through: :variant_media, source: :asset, class_name: 'Spree::Media'
+
+    belongs_to :primary_media, class_name: 'Spree::Media', optional: true, foreign_key: :primary_media_id
 
-    belongs_to :primary_media, class_name: 'Spree::Asset', optional: true, foreign_key: :primary_media_id
+    # The variant's own image, or its product's when it has none — the
+    # picture a list row shows for it.
+    #
+    # @return [Spree::Media, nil]
+    def thumbnail
+      primary_media || product&.primary_media
+    end
 
     has_many :prices,
              class_name: 'Spree::Price',
@@ -68,50 +99,126 @@ module Spree
              inverse_of: :variant,
              autosave: true
 
-    has_many :wished_items, dependent: :destroy
+    has_many :wishlist_items, class_name: 'Spree::WishlistItem', dependent: :destroy
+    has_many :wished_items, class_name: 'Spree::WishlistItem', inverse_of: :variant, deprecated: true
 
-    has_many :digitals
+    has_many :digital_assets, class_name: 'Spree::DigitalAsset', dependent: :destroy
+    has_many :digitals, class_name: 'Spree::DigitalAsset', deprecated: true
 
     before_validation :set_cost_currency
     before_validation :apply_pending_options, if: :pending_options?
-
-    validate :check_price, if: -> { Spree::Config.enable_legacy_default_price }
-
-    validates :option_value_variants, presence: true, unless: :is_master?
+    before_validation :apply_pending_stock_levels, if: :pending_stock_levels?
 
     validates :cost_price, numericality: { greater_than_or_equal_to: 0, allow_nil: true }
-    validates :price, numericality: { greater_than_or_equal_to: 0, allow_nil: true },
-                      if: -> { Spree::Config.enable_legacy_default_price }
-    validates :sku, uniqueness: { conditions: -> { where(deleted_at: nil) }, case_sensitive: false, scope: spree_base_uniqueness_scope },
-                    allow_blank: true, unless: :disable_sku_validation?
+    # Uniqueness is scoped to the seller — see #validate_sku_uniqueness. Written
+    # by hand rather than as a `scope:` option because the seller is resolved
+    # (the variant's own, else its product's) and the built-in validator reads
+    # the raw column, which would let two sellers who each own a whole product
+    # collide.
+    validate :validate_sku_uniqueness, if: -> { sku.present? && !disable_sku_validation? }
+
+    # Both guards catch raw prefixed-id assignment as well as association
+    # writes, the way the same pair does on Product: a seller or a shipping
+    # configuration from another store must never be reachable by id.
+    validate :seller_must_belong_to_store, if: -> { will_save_change_to_seller_id? }
+    validate :delivery_profile_must_belong_to_store, if: -> { will_save_change_to_delivery_profile_id? }
+    validate :carton_package_type_must_belong_to_store, if: -> { will_save_change_to_carton_package_type_id? }
+
+    # On an owned product the variant's own seller and profile columns carry
+    # no meaning — every variant is the product's seller's and ships as the
+    # product does — so they are kept blank rather than validated. A client
+    # that reads a resolved `seller_id` and writes it straight back therefore
+    # changes nothing, and the storefront never has to know which mode it is
+    # in. Only a variant on a master product keeps what it is given.
+    before_validation :blank_owned_product_overrides
 
     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?
+    # Base purchasing rules. Blank means unrestricted, so the columns start
+    # empty and every existing variant keeps buying one at a time.
+    validates :minimum_order_quantity, numericality: { only_integer: true, greater_than: 0, allow_nil: true }
+    validates :order_multiple, numericality: { only_integer: true, greater_than: 0, allow_nil: true }
+    validates :units_per_carton, numericality: { only_integer: true, greater_than: 0, allow_nil: true }
+    validates :cartons_per_pallet, numericality: { only_integer: true, greater_than: 0, allow_nil: true }
+    validates :carton_weight, numericality: { greater_than: 0, allow_nil: true }
+    validate :carton_package_type_is_a_carton
+    validates :purchase_unit, inclusion: { in: PURCHASE_UNITS }, allow_blank: true
+
+    # Both are data errors the merchant should hear about while editing, not
+    # discover through a customer complaint: an order multiple that straddles
+    # carton boundaries can never be shipped whole, and quoting cartons
+    # without saying how many units one holds leaves the storefront no way to
+    # render the offer.
+    validate :order_multiple_fits_cartons
+    validate :carton_purchase_unit_has_divisor
+
+    # Customs classification. Optional everywhere — only an international
+    # shipment or a duties provider needs it, and each raises its own error
+    # when it does. Carriers reject an HS code outside 6..13 digits, so the
+    # format is checked here rather than at the label counter.
+    validates :hs_code, format: { with: /\A\d{6,13}\z/ }, allow_blank: true
+    validates :country_of_origin, format: { with: /\A[A-Z]{2}\z/ }, allow_blank: true
+
+    after_create :create_stock_levels
     after_commit :clear_line_items_cache, on: :update
 
-    after_save :create_default_stock_item, unless: :track_inventory?
+    after_save :create_default_stock_level, unless: :track_inventory?
     after_update_commit :handle_track_inventory_change
 
-    after_commit :remove_prices_from_master_variant, on: [:create, :update], unless: :is_master?
-    after_commit :remove_stock_items_from_master_variant, on: :create, unless: :is_master?
-    after_create :increment_product_variant_count, unless: :is_master?
-    after_destroy :decrement_product_variant_count, unless: :is_master?
+    after_create :increment_product_variant_count
+    after_destroy :decrement_product_variant_count
 
-    scope :in_stock, -> { left_joins(:stock_items).where("#{Spree::Variant.table_name}.track_inventory = ? OR #{Spree::StockItem.table_name}.count_on_hand > ?", false, 0) }
-    scope :backorderable, -> { left_joins(:stock_items).where(spree_stock_items: { backorderable: true }) }
+    scope :in_stock, -> { left_joins(:stock_levels).where("#{Spree::Variant.table_name}.track_inventory = ? OR (#{Spree::StockLevel.table_name}.count_on_hand - #{Spree::StockLevel.table_name}.allocated_count) > ?", false, 0) }
+    scope :backorderable, -> { left_joins(:stock_levels).where(Spree::StockLevel.table_name => { backorderable: true }) }
     scope :in_stock_or_backorderable, -> { in_stock.or(backorderable) }
 
-    scope :eligible, lambda {
-      joins(:product).where(
-        arel_table[:is_master].eq(false).or(
-          Spree::Product.arel_table[:variant_count].eq(0)
-        )
-      )
+    # Variants one warehouse could actually send: it holds a level for them
+    # with something available on it. Written for the transfer form's picker,
+    # which would otherwise offer SKUs the source has none of — and
+    # `MarkInTransit` refuses those per line, once the van is supposedly
+    # loaded and the merchant has moved on.
+    #
+    # Untracked variants are excluded on purpose, unlike `in_stock`: a
+    # transfer moves counted units, and the ship guard would refuse them too.
+    #
+    # Takes a prefixed or a raw id — a ransackable scope decodes its own
+    # argument, since the controller only decodes keys carrying a predicate
+    # suffix.
+    scope :available_at_stock_location, ->(stock_location) {
+      levels = Spree::StockLevel.table_name
+      # Decoded against the stock location's own prefix, so another model's ID
+      # cannot resolve to a warehouse whose numeric payload happens to match.
+      # Anything that is neither that nor a raw id selects nothing rather than
+      # reaching the database, where a non-numeric value raises on PostgreSQL.
+      location_id = Spree::StockLocation.decode_own_prefixed_id(stock_location)
+      location_id ||= stock_location if stock_location.to_s.match?(/\A\d+\z/)
+
+      next none if location_id.blank?
+
+      joins(:stock_levels).
+        where(levels => { stock_location_id: location_id }).
+        where("#{levels}.count_on_hand - #{levels}.allocated_count > ?", 0)
+    }
+
+    scope :eligible, -> { all }
+
+    # Variants whose *resolved* seller is the given one: their own column when
+    # set, otherwise their product's. Passing nil selects first-party listings,
+    # which on a store with no sellers is the whole catalog.
+    scope :for_seller, lambda { |seller|
+      seller_id = seller.respond_to?(:id) ? seller.id : seller
+      own = arel_table[:seller_id]
+      products = Spree::Product.arel_table[:seller_id]
+
+      relation = joins(:product)
+      if seller_id.nil?
+        relation.where(own.eq(nil).and(products.eq(nil)))
+      else
+        relation.where(own.eq(seller_id).or(own.eq(nil).and(products.eq(seller_id))))
+      end
     }
 
     scope :not_discontinued, lambda {
@@ -124,9 +231,15 @@ module Spree
 
     scope :not_deleted, -> { where("#{Spree::Variant.quoted_table_name}.deleted_at IS NULL") }
 
+    # Variants the shop sells in this currency. Base prices only: a price
+    # list's rows are what one audience pays under an agreement, and a ladder
+    # holds several rows for one variant, so a contract-only variant is not
+    # available to everyone (docs/plans/6.0-volume-pricing.md).
     scope :for_currency_and_available_price_amount, lambda { |currency = nil|
       currency ||= Spree::Store.default.default_currency
-      joins(:prices).where("#{Spree::Price.table_name}.currency = ?", currency).where("#{Spree::Price.table_name}.amount IS NOT NULL").distinct
+      joins(:prices).
+        where(Spree::Price.table_name => { currency: currency, price_list_id: nil }).
+        where("#{Spree::Price.table_name}.amount IS NOT NULL").distinct
     }
 
     scope :active, lambda { |currency = nil|
@@ -135,13 +248,18 @@ module Spree
     }
 
     scope :with_option_value, lambda { |option_name, option_value|
-      option_type_ids = OptionType.where(name: option_name).ids
+      # Option types are per store, so two stores may each define `size`;
+      # narrow to the store in context so a filter never matches another
+      # store's values.
+      option_types = OptionType.where(name: option_name)
+      option_types = option_types.where(store_id: Spree::Current.store.id) if Spree::Current.store
+      option_type_ids = option_types.ids
       return none if option_type_ids.empty?
 
       joins(:option_values).where(Spree::OptionValue.table_name => { name: option_value, option_type_id: option_type_ids })
     }
 
-    scope :with_digital_assets, -> { joins(:digitals) }
+    scope :with_digital_assets, -> { joins(:digital_assets) }
 
     # Free-text variant search: SKU, parent product name, and any
     # option-value presentation (e.g. "Red", "XL"). The 3-char floor
@@ -151,7 +269,7 @@ module Spree
 
       conditions = [
         search_condition(self, :sku, query),
-        search_condition(Spree::OptionValue, :presentation, query),
+        search_condition(Spree::OptionValue, :label, query),
       ]
 
       if Spree.use_translations?
@@ -180,7 +298,7 @@ module Spree
     end
 
     accepts_nested_attributes_for(
-      :stock_items,
+      :stock_levels,
       reject_if: ->(attributes) { attributes['stock_location_id'].blank? || attributes['count_on_hand'].blank? },
       allow_destroy: false
     )
@@ -197,10 +315,21 @@ module Spree
       allow_destroy: false
     )
 
-    self.whitelisted_ransackable_associations = %w[option_values product tax_category prices default_price]
-    self.whitelisted_ransackable_attributes = %w[weight depth width height sku discontinue_on is_master cost_price cost_currency track_inventory
-                                                 deleted_at product_id]
-    self.whitelisted_ransackable_scopes = %i(product_name_or_sku_cont search_by_product_name_or_sku search)
+    self.whitelisted_ransackable_associations = %w[option_values product tax_category prices seller]
+    # `seller_id` and `delivery_profile_id` are deliberately absent: they are
+    # the raw columns, nil on every variant that inherits from its product —
+    # so "filter by seller" against them would silently miss the inheritors,
+    # which on a single-owner catalog is all of them. Server-side callers
+    # narrow by seller with the `for_seller` scope, which resolves the way
+    # `resolved_seller` does; a client-facing filter needs an endpoint that
+    # applies it, not an allowlist entry that quietly answers a different
+    # question.
+    self.whitelisted_ransackable_attributes = %w[weight depth width height sku discontinue_on cost_price cost_currency track_inventory
+                                                 deleted_at product_id hs_code country_of_origin
+                                                 minimum_order_quantity order_multiple purchase_unit units_per_carton
+                                                 carton_package_type_id carton_weight cartons_per_pallet]
+    self.whitelisted_ransackable_scopes = %i(product_name_or_sku_cont search_by_product_name_or_sku search
+                                             available_at_stock_location)
 
     def self.product_name_or_sku_cont(query)
       sanitized_query = ActiveRecord::Base.sanitize_sql_like(query.to_s.downcase.strip)
@@ -231,7 +360,7 @@ module Spree
                       joins(option_type: :product_option_types).
                       merge(product.product_option_types).
                       reorder('spree_product_option_types.position').
-                      pluck(:presentation).join('/')
+                      pluck(:label).join('/')
     end
 
     # Returns true if the variant is available.
@@ -279,16 +408,72 @@ module Spree
                            end
     end
 
+    # Who sells this variant. Two modes, and they never mix:
+    #
+    # * An OWNED product (`product.seller_id` set) — every variant is that
+    #   seller's, by definition. No other seller can create a variant here, so
+    #   the variant's own column is meaningless and is kept blank.
+    # * A MASTER product (`product.seller_id` nil) — the shared catalog. This
+    #   is the only place `variant.seller_id` means anything: several sellers
+    #   list variants on one page, and each row names its own.
+    #
+    # So the answer is the product's seller if it has one, else the variant's
+    # own — a plain read, not an inheritance chain. Line items snapshot it at
+    # add-to-cart, and the buy box and SKU check read it. Nil is first-party.
+    #
+    # @return [Spree::Seller, nil]
+    def resolved_seller
+      product&.seller || seller
+    end
+
+    # @return [Integer, nil]
+    def resolved_seller_id
+      product&.seller_id || self[:seller_id]
+    end
+
+    # Whether this variant sits on an owned product — the mode in which the
+    # variant's own seller and delivery-profile columns carry no meaning.
+    #
+    # @return [Boolean]
+    def owned_by_product_seller?
+      product&.seller_id.present?
+    end
+
+    # How this variant ships, on the same two-mode rule as the seller, keyed
+    # on OWNERSHIP rather than on whether the product has a profile — every
+    # product does, so "product's profile if set" would never reach the
+    # variant's own and no seller on a master could ship differently.
+    #
+    # * Owned product: every variant ships as the product does; the variant's
+    #   own column is meaningless and is kept blank.
+    # * Master product: each seller's row names how that seller ships, and
+    #   falls back to the master's profile when it does not.
+    #
+    # A plain read, not memoized.
+    #
+    # @return [Spree::DeliveryProfile, nil]
+    def resolved_delivery_profile
+      return product&.resolved_delivery_profile if owned_by_product_seller?
+
+      delivery_profile || product&.resolved_delivery_profile
+    end
+
+    # @return [Integer, nil]
+    def resolved_delivery_profile_id
+      resolved_delivery_profile&.id
+    end
+
+
     # Returns the options text of the variant.
     # @return [String] the options text of the variant
     def options_text
       @options_text ||= if option_values.loaded?
                           option_values.sort_by do |ov|
                             ov.option_type.position
-                          end.map { |ov| "#{ov.option_type.presentation}: #{ov.presentation}" }.to_sentence(words_connector: ', ', two_words_connector: ', ')
+                          end.map { |ov| "#{ov.option_type.label}: #{ov.label}" }.to_sentence(words_connector: ', ', two_words_connector: ', ')
                         else
                           option_values.includes(:option_type).joins(:option_type).order("#{Spree::OptionType.table_name}.position").map do |ov|
-                            "#{ov.option_type.presentation}: #{ov.presentation}"
+                            "#{ov.option_type.label}: #{ov.label}"
                           end.to_sentence(words_connector: ', ', two_words_connector: ', ')
                         end
     end
@@ -296,13 +481,21 @@ module Spree
     # Returns the exchange name of the variant.
     # @return [String] the exchange name of the variant
     def exchange_name
-      is_master? ? name : options_text
+      option_values.any? ? options_text : name
     end
 
     # Returns the descriptive name of the variant.
     # @return [String] the descriptive name of the variant
     def descriptive_name
-      is_master? ? name + ' - Master' : name + ' - ' + options_text
+      option_values.any? ? "#{name} - #{options_text}" : name
+    end
+
+    # Plain-language contents description for a customs declaration. Customs
+    # authorities reject marketing names, so merchants set an explicit one;
+    # the product name is the fallback that keeps a declaration valid.
+    # @return [String, nil]
+    def customs_description_for_declaration
+      customs_description.presence || name
     end
 
     # Returns the variant's media gallery.
@@ -335,42 +528,45 @@ module Spree
       variant_media.exists?
     end
 
-    # @deprecated Use #primary_media instead.
-    def default_image
-      Spree::Deprecation.warn('Spree::Variant#default_image is deprecated and will be removed in Spree 6.0. Please use Spree::Variant#primary_media instead.')
-      primary_media
-    end
-
     # Updates primary_media_id to the first media item by position.
     # Called when media is added, removed, or reordered.
     # Uses gallery_media so product-level assets linked via VariantMedia are
     # considered alongside legacy variant-pinned images.
     def update_thumbnail!
-      first_media = gallery_media.first
-      update_column(:primary_media_id, first_media&.id)
-    end
+      # Read through a fresh scope, never the cached association — this runs
+      # from a media row's after_commit, and a loaded `images`/`associated_media`
+      # would be missing the sibling rows created after it.
+      candidates = gallery_media.reload.to_a
+      # See Product#update_thumbnail! — a video without a still can't be a thumbnail.
+      first_media = candidates.find(&:renderable_as_image?)
 
-    # Returns first Image for Variant.
-    # @deprecated Use #primary_media instead.
-    # @return [Spree::Image, nil]
-    def primary_image
-      Spree::Deprecation.warn('Spree::Variant#primary_image is deprecated and will be removed in Spree 6.0. Please use Spree::Variant#primary_media instead.')
-      primary_media
+      update_column(:primary_media_id, first_media&.id)
     end
 
-    # Returns second Image for Variant (for hover effects).
-    # @return [Spree::Image, nil]
+    # @deprecated Read #gallery_media directly; removed in 6.1. Nothing in
+    #   Spree calls this — a hover image is a storefront presentation choice,
+    #   not something core should name.
+    # @return [Spree::Media, nil]
     def secondary_image
-      images.second
+      Spree::Deprecation.warn('Spree::Variant#secondary_image is deprecated and will be removed in Spree 6.1. Use #gallery_media instead.')
+      gallery_media.second
     end
 
-    # Returns all images except the default image, combining variant and product images.
-    # @return [Array<Spree::Image>]
+    # @deprecated Read #gallery_media directly; removed in 6.1. Nothing in
+    #   Spree calls this, and which images to show beside the main one is a
+    #   storefront presentation choice.
+    # @return [Array<Spree::Media>]
     def additional_images
-      @additional_images ||= (images + product.images).uniq.reject { |image| image.id == default_image&.id }
+      Spree::Deprecation.warn('Spree::Variant#additional_images is deprecated and will be removed in Spree 6.1. Use #gallery_media instead.')
+      gallery_media.reject { |media| media.id == primary_media&.id }
     end
 
-    # Returns an array of hashes with the option type name, value and presentation
+    # Returns an array of hashes with the option type name, value and label.
+    #
+    # The +presentation+ key keeps its name through the 6.0 column rename: it
+    # is a return shape host apps read, nothing in Spree consumes it, and a
+    # renamed hash key breaks silently.
+    #
     # @return [Array<Hash>]
     def options
       @options ||= option_values.
@@ -381,7 +577,7 @@ module Spree
                      {
                        name: option_value.option_type.name,
                        value: option_value.name,
-                       presentation: option_value.presentation
+                       presentation: option_value.label
                      }
                    end
     end
@@ -408,11 +604,8 @@ module Spree
     # @param opt_type_position [Integer] the position of the option type
     # @return [void]
     def set_option_value(opt_name, opt_value, opt_type_position = nil)
-      # no option values on master
-      return if is_master
-
       option_type = Spree::OptionType.where(name: opt_name.parameterize).first_or_initialize do |o|
-        o.name = o.presentation = opt_name
+        o.name = o.label = opt_name
         o.save!
       end
 
@@ -435,7 +628,7 @@ module Spree
       end
 
       option_value = option_type.option_values.where(name: opt_value.parameterize).first_or_initialize do |o|
-        o.name = o.presentation = opt_value
+        o.name = o.label = opt_value
         o.save!
       end
 
@@ -455,9 +648,9 @@ module Spree
     # @return [String] the presentation of the option value for the given option type
     def option_value(option_type)
       if option_type.is_a?(Spree::OptionType)
-        option_values.detect { |o| o.option_type_id == option_type.id }.try(:presentation)
+        option_values.detect { |o| o.option_type_id == option_type.id }.try(:label)
       else
-        find_option_value(option_type).try(:presentation)
+        find_option_value(option_type).try(:label)
       end
     end
 
@@ -530,22 +723,69 @@ module Spree
     # Syncs stock items from an array of hashes.
     # Upserts stock for listed locations, soft-deletes stock items for unlisted locations.
     # On new records, defers to after_create callback.
-    # @param stock_items_params [Array<Hash>] array of { stock_location_id:, count_on_hand:, backorderable: }
+    # @param stock_levels_params [Array<Hash>] array of { stock_location_id:, count_on_hand:, backorderable: }
     # @return [void]
-    def stock_items=(stock_items_params)
-      return super if stock_items_params.blank? || stock_items_params.first.is_a?(Spree::StockItem)
+    def stock_levels=(stock_levels_params)
+      return super if stock_levels_params.blank? || stock_levels_params.first.is_a?(Spree::StockLevel)
+      return if defer_stock_levels(:stock_levels=, stock_levels_params)
 
       location_ids_in_payload = []
 
-      stock_items_params.each do |stock_data|
+      stock_levels_params.each do |stock_data|
         stock_data = stock_data.to_h.with_indifferent_access
-        location = Spree::StockLocation.find_by_param(stock_data[:stock_location_id])
+        location = stock_location_for_param(stock_data[:stock_location_id])
+        # A stale or foreign location id is skipped rather than raising, which
+        # is what #stock_levels_attributes= already does for the same payload.
+        next if location.nil?
+
         location_ids_in_payload << location.id
         set_stock(stock_data[:count_on_hand], stock_data[:backorderable], location)
       end
 
-      # Soft-delete stock items for locations not in the payload
-      stock_items.where.not(stock_location_id: location_ids_in_payload).destroy_all if persisted?
+      # Soft-delete stock levels for locations not in the payload
+      stock_levels.where.not(stock_location_id: location_ids_in_payload).destroy_all if persisted?
+    end
+
+    # @deprecated Use {#stock_levels}; removed in 6.1.
+    def stock_items
+      Spree::Deprecation.warn('Spree::Variant#stock_items is deprecated and will be removed in Spree 6.1. Use #stock_levels instead.')
+      stock_levels
+    end
+
+    # @deprecated Use {#stock_levels=}; removed in 6.1.
+    def stock_items=(value)
+      Spree::Deprecation.warn('Spree::Variant#stock_items= is deprecated and will be removed in Spree 6.1. Use #stock_levels= instead.')
+      self.stock_levels = value
+    end
+
+    # The v3 API sends `stock_levels: [...]`, which the params normalizer
+    # rewrites to nested attributes — and Rails would then write count_on_hand
+    # straight onto the row. Each entry is routed through {#set_stock} instead,
+    # so a count typed in the dashboard lands in the stock history like every
+    # other change. Entries are upserted and never removed, which is what
+    # accepts_nested_attributes_for did here.
+    #
+    # @param rows [Array<Hash>, Hash]
+    # @return [void]
+    def stock_levels_attributes=(rows)
+      rows = rows.values if rows.respond_to?(:values) && !rows.is_a?(Array)
+      return if defer_stock_levels(:stock_levels_attributes=, rows)
+
+      Array.wrap(rows).each do |row|
+        row = (row.respond_to?(:to_unsafe_h) ? row.to_unsafe_h : row.to_h).with_indifferent_access
+        next if row[:stock_location_id].blank? || row[:count_on_hand].blank?
+
+        stock_location = stock_location_for_param(row[:stock_location_id])
+        next if stock_location.nil?
+
+        set_stock(row[:count_on_hand], row[:backorderable], stock_location)
+      end
+    end
+
+    # @deprecated Use +stock_levels_attributes=+; removed in 6.1.
+    def stock_items_attributes=(value)
+      Spree::Deprecation.warn('Spree::Variant#stock_items_attributes= is deprecated and will be removed in Spree 6.1. Use #stock_levels_attributes= instead.')
+      self.stock_levels_attributes = value
     end
 
     # Sets the base price (global price, not for a price list) for the given currency.
@@ -556,26 +796,49 @@ module Spree
     def set_price(currency, amount, compare_at_amount = nil)
       # When the prices association is already loaded (eager-loaded for
       # serialization), reuse the cached base-price instance so readers that
-      # branch on `prices.loaded?` (Pricing::Resolver, #price_in, serializers)
+      # branch on `prices.loaded?` (the Internal provider's resolution,
+      # #price_in, serializers)
       # observe the write without a reload. `base_prices.find_or_initialize_by`
       # would issue a fresh query and return a detached object, leaving the
       # loaded collection — and the serialized response — stale.
-      price =
+      existing =
         if prices.loaded?
-          prices.detect { |p| p.price_list_id.nil? && p.currency == currency } ||
-            prices.build(currency: currency)
+          prices.detect { |p| p.price_list_id.nil? && p.currency == currency }
         else
-          prices.base_prices.find_or_initialize_by(currency: currency)
+          prices.base_prices.find_by(currency: currency)
         end
 
+      # A blank amount means the merchant left that currency empty, which is
+      # the same statement as leaving it out of the payload: there is no base
+      # price in this currency. Writing it would persist a nil amount, and a
+      # base price (unlike a price-list placeholder) must have one.
+      if amount.blank?
+        return if existing.nil?
+
+        prices.delete(existing) if prices.loaded?
+        existing.destroy if existing.persisted?
+        return
+      end
+
+      price = existing || if prices.loaded?
+                            prices.build(currency: currency)
+                          else
+                            prices.base_prices.build(currency: currency)
+                          end
+
       price.amount = amount
       price.compare_at_amount = compare_at_amount
       price.save! if persisted?
     end
 
     # Returns the price for the given context or options.
+    #
+    # Answered by the store's pricing provider, which is Spree's own resolver
+    # unless a connector has been configured. An external provider's price is
+    # an unsaved, readonly Spree::Price — see Spree::PricingProvider::Base.
+    #
     # @param context_or_options [Spree::Pricing::Context|Hash] the context or options to get the price for
-    # @return [Spree::Price] the price for the given context or options
+    # @return [Spree::Price, nil] the price for the given context or options
     def price_for(context_or_options)
       context = if context_or_options.is_a?(Spree::Pricing::Context)
                   context_or_options
@@ -585,21 +848,37 @@ module Spree
                   raise ArgumentError, 'Must provide a Pricing::Context or options hash'
                 end
 
-      Spree::Pricing::Resolver.new(context).resolve
+      Spree::Pricing::PriceResolution.call(context)
     end
 
-    # Sets the stock for the variant at a given location.
-    # Mirrors set_price: find-or-initialize, set attrs, save only if persisted.
-    # @param count_on_hand [Integer] the count on hand
-    # @param backorderable [Boolean] the backorderable flag
-    # @param stock_location [Spree::StockLocation] the stock location (defaults to store default)
+    # Sets the count at a location. The correction goes through an `adjusted`
+    # movement so it shows up in the stock history like every other change.
+    # A count below zero is refused whatever the variant's backorder settings
+    # say, so a caller passing one gets ActiveRecord::RecordInvalid.
+    #
+    # @param count_on_hand [Integer] the count the level should end up at
+    # @param backorderable [Boolean, nil] left as it is when nil
+    # @param stock_location [Spree::StockLocation, nil] defaults to the store's
     # @return [void]
     def set_stock(count_on_hand, backorderable = nil, stock_location = nil)
       stock_location ||= default_stock_location
-      stock_item = stock_items.find_or_initialize_by(stock_location: stock_location)
-      stock_item.count_on_hand = count_on_hand
-      stock_item.backorderable = backorderable if backorderable.present?
-      stock_item.save! if persisted?
+      stock_level = stock_levels.find_or_initialize_by(stock_location: stock_location)
+      # `unless nil?`, not `if present?` — a caller passing false means it.
+      stock_level.backorderable = backorderable unless backorderable.nil?
+
+      # Nothing is saved yet, so the count rides on the in-memory record and
+      # the autosave association persists it with the variant.
+      unless persisted?
+        stock_level.count_on_hand = count_on_hand
+        return
+      end
+
+      stock_level.save! if stock_level.changed?
+
+      delta = count_on_hand.to_i - stock_level.count_on_hand.to_i
+      return if delta.zero?
+
+      stock_location.adjust(self, delta, reason: Spree::StockMovement.default_adjustment_reason)
     end
 
     def default_stock_location
@@ -678,13 +957,25 @@ module Spree
     end
 
     # Shortcut method to determine if inventory tracking is enabled for this variant
-    # This considers both variant tracking flag and site-wide inventory tracking settings
+    # This considers both the variant tracking flag and the store's setting
     def should_track_inventory?
-      track_inventory? && Spree::Config.track_inventory_levels
+      track_inventory? && store_preference(:track_inventory_levels)
+    end
+
+    # Variants carry no store of their own; the product owns it.
+    # @return [Spree::Store, nil]
+    def preference_store
+      product&.store
     end
 
+    # The cubic meters one unit of this variant occupies. Multiplying the
+    # raw dimension columns would answer in whatever unit the merchant typed,
+    # which is a sixteenfold error between inches and centimeters — so the
+    # name means CBM everywhere it appears (Variant, ContentItem, Package).
+    #
+    # @return [BigDecimal]
     def volume
-      (width || 0) * (height || 0) * (depth || 0)
+      Spree::Measurement.cubic_meters(width, height, depth, unit: dimensions_unit) || 0
     end
 
     def dimension
@@ -693,8 +984,33 @@ module Spree
 
     # Returns the weight unit for the variant
     # @return [String]
+    # Falls back to the variant's own store, like {#dimensions_unit} below —
+    # on a multi-store install the default store's unit is someone else's,
+    # and converting a kilogram catalog as pounds misweighs every quote.
     def weight_unit
-      attributes['weight_unit'] || Spree::Store.default.preferred_weight_unit
+      attributes['weight_unit'] || (preference_store || Spree::Store.default)&.preferred_weight_unit
+    end
+
+    # The unit this variant's width/height/depth are expressed in. Falls back
+    # to what the store's unit system implies, which is what every other
+    # dimension in the store already means — there is no separate store
+    # preference for it, so a second settable value cannot contradict the
+    # first. Mirrors {#weight_unit}, which has always resolved this way.
+    #
+    # Surfaces that show or export what the merchant actually stored — the CSV
+    # export, so a round-trip does not stamp one store's unit onto every
+    # variant — read the raw column instead.
+    #
+    # @return [String] one of {DIMENSION_UNITS}
+    def dimensions_unit
+      attributes['dimensions_unit'].presence || self.class.store_dimensions_unit(preference_store)
+    end
+
+    # @param store [Spree::Store, nil]
+    # @return [String]
+    def self.store_dimensions_unit(store)
+      store ||= Spree::Store.default
+      store&.metric_unit_system? ? 'cm' : 'in'
     end
 
     def discontinue!
@@ -706,22 +1022,137 @@ module Spree
     end
 
     def backordered?
-      @backordered ||= !in_stock? && stock_items.exists?(backorderable: true)
+      @backordered ||= !in_stock? && stock_levels.exists?(backorderable: true)
     end
 
     # Is this variant purely digital? (no physical product)
     #
+    # Answered by the variant's own profile so a download and its printed
+    # edition can sit on one product — the profile kind declares it, here as
+    # everywhere else.
+    #
     # @return [Boolean]
     def digital?
-      product.digital?
+      !!resolved_delivery_profile&.digital?
     end
 
     def with_digital_assets?
-      digitals.any?
+      digital_assets.any?
+    end
+
+    # The variant's own purchasing rules — the base every cart obeys, and the
+    # floor a buyer falls back to when their catalogs state nothing. A buyer's
+    # effective rules resolve through {Spree::Catalogs::ResolveQuantityRules};
+    # nothing below the cart layer reads either.
+    #
+    # @return [Spree::QuantityRule]
+    def quantity_rule
+      Spree::QuantityRule.new(
+        minimum_order_quantity: minimum_order_quantity,
+        order_multiple: order_multiple
+      )
+    end
+
+    # True when this variant is quoted in cartons rather than units. Requires
+    # +units_per_carton+, which the validation above guarantees.
+    #
+    # @return [Boolean]
+    def sold_by_carton?
+      purchase_unit == 'carton' && units_per_carton.to_i.positive?
+    end
+
+    # How many cartons a unit quantity fills, rounded up — a part carton still
+    # ships as a carton. Nil when the variant declares no carton size.
+    #
+    # @param quantity [Integer]
+    # @return [Integer, nil]
+    def cartons_for(quantity)
+      return nil unless units_per_carton.to_i.positive?
+
+      (quantity.to_i / units_per_carton.to_f).ceil
+    end
+
+    # The cubic meters one packed carton of this variant occupies. Geometry
+    # comes from the shared carton row, so correcting a carton size fixes
+    # every product packed in it.
+    #
+    # @return [BigDecimal, nil]
+    def carton_volume
+      carton_package_type&.volume
+    end
+
+    # How many units a full pallet of this variant holds. Nil unless both
+    # halves of the chain are recorded.
+    #
+    # @return [Integer, nil]
+    def units_per_pallet
+      return if units_per_carton.to_i.zero? || cartons_per_pallet.to_i.zero?
+
+      units_per_carton * cartons_per_pallet
     end
 
     private
 
+    def order_multiple_fits_cartons
+      return if order_multiple.to_i.zero? || units_per_carton.to_i.zero?
+      return if (order_multiple % units_per_carton).zero? || (units_per_carton % order_multiple).zero?
+
+      errors.add(:order_multiple, :incompatible_with_carton, units_per_carton: units_per_carton)
+    end
+
+    # A pallet or a shipping box is not what a product is packed into; only
+    # a carton row can stand in this slot.
+    def carton_package_type_is_a_carton
+      return if carton_package_type.blank? || carton_package_type.carton?
+
+      errors.add(:carton_package_type, :must_be_a_carton)
+    end
+
+    def carton_purchase_unit_has_divisor
+      return unless purchase_unit == 'carton'
+      return if units_per_carton.to_i.positive?
+
+      errors.add(:units_per_carton, :required_for_carton_purchase_unit)
+    end
+
+    # Resolved through the product's own store, because
+    # +Spree::StockLocation.find_by_param+ is global: an id belonging to another
+    # store would otherwise resolve and put this variant's stock in that store's
+    # warehouse. There is no global fallback — a variant is only reachable
+    # through a product, and a product belongs to a store.
+    #
+    # @param param [String, Integer, nil] prefixed or raw stock location id
+    # @return [Spree::StockLocation, nil]
+    def stock_location_for_param(param)
+      return if param.blank?
+
+      product&.store&.stock_locations&.find_by_param(param)
+    end
+
+    # +product.variants.create(stock_levels_attributes: …)+ assigns attributes
+    # before Rails wires the owner, so the store these location ids have to be
+    # scoped against is not known yet. The payload waits for the product rather
+    # than resolving against every warehouse in the installation.
+    #
+    # @return [Boolean] true when the write was deferred
+    def defer_stock_levels(writer, payload)
+      return false if product.present?
+
+      @pending_stock_levels = { writer: writer, payload: payload }
+      true
+    end
+
+    def pending_stock_levels?
+      @pending_stock_levels.present?
+    end
+
+    def apply_pending_stock_levels
+      pending = @pending_stock_levels
+      @pending_stock_levels = nil
+
+      public_send(pending[:writer], pending[:payload])
+    end
+
     def pending_options?
       @pending_options.present?
     end
@@ -754,70 +1185,118 @@ module Spree
       Spree::Stock::Quantifier.new(self)
     end
 
-    def set_master_out_of_stock
-      if product.master&.in_stock?
-        product.master.stock_items.update_all(backorderable: false)
-        product.master.stock_items.each(&:reduce_count_on_hand_to_zero)
+    def set_cost_currency
+      self.cost_currency = Spree::Store.default.default_currency if cost_currency.blank?
+    end
+
+    # Only the product's own store's locations — a new variant must not grow
+    # stock items in every other store's warehouses.
+    def create_stock_levels
+      locations = product&.store ? product.store.stock_locations : StockLocation.all
+      locations.where(propagate_all_variants: true).each do |stock_location|
+        stock_location.propagate_variant(self)
       end
     end
 
-    # Ensures a new variant takes the product master price when price is not supplied
-    def check_price
-      return if prices.any?
+    def disable_sku_validation?
+      store_preference(:disable_sku_validation)
+    end
+
+    # A SKU identifies an item within one seller's catalog, not across the
+    # marketplace: two sellers listing the same manufacturer part number is
+    # ordinary, and rejecting the second one would be refusing the sale.
+    #
+    # Compared on the *resolved* seller, so a seller who owns whole products
+    # is separated from another who does, not merged into the nil scope.
+    #
+    # Case-insensitive over a join, so it runs behind index_spree_variants_on_sku
+    # rather than on it. A functional index on LOWER(sku) would suit it better,
+    # but MariaDB rejects MySQL's syntax for one, so bulk writers that care pay
+    # this or turn the check off with the disable_sku_validation preference.
+    # Reads the raw column, not the resolved seller: what is being checked is
+    # the variant's *own* link, and a product-owned variant has none to check.
+    def blank_owned_product_overrides
+      return unless owned_by_product_seller?
+
+      self.seller_id = nil
+      self.delivery_profile_id = nil
+    end
+
+    def seller_must_belong_to_store
+      return if self[:seller_id].nil?
+
+      store = product&.store
+      return if store.nil?
+      return if association(:seller).reader&.store_id == store.id
 
-      infer_price_from_default_variant_if_needed
+      errors.add(:seller, :invalid)
     end
 
-    def infer_price_from_default_variant_if_needed
-      default_currency = Spree::Store.default.default_currency
-      current_price = price_in(default_currency).amount
+    def delivery_profile_must_belong_to_store
+      return if self[:delivery_profile_id].nil?
 
-      if current_price.nil?
-        return errors.add(:base, :no_master_variant_found_to_infer_price) unless product&.master
+      store = product&.store
+      return if store.nil?
+      return if association(:delivery_profile).reader&.store_id == store.id
 
-        # At this point, master can have or have no price, so let's use price from the default variant
-        inferred_price = product.default_variant.price_in(default_currency).amount
-        set_price(default_currency, inferred_price) if inferred_price.present?
-      end
+      errors.add(:delivery_profile, :invalid)
     end
 
-    def set_cost_currency
-      self.cost_currency = Spree::Store.default.default_currency if cost_currency.blank?
+    # Same guard as the delivery profile above, widened to ownership: a carton
+    # must belong to this store, and be either the marketplace's shared
+    # vocabulary or this variant's own seller's. Another seller's carton must
+    # never be reachable by id — its measurements would feed this variant's
+    # freight rollups (docs/plans/6.0-seller-package-types.md).
+    def carton_package_type_must_belong_to_store
+      return if self[:carton_package_type_id].nil?
+
+      store = product&.store
+      return if store.nil?
+
+      carton = association(:carton_package_type).reader
+      return if carton&.store_id == store.id && carton.available_to_seller?(resolved_seller_id)
+
+      errors.add(:carton_package_type, :invalid)
     end
 
-    def create_stock_items
-      StockLocation.where(propagate_all_variants: true).each do |stock_location|
-        stock_location.propagate_variant(self)
+    def validate_sku_uniqueness
+      scope = self.class.for_seller(resolved_seller_id).
+              where(deleted_at: nil).
+              where(self.class.arel_table[:sku].lower.eq(sku.to_s.downcase))
+      # Honour a host app's tenancy scope, as the validator this replaced did.
+      # Empty in core, so this narrows nothing here.
+      Array(self.class.spree_base_uniqueness_scope).each do |attribute|
+        scope = scope.where(attribute => self[attribute])
       end
-    end
+      scope = scope.where.not(id: id) if persisted?
 
-    def disable_sku_validation?
-      Spree::Config[:disable_sku_validation]
+      errors.add(:sku, :taken, value: sku) if scope.exists?
     end
 
     def clear_line_items_cache
       line_items.update_all(updated_at: Time.current)
     end
 
-    def create_default_stock_item
-      return if stock_items.any?
+    def create_default_stock_level
+      return if stock_levels.any?
 
-      Spree::Store.current.default_stock_location.set_up_stock_item(self)
+      Spree::Store.current.default_stock_location.set_up_stock_level(self)
     end
 
+    # Turning tracking off writes the remaining stock away. That is a stock
+    # decision, so it goes in the log like any other correction rather than
+    # disappearing through update_all.
     def handle_track_inventory_change
       return unless track_inventory_previously_changed?
       return if track_inventory
 
-      stock_items.update_all(count_on_hand: 0, updated_at: Time.current)
-    end
+      stock_levels.reload.each do |stock_level|
+        next if stock_level.count_on_hand.zero?
 
-    def remove_prices_from_master_variant
-      product.master.prices.delete_all if prices.exists?
-    end
-
-    def remove_stock_items_from_master_variant
-      product.master.stock_items.delete_all
+        stock_level.stock_location.adjust(
+          self, -stock_level.count_on_hand, reason: Spree::StockMovement.default_adjustment_reason
+        )
+      end
     end
 
     def increment_product_variant_count