spree_core 6.0.0.rc7 → 6.0.1

data/app/services/spree/stock_reservations/reserve.rb

@@ -14,13 +14,17 @@ module Spree
 
         ApplicationRecord.transaction do
           targets = build_targets(cart)
-          break if targets.empty?
 
           # Pessimistic lock + fresh read of count_on_hand. The lock serializes
           # concurrent checkouts and we use the locked rows below so we never
-          # check stock against a stale association cache.
+          # check stock against a stale association cache. The shelves held
+          # now are locked with the new ones, in id order, so two checkouts
+          # moving holds past each other cannot deadlock.
+          stock_level_ids = targets.map { |_, si, _| si.id } |
+                            Spree::StockReservation.for_order(cart).pluck(:stock_level_id)
           locked_stock_levels = Spree::StockLevel
-            .where(id: targets.map { |_, si| si.id })
+            .where(id: stock_level_ids)
+            .order(:id)
             .lock
             .index_by(&:id)
 
@@ -29,22 +33,13 @@ module Spree
 
           this_order_used = Hash.new(0)
 
-          targets.each do |line_item, stock_level|
+          reservations = targets.map do |line_item, stock_level, quantity|
             stock_level = locked_stock_levels.fetch(stock_level.id)
             available = stock_level.available_count - held.fetch(stock_level.id, 0) - this_order_used[stock_level.id]
 
-            if available < line_item.quantity
-              raise InsufficientStockError.new(
-                line_item,
-                I18n.t(
-                  'spree.insufficient_stock_for_reservation',
-                  item: line_item.variant.name,
-                  available: [available, 0].max
-                )
-              )
-            end
+            raise_insufficient_stock(line_item, available) if available < quantity
 
-            this_order_used[stock_level.id] += line_item.quantity
+            this_order_used[stock_level.id] += quantity
 
             reservation = existing[[stock_level.id, line_item.id]] ||
                           Spree::StockReservation.new(stock_level: stock_level, line_item: line_item)
@@ -55,10 +50,15 @@ module Spree
               reservation.order = cart
               reservation.cart = nil
             end
-            reservation.quantity = line_item.quantity
+            reservation.quantity = quantity
             reservation.expires_at = expires_at
             reservation.save!
+            reservation
           end
+
+          # Left in place, a hold the allocation moved away from blocks other buyers until it expires.
+          moved = Spree::StockReservation.for_order(cart).where.not(id: reservations.map(&:id))
+          Spree::StockReservation.withdraw(moved)
         end
 
         success(cart)
@@ -68,23 +68,71 @@ module Spree
 
       private
 
+      # Held where the allocation packs each unit, so the hold protects the stock the order will ship.
       def build_targets(cart)
-        cart.line_items.includes(variant: [:product, { stock_levels: :stock_location }]).filter_map do |line_item|
+        cart.line_items.reset
+        coordinator = Spree::Stock::Coordinator.new(cart)
+        packages = coordinator.allocated_packages
+        check_allocated_in_full(cart, packages_items(packages))
+
+        # Once the address is known, a unit only an origin unable to reach it
+        # would pack cannot ship, so it is left to the delivery check rather
+        # than held where it blocks buyers that origin does serve.
+        packages = packages.select { |package| coordinator.deliverable?(package) } if cart.ship_address.present?
+        items = packages_items(packages)
+        stock_levels = Spree::Stock::Packer.stock_levels_by_location(packages.map(&:stock_location).uniq,
+                                                                     cart.line_items.map(&:variant_id).uniq)
+
+        # Summed because a splitter can pack one line into several packages from one location.
+        quantities = Hash.new(0)
+        items.each do |stock_location, item|
+          next unless item.on_hand?
+
+          line_item = item.inventory_unit.line_item
           variant = line_item.variant
-          next unless variant&.should_track_inventory?
-
-          stock_level = select_stock_level(variant)
+          stock_level = stock_levels.dig(stock_location.id, variant.id)
           # Backorderable and pre-cart variants oversell past count_on_hand,
           # so a reservation capped at on-hand stock would wrongly reject them;
           # their cap is enforced by Stock::Quantifier#can_supply? instead.
+          next unless variant.should_track_inventory?
           next if stock_level.nil? || stock_level.backorderable? || variant.preorder?
 
-          [line_item, stock_level]
+          quantities[[line_item, stock_level]] += item.quantity
+        end
+
+        quantities.map { |(line_item, stock_level), quantity| [line_item, stock_level, quantity] }
+      end
+
+      def packages_items(packages)
+        packages.flat_map { |package| package.contents.map { |item| [package.stock_location, item] } }
+      end
+
+      # A line placed nowhere is left to the delivery check, which can say why;
+      # one placed in part has shelves that fall short, and is refused.
+      def check_allocated_in_full(cart, items)
+        allocated = items.each_with_object(Hash.new(0)) do |(_, item), quantities|
+          quantities[item.inventory_unit.line_item_id] += item.quantity
+        end
+
+        cart.line_items.each do |line_item|
+          variant = line_item.variant
+          next unless variant&.should_track_inventory?
+          next if variant.preorder?
+
+          placed = allocated[line_item.id]
+          raise_insufficient_stock(line_item, placed) if placed.positive? && placed < line_item.quantity
         end
       end
 
-      def select_stock_level(variant)
-        variant.stock_levels.detect { |si| si.stock_location&.active? && si.available? }
+      def raise_insufficient_stock(line_item, available)
+        raise InsufficientStockError.new(
+          line_item,
+          I18n.t(
+            'spree.insufficient_stock_for_reservation',
+            item: line_item.variant.name,
+            available: [available, 0].max
+          )
+        )
       end
 
       def held_by_others(stock_level_ids, owner)
@@ -104,8 +152,8 @@ module Spree
       def existing_reservations_for(targets)
         return {} if targets.empty?
 
-        stock_level_ids = targets.map { |_, si| si.id }
-        line_item_ids = targets.map { |li, _| li.id }
+        stock_level_ids = targets.map { |_, si, _| si.id }
+        line_item_ids = targets.map { |li, _, _| li.id }
 
         Spree::StockReservation
           .where(stock_level_id: stock_level_ids, line_item_id: line_item_ids)

data/app/workflows/spree/seller_transfers/reverse.rb

@@ -202,34 +202,15 @@ module Spree
               kind: 'refund_reversal',
               provider: @earning.provider,
               status: 'pending'
-            }.merge(settlement_of(bounded))
+            }.merge(@earning.reversal_settlement(bounded))
           )
         end
       end
 
-      # A clawback has to settle where its earning settled. Payouts are swept by
-      # settlement currency, so a reversal left in the sale's currency would
-      # never join the batch that pays the earning it cancels — the seller would
-      # be paid in full for goods that came back, and the row would sit in a
-      # currency their account cannot pay.
-      #
-      # Prorated from the earning's own settled figure rather than converted at
-      # today's rate, so the money comes back at the rate it went out at.
-      def settlement_of(bounded)
-        return {} if @earning.settled_amount.blank? || @earning.amount.zero?
-
-        share = @earning.settled_amount * (bounded / @earning.amount)
-
-        {
-          settled_amount: -Spree::Money::Rounding.quantize(
-            share, Spree::Money::Rounding.precision(@earning.settlement_currency)
-          ),
-          settled_currency: @earning.settled_currency
-        }
-      end
-
+      # Asked of the provider that made the earning — see
+      # {Spree::SellerTransfer#payout_provider_instance}.
       def execute_reversal
-        provider.reverse!(reversal)
+        @earning.payout_provider_instance.reverse!(reversal)
       rescue Spree::Core::AmbiguousGatewayError => e
         # Whether the clawback happened is the provider's to say. Recorded as
         # such rather than as a refusal, so an operator reconciling knows which
@@ -238,31 +219,11 @@ module Spree
         Rails.error.report(e, handled: true, context: { seller_transfer_id: reversal.id }, source: 'spree.core')
         failure(reversal, e.message)
       rescue StandardError => e
+        # Left retryable: `ExecutePendingJob` asks the provider again.
         reversal.update!(status: 'processing')
         Rails.error.report(e, handled: true, context: { seller_transfer_id: reversal.id }, source: 'spree.core')
         failure(reversal, e.message)
       end
-
-      # The provider that made the earning, not whichever one the store uses
-      # now. A marketplace that changes provider still has money sitting with
-      # the old one, and asking the new one to reverse a transfer it never
-      # made leaves the original standing — the seller keeps a refunded sale.
-      def provider
-        @provider ||= begin
-          configured = Spree.payout_providers.find { |candidate| candidate.to_s == @earning.provider }
-
-          # No silent fallback to whatever the store uses now. A provider that
-          # is no longer installed still holds the transfer this reverses, and
-          # handing the job to a different one would mark the row reversed
-          # while the money stayed where it was. An operator has to know.
-          if configured.nil?
-            raise Spree::Core::GatewayError,
-                  "Payout provider #{@earning.provider} is not registered, so its transfer cannot be reversed"
-          end
-
-          configured.new
-        end
-      end
     end
   end
 end

data/config/locales/en.yml

@@ -1032,6 +1032,7 @@ en:
     locale_not_supported_by_market: is not offered by the chosen market
     locale_not_supported_by_store: is not supported by this store
     locales_not_listed: 'includes locales Spree does not support: %{codes}'
+    maintenance_tasks_turned_off: Maintenance tasks are turned off for this installation. Run upgrade steps from the command line with `spree upgrade` (or `bin/rake spree:upgrade`).
     manual: Manual
     market: Market
     me_no_current_user: No admin user authenticated this request

data/db/migrate/20260813130001_add_capture_method_to_payment_methods.rb

@@ -10,7 +10,7 @@ class AddCaptureMethodToPaymentMethods < ActiveRecord::Migration[8.1]
   # from the provider configuration form.
   #
   # Existing auto_capture values are carried over by
-  # spree:migrate_capture_methods, never here.
+  # the capture_methods maintenance task, never here.
   def change
     add_column :spree_payment_methods, :capture_method, :string
   end

data/db/migrate/20260815000001_create_spree_maintenance_task_runs.rb

@@ -0,0 +1,40 @@
+class CreateSpreeMaintenanceTaskRuns < ActiveRecord::Migration[8.1]
+  def change
+    create_table :spree_maintenance_task_runs do |t|
+      t.string :task_name, null: false
+      t.string :status, null: false
+      t.boolean :dry_run, null: false, default: false
+
+      t.string :cursor
+      t.integer :tick_count, null: false, default: 0
+      t.integer :tick_total
+
+      t.decimal :time_running, null: false, default: 0.0, precision: 12, scale: 3
+      t.datetime :started_at
+      t.datetime :ended_at
+
+      t.string :error_class
+      t.text :error_message
+      t.text :error_backtrace
+
+      t.string :job_id
+      t.string :initiated_via, null: false
+
+      t.references :admin_user, null: true
+      t.references :api_key, null: true
+
+      if t.respond_to?(:jsonb)
+        t.jsonb :arguments
+        t.jsonb :tallies
+      else
+        t.json :arguments
+        t.json :tallies
+      end
+
+      t.timestamps
+    end
+
+    add_index :spree_maintenance_task_runs, [:task_name, :status]
+    add_index :spree_maintenance_task_runs, :created_at
+  end
+end

data/db/migrate/20260816000001_create_spree_upgrade_records.rb

@@ -0,0 +1,17 @@
+class CreateSpreeUpgradeRecords < ActiveRecord::Migration[8.1]
+  def change
+    create_table :spree_upgrade_records do |t|
+      # The release boundary this installation has completed the data steps
+      # for — "5.6" means every manifest up to and including 5.5 → 5.6 is done.
+      t.string :version, null: false
+      # How we know: `walk` (a successful upgrade walk), `install` (a fresh
+      # install, which needs no historical steps) or `manual`.
+      t.string :source, null: false
+      t.datetime :completed_at, null: false
+
+      t.timestamps
+    end
+
+    add_index :spree_upgrade_records, :version, unique: true
+  end
+end

data/db/migrate/20261029100001_add_lockout_columns_to_spree_admin_users.rb

@@ -0,0 +1,8 @@
+# Spree::AccountLockout reads these columns. Installs upgraded from a Devise
+# admin model without :lockable reach 6.0 with neither of them.
+class AddLockoutColumnsToSpreeAdminUsers < ActiveRecord::Migration[8.1]
+  def change
+    add_column :spree_admin_users, :failed_attempts, :integer unless column_exists?(:spree_admin_users, :failed_attempts)
+    add_column :spree_admin_users, :locked_at, :datetime unless column_exists?(:spree_admin_users, :locked_at)
+  end
+end

data/lib/generators/spree/api_resource/api_resource_generator.rb

@@ -108,7 +108,7 @@ module Spree
 
     # Override parent: skip if the model existed before this run. Migrations
     # are append-only — schema changes get a separate migration:
-    #   pnpm exec spree rails g migration AddFooToBar foo:string
+    #   pnpm exec spree generate migration AddFooToBar foo:string
     def create_migration_file
       if @model_existed_before_run
         say_status :skip, 'migration (model already exists; add a new migration for schema changes)', :yellow
@@ -295,7 +295,7 @@ module Spree
       end
       say "    4. Add `has_many :#{plural_name}` to Spree::Store" if store_scoped?
       if options[:store] || options[:admin]
-        say "    #{store_scoped? ? 5 : 4}. Run the specs:  pnpm exec spree rspec spec/controllers/spree/api/v3/"
+        say "    #{store_scoped? ? 5 : 4}. Run the specs:  pnpm exec spree test spec/controllers/spree/api/v3/"
       end
       say ''
     end

data/lib/spree/checkout/default_requirements.rb

@@ -10,6 +10,12 @@ module Spree
     #
     # @see Requirements
     class DefaultRequirements
+      # Everything the discontinuation and stock checks read, so a set of
+      # lines is checked at once.
+      STOCK_CHECK_ASSOCIATIONS = {
+        variant: [{ product: %i[store product_publications] }, { stock_levels: %i[stock_location active_stock_reservations] }]
+      }.freeze
+
       # @param cart [Spree::Cart]
       def initialize(cart)
         @cart = cart
@@ -33,6 +39,7 @@ module Spree
           r << req('address', 'email', I18n.t('spree.checkout_requirements.email_required')) unless @cart.email.present?
           r << req('address', 'ship_address', I18n.t('spree.checkout_requirements.ship_address_required')) if @cart.shipping_address_required? && @cart.ship_address.blank?
           r << req('delivery', 'delivery_method', I18n.t('spree.checkout_requirements.delivery_method_required')) if delivery_step_required? && !delivery_method_selected?
+          r.concat(undeliverable_errors)
           r << req('payment', 'payment', I18n.t('spree.checkout_requirements.payment_required')) if payment_required? && !payment_satisfied?
           r << req('address', 'po_number', I18n.t('spree.checkout_requirements.po_number_required')) if po_number_missing?
           r << order_minimum_requirement if below_order_minimum?
@@ -102,16 +109,37 @@ module Spree
         end
       end
 
+      # A rebuild drops a proposal no method can quote with only a transient
+      # warning, so part of a line can be in no fulfillment. Advisory, so the
+      # buyer reads it while they can still change the address or the cart.
+      def undeliverable_errors
+        return [] unless delivery_step_required? && @cart.fulfillments.any?
+
+        undelivered_line_items.map do |line_item|
+          req('delivery', 'line_items', I18n.t('spree.cart_line_item.delivery_unavailable', li_name: line_item.name),
+              code: 'delivery_unavailable')
+        end
+      end
+
+      # A line short of stock is packed short too; the stock check already
+      # names it. Only lines short of a fulfillment pay for that check, so a
+      # cart read stays at one query.
+      def undelivered_line_items
+        allocated = Spree::FulfillmentItem.where(fulfillment_id: @cart.fulfillments.select(:id))
+                                          .group(:line_item_id).sum(:quantity)
+        short = @cart.line_items.select { |line_item| allocated.fetch(line_item.id, 0) < line_item.quantity }
+        return [] if short.empty?
+
+        ActiveRecord::Associations::Preloader.new(records: short, associations: STOCK_CHECK_ASSOCIATIONS).call
+        short.reject { |line_item| discontinued?(line_item) || !line_item.sufficient_stock? }
+      end
+
       def discontinued?(line_item)
         line_item.variant.nil? || line_item.variant.discontinued? || line_item.variant.product.discontinued?
       end
 
       def completion_line_items
-        # Everything the discontinuation and stock checks read, for every line
-        # at once.
-        @completion_line_items ||= @cart.line_items.includes(
-          variant: [{ product: %i[store product_publications] }, { stock_levels: %i[stock_location active_stock_reservations] }]
-        ).to_a
+        @completion_line_items ||= @cart.line_items.includes(STOCK_CHECK_ASSOCIATIONS).to_a
       end
 
       def delivery_step_required?

data/lib/spree/core/configuration.rb

@@ -195,6 +195,12 @@ module Spree
       # imports
       preference :large_import_threshold, :integer, default: 500, env: 'SPREE_LARGE_IMPORT_THRESHOLD' # imports with more rows than this skip per-row UI broadcasts and use bulk processing
 
+      # maintenance tasks
+      # Turn off to run upgrade steps only from the command line: the dashboard
+      # page and its Admin API endpoints are refused. For hosts where the people
+      # holding a store's admin role are not the ones operating the installation,
+      # such as a platform serving many merchants from one database.
+      preference :maintenance_tasks_dashboard_enabled, :boolean, default: true, env: 'SPREE_MAINTENANCE_TASKS_DASHBOARD_ENABLED'
     end
   end
 end

data/lib/spree/core/engine.rb

@@ -46,6 +46,7 @@ module Spree
                                :admin_agent_tools,
                                :store_agent_tools,
                                :integrations,
+                               :maintenance_tasks,
                                :number_generators,
                                :subscribers,
                                :store_authentication_strategies,
@@ -77,7 +78,8 @@ module Spree
         # Core's defaults are concatenated in after_initialize below.
         %i[subscribers actor_classes commission_rules delivery_method_rules seller_requirements
            delivery_rate_providers tax_providers pricing_providers inventory_providers
-           payout_providers digital_asset_providers delivery_profile_types pickup_point_providers].each do |registry|
+           payout_providers digital_asset_providers delivery_profile_types pickup_point_providers
+           maintenance_tasks].each do |registry|
           app.config.spree[registry] = []
         end
         app.config.spree.line_item_comparison_hooks = Set.new
@@ -540,6 +542,13 @@ module Spree
 
         Rails.application.config.spree.integrations = []
 
+        # Upgrade steps backed by a task class are registered from the manifests
+        # that name them, so adding a step never means editing a second list.
+        Rails.application.config.spree.maintenance_tasks.concat [
+          'Spree::MaintenanceTasks::UpgradeStep',
+          *Spree::Upgrade.steps.filter_map { |step| step['task_class'] }
+        ]
+
         Rails.application.config.spree.validators.addresses = [
           Spree::Addresses::PhoneValidator
         ]

data/lib/spree/core/permissions/default_catalog.rb

@@ -201,6 +201,13 @@ module Spree
         })
         catalog.register_scope(:integrations, group: :settings, resources: -> { [Spree::Integration] })
 
+        # Sits with the other sensitive access grants rather than under
+        # settings: a task can rewrite any data in the install, so out of the
+        # box only the admin role holds it (docs/plans/6.0-maintenance-tasks.md).
+        catalog.register_scope(:maintenance_tasks, group: :access, resources: -> {
+          [Spree::MaintenanceTaskRun, :maintenance_task]
+        })
+
         # The CORS allowlist is a credential as much as a key is: an origin on
         # it may call the cookie-authenticated refresh endpoint from a browser
         # and read back any signed-in admin's access token. So it sits with

data/lib/spree/core/version.rb

@@ -1,5 +1,5 @@
 module Spree
-  VERSION = '6.0.0.rc7'.freeze
+  VERSION = '6.0.1'.freeze
 
   def self.version
     VERSION

data/lib/spree/core.rb

@@ -135,7 +135,8 @@ module Spree
       stock_reservations: :default,
       tax_identifiers: :default,
       data_requests: :default,
-      payouts: :default
+      payouts: :default,
+      maintenance_tasks: :default
     ).tap do |queues|
       # @deprecated The taxons queue was renamed to categories in 6.0; removed in 6.1.
       queues.define_singleton_method(:taxons) do
@@ -455,6 +456,19 @@ module Spree
     custom_fields
   end
 
+  # Registered maintenance task class names — the tasks an operator can run
+  # from the dashboard, the Admin API or the CLI
+  # (docs/plans/6.0-maintenance-tasks.md). Extensions append their own from an
+  # initializer:
+  #
+  #   Spree.maintenance_tasks << 'SpreeReviews::MaintenanceTasks::RecountRatings'
+  #
+  # Class names rather than classes, so registration is safe at initializer
+  # time and survives code reloading in development.
+  #
+  # @return [Array<String, Class>]
+  singleton_class.delegate :maintenance_tasks, :maintenance_tasks=, to: :spree_config
+
   # Registry mapping a numbered resource to the generator that produces its
   # document numbers. With no entry, the store's `document_number_format`
   # preference picks between the sequential and random strategies.
@@ -644,6 +658,7 @@ require 'spree/core/version'
 require 'spree/core/number_generator'
 require 'spree/number_generators/registry'
 require 'spree/migrations'
+require 'spree/upgrade'
 require 'spree/validators'
 require 'spree/core/engine'
 
@@ -651,6 +666,7 @@ require 'spree/i18n'
 require 'spree/iso_data'
 require 'spree/localized_number'
 require 'spree/measurement'
+require 'spree/time_zones'
 require 'spree/translations'
 require 'spree/money'
 require 'spree/service_module'

data/lib/spree/testing_support/factories/maintenance_task_run_factory.rb

@@ -0,0 +1,7 @@
+FactoryBot.define do
+  factory :maintenance_task_run, class: 'Spree::MaintenanceTaskRun' do
+    task_name { 'Spree::MaintenanceTasks::BackfillOrderMarkets' }
+    status { 'enqueued' }
+    initiated_via { 'api' }
+  end
+end

data/lib/spree/time_zones.rb

@@ -0,0 +1,34 @@
+module Spree
+  # Time zones are stored and exchanged as IANA identifiers (`Europe/Berlin`),
+  # the names browsers and every non-Ruby client understand. Rails' display
+  # names ("Eastern Time (US & Canada)") are converted to them on the way in.
+  module TimeZones
+    # The zones clients are offered: the IANA zones Rails gives a display name
+    # to, with plain `UTC` standing in for `Etc/UTC`. Any other valid IANA
+    # identifier is accepted too. The list comes with the Rails version rather
+    # than the machine's time zone database, so generated types match wherever
+    # the same Rails version runs.
+    SUGGESTED = (ActiveSupport::TimeZone::MAPPING.values - ['Etc/UTC'] + ['UTC']).uniq.sort.freeze
+
+    # @param identifier [String, nil]
+    # @return [Boolean] whether the value is an IANA time zone identifier
+    def self.valid?(identifier)
+      return false if identifier.blank?
+
+      TZInfo::Timezone.get(identifier.to_s)
+      true
+    rescue TZInfo::InvalidTimezoneIdentifier
+      false
+    end
+
+    # @param value [String, nil] an IANA identifier or a Rails time zone name
+    # @return [String, nil] the IANA identifier, or the value unchanged when it
+    #   names no zone the installed time zone database knows
+    def self.normalize(value)
+      return value if value.blank? || valid?(value)
+
+      identifier = ActiveSupport::TimeZone::MAPPING[value.to_s]
+      valid?(identifier) ? identifier : value
+    end
+  end
+end