Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

Retire the state machine on FulfillmentItem

Damian Legawieca4127dd43d4b
diff --git a/spree/core/app/models/spree/fulfillment_item.rb b/spree/core/app/models/spree/fulfillment_item.rb
index 9a9cccb620..7163d1b5e6 100644
--- a/spree/core/app/models/spree/fulfillment_item.rb
+++ b/spree/core/app/models/spree/fulfillment_item.rb
@@ -38,20 +38,50 @@ module Spree
money_methods :charged_amount
- # state machine (see http://github.com/pluginaweek/state_machine/tree/master for details)
- state_machine :status, initial: :on_hand do
- event :fill_backorder do
- transition to: :on_hand, from: :backordered
- end
- after_transition on: :fill_backorder, do: :fulfill_order
+ # 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?)
- event :ship do
- transition to: :shipped, if: :allow_ship?
- end
+ update!(status: 'shipped')
+ true
+ end
- event :return do
- transition to: :returned, from: :shipped
- 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
@@ -114,16 +144,5 @@ module Spree
def percentage_of_line_item
quantity / BigDecimal(line_item.quantity)
end
-
- private
-
- def allow_ship?
- on_hand?
- end
-
- def fulfill_order
- reload
- order.fulfill!
- end
end
end
diff --git a/spree/core/app/models/spree/stock_level.rb b/spree/core/app/models/spree/stock_level.rb
index 7bac859432..8668acf1a7 100644
--- a/spree/core/app/models/spree/stock_level.rb
+++ b/spree/core/app/models/spree/stock_level.rb
@@ -167,6 +167,7 @@ module Spree
return unless number.positive?
units = backordered_inventory_units.first(number) # We can process atmost n backorders
+ filled_units = []
units.each do |unit|
break unless number.positive?
@@ -181,12 +182,17 @@ module Spree
# if required quantity is greater than available
# split off and fulfill that
split = unit.split_inventory!(number)
- split.fill_backorder
+ filled_units << split if split.fill_backorder!
else
- unit.fill_backorder
+ filled_units << unit if unit.fill_backorder!
end
number -= filled
end
+
+ # One recalculation per affected order, after the whole arrival is
+ # allocated — filling five backorders on one order is one order update,
+ # not five.
+ filled_units.filter_map(&:order).uniq.each(&:fulfill!)
end
end
end
diff --git a/spree/core/app/workflows/spree/fulfillments/create.rb b/spree/core/app/workflows/spree/fulfillments/create.rb
index 39dca6d8c1..0c95eb592f 100644
--- a/spree/core/app/workflows/spree/fulfillments/create.rb
+++ b/spree/core/app/workflows/spree/fulfillments/create.rb
@@ -313,7 +313,7 @@ module Spree
# is forced — the goods already left, so refusing on an unpaid order
# would just refuse to record history.
def mark_shipped(fulfillment)
- fulfillment.fulfillment_items.backordered.each(&:fill_backorder!)
+ fulfillment.fulfillment_items.backordered.update_all(status: 'on_hand', updated_at: Time.current)
fulfillment.reload
Spree.fulfillment_fulfill_workflow.call(fulfillment: fulfillment, force: true)
end
diff --git a/spree/core/app/workflows/spree/fulfillments/fulfill.rb b/spree/core/app/workflows/spree/fulfillments/fulfill.rb
index 1dd8bb626f..bd8c146e00 100644
--- a/spree/core/app/workflows/spree/fulfillments/fulfill.rb
+++ b/spree/core/app/workflows/spree/fulfillments/fulfill.rb
@@ -324,7 +324,13 @@ module Spree
# reads it when building the event metadata.
def mark_fulfilled
@fulfillment.notify_customer = notify_customer
- @fulfillment.fulfillment_items.each(&:ship!)
+ # Stock in hand always leaves; a forced dispatch takes backordered
+ # units with it, because the parcel has physically gone.
+ shippable = force ? %w[on_hand backordered] : %w[on_hand]
+ @fulfillment.fulfillment_items.where(status: shippable).update_all(status: 'shipped', updated_at: Time.current)
+ # update_all leaves the loaded association holding the old statuses,
+ # which later steps and hook handlers would read.
+ @fulfillment.fulfillment_items.reset
@fulfillment.update!(status: 'fulfilled', fulfilled_at: Time.current)
@fulfillment.publish_fulfillment_fulfilled_event
end
diff --git a/spree/core/lib/spree/testing_support/factories/order_factory.rb b/spree/core/lib/spree/testing_support/factories/order_factory.rb
index 090b4f53ac..6debf057d8 100644
--- a/spree/core/lib/spree/testing_support/factories/order_factory.rb
+++ b/spree/core/lib/spree/testing_support/factories/order_factory.rb
@@ -128,7 +128,7 @@ FactoryBot.define do
end
order.fulfillments.each do |shipment|
- shipment.fulfillment_items.update_all state: 'on_hand'
+ shipment.fulfillment_items.update_all status: 'on_hand'
shipment.update_column(:status, 'unfulfilled')
end
order.reload
diff --git a/spree/core/spec/models/spree/fulfilment_changer_spec.rb b/spree/core/spec/models/spree/fulfilment_changer_spec.rb
index de475a6a32..a6edab9f9c 100644
--- a/spree/core/spec/models/spree/fulfilment_changer_spec.rb
+++ b/spree/core/spec/models/spree/fulfilment_changer_spec.rb
@@ -263,7 +263,7 @@ describe Spree::FulfilmentChanger do
let(:backordered_units) { 6 }
before do
- current_shipment.inventory_units.limit(backordered_units).update_all(state: :backordered)
+ current_shipment.inventory_units.limit(backordered_units).update_all(status: :backordered)
current_stock_level.update_column(:count_on_hand, -backordered_units)
end
diff --git a/spree/core/spec/models/spree/order_spec.rb b/spree/core/spec/models/spree/order_spec.rb
index 1b082f7f6b..3808815704 100644
--- a/spree/core/spec/models/spree/order_spec.rb
+++ b/spree/core/spec/models/spree/order_spec.rb
@@ -1094,7 +1094,7 @@ describe Spree::Order, type: :model do
context 'when shipped' do
before do
- inventory_unit.update_column(:state, 'shipped')
+ inventory_unit.update_column(:status, 'shipped')
end
it 'does not delete inventory_unit' do
@@ -1105,7 +1105,7 @@ describe Spree::Order, type: :model do
context 'when returned' do
before do
- inventory_unit.update_column(:state, 'returned')
+ inventory_unit.update_column(:status, 'returned')
end
it 'does not delete inventory_unit' do
@@ -1116,7 +1116,7 @@ describe Spree::Order, type: :model do
context 'when on_hand' do
before do
- inventory_unit.update_column(:state, 'on_hand')
+ inventory_unit.update_column(:status, 'on_hand')
end
it 'deletes inventory_unit' do
@@ -1127,7 +1127,7 @@ describe Spree::Order, type: :model do
context 'when backordered' do
before do
- inventory_unit.update_column(:state, 'backordered')
+ inventory_unit.update_column(:status, 'backordered')
end
it 'deletes inventory_unit' do
@@ -1242,7 +1242,7 @@ describe Spree::Order, type: :model do
let(:order) { create(:order_with_line_items, line_items_count: 3) }
context 'all inventory units are returned' do
- before { order.inventory_units.update_all(state: 'returned') }
+ before { order.inventory_units.update_all(status: 'returned') }
it 'is true' do
expect(subject).to eq true
diff --git a/spree/core/spec/models/spree/stock_level_spec.rb b/spree/core/spec/models/spree/stock_level_spec.rb
index 4f76e441ee..433eccb15f 100644
--- a/spree/core/spec/models/spree/stock_level_spec.rb
+++ b/spree/core/spec/models/spree/stock_level_spec.rb
@@ -167,9 +167,9 @@ describe Spree::StockLevel, type: :model do
it 'splits inventory to fulfill partial backorder' do
expect(inventory_unit_2).not_to receive(:split_inventory!)
- expect(split_inventory_unit).to receive(:fill_backorder)
- expect(inventory_unit).not_to receive(:fill_backorder)
- expect(inventory_unit_2).not_to receive(:fill_backorder)
+ expect(split_inventory_unit).to receive(:fill_backorder!)
+ expect(inventory_unit).not_to receive(:fill_backorder!)
+ expect(inventory_unit_2).not_to receive(:fill_backorder!)
subject.adjust_count_on_hand(3)
expect(subject.count_on_hand).to eq(-2)
@@ -190,8 +190,8 @@ describe Spree::StockLevel, type: :model do
# Regression test for #3755
it 'processes existing backorders, even with negative stock' do
- expect(inventory_unit).to receive(:fill_backorder)
- expect(inventory_unit_2).not_to receive(:fill_backorder)
+ expect(inventory_unit).to receive(:fill_backorder!)
+ expect(inventory_unit_2).not_to receive(:fill_backorder!)
subject.adjust_count_on_hand(1)
expect(subject.count_on_hand).to eq(-1)
end
@@ -199,8 +199,8 @@ describe Spree::StockLevel, type: :model do
# Test for #3755. Only a dispatch may drive the shelf further below zero
# now, so this says so at the call.
it 'does not process backorders when stock is adjusted negatively' do
- expect(inventory_unit).not_to receive(:fill_backorder)
- expect(inventory_unit_2).not_to receive(:fill_backorder)
+ expect(inventory_unit).not_to receive(:fill_backorder!)
+ expect(inventory_unit_2).not_to receive(:fill_backorder!)
subject.adjust_count_on_hand(-1, force: true)
expect(subject.count_on_hand).to eq(-3)
end
@@ -209,8 +209,8 @@ describe Spree::StockLevel, type: :model do
before { allow(subject).to receive_messages(backordered_inventory_units: [inventory_unit, inventory_unit_2]) }
it 'fills existing backorders' do
- expect(inventory_unit).to receive(:fill_backorder)
- expect(inventory_unit_2).to receive(:fill_backorder)
+ expect(inventory_unit).to receive(:fill_backorder!)
+ expect(inventory_unit_2).to receive(:fill_backorder!)
subject.adjust_count_on_hand(3)
expect(subject.count_on_hand).to eq(1)
@@ -251,8 +251,8 @@ describe Spree::StockLevel, type: :model do
end
it 'fills existing backorders' do
- expect(inventory_unit).to receive(:fill_backorder)
- expect(inventory_unit_2).to receive(:fill_backorder)
+ expect(inventory_unit).to receive(:fill_backorder!)
+ expect(inventory_unit_2).to receive(:fill_backorder!)
subject.set_count_on_hand(1)
expect(subject.count_on_hand).to eq(1)
diff --git a/spree/core/spec/workflows/spree/fulfillments/create_spec.rb b/spree/core/spec/workflows/spree/fulfillments/create_spec.rb
index 8dcb7a21b5..ec1155c25e 100644
--- a/spree/core/spec/workflows/spree/fulfillments/create_spec.rb
+++ b/spree/core/spec/workflows/spree/fulfillments/create_spec.rb
@@ -248,7 +248,7 @@ module Spree
context 'with backordered units' do
before do
- source_shipment.inventory_units.update_all(state: 'backordered')
+ source_shipment.inventory_units.update_all(status: 'backordered')
end
it 'fills backorders before shipping' do
diff --git a/spree/core/spec/workflows/spree/fulfillments/fulfill_spec.rb b/spree/core/spec/workflows/spree/fulfillments/fulfill_spec.rb
index 5e061adbf8..17a9c786f9 100644
--- a/spree/core/spec/workflows/spree/fulfillments/fulfill_spec.rb
+++ b/spree/core/spec/workflows/spree/fulfillments/fulfill_spec.rb
@@ -240,6 +240,18 @@ module Spree
expect(stock_level.reload.count_on_hand).to eq(0)
end
+ # Same doctrine one level down: the items go with the parcel. The old
+ # machine's guarded `ship` event raised here instead, aborting a
+ # dispatch the merchant had explicitly forced.
+ it 'ships backordered items on a forced dispatch' do
+ fulfillment.fulfillment_items.each { |item| item.update_columns(status: 'backordered') }
+
+ result = subject.call(fulfillment: fulfillment, force: true)
+
+ expect(result.success?).to eq(true)
+ expect(fulfillment.reload.fulfillment_items.map(&:status).uniq).to eq(['shipped'])
+ end
+
# Departure is a physical fact: a forced dispatch records the parcel even
# when the shelf says the goods were never there. Availability is
# untouched on the way through — the promise had already been subtracted.