Add an allocator class to extend the Solidus initial allocation logic

With this PR we add the possibility to change the stock allocation logic
using a custom class without override the allocate_inventory method in
SimpleCoordinator.

core/app/models/spree/stock/allocator/base.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Spree
+  module Stock
+    module Allocator
+      class Base
+        attr_reader :availability
+
+        def initialize(availability)
+          @availability = availability
+        end
+
+        def allocate_inventory(_desired)
+          raise NotImplementedError
+        end
+      end
+    end
+  end
+end

core/app/models/spree/stock/allocator/on_hand_first.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Spree
+  module Stock
+    module Allocator
+      class OnHandFirst < Spree::Stock::Allocator::Base
+        def allocate_inventory(desired)
+          # Allocate any available on hand inventory
+          on_hand = allocate_on_hand(desired)
+          desired -= on_hand.values.sum if on_hand.present?
+
+          # Allocate remaining desired inventory from backorders
+          backordered = allocate_backordered(desired)
+          desired -= backordered.values.sum if backordered.present?
+
+          # If all works at this point desired must be empty
+          [on_hand, backordered, desired]
+        end
+
+        protected
+
+        def allocate_on_hand(desired)
+          allocate(availability.on_hand_by_stock_location_id, desired)
+        end
+
+        def allocate_backordered(desired)
+          allocate(availability.backorderable_by_stock_location_id, desired)
+        end
+
+        def allocate(availability_by_location, desired)
+          availability_by_location.transform_values do |available|
+            # Find the desired inventory which is available at this location
+            packaged = available & desired
+            # Remove found inventory from desired
+            desired -= packaged
+            packaged
+          end
+        end
+      end
+    end
+  end
+end

core/app/models/spree/stock/simple_coordinator.rb

@@ -11,6 +11,9 @@ module Stock
     #   * Repeat but for backordered inventory
     #   * Combine allocated and on hand inventory into a single shipment per-location
     #
+    # Allocation logic can be changed using a custom class (as
+    # configured in Spree::Config::stock_allocator_class )
+    #
     # After allocation, splitters are run on each Package (as configured in
     # Spree::Config.environment.stock_splitters)
     #
@@ -31,6 +34,8 @@ def initialize(order, inventory_units = nil)
           variants: @desired.variants,
           stock_locations: @stock_locations
         )
+
+        @allocator = Spree::Config.stock.allocator_class.new(@availability)
       end
 
       def shipments
@@ -40,13 +45,10 @@ def shipments
       private
 
       def build_shipments
-        # Allocate any available on hand inventory
-        on_hand_packages = allocate_inventory(@availability.on_hand_by_stock_location_id)
-
-        # allocate any remaining desired inventory from backorders
-        backordered_packages = allocate_inventory(@availability.backorderable_by_stock_location_id)
+        # Allocate any available on hand inventory and remaining desired inventory from backorders
+        on_hand_packages, backordered_packages, leftover = @allocator.allocate_inventory(@desired)
 
-        unless @desired.empty?
+        unless leftover.empty?
           raise Spree::Order::InsufficientStock
         end
 
@@ -88,13 +90,13 @@ def allocate_inventory(availability_by_location)
         availability_by_location.transform_values do |available|
           # Find the desired inventory which is available at this location
           packaged = available & @desired
-
           # Remove found inventory from desired
           @desired -= packaged
-
           packaged
         end
       end
+      deprecate allocate_inventory: 'allocate_inventory is deprecated. Please write your own allocator defining' \
+        'a Spree::Stock::Allocator::Base subclass', deprecator: Spree::Deprecation
 
       def get_units(quantities)
         # Change our raw quantities back into inventory units

core/lib/spree/app_configuration.rb

@@ -295,6 +295,8 @@ def default_pricing_options
     # promotion_chooser_class allows extensions to provide their own PromotionChooser
     class_name_attribute :promotion_chooser_class, default: 'Spree::PromotionChooser'
 
+    class_name_attribute :allocator_class, default: 'Spree::Stock::Allocator::OnHandFirst'
+
     class_name_attribute :shipping_rate_sorter_class, default: 'Spree::Stock::ShippingRateSorter'
 
     class_name_attribute :shipping_rate_selector_class, default: 'Spree::Stock::ShippingRateSelector'

core/lib/spree/core/stock_configuration.rb

@@ -3,8 +3,7 @@
 module Spree
   module Core
     class StockConfiguration
-      attr_writer :coordinator_class
-      attr_writer :estimator_class
+      attr_writer :coordinator_class, :estimator_class, :allocator_class
 
       def coordinator_class
         @coordinator_class ||= '::Spree::Stock::SimpleCoordinator'
@@ -15,6 +14,11 @@ def estimator_class
         @estimator_class ||= '::Spree::Stock::Estimator'
         @estimator_class.constantize
       end
+
+      def allocator_class
+        @allocator_class ||= '::Spree::Stock::Allocator::OnHandFirst'
+        @allocator_class.constantize
+      end
     end
   end
 end

core/spec/models/spree/stock/allocator/on_hand_first_spec.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+
+module Spree
+  module Stock
+    module Allocator
+      RSpec.describe OnHandFirst, type: :model do
+        subject { described_class.new(availability) }
+
+        let(:availability) { double(Spree::Stock::Availability) }
+
+        let!(:default_stock_location) { create(:stock_location, default: true, backorderable_default: false) }
+        let!(:backorderable_stock_location) { create(:stock_location) }
+
+        let(:first_variant) { create(:variant) }
+        let(:second_variant) { create(:variant) }
+
+        let(:desired_quantities) do
+          quantities = {}
+          quantities[first_variant] = first_variant_desired
+          quantities[second_variant] = second_variant_desired
+          quantities
+        end
+
+        let(:desired) { Spree::StockQuantities.new(desired_quantities) }
+
+        describe '#allocate_inventory' do
+          let(:default_on_hand_availability) do
+            quantities = {}
+            quantities[first_variant] = first_variant_default_availability
+            quantities[second_variant] = second_variant_default_availability
+            quantities
+          end
+
+          let(:dropship_on_hand_availability) do
+            quantities = {}
+            quantities[first_variant] = first_variant_dropship_availability
+            quantities[second_variant] = second_variant_dropship_availability
+            quantities
+          end
+
+          let(:on_hand_by_stock_location_id) do
+            availability = {}
+            availability[default_stock_location.id] = Spree::StockQuantities.new(default_on_hand_availability)
+            availability[backorderable_stock_location.id] = Spree::StockQuantities.new(dropship_on_hand_availability)
+            availability
+          end
+
+          let(:dropship_backorderable_availability) do
+            quantities = {}
+            quantities[first_variant] = Float::INFINITY
+            quantities[second_variant] = Float::INFINITY
+            quantities
+          end
+
+          let(:backorderable_by_stock_location_id) do
+            availability = {}
+            availability[backorderable_stock_location.id] = Spree::StockQuantities.new(dropship_backorderable_availability)
+            availability
+          end
+
+          before do
+            allow(availability).to receive(:on_hand_by_stock_location_id)
+              .and_return(on_hand_by_stock_location_id)
+
+            allow(availability).to receive(:backorderable_by_stock_location_id)
+              .and_return(backorderable_by_stock_location_id)
+          end
+
+          context 'when default stock location has enough items' do
+            let(:first_variant_default_availability) { 100 }
+            let(:second_variant_default_availability) { 100 }
+            let(:first_variant_dropship_availability) { 0 }
+            let(:second_variant_dropship_availability) { 0 }
+            let(:first_variant_desired) { 30 }
+            let(:second_variant_desired) { 5 }
+
+            it 'allocates all the desired units on the default stock location' do
+              on_hand_packages, backordered_packages, leftover = subject.allocate_inventory(desired)
+
+              expect(on_hand_packages[default_stock_location.id][first_variant]).to eq(30)
+              expect(on_hand_packages[default_stock_location.id][second_variant]).to eq(5)
+              expect(on_hand_packages[backorderable_stock_location.id][first_variant]).to eq(0)
+              expect(on_hand_packages[backorderable_stock_location.id][second_variant]).to eq(0)
+
+              expect(backordered_packages[backorderable_stock_location.id][first_variant]).to eq(0)
+              expect(backordered_packages[backorderable_stock_location.id][second_variant]).to eq(0)
+
+              expect(leftover[first_variant]).to eq(0)
+              expect(leftover[second_variant]).to eq(0)
+            end
+          end
+
+          context 'when default stock location hasn\'t enough items' do
+            let(:first_variant_default_availability) { 10 }
+            let(:second_variant_default_availability) { 10 }
+
+            let(:first_variant_desired) { 15 }
+            let(:second_variant_desired) { 5 }
+
+            context 'when dropship stock location has enough items' do
+              let(:first_variant_dropship_availability) { 20 }
+              let(:second_variant_dropship_availability) { 0 }
+
+              it 'allocates all the desired units on the stock locations while stocks last' do
+                on_hand_packages, backordered_packages, leftover = subject.allocate_inventory(desired)
+
+                expect(on_hand_packages[default_stock_location.id][first_variant]).to eq(10)
+                expect(on_hand_packages[default_stock_location.id][second_variant]).to eq(5)
+                expect(on_hand_packages[backorderable_stock_location.id][first_variant]).to eq(5)
+                expect(on_hand_packages[backorderable_stock_location.id][second_variant]).to eq(0)
+
+                expect(backordered_packages[backorderable_stock_location.id][first_variant]).to eq(0)
+                expect(backordered_packages[backorderable_stock_location.id][second_variant]).to eq(0)
+
+                expect(leftover[first_variant]).to eq(0)
+                expect(leftover[second_variant]).to eq(0)
+              end
+            end
+
+            context 'when dropship stock location hasn\'t enough items' do
+              let(:first_variant_dropship_availability) { 2 }
+              let(:second_variant_dropship_availability) { 0 }
+
+              it 'allocates all the desired units on the stock locations while stocks last' do
+                on_hand_packages, backordered_packages, leftover = subject.allocate_inventory(desired)
+
+                expect(on_hand_packages[default_stock_location.id][first_variant]).to eq(10)
+                expect(on_hand_packages[default_stock_location.id][second_variant]).to eq(5)
+                expect(on_hand_packages[backorderable_stock_location.id][first_variant]).to eq(2)
+                expect(on_hand_packages[backorderable_stock_location.id][second_variant]).to eq(0)
+
+                expect(backordered_packages[backorderable_stock_location.id][first_variant]).to eq(3)
+                expect(backordered_packages[backorderable_stock_location.id][second_variant]).to eq(0)
+
+                expect(leftover[first_variant]).to eq(0)
+                expect(leftover[second_variant]).to eq(0)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

core/spec/models/spree/stock/simple_coordinator_spec.rb

@@ -15,6 +15,11 @@ module Stock
           subject.shipments
         end
 
+        it 'uses the pluggable allocator class' do
+          expect(Spree::Config.stock).to receive(:allocator_class).and_call_original
+          subject.shipments
+        end
+
         it 'builds shipments' do
           expect(subject.shipments.size).to eq(1)
         end
@@ -41,6 +46,13 @@ module Stock
         end
       end
 
+      describe "#allocate_inventory" do
+        it 'is deprecated' do
+          expect(Spree::Deprecation).to receive(:warn)
+          subject.send :allocate_inventory, subject.instance_variable_get(:@availability).on_hand_by_stock_location_id
+        end
+      end
+
       # regression spec
       context "when there is one unit that has stock in a stock location that a non-tracked unit has no stock item in" do
         let!(:stock_location_1) { create(:stock_location, propagate_all_variants: false, active: true) }

guides/source/developers/shipments/stock-allocator.html.md

@@ -0,0 +1,58 @@
+# Stock allocator
+
+This article explains the concept of a stock allocator and its usage.
+
+During the checkout process, after the delivery step, the order stocks the ordered stock items
+to ship them.
+
+The stock allocator defines the logic with which these packages are created.
+
+The allocator is called by `Spree::Stock::SimpleCoordinator` when allocating inventory for an order.
+
+## Pre-configured allocator
+
+Currently, we only have one allocator, which you should use unless you need custom logic:
+
+- [On-hand First](https://github.com/solidusio/solidus/blob/master/core/app/models/spree/stock/allocator/on_hand_first.rb),
+  which allocates inventory using Solidus' pre-existing logic.
+
+  Examples:
+    - Someone orders a product which doesn't have stock items on hand, but is backorderable:
+      - The order stocks the inventory and create one backordered shipment.
+    - Someone orders a product which has on hand stock items and it's backorderable:
+      - If the ordered quantity doesn't exceed the availability, the order stocks the inventory
+        and creates one `on_hand` shipment.
+      - Otherwise, if the order exceeds the availability, the order stocks the inventory
+        and create two shipments, one `on_hand` up to the number of available stock items and one
+        backordered for the rest.
+
+## Custom allocator API
+
+A custom allocator should inherit from `Spree::Stock::Allocator::Base` and implement an
+`allocate_inventory` method which accepts a `Spree::StockQuantities` and returns the packages
+splitted with the allocator's logic.
+
+```ruby
+class Spree::Stock::Allocator::CustomAllocator < Spree::Stock::Allocator::Base
+  def allocate_inventory(desired)
+    # Some code to allocate packages with different logic
+  end
+end
+```
+
+### Switching the allocator
+
+Once you have created the logic for the new allocator, you need to register it so that it's used by
+`Spree::Stock::SimpleCoordinator`.
+
+For example, you can register it in your `/config/initializer/spree.rb` initializer:
+
+```ruby
+# /config/initializer/spree.rb
+Spree.config do |config|
+    # ...
+
+    config.stock.allocator_class = 'Spree::Stock::Allocator::CustomAllocator'
+  end
+end
+```