spree_core 5.6.0 → 6.0.0.beta1

data/app/models/spree/stock/estimator.rb

@@ -10,65 +10,230 @@ module Spree
         @currency = order.currency
       end
 
-      def shipping_rates(package, shipping_method_filter = ShippingMethod::DISPLAY_ON_FRONT_END)
-        rates = calculate_shipping_rates(package, shipping_method_filter)
-        choose_default_shipping_rate(rates)
-        sort_shipping_rates(rates)
+      # @param package [Spree::Stock::Package]
+      # @param audience [Symbol] {Spree::DeliveryMethod::STOREFRONT} (default)
+      #   or {Spree::DeliveryMethod::BACKOFFICE}
+      # @return [Array<Spree::DeliveryRate>]
+      def delivery_rates(package, audience = DeliveryMethod::STOREFRONT)
+        rates = calculate_delivery_rates(package, audience)
+        choose_default_delivery_rate(rates)
+        sort_delivery_rates(rates)
+      end
+
+      # Whether any delivery method is eligible to carry this package — the
+      # same eligibility a rate refresh applies, stopping short of asking any
+      # rate provider for a price. Allocation reads it to prefer an origin
+      # whose methods can actually reach the destination, so it must never
+      # cost a carrier API call.
+      #
+      # @param package [Spree::Stock::Package]
+      # @param audience [Symbol] {Spree::DeliveryMethod::STOREFRONT} (default)
+      #   or {Spree::DeliveryMethod::BACKOFFICE}
+      # @return [Boolean]
+      def deliverable?(package, audience = DeliveryMethod::STOREFRONT)
+        delivery_methods(package, audience).any?
+      end
+
+      # @deprecated Use {#delivery_rates}; removed in 6.1.
+      def shipping_rates(package, audience = DeliveryMethod::STOREFRONT)
+        Spree::Deprecation.warn('Spree::Stock::Estimator#shipping_rates is deprecated and will be removed in Spree 6.1. Use #delivery_rates instead.')
+        delivery_rates(package, audience)
       end
 
       private
 
-      def choose_default_shipping_rate(shipping_rates)
-        unless shipping_rates.empty?
-          shipping_rates.min_by(&:cost).selected = true
+      # Shipping is what "delivery" means unless someone chooses otherwise, so
+      # the cheapest *shipped* rate wins by default. Picking the cheapest of
+      # all rates handed every order to free store pickup the moment a pickup
+      # method existed. Profiles offering nothing shipped (pickup-only,
+      # digital) still get their cheapest rate.
+      def choose_default_delivery_rate(delivery_rates)
+        return if delivery_rates.empty?
+
+        shipped = delivery_rates.select { |rate| rate.delivery_method&.requires_address? }
+        candidates = shipped.presence || delivery_rates
+        # An unpriced rate costs zero, so preselecting on price alone would
+        # hand every mixed offering to freight. Prefer something actually
+        # priced; fall back to freight when that is all there is.
+        priced = candidates.reject(&:unpriced?)
+        (priced.presence || candidates).min_by(&:cost).selected = true
+      end
+
+      # Cheapest first, with unpriced rates after the priced ones — their zero
+      # cost is an absence of information, not a bargain.
+      def sort_delivery_rates(delivery_rates)
+        delivery_rates.sort_by! { |rate| [rate.unpriced? ? 1 : 0, rate.cost] }
+      end
+
+      # Quoting runs through the method's rate provider — Internal prices
+      # through the calculator, carrier providers call their API and may
+      # return several estimates (one per carrier service). An empty result
+      # suppresses the method, matching the calculator contract. Service
+      # filtering, markup, naming, VAT gross-up, tax resolution and sorting
+      # stay here so every provider gets them identically.
+      def calculate_delivery_rates(package, audience)
+        delivery_methods(package, audience).flat_map do |delivery_method|
+          provider = delivery_method.rate_provider_instance
+
+          provider.estimates(package).filter_map do |estimate|
+            next unless delivery_method.offers_service?(estimate)
+            # A quote in another currency (a USD carrier account under a EUR
+            # cart) is unusable — mislabeling it would misprice checkout.
+            if estimate.currency.present? && estimate.currency.casecmp(currency) != 0
+              Rails.logger.debug { "Spree::Stock::Estimator: dropping #{delivery_method.name} estimate quoted in #{estimate.currency} for a #{currency} order" }
+              next
+            end
+
+            service_row = delivery_method.service_for(estimate)
+
+            delivery_method.delivery_rates.new(
+              cost: rate_cost(estimate, delivery_method, service_row, provider),
+              tax_rate: (first_tax_rate_for(delivery_method.tax_category) unless estimate.unpriced),
+              unpriced: estimate.unpriced,
+              name: rate_name(estimate, service_row),
+              carrier: estimate.carrier,
+              service_level: estimate.service_level,
+              estimated_delivery_date: estimate.estimated_delivery_date,
+              # presence: rates are rewritten on every refresh, so calculator-
+              # priced methods store NULL rather than an empty hash each time.
+              metadata: estimate.metadata.presence
+            )
+          end
         end
       end
 
-      def sort_shipping_rates(shipping_rates)
-        shipping_rates.sort_by!(&:cost)
+      # An unpriced quote has no amount to mark up or tax — a percentage of an
+      # unknown price is still unknown, and rounding zero through the VAT
+      # gross-up would only invent a number. Its cost stays zero and every
+      # display surface reads +unpriced+ instead.
+      def rate_cost(estimate, delivery_method, service_row, provider)
+        return 0 if estimate.unpriced
+
+        cost = apply_markup(estimate.cost, delivery_method, service_row, provider)
+        gross_amount(cost, taxation_options_for(delivery_method))
       end
 
-      def calculate_shipping_rates(package, ui_filter)
-        shipping_methods(package, ui_filter).map do |shipping_method|
-          cost = shipping_method.calculator.compute(package)
+      # Handling fee on top of provider quotes: the service row's values when
+      # set, else the method-level defaults. Calculator-priced methods are
+      # exempt — their calculator IS the price.
+      def apply_markup(cost, delivery_method, service_row, provider)
+        return cost if provider.class.uses_calculator?
 
-          next unless cost
+        percent = service_row&.markup_percent || delivery_method.markup_percent || 0
+        flat = service_row&.markup_flat || delivery_method.markup_flat || 0
+        (cost * (1 + (percent / 100)) + flat).round(2)
+      end
 
-          shipping_method.shipping_rates.new(
-            cost: gross_amount(cost, taxation_options_for(shipping_method)),
-            tax_rate: first_tax_rate_for(shipping_method.tax_category)
-          )
-        end.compact
+      # Display name for provider-priced rates: the merchant's label override,
+      # else carrier + service from the quote. Nil for calculator rates —
+      # DeliveryRate#name falls back to the method name.
+      def rate_name(estimate, service_row)
+        service_row&.label.presence || estimate.name.presence ||
+          [estimate.carrier, estimate.service_level].compact.join(' ').presence
       end
 
-      # Override this if you need the prices for shipping methods to be handled just like the
+      # Override this if you need the prices for delivery methods to be handled just like the
       # prices for products in terms of included tax manipulation.
       #
-      def taxation_options_for(shipping_method)
+      def taxation_options_for(delivery_method)
         {
-          tax_category: shipping_method.tax_category,
-          tax_zone: @order.tax_zone
+          tax_category: delivery_method.tax_category,
+          address: @order.tax_address,
+          country: @order.tax_country,
+          market: @order.market
         }
       end
 
       def first_tax_rate_for(tax_category)
-        return unless @order.tax_zone && tax_category
+        return unless @order.tax_address && tax_category
 
-        Spree::TaxRate.for_tax_category(tax_category).
-          potential_rates_for_zone(@order.tax_zone).first
+        scope = Spree::TaxRate.for_tax_category(tax_category).for_address(@order.tax_address)
+        scope = scope.for_store(@order.store) if @order.store
+        scope.first
       end
 
-      def shipping_methods(package, display_filter)
-        package.shipping_methods.select do |ship_method|
-          calculator = ship_method.calculator
+      # The eligibility seam: every rate consumer (checkout, routing, cart
+      # estimates) filters through here, and host apps override it to add
+      # their own rules.
+      #
+      # Dispatches through the legacy +shipping_methods+ name so overrides
+      # written against it keep running until 6.1 — without this, a host
+      # override would be silently skipped and checkout could quote rates
+      # the host meant to filter out.
+      def delivery_methods(package, audience)
+        return shipping_methods(package, audience) if overrides_legacy_seam?
 
-          ship_method.available_to_display?(display_filter) &&
-            ship_method.include?(order.ship_address) &&
-            calculator.available?(package) &&
-            (calculator.preferences[:currency].blank? ||
-             calculator.preferences[:currency] == currency)
+        filter_delivery_methods(package, audience)
+      end
+
+      # @deprecated Call or override {#delivery_methods}; removed in 6.1.
+      # Only reached when a caller uses the old name directly — the override
+      # dispatch above goes straight to the override's own definition.
+      def shipping_methods(package, audience)
+        Spree::Deprecation.warn('Spree::Stock::Estimator#shipping_methods is deprecated and will be removed in Spree 6.1. Use #delivery_methods instead.')
+        filter_delivery_methods(package, audience)
+      end
+
+      def filter_delivery_methods(package, audience)
+        methods = package.eligible_delivery_methods
+        # Storeless orders exist only in specs; real orders always carry one.
+        methods = methods.merge(order.store.delivery_methods) if order.store
+
+        # On a marketplace, a package's seller is its stock location's, and it
+        # is quoted by that seller's own methods plus whatever the operator
+        # shares. This is the one place that decision is made
+        # (docs/plans/6.0-multi-vendor-marketplace.md, Decision 13).
+        package_seller_id = package.stock_location&.seller_id
+
+        methods.select do |delivery_method|
+          offered_to_seller?(delivery_method, package_seller_id) &&
+            delivery_method.available_to?(audience) &&
+            delivery_method.include?(order.ship_address) &&
+            delivery_method.serves_location?(package.stock_location) &&
+            delivery_method.eligible_for_package?(package) &&
+            calculator_offers?(delivery_method, package)
         end
       end
+
+      # A seller's package is quoted by that seller's own methods plus the
+      # marketplace ones the operator shares; a first-party package sees the
+      # marketplace's methods only.
+      def offered_to_seller?(delivery_method, package_seller_id)
+        return delivery_method.seller_id.nil? if package_seller_id.nil?
+        return true if delivery_method.seller_id == package_seller_id
+
+        delivery_method.seller_id.nil? && delivery_method.available_to_sellers?
+      end
+
+      # The calculator's say in eligibility.
+      #
+      # `available?` is a documented extension point — a host app overrides it
+      # to refuse a method for a package — so it applies to every method,
+      # however the method is priced.
+      #
+      # The currency check does not. A provider-priced method carries a
+      # calculator the admin hides and nothing reads an amount from, so its
+      # leftover currency would silence exactly the methods built for foreign
+      # trade: a freight method's default calculator speaks only the default
+      # store's currency, and international wholesale is what the freight
+      # provider exists for. Provider quotes get their currency check where it
+      # belongs, against the estimate itself.
+      def calculator_offers?(delivery_method, package)
+        calculator = delivery_method.calculator
+        return false unless calculator.available?(package)
+        return true unless delivery_method.rate_provider_instance.class.uses_calculator?
+
+        calculator.supports_currency?(currency)
+      end
+
+      # True when a subclass or decorator redefined the legacy seam, so its
+      # filtering still applies.
+      def overrides_legacy_seam?
+        return @overrides_legacy_seam if defined?(@overrides_legacy_seam)
+
+        @overrides_legacy_seam =
+          method(:shipping_methods).owner != Spree::Stock::Estimator
+      end
     end
   end
 end

data/app/models/spree/stock/inventory_unit_builder.rb

@@ -6,6 +6,11 @@ module Spree
       end
 
       def units
+        # Same rule as Spree::Fulfillment#set_up_inventory: the item's order_id
+        # is a completion-time denormalization, so during checkout it stays nil
+        # rather than pointing at whatever order happens to share the cart's
+        # id — a stranger's order whose currency and ship address would then
+        # stand in for the customer's.
         @order.line_items.map do |line_item|
           # They go through multiple splits, avoid loading the
           # association to order until needed.
@@ -14,7 +19,7 @@ module Spree
             line_item_id: line_item.id,
             variant_id: line_item.variant_id,
             quantity: line_item.quantity,
-            order_id: @order.id
+            order_id: @order.is_a?(Spree::Order) ? @order.id : nil
           )
         end
       end

data/app/models/spree/stock/package.rb

@@ -2,17 +2,50 @@ module Spree
   module Stock
     class Package
       attr_reader :stock_location, :contents
-      attr_accessor :shipping_rates
+      attr_accessor :delivery_rates
+      # The cart or order this package is being quoted for. Every builder sets
+      # it — a fulfillment, the allocator for a proposal — so the package takes
+      # its currency, store and destination from the real record instead of
+      # {#owner}'s fallback.
+      attr_writer :owner
 
       def initialize(stock_location, contents = [])
         @stock_location = stock_location
         @contents = contents
-        @shipping_rates = []
+        @delivery_rates = []
+      end
+
+      # Who this package is for.
+      #
+      # Prefers the owner it was built with. The walk to `inventory_unit.order`
+      # is only a safety net for packages built by code that sets none, and it
+      # answers badly in both directions: a cart's units carry no order_id, so
+      # it returns nil and the package has no store or currency of its own,
+      # while a unit carrying an order_id from elsewhere returns a stranger's
+      # order — whose currency and ship address would stand in for the
+      # customer's.
+      #
+      # @return [Spree::Cart, Spree::Order, nil]
+      def owner
+        @owner || order
+      end
+
+      # @deprecated Use {#delivery_rates}; removed in 6.1.
+      def shipping_rates
+        Spree::Deprecation.warn('Spree::Stock::Package#shipping_rates is deprecated and will be removed in Spree 6.1. Use #delivery_rates instead.')
+        delivery_rates
+      end
+
+      # @deprecated Use {#delivery_rates=}; removed in 6.1.
+      def shipping_rates=(rates)
+        Spree::Deprecation.warn('Spree::Stock::Package#shipping_rates= is deprecated and will be removed in Spree 6.1. Use #delivery_rates= instead.')
+        self.delivery_rates = rates
       end
 
       def add(inventory_unit, state = :on_hand)
         # Remove find_item check as already taken care by prioritizer
         contents << ContentItem.new(inventory_unit, state)
+        @freight_summary = nil
       end
 
       def add_multiple(inventory_units, state = :on_hand)
@@ -26,6 +59,7 @@ module Spree
 
       def remove_item(item)
         @contents -= [item]
+        @freight_summary = nil
       end
 
       # Fix regression that removed package.order.
@@ -38,8 +72,34 @@ module Spree
         contents.sum(&:amount)
       end
 
+      # Content weight plus the tare of the store's default package (the box
+      # itself, plus filler). This is the single point every weight consumer
+      # reads — calculators, rate providers, weight rules and the weight
+      # splitter — so the tare applies everywhere without any of them knowing
+      # about it.
       def weight
-        contents.sum(&:weight)
+        contents.sum(&:weight) + tare
+      end
+
+      # The store's default package dimensions (the box this package ships
+      # in), used verbatim by carrier rate providers for dimensional-weight
+      # pricing. Item dimensions are deliberately not summed — items don't
+      # stack into a box shape. Nil until the store records all three.
+      #
+      # @return [Hash{Symbol => Float}, nil]
+      def dimensions
+        default_package_type&.dimensions_in(store_dimensions_unit)
+      end
+
+      # How this package's contents roll up into freight logistics — cartons,
+      # pallets, cubic meters, gross weight. Computed live; an order's summary
+      # comes from the frozen copy on its selected delivery rate instead.
+      #
+      # @return [Spree::FreightSummary]
+      # Memoized because quoting reads it repeatedly, and dropped whenever the
+      # contents change — a stale volume would pick the wrong freight tier.
+      def freight_summary
+        @freight_summary ||= Spree::FreightSummary.build(contents)
       end
 
       def on_hand
@@ -67,16 +127,37 @@ module Spree
       end
 
       def currency
-        order.currency
+        owner&.currency ||
+          contents.filter_map { |item| item.try(:inventory_unit)&.line_item&.currency }.first ||
+          Spree::Current.currency
       end
 
-      def shipping_categories
-        Spree::ShippingCategory.joins(products: :variants_including_master).
-          where(spree_variants: { id: variant_ids }).distinct
+      # The delivery profile every item in this package belongs to.
+      # Splitters keep packages profile-homogeneous, so the first item's
+      # profile is the package's.
+      #
+      # @return [Spree::DeliveryProfile, nil]
+      def delivery_profile
+        contents.first&.variant&.resolved_delivery_profile
       end
 
+      # Delivery methods eligible to serve this package: exactly the
+      # package's profile's methods. Per-product exclusions are
+      # DeliveryMethodRules::ExcludedProductsRule, enforced with the other
+      # rules in the Estimator's method filter.
+      #
+      # @return [ActiveRecord::Relation<Spree::DeliveryMethod>]
+      def eligible_delivery_methods
+        profile = delivery_profile
+        return Spree::DeliveryMethod.none if profile.nil?
+
+        profile.delivery_methods
+      end
+
+      # @deprecated Use {#eligible_delivery_methods}; removed in 6.1.
       def shipping_methods
-        shipping_categories.includes(:shipping_methods).map(&:shipping_methods).reduce(:&).to_a
+        Spree::Deprecation.warn('Spree::Stock::Package#shipping_methods is deprecated and will be removed in Spree 6.1. Use #eligible_delivery_methods instead.')
+        eligible_delivery_methods.to_a
       end
 
       def inspect
@@ -85,21 +166,32 @@ module Spree
         end.join(' / ')
       end
 
-      def to_shipment
+      def to_fulfillment
         # At this point we should only have one content item per inventory unit
         # across the entire set of inventory units to be shipped, which has been
         # taken care of by the Prioritizer
-        contents.each { |content_item| content_item.inventory_unit.state = content_item.state.to_s }
+        contents.each { |content_item| content_item.inventory_unit.status = content_item.state.to_s }
 
-        Spree::Shipment.new(
+        Spree::Fulfillment.new(
           stock_location: stock_location,
-          shipping_rates: shipping_rates,
-          inventory_units: contents.map(&:inventory_unit)
+          delivery_rates: delivery_rates,
+          fulfillment_items: contents.map(&:inventory_unit)
         )
       end
 
+      # @deprecated Use {#to_fulfillment}; removed in 6.1.
+      def to_shipment
+        Spree::Deprecation.warn('Spree::Stock::Package#to_shipment is deprecated and will be removed in Spree 6.1. Use #to_fulfillment instead.')
+        to_fulfillment
+      end
+
+      # Cubic meters of packed goods — carton volume where the contents
+      # declare cartons, unit volume otherwise. Cartons stack, so unlike
+      # +dimensions+ this genuinely sums.
+      #
+      # @return [BigDecimal]
       def volume
-        contents.sum(&:volume)
+        freight_summary.total_volume
       end
 
       def dimension
@@ -108,6 +200,45 @@ module Spree
 
       private
 
+      # The box this package is quoted with: the seller's own, falling back to
+      # the marketplace's.
+      #
+      # A package's seller is its stock location's — the derivation used
+      # everywhere else — so a parcel leaving a seller's warehouse takes that
+      # seller's tare and dimensions. The fallback keeps checkout whole for a
+      # seller who has not recorded a box yet; the `PackageType` onboarding
+      # requirement is what asks them to
+      # (docs/plans/6.0-seller-package-types.md).
+      #
+      # @return [Spree::PackageType, nil]
+      def default_package_type
+        return @default_package_type if defined?(@default_package_type)
+
+        @default_package_type = stock_location&.seller&.default_package_type ||
+                                owner&.store&.default_package_type
+      end
+
+      # The box's own weight, converted into the unit the contents are
+      # measured in. A merchant may record a carton in kilograms while the
+      # store quotes in pounds, and adding those numbers together would
+      # understate the tare by more than half.
+      #
+      # @return [BigDecimal]
+      def tare
+        package_type = default_package_type
+        return 0 if package_type.nil?
+
+        package_type.weight_in(owner&.store&.preferred_weight_unit || Spree::Measurement::DEFAULT_WEIGHT_UNIT)
+      end
+
+      # What a dimension means to this store, matching the fallback a
+      # variant's own dimensions take.
+      #
+      # @return [String]
+      def store_dimensions_unit
+        Spree::Variant.store_dimensions_unit(owner&.store)
+      end
+
       def variant_ids
         contents.map { |item| item.inventory_unit.variant_id }.compact.uniq
       end

data/app/models/spree/stock/packer.rb

@@ -1,12 +1,19 @@
 module Spree
   module Stock
     class Packer
-      attr_reader :stock_location, :inventory_units, :splitters
+      attr_reader :stock_location, :inventory_units, :splitters, :owner
 
-      def initialize(stock_location, inventory_units, splitters = [Splitter::Base])
+      # @param owner [Spree::Cart, Spree::Order, nil] the purchase being
+      #   packed. Every package it builds carries this, including the ones
+      #   splitters derive, because a proposed package's inventory units
+      #   belong to no order yet — so anything reading the buyer through the
+      #   package (the packaging tare, the channel and company eligibility
+      #   rules) would otherwise see nothing.
+      def initialize(stock_location, inventory_units, splitters = [Splitter::Base], owner: nil)
         @stock_location = stock_location
         @inventory_units = inventory_units
         @splitters = splitters
+        @owner = owner
       end
 
       def packages
@@ -18,7 +25,7 @@ module Spree
       end
 
       def default_package
-        package = Package.new(stock_location)
+        package = build_package
 
         # Group by variant_id as grouping by variant fires cached query.
         inventory_units.index_by(&:variant_id).each do |variant_id, inventory_unit|
@@ -38,6 +45,16 @@ module Spree
         package
       end
 
+      # The single point every package this packer emits is born at, so the
+      # owner cannot be lost by a splitter that builds its own.
+      #
+      # @return [Spree::Stock::Package]
+      def build_package(contents = [])
+        package = Package.new(stock_location, contents)
+        package.owner = owner
+        package
+      end
+
       private
 
       def build_splitter

data/app/models/spree/stock/prioritizer.rb

@@ -1,11 +1,18 @@
 module Spree
   module Stock
     class Prioritizer
-      attr_reader :packages
+      attr_reader :packages, :estimator
 
-      def initialize(packages, adjuster_class = Adjuster)
+      # @param packages [Array<Spree::Stock::Package>] candidate packages, in
+      #   the order the caller prefers them (routing rank, location order)
+      # @param adjuster_class [Class]
+      # @param estimator [Spree::Stock::Estimator, nil] consulted for
+      #   deliverability, so an origin that cannot serve the destination loses
+      #   to one that can. Omitted, the caller's order stands as given.
+      def initialize(packages, adjuster_class = Adjuster, estimator: nil)
         @packages = packages
         @adjuster_class = adjuster_class
+        @estimator = estimator
         @adjusters = {}
       end
 
@@ -36,8 +43,24 @@ module Spree
         @adjusters[hash_item item]
       end
 
+      # Origins that can deliver go first, so the Adjuster fills each unit from
+      # one of them and the origins that cannot are left empty and pruned. A
+      # profile with per-region origin groups would otherwise allocate to
+      # whichever warehouse came first, and when that warehouse's group has no
+      # method for the destination the item is dropped as undeliverable even
+      # though another warehouse could have shipped it.
+      #
+      # The caller's order survives within each group, so routing rank and the
+      # store's location order still decide between origins that can both
+      # deliver.
       def sort_packages
-        # order packages by preferred stock_locations
+        return if estimator.nil?
+
+        ranked = packages.each_with_index.sort_by do |package, index|
+          [estimator.deliverable?(package) ? 0 : 1, index]
+        end
+
+        packages.replace(ranked.map(&:first))
       end
 
       def prune_packages
@@ -45,7 +68,7 @@ module Spree
       end
 
       def hash_item(item)
-        shipment = item.inventory_unit.shipment
+        shipment = item.inventory_unit.fulfillment
         variant  = item.inventory_unit.variant
         if shipment.present?
           variant.hash ^ shipment.hash