spree_core 5.6.0 → 6.0.0.beta1

data/app/models/spree/fulfillment_changer.rb

@@ -0,0 +1,170 @@
+module Spree
+  class FulfillmentChanger
+    include ActiveModel::Validations
+
+    validates :quantity, numericality: { greater_than: 0 }
+    validates :desired_stock_location, presence: true
+    validate  :current_shipment_not_already_shipped
+    validate  :desired_shipment_different_from_current
+    validate  :enough_stock_at_desired_location, if: :handle_stock_counts?
+
+    def initialize(params = {})
+      @current_stock_location = params[:current_stock_location]
+      @desired_stock_location = params[:desired_stock_location]
+      @current_shipment       = params[:current_shipment]
+      @desired_shipment       = params[:desired_shipment]
+      @variant                = params[:variant]
+      @quantity               = params[:quantity]
+      @available_quantity     = [
+        desired_stock_location&.stock_level(variant)&.available_count.to_i,
+        current_quantity
+      ].max
+    end
+
+    def run!
+      return false if invalid?
+
+      desired_shipment.save! if desired_shipment.new_record?
+
+      handle_stock
+      reload_shipment_inventory_units
+      after_process_shipments
+
+      true
+    end
+
+    private
+
+    attr_reader :variant, :quantity, :current_stock_location, :desired_stock_location,
+                :current_shipment, :desired_shipment, :available_quantity
+
+    def handle_stock
+      ActiveRecord::Base.transaction do
+        carry_allocation
+        move_inventory_units_between_shipments
+      end
+    end
+
+    # Re-pointing a promise between fulfillments moves no goods, so this runs
+    # whether or not the origin changes. Only a promise that exists can move:
+    # a fulfillment on an order that was never placed, or one created before
+    # typed movements, carries nothing.
+    def carry_allocation
+      carried = [current_shipment.allocated_quantities[variant.id].to_i, quantity].min
+      return unless carried.positive?
+
+      current_stock_location.release(variant, carried, current_shipment)
+      desired_stock_location.allocate(variant, carried, desired_shipment)
+    end
+
+    def move_inventory_units_between_shipments
+      update_desired_shipment_inventory_units
+      update_current_shipment_inventory_units
+    end
+
+    def current_shipment_units
+      @current_shipment_units ||= current_shipment.fulfillment_items.on_hand_or_backordered.where(variant_id: variant.id)
+    end
+
+    def update_desired_shipment_inventory_units
+      on_hand_unit = get_desired_shipment_inventory_unit(:on_hand)
+      on_hand_unit.update(quantity: on_hand_unit.quantity + new_on_hand_quantity)
+
+      new_backorder_quantity = current_on_hand_quantity - new_on_hand_quantity
+      if new_backorder_quantity > 0
+        backordered_unit = get_desired_shipment_inventory_unit(:backordered)
+        backordered_unit.update(quantity: backordered_unit.quantity + new_backorder_quantity)
+      end
+    end
+
+    def update_current_shipment_inventory_units
+      reduced_quantity = current_on_hand_quantity
+
+      # Reduce quantities from all backordered units first in case there is more than one.
+      backorder_units = current_shipment_units.backordered
+      reduced_quantity = reduce_units_quantities(reduced_quantity, backorder_units) if backorder_units.any?
+
+      # Reduce quantities from all on_hand units in case there is more than one.
+      if reduced_quantity > 0
+        on_hand_units = current_shipment_units.on_hand
+        reduce_units_quantities(reduced_quantity, on_hand_units) if on_hand_units.any?
+      end
+    end
+
+    def reduce_units_quantities(reduced_quantity, units)
+      units.each do |unit|
+        if unit.quantity > reduced_quantity
+          unit.update(quantity: unit.quantity - reduced_quantity)
+          reduced_quantity = 0
+        else
+          reduced_quantity -= unit.quantity
+          unit.destroy!
+        end
+        break if reduced_quantity.zero?
+      end
+      reduced_quantity
+    end
+
+    def get_desired_shipment_inventory_unit(state)
+      desired_shipment.fulfillment_items.find_or_create_by(status: state, variant: variant) do |unit|
+        current_shipment_unit = current_shipment_units.first
+        unit.variant_id = current_shipment_unit.variant_id
+        unit.order_id = current_shipment_unit.order_id
+        unit.line_item_id = current_shipment_unit.line_item_id
+        unit.quantity = 0
+      end
+    end
+
+    def after_process_shipments
+      if current_shipment.fulfillment_items.sum(:quantity).zero?
+        current_shipment.destroy!
+      else
+        current_shipment.refresh_rates
+      end
+
+      desired_shipment.refresh_rates
+      desired_shipment.update_amounts
+
+      desired_shipment.order.reload
+      desired_shipment.order.recalculate_totals!
+    end
+
+    def new_on_hand_quantity
+      [available_quantity, current_on_hand_quantity].min
+    end
+
+    def current_on_hand_quantity
+      [current_shipment.fulfillment_items.on_hand_or_backordered.sum(:quantity), quantity].min
+    end
+
+    def reload_shipment_inventory_units
+      [current_shipment, desired_shipment].each { |shipment| shipment.fulfillment_items.reload }
+    end
+
+    def current_quantity
+      desired_stock_location == current_stock_location ? quantity : 0
+    end
+
+    def handle_stock_counts?
+      current_shipment.order.completed? && current_stock_location != desired_stock_location
+    end
+
+    def current_shipment_not_already_shipped
+      return unless current_shipment.fulfilled?
+
+      errors.add(:current_shipment, :has_already_been_shipped)
+    end
+
+    def enough_stock_at_desired_location
+      return if Spree::Stock::Quantifier.new(variant, desired_stock_location).can_supply?(quantity)
+
+      errors.add(:desired_shipment, :has_not_enough_stock_at_desired_location)
+    end
+
+    def desired_shipment_different_from_current
+      return unless desired_shipment.id == current_shipment.id
+
+      errors.add(:desired_shipment, :can_not_transfer_within_same_shipment)
+    end
+  end
+end

data/app/models/spree/fulfillment_item.rb

@@ -0,0 +1,148 @@
+module Spree
+  class FulfillmentItem < Spree.base_class
+    has_prefix_id :fi
+
+    extend Spree::DisplayMoney
+
+    with_options inverse_of: :fulfillment_items do
+      belongs_to :variant, -> { with_deleted }, class_name: 'Spree::Variant'
+      # Optional because cart-phase items have no order yet — their owner is
+      # reached through the fulfillment; order_id arrives at completion.
+      belongs_to :order, class_name: 'Spree::Order', optional: true
+      belongs_to :fulfillment, class_name: 'Spree::Fulfillment', touch: true, optional: true
+      has_many :return_line_items, class_name: 'Spree::ReturnLineItem', inverse_of: :fulfillment_item
+      has_many :returns, class_name: 'Spree::Return', through: :return_line_items
+      belongs_to :line_item, class_name: 'Spree::LineItem'
+    end
+
+    scope :backordered, -> { where status: 'backordered' }
+    scope :on_hand, -> { where status: 'on_hand' }
+    scope :on_hand_or_backordered, -> { where status: ['backordered', 'on_hand'] }
+    scope :shipped, -> { where status: 'shipped' }
+    scope :returned, -> { where status: 'returned' }
+    scope :backordered_per_variant, ->(stock_level) do
+      includes(:fulfillment, :order).
+        where.not(Spree::Fulfillment.table_name => { status: 'canceled' }).
+        where(variant_id: stock_level.variant_id).
+        where.not(spree_orders: { completed_at: nil }).
+        backordered.order('spree_orders.completed_at ASC')
+    end
+
+    # Legacy names — removed in 6.1.
+    belongs_to :shipment, class_name: 'Spree::Fulfillment', foreign_key: :fulfillment_id, optional: true, touch: true, deprecated: true
+    alias_attribute :shipment_id, :fulfillment_id
+    # @deprecated the column is +status+ since 6.0
+    alias_attribute :state, :status
+
+    validates :quantity, numericality: { greater_than: 0 }
+
+    money_methods :charged_amount
+
+    # No state machine — the moves are driven by the Spree::Fulfillments
+    # workflows and by Spree::StockLevel when stock arrives for a backorder
+    # (docs/plans/6.0-service-workflows.md). Filling a backorder used to
+    # recalculate the whole order from a transition callback, once per item;
+    # the callers now do that themselves, after the loop.
+    include Spree::HasStatus
+    has_status :on_hand, :backordered, :shipped, :returned, default: :on_hand
+
+    # Marks the item dispatched. Normally only stock in hand can leave, but a
+    # forced dispatch ships a backordered item too: departure is a physical
+    # fact, and a parcel the merchant has already handed over is recorded
+    # whatever the shelf says. An item that has already shipped or been
+    # returned is left alone.
+    #
+    # @param force [Boolean] dispatch a backordered item as well
+    # @return [Boolean] whether the item moved
+    def ship!(force: false)
+      return false unless on_hand? || (force && backordered?)
+
+      update!(status: 'shipped')
+      true
+    end
+
+    # Stock arrived for a backordered item. Callers recalculate the order once
+    # afterwards; this only moves the row.
+    #
+    # @return [Boolean] whether the item moved
+    def fill_backorder!
+      return false unless backordered?
+
+      update!(status: 'on_hand')
+      true
+    end
+    alias fill_backorder fill_backorder!
+
+    # @deprecated Write the status — removed in 6.1. `return` was a state
+    #   machine event name and could never be called as written (it parses as
+    #   the keyword), so this exists only for `send(:return!)`-style callers.
+    def return!
+      Spree::Deprecation.warn('Spree::FulfillmentItem#return! is deprecated and will be removed in Spree 6.1. Write the status instead.')
+      return false unless shipped?
+
+      update!(status: 'returned')
+      true
+    end
+
+    # This was refactored from a simpler query because the previous implementation
+    # led to issues once users tried to modify the objects returned. That's due
+    # to ActiveRecord `joins(shipment: :stock_location)` only returning readonly
+    # objects
+    #
+    # Returns an array of backordered inventory units as per a given stock item
+    def self.backordered_for_stock_level(stock_level)
+      backordered_per_variant(stock_level).select do |unit|
+        unit.fulfillment.stock_location == stock_level.stock_location
+      end
+    end
+
+    def self.finalize_units!
+      update_all(pending: false, updated_at: Time.current)
+    end
+
+    def find_stock_level
+      fulfillment.stock_location.stock_level_or_create(variant)
+    end
+
+    def self.split(original_inventory_unit, extract_quantity)
+      split = original_inventory_unit.dup
+      split.quantity = extract_quantity
+      original_inventory_unit.quantity -= extract_quantity
+      split
+    end
+
+    # This will fail if extract >= available_quantity
+    def split_inventory!(extract_quantity)
+      split = self.class.split(self, extract_quantity)
+      transaction do
+        split.save!
+        save!
+      end
+      split
+    end
+
+    def extract_singular_inventory!
+      split_inventory!(1)
+    end
+
+    def additional_tax_total
+      line_item.additional_tax_total * percentage_of_line_item
+    end
+
+    def included_tax_total
+      line_item.included_tax_total * percentage_of_line_item
+    end
+
+    def required_quantity
+      @required_quantity ||= line_item.quantity
+    end
+
+    def charged_amount
+      percentage_of_line_item * line_item.pre_tax_amount
+    end
+
+    def percentage_of_line_item
+      quantity / BigDecimal(line_item.quantity)
+    end
+  end
+end

data/app/models/spree/fulfillment_provider/base.rb

@@ -0,0 +1,130 @@
+module Spree
+  module FulfillmentProvider
+    # Strategy handling create/track/cancel mechanics per fulfillment type.
+    # Stored as a string class name on DeliveryMethod, constantized at call
+    # time; registered via Spree.fulfillment_providers. Replaces the legacy
+    # ShipmentHandler name-constantize mechanism.
+    class Base
+      include Spree::IntegrationBackedProvider
+
+      class << self
+        # Behavior predicates — the class hierarchy IS the vocabulary.
+        # Subclasses override the one that describes their mechanics; admin
+        # UIs and profile kinds compose against these, never string lists.
+        def digital?
+          false
+        end
+
+        def pickup?
+          false
+        end
+
+        def pickup_point?
+          false
+        end
+
+        # Whether this provider produces shipping labels (and so supports the
+        # explicit buy-label step before fulfilling). Carrier gems override.
+        def generates_labels?
+          false
+        end
+
+      end
+
+      # @return [Boolean] whether the fulfillment may transition to fulfilled
+      def can_fulfill?(_fulfillment)
+        true
+      end
+
+      # Whether fulfillments handled by this provider fulfill themselves on
+      # order completion (digital delivery).
+      def auto_fulfill?
+        false
+      end
+
+      # Whether this provider dispatches to a customer shipping address.
+      # Address-free providers (digital, the pickup kinds) override to false;
+      # it also drives delivery-zone checks, which describe the customer
+      # destination.
+      def requires_address?
+        true
+      end
+
+      # Whether packages originating from this stock location may use the
+      # method — answered by the method's origin group (no group or no
+      # members means every location). Pickup overrides with its own policy
+      # semantics (pickup-enabled counters, ship-to-store transfers).
+      def serves_location?(delivery_method, stock_location)
+        group = delivery_method.delivery_origin_group
+        return true if group.nil?
+
+        group.covers_location?(stock_location)
+      end
+
+      # Buys a carrier label for the owner — a +Spree::Fulfillment+ for an
+      # outbound parcel, a +Spree::Return+ for the inbound one. Core turns the
+      # answer into a +Spree::ShippingLabel+ and its +Spree::Delivery+, and
+      # never asks twice for an owner that already holds an active label, so
+      # a provider needs no idempotency bookkeeping of its own. Only
+      # providers answering +generates_labels?+ are asked.
+      #
+      # @param _owner [Spree::Fulfillment, Spree::Return]
+      # @return [Spree::LabelPurchase, nil] nil when no label could be bought
+      def purchase_label(_owner)
+        nil
+      end
+
+      # Asks the carrier to refund a purchased label.
+      #
+      # @param _shipping_label [Spree::ShippingLabel]
+      # @return [String, false] +'refunded'+ when the carrier settled it,
+      #   +'refund_requested'+ when it will answer later, false when refused
+      def refund_label(_shipping_label)
+        false
+      end
+
+      # Performs the provider-side dispatch when a fulfillment fulfills — a
+      # 3PL pick, a pickup counter, digital links. Label-generating providers
+      # implement +purchase_label+ instead.
+      #
+      # @return [Hash] optionally { tracking_number:, tracking_url: }
+      def create_fulfillment(_fulfillment)
+        raise NotImplementedError, "Please implement 'create_fulfillment' in your fulfillment provider: #{self.class.name}"
+      end
+
+      # Cancels the provider-side dispatch.
+      def cancel_fulfillment(_fulfillment)
+        raise NotImplementedError, "Please implement 'cancel_fulfillment' in your fulfillment provider: #{self.class.name}"
+      end
+
+      # The provider's own tracker page for a consignment.
+      #
+      # @param _delivery [Spree::Delivery]
+      # @return [String, nil]
+      def tracking_url(_delivery)
+        nil
+      end
+
+      # Documents the provider produced beside the label — customs forms,
+      # commercial invoices. The label itself is a +Spree::ShippingLabel+ and
+      # is never reported here.
+      #
+      # @param _owner [Spree::Fulfillment, Spree::Return]
+      # @return [Array<Spree::ShippingDocument>]
+      def documents(_owner)
+        []
+      end
+
+      # The connected, active integration carrying this provider's
+      # credentials, resolved from the owner's store.
+      #
+      # @param owner [Spree::Fulfillment, Spree::Return]
+      # @return [Spree::Integration, nil]
+      def integration_for(owner)
+        return if self.class.integration_class.blank?
+
+        owner.store&.integrations&.active&.find_by(type: self.class.integration_class)
+      end
+    end
+  end
+end

data/app/models/spree/fulfillment_provider/digital.rb

@@ -0,0 +1,44 @@
+module Spree
+  module FulfillmentProvider
+    # Digital delivery: fulfills itself on order completion and generates
+    # DigitalLinks idempotently, one per unit of quantity — replacing the
+    # legacy non-idempotent checkout callback that created one link per line
+    # item regardless of quantity.
+    class Digital < Base
+      def self.digital?
+        true
+      end
+
+      def auto_fulfill?
+        true
+      end
+
+      def requires_address?
+        false
+      end
+
+      def create_fulfillment(fulfillment)
+        fulfillment.line_items.each do |line_item|
+          ensure_links_for(line_item)
+        end
+        {}
+      end
+
+      def cancel_fulfillment(_fulfillment)
+        true
+      end
+
+      # Tops the line item up to one link per asset per unit of quantity.
+      # Also used at order completion for physical items carrying digital
+      # assets (e.g. a manual with a device) that ship through other providers.
+      def ensure_links_for(line_item)
+        line_item.variant.digital_assets.each do |digital_asset|
+          existing = line_item.digital_links.where(digital_asset: digital_asset).count
+          (line_item.quantity - existing).times do
+            line_item.digital_links.create!(digital_asset: digital_asset)
+          end
+        end
+      end
+    end
+  end
+end

data/app/models/spree/fulfillment_provider/manual.rb

@@ -0,0 +1,15 @@
+module Spree
+  module FulfillmentProvider
+    # Default provider — admin-driven fulfillment with no provider-side
+    # mechanics (tracking numbers are entered by hand).
+    class Manual < Base
+      def create_fulfillment(_fulfillment)
+        {}
+      end
+
+      def cancel_fulfillment(_fulfillment)
+        true
+      end
+    end
+  end
+end

data/app/models/spree/fulfillment_provider/pickup.rb

@@ -0,0 +1,38 @@
+module Spree
+  module FulfillmentProvider
+    # Merchant-location pickup: hand-over is confirmed by staff, no
+    # provider-side mechanics.
+    class Pickup < Base
+      def self.pickup?
+        true
+      end
+
+      def requires_address?
+        false
+      end
+
+      # A pickup rate is only real when the package can reach a counter the
+      # customer may collect from: either the package is sourced from an
+      # eligible pickup location itself, or some eligible location accepts
+      # remote stock (pickup_stock_policy 'any' — ship-to-store transfers).
+      def serves_location?(delivery_method, stock_location)
+        return false if stock_location.nil?
+
+        stock_locations = Spree::StockLocation.arel_table
+        delivery_method.available_pickup_locations.where(
+          stock_locations[:id].eq(stock_location.id).or(
+            stock_locations[:pickup_stock_policy].eq('any')
+          )
+        ).exists?
+      end
+
+      def create_fulfillment(_fulfillment)
+        {}
+      end
+
+      def cancel_fulfillment(_fulfillment)
+        true
+      end
+    end
+  end
+end

data/app/models/spree/fulfillment_provider/pickup_point.rb

@@ -0,0 +1,24 @@
+module Spree
+  module FulfillmentProvider
+    # Third-party pickup point (parcel locker, service point). Point
+    # discovery and validation live on the delivery method's
+    # PickupPointProvider; hand-over mechanics default to manual.
+    class PickupPoint < Base
+      def self.pickup_point?
+        true
+      end
+
+      def requires_address?
+        false
+      end
+
+      def create_fulfillment(_fulfillment)
+        {}
+      end
+
+      def cancel_fulfillment(_fulfillment)
+        true
+      end
+    end
+  end
+end