spree_cm_commissioner 2.15.1 → 2.15.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7cd929df06e0243dc4cf2b0b4ffc57d3346ced9f9d0cb5bdd3142d6adc153a88
-  data.tar.gz: 29a71dceac61e9e6497137c525ff9e76ace8ca1a179f0dc6eab157fd83a30a4d
+  metadata.gz: 32502c54cc175c2fc2c4d6c86d97385fe1c02192ddfa240e6ac28b043fc923c3
+  data.tar.gz: be2a8f37d0f078acd74e6e16155928065a2915b868525c01ae01232dcc8d9e39
 SHA512:
-  metadata.gz: 2bd7890db6844d7057a5e89f8e2cd0285e387772aaccba0ba2806aee4b7f78de3cea566402fb5a97279613bae6be342bbef2b55e2d185c82d8d85fec59401520
-  data.tar.gz: 682f9b46dae492ff3f0bdb9f558dccc3185ec4b9a6a0770e4fca4146ecd496e90577b97c049a9a171f7ab6ac76486fc14d4cdefe6bf7098ec96de9b8c09c170b
+  metadata.gz: eddc350347e96f820443be5e8e9524cab22623c8c1f1cd16241a86d5d1e851e206e264328d1c9734b427243682f8bffcdacb1215fb0647b472071d2c5484429b
+  data.tar.gz: 767d8e127f3cd3ddb498e0fe3237571acb753b6481480531d4094500b4d58e5f60d360184475f951c75217d6c2eb91b2b1e3862fd83b2ba140dcc35de81e880e

data/.env.example

@@ -94,3 +94,6 @@ PRE_INVENTORY_DAYS_TRANSIT=180  # How many days ahead inventory items are pre-ge
 PRE_INVENTORY_DAYS_ACCOMMODATION=365  # How many days ahead inventory items are pre-generated for accommodation variants
 PRE_INVENTORY_DAYS_SERVICE=180  # How many days ahead inventory items are pre-generated for service variants
 PAYMENT_BASE_URL=http://localhost:4000
+
+# See: app/services/spree_cm_commissioner/integrations/call_limiter.rb
+BOOKMEBUS_MAX_CALLS_PER_MINUTE=60  # Most calls a minute BookMe+ sends to BookMeBus, shared by all vendors (checkout is never limited); lower it to protect their server, raise it only after agreeing a limit with them

data/Gemfile.lock

@@ -34,7 +34,7 @@ GIT
 PATH
   remote: .
   specs:
-    spree_cm_commissioner (2.15.1)
+    spree_cm_commissioner (2.15.3)
       activerecord-multi-tenant
       activerecord_json_validator (~> 2.1, >= 2.1.3)
       aws-sdk-cloudfront
@@ -886,7 +886,7 @@ GEM
       spree_backend (>= 4.3.0.rc1)
       spree_emails (>= 4.3.0.rc1)
       spree_extension
-    spree_vpago (2.4.6)
+    spree_vpago (2.4.7)
       faraday
       google-cloud-firestore
       spree_api (>= 4.5)

data/app/controllers/spree/admin/inventory_holds_controller.rb

@@ -4,12 +4,7 @@ module Spree
       def index
         authorize! :manage, SpreeCmCommissioner::InventoryHold
 
-        q = params.fetch(:q, {})
-        q = q.respond_to?(:to_unsafe_h) ? q.to_unsafe_h.deep_dup : q.deep_dup
-        q['s'] ||= 'created_at desc'
-        q['created_at_gt'] = parse_time_or_nil(q['created_at_gt'], :beginning_of_day) if q['created_at_gt'].present?
-        q['created_at_lt'] = parse_time_or_nil(q['created_at_lt'], :end_of_day) if q['created_at_lt'].present?
-        normalize_enum_filters!(q)
+        q = search_query
 
         @search = scope.ransack(q)
         result_scope = @search.result(distinct: true)
@@ -26,6 +21,27 @@ module Spree
                               .reorder(nil).group(:status).count
       end
 
+      # Same filters as the table; without a start date it covers the last 24h so the GROUP BYs stay cheap.
+      def overview
+        authorize! :manage, SpreeCmCommissioner::InventoryHold
+
+        q = search_query
+        @overview_from = q['created_at_gt'].presence || 24.hours.ago
+        q['created_at_gt'] = @overview_from
+        @overview = SpreeCmCommissioner::InventoryHoldOverviewQuery.new(holds: scope.ransack(q).result).call
+
+        render partial: 'overview', layout: false
+      end
+
+      def insights
+        authorize! :manage, SpreeCmCommissioner::InventoryHold
+
+        hold = scope.includes(:user, order: :user).find(params[:id])
+        @insights = SpreeCmCommissioner::InventoryHoldInsightsQuery.new(hold: hold).call
+
+        render partial: 'insights', layout: false
+      end
+
       def release
         authorize! :manage, SpreeCmCommissioner::InventoryHold
 
@@ -49,6 +65,16 @@ module Spree
 
       private
 
+      def search_query
+        q = params.fetch(:q, {})
+        q = q.respond_to?(:to_unsafe_h) ? q.to_unsafe_h.deep_dup : q.deep_dup
+        q['s'] ||= 'created_at desc'
+        q['created_at_gt'] = parse_time_or_nil(q['created_at_gt'], :beginning_of_day) if q['created_at_gt'].present?
+        q['created_at_lt'] = parse_time_or_nil(q['created_at_lt'], :end_of_day) if q['created_at_lt'].present?
+        normalize_enum_filters!(q)
+        q
+      end
+
       # `status` and `release_reason` are integer-backed enums. Ransack casts a string
       # value for an integer column with String#to_i, so "payment_locked" becomes 0
       # (== :pending) and every label silently filters to the wrong status. Translate

data/app/errors/spree_cm_commissioner/integrations/rate_limited_error.rb

@@ -0,0 +1,28 @@
+module SpreeCmCommissioner::Integrations
+  # The partner answered 429 (or CallLimiter refused the call). Sync code stops at the first one instead of
+  # retrying. An ExternalClientError, so checkout handles it like any other failed call.
+  class RateLimitedError < ExternalClientError
+    DEFAULT_RETRY_AFTER = 60.seconds
+    MAX_RETRY_AFTER = 2.hours
+
+    attr_reader :retry_after
+
+    # @param retry_after [Integer, nil] seconds to wait (the Retry-After header)
+    def initialize(message, retry_after: nil)
+      super(message, 429)
+      @retry_after = (retry_after || DEFAULT_RETRY_AFTER).to_i.clamp(DEFAULT_RETRY_AFTER.to_i, MAX_RETRY_AFTER.to_i)
+    end
+
+    # Retry-After is a number of seconds or an HTTP date; anything else is nil.
+    def self.parse_retry_after(header)
+      value = header.to_s.strip
+      return nil if value.empty?
+      return value.to_i if value.match?(/\A\d+\z/)
+
+      seconds = (Time.httpdate(value) - Time.current).ceil
+      seconds.positive? ? seconds : nil
+    rescue ArgumentError
+      nil
+    end
+  end
+end

data/app/jobs/spree_cm_commissioner/integrations/book_me_bus_v1/sync_route_job.rb

@@ -0,0 +1,70 @@
+# Syncs the trips of one route for the next `sync_days` days. The daily full sync queues one per route, so a failing
+# route only fails itself, a deploy redoes one route (seconds, not minutes), and a rerun skips routes done today.
+class SpreeCmCommissioner::Integrations::BookMeBusV1::SyncRouteJob < SpreeCmCommissioner::ApplicationUniqueJob
+  queue_as :integration
+
+  MAX_ATTEMPTS = 3
+  RETRY_DELAY = 15.minutes
+  MIN_PAUSE = 1.minute # the call limit refills every minute
+
+  # @param options [Hash] :integration_id, :route_id, :attempt (1 for the first run, set by the retries)
+  def perform(options)
+    integration = SpreeCmCommissioner::Integration.find_by(id: options[:integration_id])
+    route = SpreeCmCommissioner::Route.find_by(id: options[:route_id])
+    return unless integration&.active? && route
+
+    # While BookMeBus is paused after a 429, don't call it: retry after the pause.
+    limiter = SpreeCmCommissioner::Integrations::CallLimiter.new(base_url: integration.base_url)
+    return retry_after_pause(options, limiter.paused_for) if limiter.paused?
+
+    sync_result = SpreeCmCommissioner::Integrations::Base::SyncResult.new
+    sync(integration, route, sync_result)
+
+    # Told to wait (our call limit or a 429): nothing wrong with the route, so no outcome is recorded.
+    return retry_after_pause(options, sync_result.to_h.dig(:error, :retry_after)) if sync_result.rate_limited?
+
+    record_outcome(integration, route, sync_result)
+    retry_later(options) unless sync_result.success?
+  end
+
+  private
+
+  def sync(integration, route, sync_result)
+    SpreeCmCommissioner::Integrations::BookMeBusV1::Polling::SyncTrips.new(
+      integration: integration, sync_result: sync_result, route: route
+    ).call(on_dates: integration.sync_dates)
+  rescue StandardError => e
+    sync_result.record_error(e)
+  end
+
+  # Kept on the route's mapping: `full_synced_on` (the next full sync skips it) or `last_error`.
+  def record_outcome(integration, route, sync_result)
+    mapping = SpreeCmCommissioner::IntegrationMapping.active_routes_of(integration).find_by(internal_id: route.id)
+    return unless mapping
+
+    outcome = sync_result.success? ? { 'full_synced_on' => Date.current.iso8601 } : { 'last_error' => sync_result.to_h.dig(:error, :message) }
+
+    # The incremental sync stamps the same column: the lock (which reloads first) keeps either from erasing the other's key.
+    mapping.with_lock do
+      mapping.update!(private_metadata: (mapping.private_metadata || {}).except('last_error', 'full_synced_on').merge(outcome))
+    end
+  end
+
+  # A real failure: tries again a few times today (15 min, then 30), then leaves it to the next full sync.
+  def retry_later(options)
+    attempt = (options[:attempt] || 1).to_i
+    return if attempt >= MAX_ATTEMPTS
+
+    self.class.set(wait: RETRY_DELAY * attempt).perform_later(options.merge(attempt: attempt + 1))
+  end
+
+  # Waits out the pause (at least a minute) and tries again as the same attempt: a large vendor queues all its routes
+  # at once, and the ones the call limit turns away must not use up their attempts just by waiting in line.
+  #
+  # `waits` changes the arguments on purpose: ApplicationUniqueJob drops a job whose arguments match one that is still
+  # running (`unique :until_executed`), and this job is still running while it queues its own retry. Without it the
+  # retry is dropped silently and the route is never synced.
+  def retry_after_pause(options, wait)
+    self.class.set(wait: [wait.to_i.seconds, MIN_PAUSE].max).perform_later(options.merge(waits: options[:waits].to_i + 1))
+  end
+end

data/app/jobs/spree_cm_commissioner/seats/auto_assign_job.rb

@@ -0,0 +1,16 @@
+module SpreeCmCommissioner
+  module Seats
+    class AutoAssignJob < ApplicationJob
+      def perform(options = {})
+        order = Spree::Order.find(options[:order_id])
+        SpreeCmCommissioner::Seats::AutoAssign.call(order: order)
+
+        # Lets the vpago processing page move past "assigning your seats" (Order#pending_completion_steps),
+        # once the assignment has committed. Every outcome counts as done: the party's tickets are valid
+        # either way, and a split or unseated party shows on the line item. A failed write raises, so the
+        # retry re-sends it; re-seating is a no-op.
+        order.user_informer.notify_step(:seats_assigning, status: :done)
+      end
+    end
+  end
+end

data/app/models/concerns/spree_cm_commissioner/line_item_seat_selection.rb

@@ -4,6 +4,15 @@ module SpreeCmCommissioner
 
     included do
       before_create :set_required_seat_selection_flag
+
+      # Where an auto-assign party is in seat assignment; nil for every other line item.
+      #
+      #   pending  — paid, waiting for Seats::AutoAssignJob (set by OrderSeatAutoAssignable)
+      #   together / split / unseated — the job's outcome (Seats::AutoAssign)
+      #
+      # A column so parties can be queried by it (e.g. split ones for the organizer). The app reads it
+      # only for a guest without a seat_number yet: after a resume, one party can hold both.
+      enum seat_assignment_status: { pending: 0, together: 1, split: 2, unseated: 3 }, _prefix: :seat_assignment
     end
 
     # Caches the required_seat_selection flag from the trip in private_metadata.
@@ -24,16 +33,29 @@ module SpreeCmCommissioner
       ActiveModel::Type::Boolean.new.cast(private_metadata['required_seat_selection'])
     end
 
+    # Cached at creation alongside required_seat_selection, and mutually exclusive with it: the
+    # customer either picks seats or Seats::AutoAssignJob assigns them once the order completes.
+    # Flipping the product flag mid-sale therefore never changes how an existing order completes.
+    def auto_assign_seats?
+      ActiveModel::Type::Boolean.new.cast(private_metadata['auto_assign_seats']) == true
+    end
+
     private
 
     def set_required_seat_selection_flag
       return if private_metadata.key?('required_seat_selection')
       return if product.nil?
 
-      private_metadata['required_seat_selection'] = if product.trip.present?
-                                                      product.trip.allow_seat_selection && variant.blocks.any?
+      has_blocks = variant.blocks.any?
+      auto_assign = product.auto_assign_seats? && has_blocks
+
+      private_metadata['auto_assign_seats'] = auto_assign
+      private_metadata['required_seat_selection'] = if auto_assign
+                                                      false
+                                                    elsif product.trip.present?
+                                                      product.trip.allow_seat_selection && has_blocks
                                                     else
-                                                      variant.blocks.any?
+                                                      has_blocks
                                                     end
     end
   end

data/app/models/concerns/spree_cm_commissioner/order_seat_auto_assignable.rb

@@ -0,0 +1,73 @@
+module SpreeCmCommissioner
+  # Order side of seat auto-assign: hands paid orders to Seats::AutoAssignJob and, on resume, sends
+  # guests whose seat was resold meanwhile back to it.
+  #
+  # Include before OrderStateMachine: its before_transition to :resumed must run ahead of that
+  # concern's around_transition unstock_inventory!, whose reserve_order_holds! re-reserves the seats
+  # kept here (state_machines runs before and around callbacks in definition order).
+  module OrderSeatAutoAssignable
+    extend ActiveSupport::Concern
+
+    included do
+      state_machine.before_transition to: :resumed, do: :unseat_guests_with_resold_seats!, if: :auto_assign_seats?
+
+      # Seats are assigned in the background: payment and stock are final by now, and choosing seats
+      # inside completion would hold its locks while buyers compete for them. Runs inside the
+      # transition's transaction on purpose: `pending` rolls back with a failed completion, and
+      # Seats::AutoAssign row-locks this order before seating anyone, so the job waits for the
+      # transition to commit, and skips it on rollback.
+      state_machine.after_transition to: %i[complete resumed], do: :queue_seat_auto_assign, if: :auto_assign_seats?
+    end
+
+    def auto_assign_seats?
+      line_items.any?(&:auto_assign_seats?)
+    end
+
+    # Keeps the vpago processing page on "assigning your seats" until Seats::AutoAssignJob finishes;
+    # appended to Order#pending_completion_steps by OrderDecorator.
+    def seat_assignment_pending?
+      line_items.seat_assignment_pending.exists?
+    end
+
+    private
+
+    # Only parties with someone left to seat: on resume, a party whose seats were all kept keeps its
+    # outcome, since the job would find nobody to seat and never move it off `pending`.
+    def queue_seat_auto_assign
+      waiting = line_items.select(&:auto_assign_seats?).select { |line_item| line_item.guests.exists?(block_id: nil) }
+      return if waiting.empty?
+
+      Spree::LineItem.where(id: waiting.map(&:id)).update_all(seat_assignment_status: :pending) # rubocop:disable Rails/SkipsModelValidations
+      SpreeCmCommissioner::Seats::AutoAssignJob.perform_later(order_id: id)
+    end
+
+    # Cancelling released the seat rows but left guest.block_id pointing at them, and they may have
+    # been resold since. A guest whose seat was resold is unseated here, which queue_seat_auto_assign
+    # then hands to Seats::AutoAssignJob; the rest keep their seat, which
+    # reserve_order_holds! re-reserves in this same transition.
+    def unseat_guests_with_resold_seats!
+      line_items.select(&:auto_assign_seats?).each do |line_item|
+        inventory_item = line_item.inventory_items.first
+        next if inventory_item.nil?
+
+        line_item.guests.where.not(block_id: nil).find_each do |guest|
+          guest.update!(block_id: nil) if resold?(guest, inventory_item)
+        end
+      end
+
+      # Guest#preload_order_block_ids refreshed another instance of this order; the transition's
+      # save of this one would write the stale list back.
+      self.preload_block_ids = blocks.pluck(:id)
+    end
+
+    # Row-locked until the transition commits, so Seats::AutoAssign cannot give a kept seat to
+    # another order before reserve_order_holds! re-reserves it. A locked row has no guest, so an
+    # operator lock counts as resold too.
+    def resold?(guest, inventory_item)
+      row = SpreeCmCommissioner::ReservedBlock.lock.find_by(inventory_item_id: inventory_item.id, block_id: guest.block_id)
+      return false if row.nil?
+
+      (row.reserved? || row.locked? || row.active_on_hold?) && row.guest_id != guest.id
+    end
+  end
+end

data/app/models/concerns/spree_cm_commissioner/product_seat_auto_assignable.rb

@@ -0,0 +1,29 @@
+module SpreeCmCommissioner
+  # Seats are picked by the server once the order completes, instead of by the customer. Turning it
+  # on is guarded by Seats::AutoAssignValidator so the product can never sell more units than there
+  # are linked seats to hand out.
+  #
+  # Needs StoreMetadata included first.
+  module ProductSeatAutoAssignable
+    extend ActiveSupport::Concern
+
+    included do
+      store_public_metadata :auto_assign_seats, :boolean, default: false
+
+      validates_with SpreeCmCommissioner::Seats::AutoAssignValidator, if: :enabling_auto_assign_seats?
+    end
+
+    private
+
+    # Only on the off → on flip: re-checking on every later save would block unrelated edits mid-sale
+    # whenever stock and seats briefly disagree (the async DB stock sync lags Redis).
+    def enabling_auto_assign_seats?
+      return false unless auto_assign_seats?
+
+      previous = attribute_in_database(:public_metadata)
+      previous = {} unless previous.is_a?(Hash)
+
+      !ActiveModel::Type::Boolean.new.cast(previous['auto_assign_seats'])
+    end
+  end
+end

data/app/models/spree_cm_commissioner/block.rb

@@ -26,6 +26,12 @@ module SpreeCmCommissioner
     validates :rotation, presence: true, numericality: { greater_than_or_equal_to: -360, less_than_or_equal_to: 360 }
     validates :shape_path, format: { with: /\A\s*[Mm]/, message: 'must start with a move command' }, allow_blank: true # rubocop:disable Rails/I18nLocaleTexts
 
+    # Position in its ticket type's seat order on this layout (written only by
+    # SeatLayouts::SaveSeatOrder): consecutive numbers are side by side, a skipped number is a break,
+    # lower sells first.
+    validates :seat_index, numericality: { only_integer: true, greater_than: 0 }, allow_nil: true
+    before_validation :clear_seat_index, if: :leaves_seat_order?
+
     validate :cannot_unassign_variant_with_active_blocks
 
     before_validation :assign_layout_from_section, if: -> { seat_layout.nil? && seat_section.present? }
@@ -54,12 +60,39 @@ module SpreeCmCommissioner
       self.class.sellable?(block_type)
     end
 
+    # The ReservedBlock row currently making this seat unbookable (reserved, on_hold, or
+    # operator-locked and not expired) — nil when the seat is open for sale. Reads off the
+    # already-loaded all_reserved_blocks association rather than querying, so a caller that
+    # preloads it (e.g. the organizer seat status view, rendering every block on a layout) does
+    # not pay a query per block.
+    #
+    # Only meaningful for a block with a single relevant InventoryItem, e.g. an Event
+    # session-variant's undated item. A Transit block spans one InventoryItem per departure date, so
+    # all_reserved_blocks can hold several simultaneously-active rows (locked on one date, sold on
+    # another) and this returns an arbitrary one of them, not "the" status for any particular date.
+    # Do not call this for a date-scoped seat map — use Seats::LockState instead, which resolves
+    # status per (block, date).
+    def current_reserved_block
+      all_reserved_blocks.detect(&:unavailable?)
+    end
+
     def assign_layout_from_section
       self.seat_layout = seat_section.seat_layout
     end
 
     private
 
+    # A seat that changes ticket type, or stops being a seat, leaves its row: its number belongs to its
+    # old type's order. Cleared rather than rejected, so a layout builder edit never fails over Seat
+    # order; the gap reads as a break, and Seats::AutoAssignValidator reports the seat as unlinked.
+    def leaves_seat_order?
+      seat_index.present? && (!seatable? || (persisted? && variant_id_changed?))
+    end
+
+    def clear_seat_index
+      self.seat_index = nil
+    end
+
     # Deleting a seat would cascade into its locked rows, dropping the deduction without giving the
     # quantity back. Unlock first.
     #

data/app/models/spree_cm_commissioner/integration_mapping.rb

@@ -6,6 +6,8 @@ module SpreeCmCommissioner
 
     enum status: { active: 0, archived: 1 }
 
+    scope :active_routes_of, -> (integration) { active.where(integration_id: integration.id, internal_type: 'SpreeCmCommissioner::Route') }
+
     # polymorphic (Spree::Taxon, Spree::Product, Spree::Variant, Spree::Vendor)
     belongs_to :internal, polymorphic: true, optional: false
     belongs_to :integration, class_name: 'SpreeCmCommissioner::Integration', inverse_of: :integration_mappings, optional: false
@@ -32,6 +34,12 @@ module SpreeCmCommissioner
       save!
     end
 
+    # True when `new_payload` differs from the stored one only in `ignoring` keys (at any depth), i.e. nothing the
+    # rest of the sync reads back has changed. Does not write anything.
+    def payload_unchanged?(new_payload, ignoring: [])
+      persisted? && active? && stable_payload(new_payload.as_json, ignoring) == stable_payload(external_payload.as_json, ignoring)
+    end
+
     # For polling, which confirms the same mappings every few seconds. last_synced_at is indexed, so each save rewrites
     # every index on this table; this skips the save while nothing a reader uses has changed. `ignoring` lists payload
     # keys that move on every poll (seats, for one), at any depth.

data/app/models/spree_cm_commissioner/integrations/book_me_bus_v1.rb

@@ -8,6 +8,11 @@ class SpreeCmCommissioner::Integrations::BookMeBusV1 < SpreeCmCommissioner::Inte
   store_private_metadata :operator_id, :string
   store_private_metadata :sync_days, :integer, default: 7
   # override
+  # The dates a full sync covers: today and the next sync_days - 1 days.
+  def sync_dates
+    (0...sync_days).map { |ahead| (Date.current + ahead).iso8601 }
+  end
+
   def sync_manager
     SpreeCmCommissioner::Integrations::BookMeBusV1::SyncManager.new(integration: self)
   end

data/app/models/spree_cm_commissioner/line_item_decorator.rb

@@ -164,6 +164,10 @@ module SpreeCmCommissioner
       return false unless variant.should_track_inventory?
       return false if required_seat_selection?
 
+      # The count hold is what guarantees an auto-assigned seat exists at completion, so these lines
+      # take it regardless of the product's enable_inventory_hold setting.
+      return true if auto_assign_seats?
+
       return true if ENV.fetch('INVENTORY_HOLD_ENABLED', nil) == 'true'
       return true if product.enable_inventory_hold?
 

data/app/models/spree_cm_commissioner/order_decorator.rb

@@ -1,11 +1,12 @@
 module SpreeCmCommissioner
-  module OrderDecorator
+  module OrderDecorator # rubocop:disable Metrics/ModuleLength
     def self.prepended(base) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
       base.include SpreeCmCommissioner::OrderChannelBitwise
       base.include SpreeCmCommissioner::StoreMetadata
       base.include SpreeCmCommissioner::PhoneNumberSanitizer
       base.include SpreeCmCommissioner::OrderIntegration
       base.include SpreeCmCommissioner::OrderHoldable
+      base.include SpreeCmCommissioner::OrderSeatAutoAssignable
       base.include SpreeCmCommissioner::OrderStateMachine
       base.include SpreeCmCommissioner::RouteOrderCountable
       base.include SpreeCmCommissioner::OrderScopes
@@ -88,6 +89,15 @@ module SpreeCmCommissioner
       end
     end
 
+    # override: Spree::Api::Webhooks::OrderDecorator#after_resume ends with
+    # `self.state_machine_resumed = false`, and state_machines halts the after_transition chain when
+    # a callback returns false — so every `after_transition to: :resumed` registered after core's
+    # (OrderStateMachine's precalculate_conversion, Seats::AutoAssignJob) silently never ran.
+    def after_resume
+      super
+      true
+    end
+
     # override: imported orders are bulk-loaded from CSV and the contact email
     # often belongs to a third party (organizer, importer) rather than the buyer,
     # so the cancellation email would notify the wrong recipient. Normal orders
@@ -191,6 +201,12 @@ module SpreeCmCommissioner
       super
     end
 
+    # override Vpago::OrderDecorator. Must live here, not in OrderSeatAutoAssignable: vpago's decorator
+    # is prepended above the included concerns, so a definition there would never be reached.
+    def pending_completion_steps
+      seat_assignment_pending? ? super + [:seats_assigning] : super
+    end
+
     # Must live here, not in OrderStateMachine: that concern is included (below Spree::Order),
     # while Spree::Emails::OrderDecorator is prepended above it and never calls super, so an
     # override there is silently dead.

data/app/models/spree_cm_commissioner/product_decorator.rb

@@ -11,6 +11,7 @@ module SpreeCmCommissioner
       base.include SpreeCmCommissioner::StoreMetadata
       base.include SpreeCmCommissioner::HomepageSectionRelatableConcern
       base.include SpreeCmCommissioner::PurchaseLimitable
+      base.include SpreeCmCommissioner::ProductSeatAutoAssignable
 
       base.delegate :is_open_dated, :is_open_dated?, to: :trip, allow_nil: true
 

data/app/models/spree_cm_commissioner/reserved_block.rb

@@ -5,7 +5,12 @@ module SpreeCmCommissioner
     has_paper_trail
 
     # Why a seat was taken off sale by an operator. Stored in private_metadata rather than as a
-    # typed column, so it cannot be an ActiveRecord enum — the constant is the source of truth.
+    # typed column, so it cannot be an ActiveRecord enum.
+    #
+    # Suggested options for a picklist-style UI (Transit's "Lock Seats" drawer) -- NOT a validation
+    # allowlist. `lock_reason` itself accepts any free text (see the presence/length validations
+    # below): the Organizer "Manage Hold Seats" screen lets the operator type their own reason, so
+    # enforcing this list at the model would reject a perfectly legitimate custom reason.
     #
     # `gender_balance` is deliberately absent: female-only seating is driven by the `gender` column,
     # and a locked row has no gender, so a lock structurally cannot express it.
@@ -25,19 +30,24 @@ module SpreeCmCommissioner
 
     enum gender: { :other => 0, :male => 1, :female => 2 }
 
+    # Every status in which a seat cannot be sold. Single source of truth for the `unavailable`
+    # scope (SQL) and `#unavailable?` (in-memory, for a caller that already preloaded the rows and
+    # cannot afford one query per row) -- kept as one list so a future status addition cannot update
+    # one and silently miss the other.
+    UNAVAILABLE_STATUSES = %w[reserved on_hold locked].freeze
+
     store_private_metadata :lock_reason, :string
     store_private_metadata :lock_note, :text
 
     validates :status, presence: true
     validates :expired_at, presence: true, if: -> { on_hold? }
-    validates :lock_reason, inclusion: { in: LOCK_REASONS }, allow_nil: true
     validates :lock_reason, presence: true, if: -> { locked? }
     validate :locked_rows_have_no_guest, if: -> { locked? }
 
     scope :reserved_or_on_hold, -> { where(status: %i[reserved on_hold]).where('expired_at IS NULL OR expired_at > ?', Time.current) }
     # Every state in which a seat cannot be sold. `reserved_or_on_hold` is kept as-is because other
     # callers depend on its narrower meaning.
-    scope :unavailable, -> { where(status: %i[reserved on_hold locked]).where('expired_at IS NULL OR expired_at > ?', Time.current) }
+    scope :unavailable, -> { where(status: UNAVAILABLE_STATUSES).where('expired_at IS NULL OR expired_at > ?', Time.current) }
     scope :active_on_hold, -> { on_hold.where('expired_at IS NULL OR expired_at > ?', Time.current) }
     scope :active, -> { where('expired_at IS NULL OR expired_at > ?', Time.current) }
 
@@ -49,6 +59,12 @@ module SpreeCmCommissioner
       on_hold? && !expired?
     end
 
+    # In-memory equivalent of the `unavailable` scope, for a caller iterating a preloaded
+    # association rather than querying -- see Block#current_reserved_block.
+    def unavailable?
+      status.in?(UNAVAILABLE_STATUSES) && !expired?
+    end
+
     def payment_locked?
       payment_locked_at.present?
     end

data/app/models/spree_cm_commissioner/seats/auto_assign_validator.rb

@@ -0,0 +1,63 @@
+module SpreeCmCommissioner
+  module Seats
+    # Guards switching a product's auto_assign_seats on: every seat is linked in Seat order, and there is
+    # a free seat for every ticket still to be sold. Checks each variant that has seats on an active
+    # layout; every problem becomes one error on :auto_assign_seats.
+    #
+    #   validates_with SpreeCmCommissioner::Seats::AutoAssignValidator
+    class AutoAssignValidator < ActiveModel::Validator
+      def validate(product)
+        seated = product.variants_including_master.filter_map do |variant|
+          seats = seats_for(variant)
+          [variant, seats] if seats.exists?
+        end
+
+        return product.errors.add(:auto_assign_seats, 'has no seats on an active seat layout to assign') if seated.empty?
+
+        seated.each do |variant, seats|
+          [unlinked_seats_error(variant, seats), *not_enough_seats_errors(variant, seats)].compact.each do |message|
+            product.errors.add(:auto_assign_seats, message)
+          end
+        end
+      end
+
+      private
+
+      def seats_for(variant)
+        SpreeCmCommissioner::Block.joins(:seat_layout)
+                                  .where(variant_id: variant.id, block_type: %i[seat sleeping_seat])
+                                  .where(cm_seat_layouts: { status: SpreeCmCommissioner::SeatLayout.statuses[:active] })
+      end
+
+      # A seat left out of Seat order (no seat_index) is never handed out, while its ticket still sells.
+      #
+      #   20 seats, 18 linked → 'VIP: 2 seats are not linked in Seat order'
+      def unlinked_seats_error(variant, seats)
+        count = seats.where(seat_index: nil).count
+        return if count.zero?
+
+        "#{variant.descriptive_name}: #{count} #{count == 1 ? 'seat is' : 'seats are'} not linked in Seat order"
+      end
+
+      # Every ticket still to be sold needs a free seat, per date (one undated item for an event).
+      # Fewer seats than tickets means a paid guest with no seat; more is fine, the extra stays empty.
+      #
+      # Tickets still to be sold: public stock + public carts + private-sale pool + its carts. A seat
+      # locked with Seats::LockBlocks is in neither side: it already lowered quantity_available, and its
+      # ReservedBlock marks it taken.
+      #
+      #   100 seats, 5 taken, 98 tickets to sell → 'VIP on 2026-12-01: 98 tickets can still be sold but only 95 seats are free'
+      def not_enough_seats_errors(variant, seats)
+        variant.inventory_items.active.filter_map do |item|
+          taken = SpreeCmCommissioner::ReservedBlock.unavailable.where(inventory_item_id: item.id).select(:block_id)
+          free = seats.where.not(id: taken).count
+          to_sell = item.quantity_available + item.quantity_on_hold + item.quantity_locked + item.quantity_locked_on_hold
+          next if free >= to_sell
+
+          on = item.inventory_date ? " on #{item.inventory_date}" : ''
+          "#{variant.descriptive_name}#{on}: #{to_sell} tickets can still be sold but only #{free} seats are free"
+        end
+      end
+    end
+  end
+end

data/app/overrides/spree/admin/products/_form/auto_assign_seats.html.erb.deface

@@ -0,0 +1,14 @@
+<!-- insert_after "[data-hook='admin_product_form_promotionable']" -->
+
+<div>
+  <%= f.field_container :auto_assign_seats do %>
+    <%= f.label :auto_assign_seats do %>
+      <%= f.check_box :auto_assign_seats %>
+      Auto-assign seats
+    <% end %>
+    <%= f.error_message_on :auto_assign_seats %>
+    <small class="form-text text-muted">
+      Customers don't pick seats; each paid order gets the best free seats together, following the layout's Seat order. Can only be switched on once every seat of this product is linked in Seat order.
+    </small>
+  <% end %>
+</div>