spree_core 5.6.1 → 6.0.0.beta2

data/app/models/spree/order_routing_rule.rb

@@ -23,6 +23,7 @@ module Spree
     has_prefix_id :orule
 
     include Spree::SingleStoreResource
+    include Spree::HasListPosition
 
     belongs_to :store, class_name: 'Spree::Store'
     belongs_to :channel, class_name: 'Spree::Channel'
@@ -34,7 +35,7 @@ module Spree
     # position would 422. Default to the end of the channel's list instead.
     before_validation :set_position_to_end, on: :create, if: -> { position.blank? && channel.present? }
 
-    validates :type, :channel, presence: true
+    validates :type, presence: true
     # One instance of each rule kind per channel — a duplicate signal would
     # either be a no-op or fight itself in the reducer walk.
     validates :type, uniqueness: { scope: [:channel_id, *spree_base_uniqueness_scope] }
@@ -42,7 +43,6 @@ module Spree
     validate :channel_belongs_to_store
 
     scope :active, -> { where(active: true) }
-    scope :ordered, -> { order(:position) }
     scope :for_channel, ->(channel) { where(channel_id: channel.id) }
 
     acts_as_list scope: :channel_id
@@ -80,17 +80,7 @@ module Spree
       raise NotImplementedError, "#{self.class} must implement #rank(order, locations)"
     end
 
-    # Routes Spree::PreferenceSchema's subclass discovery
-    # (`subclasses_with_preference_schema`, `find_by_api_type`) to the
-    # order-routing rule registry.
-    module ClassMethods
-      private
-
-      def registered_subclasses
-        Spree.order_routing.rules
-      end
-    end
-    extend ClassMethods
+    registers_subclasses_via { Spree.order_routing.rules }
 
     private
 
@@ -105,14 +95,14 @@ module Spree
       return if type.blank?
       return if Spree.order_routing.rules.any? { |rule| rule.to_s == type }
 
-      errors.add(:type, Spree.t(:invalid_order_routing_rule, scope: [:errors, :messages], default: 'is not a registered order routing rule'))
+      errors.add(:type, :invalid_order_routing_rule, message: Spree.t(:invalid_order_routing_rule, scope: [:errors, :messages], default: 'is not a registered order routing rule'))
     end
 
     def channel_belongs_to_store
       return if channel.nil? || store_id.nil?
       return if channel.store_id == store_id
 
-      errors.add(:channel, Spree.t('errors.messages.channel_store_mismatch'))
+      errors.add(:channel, :channel_store_mismatch, message: Spree.t('errors.messages.channel_store_mismatch'))
     end
   end
 end

data/app/models/spree/order_updater.rb

@@ -1,204 +1,172 @@
 module Spree
+  # @deprecated Removed in Spree 6.1. Every method is a thin shim over the
+  #   flows that own the work:
+  #
+  #   * money    — {Spree::Carts::RecalculateTotals} /
+  #                {Spree::Orders::RecalculateTotals} (or the model's
+  #                +#recalculate_totals!+)
+  #   * statuses — {Spree::Orders::UpdateStatuses} (or +#update_statuses!+),
+  #                the sole writer of +payment_status+/+fulfillment_status+
+  #
+  #   The granular partial updates no longer exist as separate computations:
+  #   the totals workflow is the single money seam, so each money shim runs
+  #   the full recalculation.
   class OrderUpdater
     attr_reader :order
-    delegate :payments, :line_items, :adjustments, :all_adjustments, :shipments, :update_hooks, :quantity, to: :order
+    delegate :payments, :line_items, :fulfillments, :update_hooks, :quantity, to: :order
 
     def initialize(order)
       @order = order
     end
 
-    # This is a multi-purpose method for processing logic related to changes in the Order.
-    # It is meant to be called from various observers so that the Order is aware of changes
-    # that affect totals and other values stored in the Order.
-    #
-    # This method should never do anything to the Order that results in a save call on the
-    # object with callbacks (otherwise you will end up in an infinite recursion as the
-    # associations try to save and then in turn try to call +update!+ again.)
+    # @deprecated Use {Spree::Carts::RecalculateTotals} /
+    #   {Spree::Orders::RecalculateTotals} (or +#recalculate_totals!+);
+    #   removed in 6.1.
     def update
-      update_item_count
-      update_totals
-      if order.completed?
-        update_payment_state
-        update_shipments
-        update_shipment_state
-        update_shipment_total
-      end
-      run_hooks
-      persist_totals
-    end
-
-    def run_hooks
-      update_hooks.each { |hook| order.send hook }
+      deprecate_totals(__method__)
+      recalculate_totals
+      update_statuses if order.completed?
     end
 
+    # @deprecated Use {Spree::Carts::RecalculateTotals}; removed in 6.1. The
+    #   totals workflow rebuilds the typed adjustment rows as part of its
+    #   money pass.
     def recalculate_adjustments
-      all_adjustments.includes(:adjustable).map(&:adjustable).uniq.each do |adjustable|
-        Adjustable::AdjustmentsUpdater.update(adjustable)
-      end
+      deprecate_totals(__method__)
+      recalculate_totals
     end
 
-    # Updates the following Order total values:
-    #
-    # +payment_total+      The total value of all finalized Payments (NOTE: non-finalized Payments are excluded)
-    # +item_total+         The total value of all LineItems
-    # +adjustment_total+   The total value of all adjustments (promotions, credits, etc.)
-    # +promo_total+        The total value of all promotion adjustments
-    # +total+              The so-called "order total."  This is equivalent to +item_total+ plus +shipment_total+ plus +adjustment_total+.
+    # @deprecated Use {Spree::Carts::RecalculateTotals}; removed in 6.1.
     def update_totals
-      update_payment_total
-      update_item_total
-      update_shipment_total
-      update_adjustment_total
-    end
-
-    # give each of the shipments a chance to update themselves
-    def update_shipments
-      shipping_method_filter = order.completed? ? ShippingMethod::DISPLAY_ON_BACK_END : ShippingMethod::DISPLAY_ON_FRONT_END
-
-      shipments.each do |shipment|
-        next unless shipment.persisted?
-
-        shipment.update!(order)
-        shipment.refresh_rates(shipping_method_filter)
-        shipment.update_amounts
-      end
+      deprecate_totals(__method__)
+      recalculate_totals
     end
 
+    # @deprecated Use {Spree::Carts::RecalculateTotals}; removed in 6.1.
     def update_payment_total
-      order.payment_total = payments.completed.includes(:refunds).inject(0) { |sum, payment| sum + payment.amount - payment.refunds.sum(:amount) }
+      deprecate_totals(__method__)
+      recalculate_totals
+      order.payment_total
     end
 
-    def update_shipment_total
-      order.shipment_total = shipments.to_a.sum(&:cost)
-      update_order_total
+    # @deprecated Use {Spree::Carts::RecalculateTotals}; removed in 6.1.
+    def update_item_total
+      deprecate_totals(__method__)
+      recalculate_totals
+      order.item_total
     end
 
+    # @deprecated Use {Spree::Carts::RecalculateTotals}; removed in 6.1.
     def update_order_total
-      order.total = order.item_total + order.shipment_total + order.adjustment_total
+      deprecate_totals(__method__)
+      recalculate_totals
+      order.total
     end
 
+    # @deprecated Use {Spree::Carts::RecalculateTotals}; removed in 6.1.
     def update_adjustment_total
-      recalculate_adjustments
-
-      # Fetch all line item totals in a single query
-      # Use reorder(nil) to remove default ordering which conflicts with aggregates in PostgreSQL
-      line_item_totals = line_items.reorder(nil).pick(
-        Arel.sql('COALESCE(SUM(adjustment_total), 0)'),
-        Arel.sql('COALESCE(SUM(included_tax_total), 0)'),
-        Arel.sql('COALESCE(SUM(additional_tax_total), 0)'),
-        Arel.sql('COALESCE(SUM(promo_total), 0)')
-      ) || [0, 0, 0, 0]
-
-      # Fetch all shipment totals in a single query
-      shipment_totals = shipments.reorder(nil).pick(
-        Arel.sql('COALESCE(SUM(adjustment_total), 0)'),
-        Arel.sql('COALESCE(SUM(included_tax_total), 0)'),
-        Arel.sql('COALESCE(SUM(additional_tax_total), 0)'),
-        Arel.sql('COALESCE(SUM(promo_total), 0)')
-      ) || [0, 0, 0, 0]
-
-      # Fetch order-level adjustment totals in a single query
-      order_adjustment_totals = adjustments.eligible.reorder(nil).pick(
-        Arel.sql('COALESCE(SUM(amount), 0)'),
-        Arel.sql("COALESCE(SUM(CASE WHEN source_type = 'Spree::PromotionAction' THEN amount ELSE 0 END), 0)")
-      ) || [0, 0]
-
-      order.adjustment_total = line_item_totals[0] + shipment_totals[0] + order_adjustment_totals[0]
-      order.included_tax_total = line_item_totals[1] + shipment_totals[1]
-      order.additional_tax_total = line_item_totals[2] + shipment_totals[2]
-      order.promo_total = line_item_totals[3] + shipment_totals[3] + order_adjustment_totals[1]
-
-      update_order_total
+      deprecate_totals(__method__)
+      recalculate_totals
+      order.adjustment_total
     end
 
+    # @deprecated Use {Spree::Carts::RecalculateTotals}; removed in 6.1.
     def update_item_count
-      order.item_count = quantity
+      deprecate_totals(__method__)
+      recalculate_totals
+      order.total_quantity
     end
 
-    def update_item_total
-      order.item_total = line_items.to_a.sum(&:amount)
-      update_order_total
+    # @deprecated Use {Spree::Carts::RecalculateTotals}; removed in 6.1.
+    def persist_totals
+      deprecate_totals(__method__)
+      recalculate_totals
     end
 
-    def persist_totals
-      order.update_columns(
-        payment_state: order.payment_state,
-        shipment_state: order.shipment_state,
-        item_total: order.item_total,
-        item_count: order.item_count,
-        adjustment_total: order.adjustment_total,
-        included_tax_total: order.included_tax_total,
-        additional_tax_total: order.additional_tax_total,
-        payment_total: order.payment_total,
-        shipment_total: order.shipment_total,
-        promo_total: order.promo_total,
-        total: order.total,
-        updated_at: Time.current
-      )
-    end
-
-    # Updates the +shipment_state+ attribute according to the following logic:
-    #
-    # shipped   when all Shipments are in the "shipped" state
-    # partial   when at least one Shipment has a state of "shipped" and there is another Shipment with a state other than "shipped"
-    #           or there are InventoryUnits associated with the order that have a state of "sold" but are not associated with a Shipment.
-    # ready     when all Shipments are in the "ready" state
-    # backorder when there is backordered inventory associated with an order
-    # pending   when all Shipments are in the "pending" state
-    #
-    # The +shipment_state+ value helps with reporting, etc. since it provides a quick and easy way to locate Orders needing attention.
+    # @deprecated Use {Spree::Carts::RecalculateTotals}; removed in 6.1.
+    def update_shipment_total
+      Spree::Deprecation.warn('Spree::OrderUpdater#update_shipment_total is deprecated and will be removed in Spree 6.1. Use Spree::Carts::RecalculateTotals / Spree::Orders::RecalculateTotals (or #recalculate_totals!) instead.')
+      recalculate_totals
+      order.delivery_total
+    end
+
+    # @deprecated Use {Spree::Orders::UpdateStatuses} (or
+    #   +#update_statuses!+); removed in 6.1. UpdateStatuses writes the 6.0
+    #   vocabulary (none/authorized/partially_paid/paid/partially_refunded/
+    #   refunded/overcharged/voided), not the legacy balance_due/credit_owed/
+    #   failed/void names.
+    def update_payment_state
+      deprecate_statuses(__method__)
+      update_statuses
+      order.payment_status
+    end
+
+    # @deprecated Use {Spree::Orders::UpdateStatuses} (or
+    #   +#update_statuses!+); removed in 6.1.
     def update_shipment_state
-      if order.backordered?
-        order.shipment_state = 'backorder'
-      else
-        # get all the shipment states for this order
-        shipment_states = shipments.states.uniq
-
-        order.shipment_state = if shipment_states.size > 1
-                                 if shipment_states.include?('shipped')
-                                   'partial'
-                                 elsif shipment_states.include?('pending')
-                                   'pending'
-                                 else
-                                   'ready'
-                                 end
-                               else
-                                 # will return nil if no shipments are found
-                                 shipment_states.first
-                                 # TODO: inventory unit states?
-                                 # if order.shipment_state && order.inventory_units.where(shipment_id: nil).exists?
-                                 #   shipments exist but there are unassigned inventory units
-                                 #   order.shipment_state = 'partial'
-                                 # end
-                               end
+      deprecate_statuses(__method__)
+      update_statuses
+      order.fulfillment_status
+    end
+
+    # @deprecated Use {Spree::Orders::UpdateStatuses} for the state roll-up
+    #   and {Spree::Carts::Recalculate} for the delivery proposal rebuild;
+    #   removed in 6.1.
+    def update_shipments
+      Spree::Deprecation.warn('Spree::OrderUpdater#update_shipments is deprecated and will be removed in Spree 6.1. Use Spree::Orders::UpdateStatuses (fulfillment states) and Spree::Carts::Recalculate (delivery proposals) instead.')
+
+      audience = order.completed? ? DeliveryMethod::BACKOFFICE : DeliveryMethod::STOREFRONT
+
+      fulfillments.each do |fulfillment|
+        next unless fulfillment.persisted?
+
+        fulfillment.update!(order)
+        next if order.completed? && fulfillment.fulfilled?
+
+        fulfillment.refresh_rates(audience)
+        fulfillment.update_amounts
       end
+    end
 
-      order.state_changed('shipment')
-      order.shipment_state
+    # @deprecated Order update hooks are removed in 6.1 — subscribe to the
+    #   +order.updated+ event instead.
+    def run_hooks
+      Spree::Deprecation.warn('Spree::OrderUpdater#run_hooks is deprecated and will be removed in Spree 6.1. Subscribe to the order.updated event instead.')
+      update_hooks.each { |hook| order.send hook }
     end
 
-    # Updates the +payment_state+ attribute according to the following logic:
-    #
-    # paid          when +payment_total+ is equal to +total+
-    # balance_due   when +payment_total+ is less than +total+
-    # credit_owed   when +payment_total+ is greater than +total+
-    # failed        when most recent payment is in the failed state
-    # void          when order is canceled and +payment_total+ is equal to zero
-    #
-    # The +payment_state+ value helps with reporting, etc. since it provides a quick and easy way to locate Orders needing attention.
-    def update_payment_state
-      last_state = order.payment_state
-      if payments.present? && payments.valid.empty?
-        order.payment_state = 'failed'
-      elsif order.canceled? && order.payment_total == 0
-        order.payment_state = 'void'
-      else
-        order.payment_state = 'balance_due' if order.outstanding_balance > 0
-        order.payment_state = 'credit_owed' if order.outstanding_balance < 0
-        order.payment_state = 'paid' unless order.outstanding_balance?
-      end
-      order.state_changed('payment') if last_state != order.payment_state
-      order.payment_state
+    private
+
+    def recalculate_totals
+      Spree.cart_recalculate_totals_workflow.call(cart: order)
+    end
+
+    # UpdateStatuses persists via update_columns, which leaves the in-memory
+    # record stale — re-read just the two status columns it wrote. The
+    # fulfillments cache is reset first: the roll-up reads that association,
+    # and callers routinely hold one loaded before their own mutations.
+    def update_statuses
+      order.association(:fulfillments).reset if order.persisted?
+
+      Spree.order_update_statuses_service.call(order: order)
+      return unless order.persisted?
+
+      statuses = order.class.where(id: order.id).pick(:payment_status, :fulfillment_status)
+      return if statuses.nil?
+
+      # write_attribute, not the setters — these columns are already
+      # persisted, so they must not show up as unsaved changes.
+      order.send(:write_attribute, :payment_status, statuses.first)
+      order.send(:write_attribute, :fulfillment_status, statuses.last)
+      order.send(:clear_attribute_changes, [:payment_status, :fulfillment_status])
+    end
+
+    def deprecate_totals(method_name)
+      Spree::Deprecation.warn("Spree::OrderUpdater##{method_name} is deprecated and will be removed in Spree 6.1. Use Spree::Carts::RecalculateTotals / Spree::Orders::RecalculateTotals (or #recalculate_totals!) instead.")
+    end
+
+    def deprecate_statuses(method_name)
+      Spree::Deprecation.warn("Spree::OrderUpdater##{method_name} is deprecated and will be removed in Spree 6.1. Use Spree::Orders::UpdateStatuses (or #update_statuses!) instead.")
     end
   end
 end

data/app/models/spree/package_type.rb

@@ -0,0 +1,191 @@
+module Spree
+  # A kind of packaging the store uses: the box it ships parcels in, the
+  # cartons its products are packed into, the pallets those cartons stack on,
+  # the containers a wholesale order fills.
+  #
+  # Geometry lives here rather than on the things packed into it because
+  # merchants reuse a handful of standard sizes across hundreds of products —
+  # one edit to a carton row fixes every product packed in that carton. What
+  # varies per product (how many units fit, what a packed carton weighs) stays
+  # on the variant.
+  #
+  # See docs/plans/6.0-b2b-wholesale-shipping.md.
+  class PackageType < Spree.base_class
+    KINDS = %w[box envelope carton pallet container].freeze
+
+    has_prefix_id :pkgtype
+
+    include Spree::SingleStoreResource
+    include Spree::Metadata
+
+    belongs_to :store, class_name: 'Spree::Store'
+
+    # Whose packaging this is. Nil is the marketplace's own row — the shared
+    # vocabulary every seller may pack into — and a seller's rows are theirs
+    # alone (docs/plans/6.0-seller-package-types.md).
+    #
+    # `with_deleted` for the reason a delivery method's owner is: a seller is
+    # paranoid and this association deliberately survives one, because a nil
+    # `seller_id` IS the marketplace's row. Releasing a departed seller's rows
+    # would hand the operator a second default box.
+    belongs_to :seller, -> { with_deleted }, class_name: 'Spree::Seller', optional: true,
+               inverse_of: :package_types
+
+    has_many :variants, class_name: 'Spree::Variant', foreign_key: :carton_package_type_id,
+             inverse_of: :carton_package_type, dependent: :restrict_with_error
+
+    validates :name, presence: true,
+              uniqueness: { scope: spree_base_uniqueness_scope + [:store_id, :seller_id] }
+    validates :kind, inclusion: { in: KINDS }
+    validates :dimensions_unit, inclusion: { in: Spree::Variant::DIMENSION_UNITS }, allow_blank: true
+    validates :weight_unit, inclusion: { in: Spree::Variant::WEIGHT_UNITS }, allow_blank: true
+    validates :length, :width, :height, :weight, :max_weight,
+              numericality: { greater_than_or_equal_to: 0, allow_nil: true }
+
+    # Demote the owner's prior default in the same transaction so the partial
+    # unique index ("one default per owner") never sees two TRUE rows, and
+    # MySQL — which cannot enforce that index — arrives at the same place.
+    validate :kind_cannot_leave_the_products_packed_in_it, on: :update
+    before_save :demote_other_defaults, if: -> { default? && will_save_change_to_default? }
+    validate :default_cannot_be_given_up, on: :update
+    # prepend so this runs before the association callbacks Rails registers,
+    # and is skipped when the store itself is going away.
+    before_destroy :ensure_not_default, prepend: true
+
+    scope :default, -> { where(default: true) }
+
+    scope :cartons, -> { where(kind: 'carton') }
+
+    # The marketplace's own packaging, and one seller's.
+    scope :first_party, -> { where(seller_id: nil) }
+    scope :for_seller, ->(seller) { where(seller_id: seller.respond_to?(:id) ? seller.id : seller) }
+    # One owner's rows within one store — the unit the default flag belongs
+    # to. Named as `Spree::StockLocation` names it, since it does the same job
+    # there for the same reason.
+    scope :owned_by, ->(store_id:, seller_id:) { where(store_id: store_id, seller_id: seller_id) }
+
+    # Everything a seller may pack into: their own rows plus the
+    # marketplace's, which they read but never write. A nil seller is the
+    # operator, who packs into their own rows only.
+    #
+    # @param seller [Spree::Seller, nil]
+    scope :available_to_seller, ->(seller) {
+      seller.nil? ? first_party : for_seller(seller).or(first_party)
+    }
+
+    # Whether the given owner may pack into this row: their own, or the
+    # marketplace's shared vocabulary. The Ruby twin of `available_to_seller`,
+    # so the validation and the scope cannot drift apart on what "mine or the
+    # marketplace's" means.
+    #
+    # @param owner_seller_id [Integer, nil] nil is the operator
+    # @return [Boolean]
+    def available_to_seller?(owner_seller_id)
+      seller_id.nil? || seller_id == owner_seller_id
+    end
+
+    # The one kind anything branches on: a variant may only be packed into a
+    # carton. The rest of the vocabulary is the merchant's to name and read.
+    #
+    # @return [Boolean]
+    def carton?
+      kind == 'carton'
+    end
+
+    # `seller_id` is what the operator's list filters by to see one seller's
+    # packaging, or (blank) the marketplace's own.
+    self.whitelisted_ransackable_attributes = %w[name kind default seller_id]
+    self.whitelisted_ransackable_associations = %w[seller]
+
+    # The unit the geometry is expressed in, falling back to what the store's
+    # unit system implies — the same fallback a variant's dimensions take.
+    #
+    # @return [String]
+    def dimensions_unit
+      self[:dimensions_unit].presence || Spree::Variant.store_dimensions_unit(store)
+    end
+
+    # @return [String]
+    def weight_unit
+      self[:weight_unit].presence || store&.preferred_weight_unit || Spree::Measurement::DEFAULT_WEIGHT_UNIT
+    end
+
+    # The cubic meters this package occupies. Nil until all three dimensions
+    # are recorded — a partially measured box has no volume to report.
+    #
+    # @return [BigDecimal, nil]
+    def volume
+      Spree::Measurement.cubic_meters(length, width, height, unit: dimensions_unit)
+    end
+
+    # Geometry expressed in the unit the given store works in, so a carton
+    # a merchant measured in centimetres is still usable by a store that
+    # quotes in inches. Nil unless all three sides are recorded.
+    #
+    # @param unit [String] one of {Spree::Variant::DIMENSION_UNITS}
+    # @return [Hash{Symbol => Float}, nil]
+    def dimensions_in(unit)
+      sides = { length: length, width: width, height: height }
+      return if sides.values.any? { |side| side.to_f.zero? }
+
+      sides.transform_values { |side| Spree::Measurement.convert_length(side, from: dimensions_unit, to: unit).to_f }
+    end
+
+    # The empty package's own weight in the given unit — the tare added to
+    # every quote.
+    #
+    # @param unit [String] one of {Spree::Variant::WEIGHT_UNITS}
+    # @return [BigDecimal]
+    def weight_in(unit)
+      Spree::Measurement.convert_weight(weight, from: weight_unit, to: unit) || 0
+    end
+
+    private
+
+    # Deleting the store's box would leave every quote with no tare and no
+    # dimensions, which under-prices bulky shipments silently. Name another
+    # default first — unless the store itself is being destroyed, where
+    # refusing would abort that too and strand the row.
+    def ensure_not_default
+      return unless default?
+      return if destroyed_by_association.present?
+
+      errors.add(:base, Spree.t('errors.messages.cannot_delete_default_package_type'))
+      throw(:abort)
+    end
+
+    # A variant may only be packed into a carton, and that is checked when the
+    # variant is saved — so letting a carton become a pallet later would leave
+    # every product already packed in it pointing at a row it could no longer
+    # choose, its geometry still feeding their freight rollups. Repack them
+    # first.
+    def kind_cannot_leave_the_products_packed_in_it
+      return unless kind_changed? && kind_was == 'carton' && kind != 'carton'
+      return unless variants.exists?
+
+      errors.add(:kind, :cannot_stop_being_a_carton)
+    end
+
+    # Clearing the flag on the only default leaves the store with no box at
+    # all, which is the same silent loss as deleting it. Promote another row
+    # instead; that demotes this one in the same save.
+    def default_cannot_be_given_up
+      return unless default_changed? && default_was && !default?
+      return if other_defaults.exists?
+
+      errors.add(:default, :cannot_be_given_up)
+    end
+
+    def demote_other_defaults
+      other_defaults.update_all(default: false)
+    end
+
+    # The other rows competing for this row's default flag: the same owner's,
+    # in the same store. The operator and each seller hold one default box
+    # apiece, so promoting a seller's box must not demote the marketplace's.
+    def other_defaults
+      self.class.owned_by(store_id: store_id, seller_id: seller_id).
+        where(default: true).where.not(id: id)
+    end
+  end
+end

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

@@ -19,18 +19,65 @@ module Spree
 
       def should_publish_paid_event?
         return false unless Spree::Events.enabled?
-        return false unless state_previously_changed?
+        return false unless status_previously_changed?
 
-        state_previous_change&.last == 'completed'
+        status_previous_change&.last == 'completed'
       end
 
       def publish_payment_paid_event
         publish_event('payment.paid')
-        publish_order_paid_event if order.paid?
+
+        # A payment shared by a split checkout belongs to no single order, so
+        # each child is asked about its own share. order.paid is a public
+        # webhook; a marketplace order must announce itself paid like any other.
+        return publish_grouped_paid_events if grouped?
+
+        # order is nil for a cart-owned payment — checkout is still in
+        # flight, so there is no order to declare paid yet.
+        return if order.nil?
+
+        # Derived from the payment rows rather than order.paid?, which reads
+        # payment_total — a column written by the order status subscriber on
+        # the payment.completed event that has not been dispatched yet when
+        # this after_commit runs. Reading it here (cached or reloaded) sees
+        # the pre-settlement figure and the order is never declared paid.
+        order.publish_event('order.paid') if order_settled_in_full?
+      end
+
+      # @return [Boolean]
+      def order_settled_in_full?
+        return false unless order.total.to_d.positive?
+
+        settled = order.payments.completed.includes(:refunds).sum { |payment| payment.amount - payment.refunds.sum(:amount) }
+        settled >= order.total.to_d
+      end
+
+      # Declares each child of a split checkout paid once its own shares cover
+      # its total — which is not all at once, since one seller can be captured
+      # on dispatch while another is still waiting.
+      def publish_grouped_paid_events
+        payment_splits.includes(:order).each do |split|
+          child = split.order
+          next if child.nil? || child.total.to_d <= 0
+
+          child.publish_event('order.paid') if settled_for(child) >= child.total.to_d
+        end
       end
 
-      def publish_order_paid_event
-        order.publish_event('order.paid')
+      # What a child has settled, counting this payment's share as taken.
+      #
+      # This runs before payment.completed reaches the subscriber that marks
+      # the shares captured, so the column still reads zero for the payment
+      # that just settled — asking it would decide no child had been paid.
+      # Its share is therefore counted from what it authorised, and the other
+      # payments from what they have actually drawn.
+      #
+      # @return [BigDecimal]
+      def settled_for(child)
+        child.payment_splits.sum do |row|
+          taken = row.payment_id == id ? row.authorized_amount : row.captured_amount
+          taken - row.refunded_amount
+        end
       end
     end
   end