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.

Phase P2.5: Move the promise, not the goods, on every other stock event

Łukasz Adamczyk47a634bb0e36
diff --git a/spree/core/app/models/spree/fulfillment_changer.rb b/spree/core/app/models/spree/fulfillment_changer.rb
index 4640a740b8..8d3d0f0158 100644
--- a/spree/core/app/models/spree/fulfillment_changer.rb
+++ b/spree/core/app/models/spree/fulfillment_changer.rb
@@ -40,15 +40,23 @@ module Spree
def handle_stock
ActiveRecord::Base.transaction do
- if handle_stock_counts?
- current_stock_location.restock(variant, current_on_hand_quantity, current_shipment)
- desired_stock_location.unstock(variant, unstock_quantity, desired_shipment)
- end
-
+ 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
diff --git a/spree/core/app/workflows/spree/fulfillments/create.rb b/spree/core/app/workflows/spree/fulfillments/create.rb
index b78f488a3c..39dca6d8c1 100644
--- a/spree/core/app/workflows/spree/fulfillments/create.rb
+++ b/spree/core/app/workflows/spree/fulfillments/create.rb
@@ -197,10 +197,9 @@ module Spree
end
# Moves the requested quantities into the fulfillment, on-hand units
- # first so the new fulfillment is shippable whenever possible. Restocks
- # the source location and unstocks the target for tracked variants when
- # the locations differ, keeping stock levels truthful about where the
- # goods actually leave from.
+ # first so the new fulfillment is shippable whenever possible, and
+ # carries each moved unit's allocation across with it so the promise
+ # follows the fulfillment that will ship it.
#
# @return [Array<Spree::Shipment>] the shipments units were taken from
def move_units(order, fulfillment, requested, units_by_line_item)
@@ -239,12 +238,20 @@ module Spree
end
end
+ # Re-pointing a promise moves no goods, so this runs even when the
+ # origin does not change: allocation is keyed to the fulfillment, and
+ # the quantity Spree::Fulfillments::Fulfill reads to decide what
+ # shipped would otherwise sit on the wrong one. Only a promise that
+ # exists can move — a fulfillment on an order that was never placed,
+ # or one created before typed movements, carries nothing.
stock_moves.each do |(source_shipment, variant), quantity|
next unless variant.track_inventory?
- next if source_shipment.stock_location_id == fulfillment.stock_location_id
- source_shipment.stock_location.restock(variant, quantity, source_shipment)
- fulfillment.stock_location.unstock(variant, quantity, fulfillment)
+ carried = [source_shipment.allocated_quantities[variant.id].to_i, quantity].min
+ next unless carried.positive?
+
+ source_shipment.stock_location.release(variant, carried, source_shipment)
+ fulfillment.stock_location.allocate(variant, carried, fulfillment)
end
source_shipments.uniq
diff --git a/spree/core/app/workflows/spree/fulfillments/resume.rb b/spree/core/app/workflows/spree/fulfillments/resume.rb
index f04e6198b1..b5f60ca5ad 100644
--- a/spree/core/app/workflows/spree/fulfillments/resume.rb
+++ b/spree/core/app/workflows/spree/fulfillments/resume.rb
@@ -1,13 +1,13 @@
module Spree
module Fulfillments
# Brings a canceled fulfillment back: the goods are going out after all, so
- # their units come off the shelf again and the fulfillment returns to
- # pending or ready depending on what the owning order can support.
+ # their units are promised again and the fulfillment returns to
+ # unfulfilled.
#
- # In the workflow tier for symmetry with Cancel — unstocking is a stock
+ # In the workflow tier for symmetry with Cancel — allocating is a stock
# movement, and a stock movement belongs in an explicit transaction rather
# than a transition callback where a failure would leave the status changed
- # and the shelf wrong.
+ # and the ledger wrong.
class Resume < Spree::Workflow
hooks :validate, :after_resume
@@ -23,7 +23,7 @@ module Spree
step :ensure_resumable
ApplicationRecord.transaction do
- step :unstock_units
+ step :allocate_units
step :mark_resumed
end
@@ -39,15 +39,17 @@ module Spree
failure(fulfillment, Spree.t('fulfillments.errors.cannot_resume'))
end
- # Takes the units back off the shelf. Runs before the transition so a
- # variant that cannot be unstocked aborts while the fulfillment is still
- # canceled, rather than leaving it live with stock never taken.
+ # Reinstating a fulfillment re-promises its units. Nothing physical
+ # moves — the goods are still on the shelf and only leave when the
+ # parcel does. Runs before the transition so a failure leaves the
+ # fulfillment canceled rather than live with no promise behind it.
# Untracked variants are skipped — nothing counts them.
- def unstock_units
+ def allocate_units
fulfillment.manifest.each do |item|
next unless item.variant.track_inventory?
+ next unless item.quantity.positive?
- fulfillment.stock_location.unstock(item.variant, item.quantity, fulfillment)
+ fulfillment.stock_location.allocate(item.variant, item.quantity, fulfillment)
end
end
diff --git a/spree/core/spec/models/spree/fulfilment_changer_spec.rb b/spree/core/spec/models/spree/fulfilment_changer_spec.rb
index 97dbbde5a3..de475a6a32 100644
--- a/spree/core/spec/models/spree/fulfilment_changer_spec.rb
+++ b/spree/core/spec/models/spree/fulfilment_changer_spec.rb
@@ -36,6 +36,9 @@ describe Spree::FulfilmentChanger do
before do
order && desired_shipment
variant.stock_levels.first.update_column(:count_on_hand, 100)
+ # Placement promises each fulfillment's units. A transfer moves that
+ # promise between fulfillments; the goods stay where they are.
+ current_shipment.stock_location.allocate(variant, current_shipment_inventory_unit_count, current_shipment)
end
context 'when the order has multiple line items' do
@@ -116,7 +119,10 @@ describe Spree::FulfilmentChanger do
let!(:stock_level) { desired_stock_location.stock_level_or_create(variant) }
before do
- stock_level.set_count_on_hand(desired_count_on_hand)
+ # update_column rather than a movement: these scenarios describe a
+ # shelf that is already in a given state, including below zero, which
+ # only a departure may now write.
+ stock_level.update_column(:count_on_hand, desired_count_on_hand)
stock_level.update(backorderable: false)
end
@@ -127,12 +133,19 @@ describe Spree::FulfilmentChanger do
expect(subject).to be true
end
- it 'stocks the current stock location back up' do
- expect { subject }.to change { current_shipment.stock_location.count_on_hand(variant) }.by(quantity)
+ it 'releases the promise at the original stock location' do
+ expect { subject }.
+ to change { current_shipment.stock_location.stock_level(variant).allocated_count }.by(-quantity)
end
- it 'unstocks the desired stock location' do
- expect { subject }.to change { desired_shipment.stock_location.count_on_hand(variant) }.by(-quantity)
+ it 'allocates at the desired stock location' do
+ expect { subject }.
+ to change { desired_shipment.stock_location.stock_level(variant).allocated_count }.by(quantity)
+ end
+
+ it 'leaves both shelves alone' do
+ expect { subject }.
+ not_to change { current_shipment.stock_location.count_on_hand(variant) }
end
context 'when the order is not completed' do
@@ -159,12 +172,14 @@ describe Spree::FulfilmentChanger do
stock_level.update(backorderable: true)
end
- it 'restocks seven at the original stock location' do
- expect { subject }.to change { current_shipment.stock_location.count_on_hand(variant) }.by(7)
+ it 'releases seven at the original stock location' do
+ expect { subject }.
+ to change { current_shipment.stock_location.stock_level(variant).allocated_count }.by(-7)
end
- it 'unstocks seven at the desired stock location' do
- expect { subject }.to change { desired_shipment.stock_location.count_on_hand(variant) }.by(-7)
+ it 'allocates seven at the desired stock location' do
+ expect { subject }.
+ to change { desired_shipment.stock_location.stock_level(variant).allocated_count }.by(7)
end
it 'creates a shipment with the correct number of on hand and backordered units' do
@@ -176,12 +191,14 @@ describe Spree::FulfilmentChanger do
context 'when the desired stock location already has a backordered units' do
let(:desired_count_on_hand) { -1 }
- it 'restocks seven at the original stock location' do
- expect { subject }.to change { current_shipment.stock_location.count_on_hand(variant) }.by(7)
+ it 'releases seven at the original stock location' do
+ expect { subject }.
+ to change { current_shipment.stock_location.stock_level(variant).allocated_count }.by(-7)
end
- it 'unstocks seven at the desired stock location' do
- expect { subject }.to change { desired_shipment.stock_location.count_on_hand(variant) }.by(-7)
+ it 'allocates seven at the desired stock location' do
+ expect { subject }.
+ to change { desired_shipment.stock_location.stock_level(variant).allocated_count }.by(7)
end
it 'creates a shipment with the correct number of on hand and backordered units' do
@@ -247,15 +264,19 @@ describe Spree::FulfilmentChanger do
before do
current_shipment.inventory_units.limit(backordered_units).update_all(state: :backordered)
- current_stock_level.set_count_on_hand(-backordered_units)
+ current_stock_level.update_column(:count_on_hand, -backordered_units)
+ end
+
+ it 'releases seven at the original stock location' do
+ expect { subject }.to change { current_stock_level.reload.allocated_count }.by(-7)
end
- it 'restocks four at the original stock location' do
- expect { subject }.to change { current_stock_level.reload.count_on_hand }.from(-backordered_units).to(1)
+ it 'allocates seven at the desired stock location' do
+ expect { subject }.to change { desired_stock_level.reload.allocated_count }.by(7)
end
- it 'unstocks five at the desired stock location' do
- expect { subject }.to change { desired_stock_level.reload.count_on_hand }.from(5).to(-2)
+ it 'leaves the original shelf where it was' do
+ expect { subject }.not_to change { current_stock_level.reload.count_on_hand }
end
it 'creates a shipment with the correct number of on hand and backordered units' do
diff --git a/spree/core/spec/models/spree/order_inventory_spec.rb b/spree/core/spec/models/spree/order_inventory_spec.rb
index 3743c9be9e..87e5ad1734 100644
--- a/spree/core/spec/models/spree/order_inventory_spec.rb
+++ b/spree/core/spec/models/spree/order_inventory_spec.rb
@@ -79,13 +79,16 @@ describe Spree::OrderInventory, type: :model do
end
end
- it 'creates stock_movement' do
+ # Editing a placed order changes what is promised, not what is on the
+ # shelf.
+ it 'allocates the added units to the fulfillment' do
expect(subject.send(:add_to_shipment, shipment, 5)).to eq(5)
stock_level = shipment.stock_location.stock_level(subject.variant)
movement = stock_level.stock_movements.last
- # movement.originator.should == shipment
- expect(movement.quantity).to eq(-5)
+
+ expect(movement).to have_attributes(kind: 'allocated', quantity: 5)
+ expect(movement.fulfillment).to eq(shipment)
end
end
@@ -231,10 +234,20 @@ describe Spree::OrderInventory, type: :model do
end
context 'backordered items are removed' do
- it 'doesn\'t create on_hand items from backordered items' do
+ # Nothing physical comes back, so the shelf is untouched and only the
+ # promise is withdrawn — the old backordered special case is gone with
+ # the negative on-hand it served.
+ it 'withdraws the promise without inventing stock' do
shipment.set_up_inventory('backordered', variant, order, line_item)
+ stock_level = shipment.stock_location.stock_level(variant)
+ shipment.stock_location.allocate(variant, 3, shipment)
+ allocated_before = stock_level.reload.allocated_count
+ removed = nil
+
+ expect { removed = subject.send(:remove_from_shipment, shipment, 3) }.
+ not_to change { line_item.variant.stock_levels.sum(:count_on_hand) }
- expect { subject.send(:remove_from_shipment, shipment, 3) }.to change { line_item.variant.stock_levels.sum(:count_on_hand) }.from(-2).to(0)
+ expect(stock_level.reload.allocated_count).to eq(allocated_before - removed)
end
end
end
diff --git a/spree/core/spec/workflows/spree/fulfillments/cancel_spec.rb b/spree/core/spec/workflows/spree/fulfillments/cancel_spec.rb
index 830d429e83..aadd03cd8e 100644
--- a/spree/core/spec/workflows/spree/fulfillments/cancel_spec.rb
+++ b/spree/core/spec/workflows/spree/fulfillments/cancel_spec.rb
@@ -15,13 +15,19 @@ module Spree
expect(fulfillment.reload).to be_canceled
end
- it 'puts the units back on the shelf' do
+ # The goods never left the shelf — placement only promised them — so
+ # cancelling withdraws the promise and the physical count stays put.
+ it 'withdraws the promise, on-hand and backordered units alike' do
variant = fulfillment.fulfillment_items.first.variant
+ quantity = fulfillment.fulfillment_items.where(variant_id: variant.id).sum(:quantity)
stock_level = fulfillment.stock_location.stock_level(variant)
+ fulfillment.stock_location.allocate(variant, quantity, fulfillment)
+ count_on_hand_before = stock_level.reload.count_on_hand
- expect { execute }.to change { stock_level.reload.count_on_hand }.by(
- fulfillment.fulfillment_items.where(variant_id: variant.id).sum(:quantity)
- )
+ expect { execute }.to change { stock_level.reload.allocated_count }.by(-quantity)
+
+ expect(stock_level.reload.count_on_hand).to eq(count_on_hand_before)
+ expect(stock_level.stock_movements.released.last.fulfillment).to eq(fulfillment)
end
# Fulfillment#provider builds a fresh Manual provider per call, so the
@@ -37,7 +43,7 @@ module Spree
# The whole reason this moved out of the transition callback: a slow or
# failing carrier must not hold the stock movements' row locks, and must
- # not roll back a restock that already happened.
+ # not roll back a release that already happened.
it 'notifies the provider only after the restock has committed' do
open_transactions = nil
allow(fulfillment).to receive(:provider).and_return(provider)
diff --git a/spree/core/spec/workflows/spree/fulfillments/create_spec.rb b/spree/core/spec/workflows/spree/fulfillments/create_spec.rb
index 4f9d3dde8f..8dcb7a21b5 100644
--- a/spree/core/spec/workflows/spree/fulfillments/create_spec.rb
+++ b/spree/core/spec/workflows/spree/fulfillments/create_spec.rb
@@ -84,17 +84,34 @@ module Spree
let(:other_stock_location) { create(:stock_location, name: 'External 3PL', backorderable_default: true) }
let(:params) { { order: order, stock_location: other_stock_location } }
- it 'restocks the source location and unstocks the target for tracked variants' do
+ # Moving units between fulfillments moves the promise, not the goods —
+ # the shelf is untouched on both sides until a parcel leaves.
+ it 'carries the allocation from the source location to the target' do
+ stock_location.allocate(variant, 1, source_shipment)
source_count = stock_location.count_on_hand(variant)
expect(execute.success?).to eq(true)
- expect(stock_location.reload.count_on_hand(variant)).to eq(source_count + 1)
- expect(other_stock_location.reload.count_on_hand(variant)).to eq(-1)
+ expect(stock_location.reload.stock_level(variant).allocated_count).to eq(0)
+ expect(other_stock_location.reload.stock_level(variant).allocated_count).to eq(1)
+ expect(stock_location.reload.count_on_hand(variant)).to eq(source_count)
end
- it 'does not touch stock when the location stays the same' do
+ # Allocation is keyed to the fulfillment, so a split has to carry it
+ # across even when the origin does not change — otherwise the quantity
+ # Fulfillments::Fulfill reads would sit on the wrong fulfillment.
+ it 'carries the allocation across a same-location split' do
+ stock_location.allocate(variant, 1, source_shipment)
params[:stock_location] = stock_location
+ params[:items] = [{ line_item: line_items.first, quantity: 1 }]
+
+ expect(execute.success?).to eq(true)
+ expect(fulfillment.allocated_quantity).to eq(1)
+ expect(source_shipment.reload.allocated_quantity).to eq(0)
+ end
+
+ it 'carries nothing when the source holds no promise' do
expect { execute }.not_to change { stock_location.reload.count_on_hand(variant) }
+ expect(other_stock_location.reload.stock_level(variant)&.allocated_count.to_i).to eq(0)
end
end
diff --git a/spree/core/spec/workflows/spree/fulfillments/fulfill_spec.rb b/spree/core/spec/workflows/spree/fulfillments/fulfill_spec.rb
index 5207838c26..4e243de903 100644
--- a/spree/core/spec/workflows/spree/fulfillments/fulfill_spec.rb
+++ b/spree/core/spec/workflows/spree/fulfillments/fulfill_spec.rb
@@ -147,13 +147,13 @@ module Spree
end
end
- # A canceled fulfillment already restocked its units, so shipping it
- # directly has to take them off the shelf again. This used to ride on the
- # resume transition callback.
+ # A canceled fulfillment gave its promise back, so shipping it directly
+ # has to re-promise the units before they can leave. This used to ride on
+ # the resume transition callback.
describe 'fulfilling a canceled fulfillment' do
before { fulfillment.update!(status: 'canceled') }
- it 'takes the units back off the shelf' do
+ it 're-promises the units and then ships them' do
variant = fulfillment.fulfillment_items.first.variant
stock_level = fulfillment.stock_location.stock_level(variant)
@@ -164,13 +164,18 @@ module Spree
expect(fulfillment.reload).to be_fulfilled
end
- it 'does not unstock when the fulfillment was open' do
+ # Resuming already re-promised the units, so fulfilling afterwards
+ # takes them off the shelf exactly once rather than twice.
+ it 'ships the re-promised units only once when the fulfillment was resumed' do
Spree.fulfillment_resume_workflow.call(fulfillment: fulfillment)
variant = fulfillment.fulfillment_items.first.variant
+ quantity = fulfillment.fulfillment_items.where(variant_id: variant.id).sum(:quantity)
stock_level = fulfillment.stock_location.stock_level(variant)
expect { subject.call(fulfillment: fulfillment) }.
- not_to change { stock_level.reload.count_on_hand }
+ to change { stock_level.reload.count_on_hand }.by(-quantity)
+
+ expect(stock_level.reload.allocated_count).to eq(0)
end
end
diff --git a/spree/core/spec/workflows/spree/fulfillments/resume_spec.rb b/spree/core/spec/workflows/spree/fulfillments/resume_spec.rb
index bef0f7a1de..748d2b8622 100644
--- a/spree/core/spec/workflows/spree/fulfillments/resume_spec.rb
+++ b/spree/core/spec/workflows/spree/fulfillments/resume_spec.rb
@@ -17,13 +17,17 @@ module Spree
expect(fulfillment.reload).not_to be_canceled
end
- it 'takes the units back off the shelf' do
+ # Reinstating a fulfillment re-promises its units; nothing physical moves
+ # until the parcel does.
+ it 're-promises the units without touching the shelf' do
variant = fulfillment.fulfillment_items.first.variant
+ quantity = fulfillment.fulfillment_items.where(variant_id: variant.id).sum(:quantity)
stock_level = fulfillment.stock_location.stock_level(variant)
+ count_on_hand_before = stock_level.reload.count_on_hand
- expect { execute }.to change { stock_level.reload.count_on_hand }.by(
- -fulfillment.fulfillment_items.where(variant_id: variant.id).sum(:quantity)
- )
+ expect { execute }.to change { stock_level.reload.allocated_count }.by(quantity)
+
+ expect(stock_level.reload.count_on_hand).to eq(count_on_hand_before)
end
it 'refuses a fulfillment that is not canceled' do