spree_cm_commissioner 2.10.1 → 2.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 34524289f2fc489da23a30fcaca4bfcdac167a60b0efd382368efda96433e4d9
-  data.tar.gz: 47cd7bcb029126c27c0dd1c7081f26b8a217e740be768662f59a208a0e440ad6
+  metadata.gz: 58bbc65915f1f69096fabf6a1778dd9d810ebdbf8e788c2b1597e3b2173f2204
+  data.tar.gz: c32858179db78672e07bc34c5f7395b59b228d5585e35647c3d5486cf0c0ea9c
 SHA512:
-  metadata.gz: 134f803e39f5fce95401a2404cf6f559baf6997651440578767022cc9c7c4ddf1368da4b16ec12b096753569794593a03a8ace0ac1522fab107a0ae57b09db04
-  data.tar.gz: d8401ff0a245a5429919380ffc56412e2a09614fe82a78bef24f2e90ff54d88feb885ea0bb78993d2f45e9e7cc6a294958642290e53f8ea41650fc3ca4652759
+  metadata.gz: 6493ccc10ddcb0dfae06115f11168207bdee8f8d687367108ba59e41885e10a989f8adcb17a220019039ef3a5c224ab3fe4356c6f1e90ae9130e4a607347e015
+  data.tar.gz: 363d64fd5b2aa2f809163134dd050b85d46d529fe35a34994381c3bc7861acd4f57afab353fdd2772081e019a5f49eb78f4d9141ee9d7a44e06991b07170d764

data/Gemfile.lock

@@ -34,7 +34,7 @@ GIT
 PATH
   remote: .
   specs:
-    spree_cm_commissioner (2.10.1)
+    spree_cm_commissioner (2.11.0)
       activerecord-multi-tenant
       activerecord_json_validator (~> 2.1, >= 2.1.3)
       aws-sdk-cloudfront

data/app/controllers/concerns/spree_cm_commissioner/content_cachable.rb

@@ -14,7 +14,7 @@ module SpreeCmCommissioner
       CountriesController
       ProvincesController
       GuestCardClassesController
-      SeatLayoutController
+      SeatLayoutsController
       CmsPagesController
       AdvertisementsController
     ].freeze

data/app/controllers/spree/admin/system/waiting_room_sessions_controller.rb

@@ -0,0 +1,27 @@
+module Spree
+  module Admin
+    module System
+      class WaitingRoomSessionsController < Spree::Admin::BaseController
+        def index
+          @filter = params[:filter] if params[:filter] == 'load_test'
+
+          sessions = SpreeCmCommissioner::WaitingRoomSession.active
+          sessions = sessions.load_test if @filter == 'load_test'
+
+          @waiting_room_sessions = sessions.order(created_at: :desc).page(params[:page]).per(50)
+        end
+
+        # Kills only the sessions the admin checked (Gmail-style select + delete), instead of the
+        # room's whole active set. Firebase's active_sessions/full reflect this only on the next
+        # WaitingGuestsCaller run (they're a once-a-minute mirror, not live).
+        def kill
+          ids = Array(params[:ids])
+          count = SpreeCmCommissioner::WaitingRoomSession.kill_by_ids!(ids)
+          flash[:success] = "Killed #{count} waiting-room session(s)."
+
+          redirect_back fallback_location: admin_system_waiting_room_sessions_path
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v2/storefront/draft_orders_controller.rb

@@ -11,7 +11,7 @@ module Spree
           # Params:
           # - line_items: Array of { variant_id:, quantity:, options: {}, public_metadata: {}, private_metadata: {} } (required)
           def create
-            result = SpreeCmCommissioner::DraftOrder::Create.call(
+            result = SpreeCmCommissioner::DraftOrders::Create.call(
               line_items: draft_order_line_items,
               user: spree_current_user,
               store: current_store,

data/app/controllers/spree/api/v2/tenant/draft_orders_controller.rb

@@ -8,7 +8,7 @@ module Spree
           # Params:
           # - line_items: Array of { variant_id:, quantity:, options: {}, public_metadata: {}, private_metadata: {} } (required)
           def create
-            result = SpreeCmCommissioner::DraftOrder::Create.call(
+            result = SpreeCmCommissioner::DraftOrders::Create.call(
               line_items: draft_order_line_items,
               user: spree_current_user,
               store: current_store,

data/app/controllers/spree/api/v2/tenant/voting_contestants_controller.rb

@@ -13,7 +13,7 @@ module Spree
           def collection
             @collection ||= @voting_session
                             .voting_contestants
-                            .includes(:voting_session, { show_contestant: :assigned_show_person },
+                            .includes(:voting_session, :eliminated_voting_session, { show_contestant: :assigned_show_person },
                                       :show_contestant_images, :show_contestant_videos,
                                       :advanced_to, :advanced_from
                             ).order(:vote_number)

data/app/controllers/spree/api/v2/tenant/voting_credit_transactions_controller.rb

@@ -20,7 +20,7 @@ module Spree
 
           def scope
             scope = spree_current_user.voting_credit_transactions
-                                      .includes(:vote_credit, :originator)
+                                      .includes(:vote_credit, :originator, contestant: :voting_session)
                                       .order(created_at: :desc)
 
             scope = scope.by_action(params[:actions].split(',')) if params[:actions].present?

data/app/controllers/spree_cm_commissioner/admin/variants_controller_decorator.rb

@@ -56,21 +56,31 @@ module SpreeCmCommissioner
         option_value.name
       end
 
-      # Builds the load-test fixture for this variant so it can be used by the k6 booking flow.
+      # Builds the load-test fixture for this variant so it can be used by a k6 booking flow.
       # Shown on a page (with a check for whether the variant can be booked) for the tester to
       # copy into the load_testing config. A product with a tenant_id belongs to a tenant
       # (SaaS-hosted) store rather than the platform — the two k6 workflows keep separate fixture
       # folders (load_testing/config/fixture/platform/booking_ticket_flow/ vs
       # load_testing/config/fixture/tenant/cash_on_booking_ticket_flow/ — the tenant flow is named
       # cash_on_* since it has an ABA sibling; the platform flow doesn't).
+      #
+      # Whether this variant needs seat_selection_booking_flow isn't picked here — it's read off
+      # the generated fixture's metadata[:select_seat] (see GenerateBookingTicketData), which
+      # derives it the same way add-to-cart itself does.
       def fixture
         @fixture_workflow = @variant.product.tenant_id.present? ? 'tenant' : 'platform'
-        @fixture_flow = @fixture_workflow == 'tenant' ? 'cash_on_booking_ticket_flow' : 'booking_ticket_flow'
+        @fixture_env = Rails.env.development? ? 'local' : Rails.env.to_s # the load_testing config calls it "local", not "development"
+
         result = SpreeCmCommissioner::LoadTest::GenerateBookingTicketData.call(variant: @variant)
         @fixture = result.value[:data]
         @fixture_issues = result.value[:issues]
-        # The load_testing config calls it "local", not "development".
-        @fixture_env = Rails.env.development? ? 'local' : Rails.env.to_s
+        @fixture_flow = @fixture[:metadata][:select_seat] ? 'seat_selection_booking_flow' : fixture_flow_for(@fixture_workflow)
+      end
+
+      private
+
+      def fixture_flow_for(workflow)
+        workflow == 'tenant' ? 'cash_on_booking_ticket_flow' : 'booking_ticket_flow'
       end
     end
   end

data/app/jobs/spree_cm_commissioner/voting_session_auto_open_job.rb

@@ -0,0 +1,14 @@
+module SpreeCmCommissioner
+  # Enqueued by VotingSessions::ScheduleVoteWindowJobs with wait_until: vote_open_at.
+  # See VotingSessions::AutoOpen for the actual open/publish logic.
+  class VotingSessionAutoOpenJob < ApplicationJob
+    queue_as :default
+
+    def perform(voting_session_id)
+      voting_session = SpreeCmCommissioner::VotingSession.find_by(id: voting_session_id)
+      return if voting_session.nil?
+
+      SpreeCmCommissioner::VotingSessions::AutoOpen.call(voting_session: voting_session)
+    end
+  end
+end

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

@@ -41,6 +41,19 @@ module SpreeCmCommissioner
       store_public_metadata :preload_seat_layout_ids, :array, default: []
       store_public_metadata :preload_active_seat_layout_ids, :array, default: []
 
+      # Use to indicate if a seat layout is the guide layout for this event. 1 guide layout per event.
+      store_public_metadata :preload_guide_seat_layout_id, :integer
+      store_public_metadata :preload_active_guide_seat_layout_id, :integer
+
+      # Denormalised price range across the event's variants, so the client can show it (e.g. "from $X")
+      # without loading every variant. Kept in sync by PriceDecorator's after_commit hook
+      store_public_metadata :min_price, :string
+      store_public_metadata :max_price, :string
+      store_public_metadata :currency, :string
+
+      store_public_metadata :spotify_embed_url, :string
+      store_public_metadata :spotify_embed_skeleton_color, :string, default: '#900033'
+
       before_validation :validate_at_least_one_check_in_flow_presence
     end
 
@@ -51,6 +64,18 @@ module SpreeCmCommissioner
       flows
     end
 
+    def display_min_price
+      return nil if min_price.blank?
+
+      Spree::Money.new(min_price, currency: currency).to_s
+    end
+
+    def display_max_price
+      return nil if max_price.blank?
+
+      Spree::Money.new(max_price, currency: currency).to_s
+    end
+
     private
 
     def validate_at_least_one_check_in_flow_presence

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

@@ -12,6 +12,14 @@ module SpreeCmCommissioner
       max_quantity_per_ip
     ].freeze
 
+    # Caps that aggregate across orders. The order cap is bounded by each of these:
+    # whichever is smaller is what the buyer actually gets.
+    AGGREGATE_LIMIT_KEYS = %i[
+      max_quantity_per_account
+      max_quantity_per_device
+      max_quantity_per_ip
+    ].freeze
+
     POSITIVE_INTEGER = { only_integer: true, greater_than: 0, message: :must_be_positive_integer }.freeze
 
     included do
@@ -27,6 +35,7 @@ module SpreeCmCommissioner
 
       validate :validate_max_quantity_per_account
       validate :validate_max_quantity_per_device
+      validate :validate_order_cap_within_aggregate_caps
 
       before_validation :normalize_purchase_limits
     end
@@ -50,6 +59,19 @@ module SpreeCmCommissioner
       errors.add(:base, I18n.t('purchase_limit.account_cap_requires_named_booking'))
     end
 
+    # An order cap above an aggregate cap is unreachable - the aggregate check counts the same
+    # cart quantity plus past orders, so it rejects first. Only the tightest cap is named:
+    # fixing it clears the rest. A blank cap reads back as 0, hence the positive? filter.
+    def validate_order_cap_within_aggregate_caps
+      order_cap = max_quantity_per_order.to_i
+      key = AGGREGATE_LIMIT_KEYS.select { |k| public_send(k).to_i.positive? && public_send(k).to_i < order_cap }
+                                .min_by { |k| public_send(k).to_i }
+      return if key.nil?
+
+      cap_name = I18n.t("purchase_limit.cap_names.#{key.to_s.delete_prefix('max_quantity_per_')}")
+      errors.add(:max_quantity_per_order, I18n.t('purchase_limit.order_cap_exceeds_scope_cap', cap_name: cap_name))
+    end
+
     def validate_max_quantity_per_device
       return unless max_quantity_per_device.to_i.positive? && !purchasable_on_app?
 

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

@@ -6,8 +6,15 @@ module SpreeCmCommissioner
   #
   # There is no mode flag: the presence of vote_open_at/vote_close_at is the signal.
   #
-  #   Pre-set at creation  — auto-activates: once #activate flips status to enabled, can_vote?
-  #                          just compares Time.current against the already-real timestamps.
+  #   Pre-set at creation  — auto-activates: #schedule_vote_window_jobs (below) enqueues
+  #                          VotingSessionAutoOpenJob for vote_open_at. If status is already
+  #                          :enabled, can_vote? was already purely time-driven, so that job just
+  #                          keeps Firestore's published state in sync. If status is :on_air (an
+  #                          organizer revealed the session but never pressed Start Vote), that
+  #                          same job flips status to :enabled once vote_open_at arrives — gated
+  #                          on visible?, so it only completes a reveal the organizer already made,
+  #                          never a private archived session. VotingSessionAutoCloseJob then
+  #                          follows the same way once enabled, for vote_close_at.
   #   Left blank           — #start_vote! rewrites them to now / now + vote_duration_seconds the
   #                          moment the organizer presses it, live during the broadcast.
   #
@@ -36,6 +43,7 @@ module SpreeCmCommissioner
       # yet — "reveal" is something an organizer does to an *existing* archived session.
       before_update :promote_from_archived_when_made_visible
       after_commit :publish_live_state_to_firestore, on: %i[create update], if: :live_state_changed?
+      after_commit :schedule_vote_window_jobs, on: %i[create update], if: :vote_window_scheduling_relevant_change?
 
       scope :visible, -> { where(visible: true) }
     end
@@ -56,8 +64,6 @@ module SpreeCmCommissioner
         status: :enabled,
         visible: true
       )
-
-      SpreeCmCommissioner::VotingSessionAutoCloseJob.set(wait_until: vote_close_at).perform_later(id)
     end
 
     # Ends the vote window immediately and moves to closed. status: closed (not just a rewritten
@@ -104,8 +110,6 @@ module SpreeCmCommissioner
     # validation.
     def extend_vote!(seconds)
       update!(vote_close_at: [vote_close_at, Time.current].max + seconds.to_i.seconds)
-
-      SpreeCmCommissioner::VotingSessionAutoCloseJob.set(wait_until: vote_close_at).perform_later(id)
     end
 
     private
@@ -131,7 +135,21 @@ module SpreeCmCommissioner
     end
 
     def publish_live_state_to_firestore
-      SpreeCmCommissioner::VotingSessionFirestorePublishJob.perform_later(id)
+      SpreeCmCommissioner::VotingSessions::PublishLiveState.call(voting_session: self)
+    end
+
+    # Either the window itself moved, or status crossed into/out of a state the scheduling cares
+    # about (archived -> on_air on reveal; on_air -> enabled when VotingSessionAutoOpenJob fires).
+    # Both matter: a reveal with a vote_open_at already set at creation only just became eligible
+    # for the open job, without vote_open_at/vote_close_at themselves changing on this save.
+    def vote_window_scheduling_relevant_change?
+      saved_change_to_attribute?(:vote_open_at) || saved_change_to_attribute?(:vote_close_at) ||
+        saved_change_to_attribute?(:status)
+    end
+
+    # See SpreeCmCommissioner::VotingSessions::ScheduleVoteWindowJobs for the scheduling rules.
+    def schedule_vote_window_jobs
+      SpreeCmCommissioner::VotingSessions::ScheduleVoteWindowJobs.call(voting_session: self)
     end
   end
 end

data/app/models/spree_cm_commissioner/block.rb

@@ -24,6 +24,7 @@ module SpreeCmCommissioner
     validates :x, presence: true, numericality: true
     validates :y, presence: true, numericality: true
     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
 
     validate :cannot_unassign_variant_with_active_blocks
 

data/app/models/spree_cm_commissioner/guest.rb

@@ -303,6 +303,11 @@ module SpreeCmCommissioner
       Array(public_metadata['eligible_check_in_session_ids']).map(&:to_i)
     end
 
+    # Set by TicketTransfers::TransferGuest when this guest was created to receive a transferred ticket
+    def from_transfer?
+      ActiveModel::Type::Boolean.new.cast(public_metadata['from_transfer']) || false
+    end
+
     def eligible_check_in_session_ids=(ids)
       # Ensure public_metadata is a hash
       self.public_metadata = {} if public_metadata.nil?

data/app/models/spree_cm_commissioner/maintenance_tasks/event.rb

@@ -10,6 +10,8 @@ module SpreeCmCommissioner
           update_conversion_for(product_taxon)
         end
 
+        refresh_price_range
+
         # These steps can be expensive and our new order state machine already prevents most cases from happening.
         # So we should only run them as manual maintenance just in case we missed some edge cases.
         reassign_guests_event_id if manually_triggered?
@@ -22,6 +24,24 @@ module SpreeCmCommissioner
         maintainable.id
       end
 
+      # Denormalises maintainable's price range onto EventMetadata#min_price/max_price/currency
+      # so the event-details bar can show "from $X" without loading the ticket list. Triggered
+      # by PriceDecorator's after_commit hook via a pending task, and run unconditionally here.
+      def refresh_price_range
+        currency = Spree::Store.default.default_currency
+
+        priced_variant_ids = maintainable.event_variants.where(is_master: false).select(:id)
+        min_amount, max_amount = Spree::Price
+                                 .where(variant_id: priced_variant_ids, currency: currency)
+                                 .pick(Arel.sql('MIN(amount)'), Arel.sql('MAX(amount)'))
+
+        maintainable.update!(
+          min_price: min_amount&.to_s,
+          max_price: max_amount&.to_s,
+          currency: min_amount.present? ? currency : nil
+        )
+      end
+
       def update_conversion_for(product_taxon)
         # Count guests (attendees) instead of line item quantity so this stays consistent
         # with EventChartQueries, which counts DISTINCT cm_guests.id on complete orders.

data/app/models/spree_cm_commissioner/order_decorator.rb

@@ -296,7 +296,7 @@ module SpreeCmCommissioner
 
     # override spree_vpago method
     def payment_host
-      tenant&.payment_url.presence || tenant&.formatted_url.presence || ENV.fetch('DEFAULT_URL_HOST')
+      tenant&.payment_url.presence || tenant&.formatted_url.presence || ENV.fetch('PAYMENT_BASE_URL')
     end
 
     # Returns arrays of connected line_item IDs grouped by connected_trip_id.

data/app/models/spree_cm_commissioner/price_decorator.rb

@@ -2,6 +2,22 @@ module SpreeCmCommissioner
   module PriceDecorator
     def self.prepended(base)
       base.belongs_to :inventory_item, class_name: 'SpreeCmCommissioner::InventoryItem', inverse_of: :prices, optional: true
+      base.after_commit :trigger_event_price_range_refresh, if: :should_trigger_event_price_range_refresh?
+    end
+
+    def should_trigger_event_price_range_refresh?
+      (saved_change_to_amount? || saved_change_to_currency?) && event_id.present?
+    end
+
+    def event_id
+      variant&.product&.event_id
+    end
+
+    def trigger_event_price_range_refresh
+      SpreeCmCommissioner::MaintenanceTasks::Event.pending.create_or_find_by(
+        maintainable_type: 'Spree::Taxon',
+        maintainable_id: event_id
+      )
     end
   end
 end

data/app/models/spree_cm_commissioner/product_decorator.rb

@@ -144,6 +144,7 @@ module SpreeCmCommissioner
 
       base.after_update :update_variants_vendor_id, if: :saved_change_to_vendor_id?
       base.after_update :sync_event_id_to_children, if: :saved_change_to_event_id?
+      base.after_commit :trigger_event_price_range_refresh_for_event_change, if: :saved_change_to_event_id?
 
       base.enum purchasable_on: { both: 0, web: 1, app: 2 }, _prefix: true
       base.enum call_to_action: { buy_now: 0,
@@ -162,6 +163,16 @@ module SpreeCmCommissioner
 
       # Create maintaining task to purge product related caches
       base.after_save { SpreeCmCommissioner::MaintenanceTasks::CacheInvalidation.pending.create_or_find_by(maintainable: self) }
+
+      # App opens the event page, not the ticket/product page, so the event's cache must be purged too.
+      base.after_commit do
+        [event_id, event_id_before_last_save].compact.uniq.each do |taxon_id|
+          SpreeCmCommissioner::MaintenanceTasks::CacheInvalidation.pending.create_or_find_by(
+            maintainable_type: 'Spree::Taxon',
+            maintainable_id: taxon_id
+          )
+        end
+      end
     end
 
     def ticket_url
@@ -184,6 +195,20 @@ module SpreeCmCommissioner
       end
     end
 
+    # override
+    # [spree_core] only checks active?/deleted?, so a scheduled product (available_on in the future)
+    # reports available even though it isn't purchasable yet. Since Variant#available? delegates
+    # here, this closes the gap for every caller (cart, checkout, Stock::AvailabilityChecker) in
+    # one place — mirrors VariantDecorator#discontinued?'s window check.
+    def available?
+      return false unless active?
+      return false if deleted?
+      return false if discontinued?
+      return false if available_on.present? && available_on > Time.current
+
+      true
+    end
+
     private
 
     def set_tenant
@@ -202,6 +227,17 @@ module SpreeCmCommissioner
       ::SpreeCmCommissioner::ProductEventIdToChildrenSyncerJob.perform_later(product_id: id)
     end
 
+    # Moving a product on/off an event stales both events' price ranges — refresh whichever
+    # side(s) actually had an event.
+    def trigger_event_price_range_refresh_for_event_change
+      [event_id, event_id_before_last_save].compact.uniq.each do |taxon_id|
+        SpreeCmCommissioner::MaintenanceTasks::Event.pending.create_or_find_by(
+          maintainable_type: 'Spree::Taxon',
+          maintainable_id: taxon_id
+        )
+      end
+    end
+
     def validate_event_taxons
       errors.add(:taxons, 'Event Taxon can\'t not be more than 1') if taxons.event.size > 1
       errors.add(:taxons, 'Must add event date to taxon') if event.from_date.nil? || event.to_date.nil?

data/app/models/spree_cm_commissioner/seat_layout.rb

@@ -1,5 +1,13 @@
 module SpreeCmCommissioner
   class SeatLayout < Base
+    include StoreMetadata
+
+    # Whole-screen theming for the app's seat-selection scaffold (background / app bar / status
+    # bar) — distinct from SeatSection#color, which fills an individual zone shape.
+    store_public_metadata :background_color, :string
+
+    has_one_attached :background_svg
+
     has_many :seat_sections, class_name: 'SpreeCmCommissioner::SeatSection', dependent: :destroy
 
     has_many :blocks, class_name: 'SpreeCmCommissioner::Block'
@@ -11,6 +19,13 @@ module SpreeCmCommissioner
                                               through: :blocks,
                                               source: :active_on_hold_reserved_blocks
 
+    # Reverse side of SeatSection#sub_seat_layout — every section, on any layout, that opens
+    # this layout when tapped. Powers the dashboard's "Referenced by …" note and the
+    # activation guard that refuses to go live while pointing at a non-active layout.
+    has_many :linking_seat_sections, class_name: 'SpreeCmCommissioner::SeatSection',
+                                     foreign_key: :sub_seat_layout_id,
+                                     inverse_of: :sub_seat_layout, dependent: :nullify
+
     belongs_to :layoutable, polymorphic: true
 
     enum status: {
@@ -20,6 +35,11 @@ module SpreeCmCommissioner
     }
 
     validates :name, presence: true
+    validates :background_color, format: { with: /\A#[0-9A-Fa-f]{6}\z/ }, allow_nil: true
+
+    # A guided layout is the one flagged to drive an event's/vehicle's customer-facing
+    # tap-to-navigate map; at most one per layoutable.
+    validates :guide, uniqueness: { scope: %i[layoutable_type layoutable_id] }, if: :guide?
 
     accepts_nested_attributes_for :seat_sections, :top_level_blocks, allow_destroy: true
 
@@ -27,26 +47,43 @@ module SpreeCmCommissioner
     # DO NOT REMOVE without implementing alternative sync (see event_metadata.rb:L16-24).
     after_commit :sync_seat_layout_id_to_layoutable!, if: -> { layoutable.present? }
 
+    def background_svg_url
+      return nil unless background_svg.attached?
+
+      Rails.application.routes.url_helpers.cdn_image_url(background_svg)
+    end
+
+    # Any section or block has been converted from the background artwork — i.e. there is
+    # something for a customer to tap. Used by the "nothing converted yet" index-card state
+    # and the activation guard that refuses to go live with an unmapped background.
+    def mapped_sections?
+      seat_sections.where.not(shape_path: nil).exists? || blocks.where.not(shape_path: nil).exists?
+    end
+
     private
 
-    def sync_seat_layout_id_to_layoutable!
+    def sync_seat_layout_id_to_layoutable! # rubocop:disable Metrics/PerceivedComplexity
       # Update layoutable's seat layout metadata after any change (create/update/destroy).
       # This keeps the cache in sync with the actual seat_layouts association.
       if layoutable.respond_to?(:seat_layouts)
         # Event has many seat layouts: `..._ids` caches every layout ever attached (any status);
         # `active_..._ids` caches only the `active` ones, for callers checking bookability.
-        layoutable.update!(
-          preload_seat_layout_ids: layoutable.seat_layouts.pluck(:id),
-          preload_active_seat_layout_ids: layoutable.seat_layouts.active.pluck(:id)
-        )
+        layoutable.preload_seat_layout_ids = layoutable.seat_layouts.pluck(:id)
+        layoutable.preload_active_seat_layout_ids = layoutable.seat_layouts.active.pluck(:id)
       elsif layoutable.respond_to?(:seat_layout)
         # Taxon/Vehicle has single seat layout: cache the ID (or nil if destroyed); the active
         # variant is also nil while the layout is inactive/archived, not just when destroyed.
-        layoutable.update!(
-          preload_seat_layout_id: destroyed? ? nil : id,
-          preload_active_seat_layout_id: destroyed? || !active? ? nil : id
-        )
+        layoutable.preload_seat_layout_id = destroyed? ? nil : id
+        layoutable.preload_active_seat_layout_id = destroyed? || !active? ? nil : id
       end
+
+      if layoutable.respond_to?(:preload_guide_seat_layout_id=)
+        guide_layout = destroyed? ? nil : layoutable.seat_layouts.find_by(guide: true)
+        layoutable.preload_guide_seat_layout_id = guide_layout&.id
+        layoutable.preload_active_guide_seat_layout_id = guide_layout&.active? ? guide_layout.id : nil
+      end
+
+      layoutable.save!
     end
   end
 end

data/app/models/spree_cm_commissioner/seat_section.rb

@@ -1,16 +1,63 @@
 module SpreeCmCommissioner
   class SeatSection < Base
+    include StoreMetadata
+
     belongs_to :seat_layout, class_name: 'SpreeCmCommissioner::SeatLayout', optional: false
+    belongs_to :sub_seat_layout, class_name: 'SpreeCmCommissioner::SeatLayout', optional: true,
+                                 inverse_of: :linking_seat_sections
 
     has_many :blocks, class_name: 'SpreeCmCommissioner::Block', dependent: :destroy
 
+    store_public_metadata :product_ids, :array, default: []
+    store_public_metadata :background_color, :string
+
     validates :name, presence: true
     validates :width, presence: true, numericality: { greater_than: 0 }
     validates :height, presence: true, numericality: { greater_than: 0 }
     validates :x, presence: true, numericality: true
     validates :y, presence: true, numericality: true
     validates :rotation, presence: true, numericality: { greater_than_or_equal_to: -360, less_than_or_equal_to: 360 }
+    validates :background_color, format: { with: /\A#[0-9A-Fa-f]{6}\z/ }, allow_nil: true
+    validates :shape_path, format: { with: /\A\s*[Mm]/, message: 'must start with a move command' }, allow_blank: true # rubocop:disable Rails/I18nLocaleTexts
+
+    validate :validate_on_tap_destination
+    validate :validate_sub_seat_layout
 
     accepts_nested_attributes_for :blocks, allow_destroy: true
+
+    private
+
+    # A section's on-tap destination is exactly one of:
+    #   1. Nothing — a normal section with blocks; the customer picks seats individually, not
+    #      the section itself.
+    #   2. Open a sub seat layout — sub_seat_layout_id is set.
+    #   3. Open a ticket list — product_ids is set.
+    #
+    # A section with blocks can only ever be case 1; a blockless section can be case 2 or 3, never
+    # both — made unreachable from the dashboard's "On tap" selector, enforced here as the source
+    # of truth for any write that bypasses it.
+    def validate_on_tap_destination
+      has_destination = product_ids.present? || sub_seat_layout_id.present?
+
+      errors.add(:base, 'a section with blocks cannot also have an on-tap destination') if has_destination && blocks.any?
+
+      return unless product_ids.present? && sub_seat_layout_id.present?
+
+      errors.add(:base, 'a section can have at most one on-tap destination')
+    end
+
+    def validate_sub_seat_layout
+      return if sub_seat_layout.blank?
+
+      errors.add(:sub_seat_layout, "cannot be the section's own seat layout") if sub_seat_layout_id == seat_layout_id
+
+      if seat_layout.present? && sub_seat_layout.layoutable != seat_layout.layoutable
+        errors.add(:sub_seat_layout, 'must belong to the same event or vehicle as this section')
+      end
+
+      return unless sub_seat_layout.guide?
+
+      errors.add(:sub_seat_layout, "cannot itself be the layoutable's guide layout")
+    end
   end
 end

data/app/models/spree_cm_commissioner/taxon_decorator.rb

@@ -47,6 +47,8 @@ module SpreeCmCommissioner
       base.belongs_to :vendor, class_name: 'Spree::Vendor'
 
       base.validates_associated :category_icon
+      base.validate :validate_event_dates, if: -> { from_date.present? && to_date.present? }
+
       base.before_save :set_kind
       base.before_save :set_slug
       base.before_save :normalize_custom_redirect_url
@@ -180,6 +182,12 @@ module SpreeCmCommissioner
 
     private
 
+    def validate_event_dates
+      return unless from_date > to_date
+
+      errors.add(:from_date, :must_be_before_to_date)
+    end
+
     def normalize_custom_redirect_url
       self.custom_redirect_url = nil if custom_redirect_url.blank?
     end

data/app/models/spree_cm_commissioner/ticket_transfer.rb

@@ -66,6 +66,10 @@ module SpreeCmCommissioner
       gift? || manual_payment?
     end
 
+    def requires_payment?
+      !free_transfer? && total.positive?
+    end
+
     # Records an audit trail of settlement_status changes to spree_state_changes.
     # Call this explicitly after a successful save to capture who changed the status and when.
     def log_settlement_status_changes(user_id:)