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.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
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.rbindex 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 Spreedef handle_stockActiveRecord::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_allocationmove_inventory_units_between_shipmentsendend+ # 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_shipmentsupdate_desired_shipment_inventory_unitsupdate_current_shipment_inventory_unitsdiff --git a/spree/core/app/workflows/spree/fulfillments/create.rb b/spree/core/app/workflows/spree/fulfillments/create.rbindex 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 Spreeend# 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 fromdef move_units(order, fulfillment, requested, units_by_line_item)@@ -239,12 +238,20 @@ module Spreeendend+ # 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)endsource_shipments.uniqdiff --git a/spree/core/app/workflows/spree/fulfillments/resume.rb b/spree/core/app/workflows/spree/fulfillments/resume.rbindex 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 Spreemodule 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::Workflowhooks :validate, :after_resume@@ -23,7 +23,7 @@ module Spreestep :ensure_resumableApplicationRecord.transaction do- step :unstock_units+ step :allocate_unitsstep :mark_resumedend@@ -39,15 +39,17 @@ module Spreefailure(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_unitsfulfillment.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)endenddiff --git a/spree/core/spec/models/spree/fulfilment_changer_spec.rb b/spree/core/spec/models/spree/fulfilment_changer_spec.rbindex 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 dobefore doorder && desired_shipmentvariant.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)endcontext 'when the order has multiple line items' do@@ -116,7 +119,10 @@ describe Spree::FulfilmentChanger dolet!(: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 doexpect(subject).to be trueend- 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) }endcontext 'when the order is not completed' do@@ -159,12 +172,14 @@ describe Spree::FulfilmentChanger dostock_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)endit 'creates a shipment with the correct number of on hand and backordered units' do@@ -176,12 +191,14 @@ describe Spree::FulfilmentChanger docontext 'when the desired stock location already has a backordered units' dolet(: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)endit 'creates a shipment with the correct number of on hand and backordered units' do@@ -247,15 +264,19 @@ describe Spree::FulfilmentChanger dobefore docurrent_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 }endit 'creates a shipment with the correct number of on hand and backordered units' dodiff --git a/spree/core/spec/models/spree/order_inventory_spec.rb b/spree/core/spec/models/spree/order_inventory_spec.rbindex 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 doendend- 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' doexpect(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)endend@@ -231,10 +234,20 @@ describe Spree::OrderInventory, type: :model doendcontext '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' doshipment.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)endendenddiff --git a/spree/core/spec/workflows/spree/fulfillments/cancel_spec.rb b/spree/core/spec/workflows/spree/fulfillments/cancel_spec.rbindex 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 Spreeexpect(fulfillment.reload).to be_canceledend- 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' dovariant = 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' doopen_transactions = nilallow(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.rbindex 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 Spreelet(: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' doexpect { 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)endenddiff --git a/spree/core/spec/workflows/spree/fulfillments/fulfill_spec.rb b/spree/core/spec/workflows/spree/fulfillments/fulfill_spec.rbindex 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 Spreeendend- # 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' dobefore { fulfillment.update!(status: 'canceled') }- it 'takes the units back off the shelf' do+ it 're-promises the units and then ships them' dovariant = fulfillment.fulfillment_items.first.variantstock_level = fulfillment.stock_location.stock_level(variant)@@ -164,13 +164,18 @@ module Spreeexpect(fulfillment.reload).to be_fulfilledend- 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' doSpree.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)endenddiff --git a/spree/core/spec/workflows/spree/fulfillments/resume_spec.rb b/spree/core/spec/workflows/spree/fulfillments/resume_spec.rbindex 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 Spreeexpect(fulfillment.reload).not_to be_canceledend- 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' dovariant = 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)endit 'refuses a fulfillment that is not canceled' do