spree_cm_commissioner 2.5.0.pre.pre8 → 2.5.0.pre.pre10

data/app/helpers/spree_cm_commissioner/external_integrations_helper.rb

@@ -0,0 +1,58 @@
+module SpreeCmCommissioner
+  module ExternalIntegrationsHelper
+    def integration_status_badge(status)
+      badge_class = case status.to_s
+                    when 'active' then 'badge-success'
+                    when 'paused' then 'badge-warning'
+                    else 'badge-secondary'
+                    end
+
+      content_tag(:span, status.to_s.humanize, class: "badge badge-pill #{badge_class}")
+    end
+
+    def integration_conflict_strategy_badge(strategy)
+      content_tag(:span, strategy.to_s.humanize, class: 'badge badge-pill badge-secondary')
+    end
+
+    def integration_interval_badge(value, unit)
+      content_tag(:span, "#{value}#{unit}", class: 'badge badge-pill badge-info')
+    end
+
+    def integration_base_url_link(url)
+      if url.present?
+        link_to url, url, target: '_blank', rel: 'noopener', class: 'text-decoration-underline'
+      else
+        content_tag(:span, '—', class: 'text-muted')
+      end
+    end
+
+    def integration_mapping_internal_link(mapping)
+      return mapping.internal_id if mapping.internal.blank?
+
+      begin
+        case mapping.internal_type
+        when 'Spree::Taxon'
+          taxon = mapping.internal
+          taxonomy_id = taxon.taxonomy_id || taxon.taxonomy&.id
+          if taxonomy_id
+            link_to mapping.internal_id,
+                    edit_admin_taxonomy_taxon_path(taxonomy_id, taxon.id),
+                    class: 'text-primary'
+          end
+        when 'Spree::Product'
+          link_to mapping.internal_id, edit_admin_product_path(mapping.internal), class: 'text-primary'
+        when 'Spree::Variant'
+          link_to mapping.internal_id, edit_admin_product_variant_path(mapping.internal.product_id, mapping.internal), class: 'text-primary'
+        when 'Spree::Vendor'
+          link_to mapping.internal_id, edit_admin_vendor_path(mapping.internal), class: 'text-primary'
+        else
+          # Try polymorphic route as fallback
+          link_to mapping.internal_id, [:edit, :admin, mapping.internal], class: 'text-primary'
+        end
+      rescue StandardError => e
+        Rails.logger.warn("Failed to generate link for mapping #{mapping.id}: #{e.message}")
+        mapping.internal_id
+      end
+    end
+  end
+end

data/app/interactors/spree_cm_commissioner/create_event.rb

@@ -94,7 +94,7 @@ module SpreeCmCommissioner
     end
 
     def generate_reports
-      SpreeCmCommissioner::ReportsAssignerJob.perform_later(@parent_taxon.id, @parent_taxon.class.to_s)
+      SpreeCmCommissioner::ReportsAssignerJob.perform_later(queryable_id: @parent_taxon.id, queryable_type: @parent_taxon.class.to_s)
     end
   end
 end

data/app/interactors/spree_cm_commissioner/customer_notification_cron_executor.rb

@@ -11,7 +11,7 @@ module SpreeCmCommissioner
     end
 
     def enqueue_customer_notification_alert(customer_notification)
-      SpreeCmCommissioner::CustomerNotificationSenderJob.perform_later(customer_notification.id)
+      SpreeCmCommissioner::CustomerNotificationSenderJob.perform_later(customer_notification_id: customer_notification.id)
     end
   end
 end

data/app/interactors/spree_cm_commissioner/stock/inventory_item_resetter.rb

@@ -35,7 +35,7 @@ module SpreeCmCommissioner
       end
 
       def clear_inventory_cache
-        SpreeCmCommissioner.redis_pool.with do |redis|
+        SpreeCmCommissioner.inventory_redis_pool.with do |redis|
           redis.del(inventory_item.redis_key)
         end
       end

data/app/interactors/spree_cm_commissioner/stock/stock_movement_creator.rb

@@ -23,8 +23,9 @@ module SpreeCmCommissioner
       private
 
       def adjust_inventory_items_async(variant_id, quantity)
-        CmAppLogger.log(label: "#{self.class.name}#adjust_inventory_items_async", data: { variant_id: variant_id, quantity: quantity }) do
-          SpreeCmCommissioner::Stock::InventoryItemsAdjusterJob.perform_later(variant_id: variant_id, quantity: quantity)
+        args = { variant_id: variant_id, quantity: quantity }
+        CmAppLogger.log(label: "#{self.class.name}#adjust_inventory_items_async", data: args) do
+          SpreeCmCommissioner::Stock::InventoryItemsAdjusterJob.perform_later(**args)
         end
       end
     end

data/app/jobs/spree_cm_commissioner/conversion_pre_calculator_job.rb

@@ -2,8 +2,8 @@ module SpreeCmCommissioner
   class ConversionPreCalculatorJob < ApplicationUniqueJob
     queue_as :default
 
-    def perform(product_id)
-      product = Spree::Product.find(product_id)
+    def perform(options = {})
+      product = Spree::Product.find(options[:product_id])
       product.classification_ids.each do |classification_id|
         SpreeCmCommissioner::ConversionPreCalculator.call(product_taxon: Spree::Classification.find(classification_id))
       end

data/app/jobs/spree_cm_commissioner/customer_notification_sender_job.rb

@@ -1,8 +1,8 @@
 module SpreeCmCommissioner
   class CustomerNotificationSenderJob < ApplicationUniqueJob
-    def perform(customer_notification_id, user_ids = nil)
-      customer_notification = SpreeCmCommissioner::CustomerNotification.find(customer_notification_id)
-      SpreeCmCommissioner::CustomerNotificationSender.call(customer_notification: customer_notification, user_ids: user_ids)
+    def perform(options = {})
+      customer_notification = SpreeCmCommissioner::CustomerNotification.find(options[:customer_notification_id])
+      SpreeCmCommissioner::CustomerNotificationSender.call(customer_notification: customer_notification, user_ids: options[:user_ids])
     end
   end
 end

data/app/jobs/spree_cm_commissioner/enqueue_cart/add_item_job.rb

@@ -1,14 +1,14 @@
 module SpreeCmCommissioner
   module EnqueueCart
     class AddItemJob < ApplicationUniqueJob
-      def perform(order_id, variant_id, quantity, public_metadata, private_metadata, options) # rubocop:disable Metrics/ParameterLists
+      def perform(options = {})
         SpreeCmCommissioner::EnqueueCart::AddItem.call(
-          order_id: order_id,
-          variant_id: variant_id,
-          quantity: quantity,
-          public_metadata: public_metadata,
-          private_metadata: private_metadata,
-          options: options,
+          order_id: options[:order_id],
+          variant_id: options[:variant_id],
+          quantity: options[:quantity],
+          public_metadata: options[:public_metadata],
+          private_metadata: options[:private_metadata],
+          options: options[:options],
           job_id: job_id
         )
       end

data/app/jobs/spree_cm_commissioner/ensure_event_for_product_line_item_guests_job.rb

@@ -5,7 +5,7 @@ module SpreeCmCommissioner
       Spree::Taxon.event.includes(:children_products).find_each do |event|
         event.children_products.where('event_id IS NULL OR event_id != ?', event.id).find_each do |product|
           product.update_columns(event_id: event.id) # rubocop:disable Rails/SkipsModelValidations
-          ::SpreeCmCommissioner::ProductEventIdToChildrenSyncerJob.perform_later(product.id)
+          ::SpreeCmCommissioner::ProductEventIdToChildrenSyncerJob.perform_later(product_id: product.id)
         end
       end
     end

data/app/jobs/spree_cm_commissioner/event_line_items_date_syncer_job.rb

@@ -1,7 +1,7 @@
 module SpreeCmCommissioner
   class EventLineItemsDateSyncerJob < ApplicationJob
-    def perform(event_id)
-      event = Spree::Taxon.event.find(event_id)
+    def perform(options = {})
+      event = Spree::Taxon.event.find(options[:event_id])
       SpreeCmCommissioner::EventLineItemsDateSyncer.call(event: event)
     end
   end

data/app/jobs/spree_cm_commissioner/export_csv_job.rb

@@ -1,7 +1,7 @@
 module SpreeCmCommissioner
   class ExportCsvJob < ApplicationUniqueJob
-    def perform(id)
-      Exports::ExportGuestCsvService.new(id).call
+    def perform(options = {})
+      Exports::ExportGuestCsvService.new(options[:export_id]).call
     end
   end
 end

data/app/jobs/spree_cm_commissioner/import_order_job.rb

@@ -1,14 +1,14 @@
 module SpreeCmCommissioner
   class ImportOrderJob < ApplicationUniqueJob
-    def perform(import_order_id, import_by_user_id, import_type)
-      if import_type == 'new_order'
+    def perform(options = {})
+      if options[:import_type] == 'new_order'
         SpreeCmCommissioner::Imports::CreateOrderService.new(
-          import_order_id: import_order_id,
-          import_by_user_id: import_by_user_id
+          import_order_id: options[:import_order_id],
+          import_by_user_id: options[:import_by_user_id]
         ).call
       else
         SpreeCmCommissioner::Imports::UpdateOrderService.new(
-          import_order_id: import_order_id
+          import_order_id: options[:import_order_id]
         ).call
       end
     end

data/app/jobs/spree_cm_commissioner/integrations/base_job.rb

@@ -0,0 +1,39 @@
+module SpreeCmCommissioner
+  module Integrations
+    # Base class for integration jobs
+    #
+    # Provides common error handling and alerting functionality for all integration jobs.
+    # Subclasses should implement their own perform logic and call the appropriate
+    # error handler methods.
+    class BaseJob < ApplicationJob
+      queue_as :integration
+
+      protected
+
+      # Handle error by logging and sending alert
+      # @param label [String] The error label for logging
+      # @param error [StandardError] The error that occurred
+      # @param data [Hash] Additional context data (e.g., sync_type, match_id, event_type)
+      def handle_error(label:, error:, data: {})
+        error_message = "#{error.class.name}: #{error.message}"
+
+        # Log the error with structured data
+        CmAppLogger.error(
+          label: label,
+          data: data.merge(
+            message: error_message,
+            backtrace: error.backtrace
+          )
+        )
+
+        # Send alert via Telegram
+        TelegramAlerts::IntegrationSyncFailureJob.perform_later(
+          error_message: error_message,
+          data: data
+        )
+
+        error_message
+      end
+    end
+  end
+end

data/app/jobs/spree_cm_commissioner/integrations/polling_job.rb

@@ -0,0 +1,53 @@
+module SpreeCmCommissioner
+  module Integrations
+    # Job that performs the actual polling (syncing) for a specific integration
+    #
+    # This job is enqueued by PollingSchedulerJob and handles:
+    # - Full syncs: Complete refresh of all data
+    # - Incremental syncs: Fetch only recent changes
+    # - Webhook syncs: Real-time event processing (triggered externally)
+    #
+    # Each integration type (StadiumXV1, LarrytaV1, etc.) must implement
+    # a sync_manager that responds to sync_full!, sync_incremental!, and sync_webhook!
+    class PollingJob < BaseJob
+      # Perform the integration pull
+      # @param integration_id [Integer] The integration ID
+      # @param sync_type [String] The sync type: 'full', 'incremental', or 'webhook_triggered'
+      # @param event_type [String] Optional event type for webhook syncs
+      # @param event_data [Hash] Optional event data for webhook syncs
+      def perform(options)
+        integration_id = options[:integration_id]
+        sync_type = options[:sync_type]
+        event_type = options[:event_type]
+        event_data = options[:event_data]
+        integration = SpreeCmCommissioner::Integration.find(integration_id)
+
+        # integration is no longer active, skip processing.
+        return unless integration.active?
+
+        SpreeCmCommissioner::Integrations::Polling.new.call(
+          integration: integration,
+          sync_type: sync_type,
+          event_type: event_type,
+          event_data: event_data
+        )
+      rescue StandardError => e
+        handle_sync_error(e, options)
+        raise
+      end
+
+      private
+
+      # Handle sync errors and alert
+      # @param error [StandardError] The error that occurred
+      # @param options [Hash] The options passed to perform
+      def handle_sync_error(error, options)
+        handle_error(
+          label: 'Integrations::IntegrationPullJob#perform Sync failed',
+          error: error,
+          data: options
+        )
+      end
+    end
+  end
+end

data/app/jobs/spree_cm_commissioner/integrations/polling_scheduler_job.rb

@@ -0,0 +1,30 @@
+module SpreeCmCommissioner
+  module Integrations
+    # Scheduler job that runs periodically to enqueue integration polling jobs
+    #
+    # This job is responsible for:
+    # - Running full syncs every 24 hours
+    # - Running incremental syncs every 10 seconds
+    # - Webhook syncs are triggered externally (not scheduled here)
+    #
+    # The job queries all active integrations and enqueues appropriate pull jobs
+    # based on their last sync time and sync type configuration.
+    class PollingSchedulerJob < BaseJob
+      def perform
+        SpreeCmCommissioner::Integrations::PollingScheduler.new.call
+      rescue StandardError => e
+        handle_scheduler_error(e)
+        raise
+      end
+
+      private
+
+      def handle_scheduler_error(error)
+        handle_error(
+          label: 'Integrations::PollingSchedulerJob#perform Error scheduling integration pulls',
+          error: error
+        )
+      end
+    end
+  end
+end

data/app/jobs/spree_cm_commissioner/invalidate_cache_request_job.rb

@@ -1,7 +1,7 @@
 module SpreeCmCommissioner
   class InvalidateCacheRequestJob < ApplicationUniqueJob
-    def perform(pattern)
-      SpreeCmCommissioner::InvalidateCacheRequest.call(pattern: pattern)
+    def perform(options = {})
+      SpreeCmCommissioner::InvalidateCacheRequest.call(pattern: options[:pattern])
     end
   end
 end

data/app/jobs/spree_cm_commissioner/inventory_item_syncer_job.rb

@@ -1,7 +1,13 @@
 module SpreeCmCommissioner
   class InventoryItemSyncerJob < ApplicationUniqueJob
-    def perform(inventory_id_and_quantities:)
-      InventoryItemSyncer.call(inventory_id_and_quantities:)
+    # :line_item_ids, :inventory_id_and_quantities
+    #
+    # :line_item_ids is included for unique job key generation to prevent duplicate jobs,
+    # though it's not used in the perform method implementation.
+    def perform(options = {})
+      InventoryItemSyncer.call(
+        inventory_id_and_quantities: options[:inventory_id_and_quantities]
+      )
     end
   end
 end

data/app/jobs/spree_cm_commissioner/option_type_variants_public_metadata_updater_job.rb

@@ -1,8 +1,12 @@
 module SpreeCmCommissioner
   class OptionTypeVariantsPublicMetadataUpdaterJob < ApplicationUniqueJob
-    def perform(option_type_id)
-      optino_type = ::Spree::OptionType.find(option_type_id)
-      optino_type.variants.find_each(&:set_options_to_public_metadata!)
+    def perform(options = {})
+      option_type = ::Spree::OptionType.find_by(id: options[:option_type_id])
+
+      # job can be queued with invalid id or record is created but rolled back or deleted.
+      return if option_type.blank?
+
+      option_type.variants.find_each(&:set_options_to_public_metadata!)
     end
   end
 end

data/app/jobs/spree_cm_commissioner/option_value_variants_public_metadata_updater_job.rb

@@ -1,7 +1,11 @@
 module SpreeCmCommissioner
   class OptionValueVariantsPublicMetadataUpdaterJob < ApplicationUniqueJob
-    def perform(option_value_id)
-      option_value = ::Spree::OptionValue.find(option_value_id)
+    def perform(options = {})
+      option_value = ::Spree::OptionValue.find_by(id: options[:option_value_id])
+
+      # job can be queued with invalid id or record is created but rolled back or deleted.
+      return if option_value.blank?
+
       option_value.variants.find_each(&:set_options_to_public_metadata!)
     end
   end

data/app/jobs/spree_cm_commissioner/order_complete_telegram_sender_job.rb

@@ -4,8 +4,8 @@ module SpreeCmCommissioner
   class OrderCompleteTelegramSenderJob < ApplicationUniqueJob
     queue_as :telegram_bot
 
-    def perform(order_id)
-      order = Spree::Order.find(order_id)
+    def perform(options = {})
+      order = Spree::Order.find(options[:order_id])
       SpreeCmCommissioner::OrderCompleteTelegramSender.call(order: order)
     end
   end

data/app/jobs/spree_cm_commissioner/product_event_id_to_children_syncer_job.rb

@@ -1,7 +1,7 @@
 module SpreeCmCommissioner
   class ProductEventIdToChildrenSyncerJob < ApplicationUniqueJob
-    def perform(product_id)
-      product = Spree::Product.find(product_id)
+    def perform(options = {})
+      product = Spree::Product.find(options[:product_id])
       SpreeCmCommissioner::ProductEventIdToChildrenSyncer.call(product: product)
     end
   end

data/app/jobs/spree_cm_commissioner/reports_assigner_job.rb

@@ -1,7 +1,7 @@
 module SpreeCmCommissioner
   class ReportsAssignerJob < ApplicationUniqueJob
-    def perform(queryable_id, queryable_type)
-      SpreeCmCommissioner::ReportsAssigner.call(queryable_id: queryable_id, queryable_type: queryable_type)
+    def perform(options = {})
+      SpreeCmCommissioner::ReportsAssigner.call(queryable_id: options[:queryable_id], queryable_type: options[:queryable_type])
     end
   end
 end

data/app/jobs/spree_cm_commissioner/sms_pin_code_job.rb

@@ -1,7 +1,7 @@
 module SpreeCmCommissioner
   class SmsPinCodeJob < SpreeCmCommissioner::SmsJob
     # options = { from: xxxx, to: xxxx, body: xxxx }
-    def perform(options)
+    def perform(options = {})
       SpreeCmCommissioner::Sms.call(options)
     end
   end

data/app/jobs/spree_cm_commissioner/state_job.rb

@@ -1,7 +1,7 @@
 module SpreeCmCommissioner
   class StateJob < ApplicationUniqueJob
-    def perform(state_id)
-      state = ::Spree::State.find_by(id: state_id)
+    def perform(options = {})
+      state = ::Spree::State.find_by(id: options[:state_id])
       StateUpdater.call(state: state)
     end
   end

data/app/jobs/spree_cm_commissioner/stock/inventory_items_adjuster_job.rb

@@ -1,10 +1,13 @@
 module SpreeCmCommissioner
   module Stock
     class InventoryItemsAdjusterJob < ApplicationUniqueJob
-      def perform(variant_id:, quantity:)
-        variant = Spree::Variant.find(variant_id)
+      def perform(options = {})
+        variant = Spree::Variant.find_by(id: options[:variant_id])
 
-        SpreeCmCommissioner::Stock::InventoryItemsAdjuster.call(variant: variant, quantity: quantity)
+        # potentially the variant was deleted during the job wait time, we just skip in that case.
+        return if variant.blank?
+
+        SpreeCmCommissioner::Stock::InventoryItemsAdjuster.call(variant: variant, quantity: options[:quantity])
       end
     end
   end

data/app/jobs/spree_cm_commissioner/stock/inventory_items_generator_job.rb

@@ -1,8 +1,8 @@
 module SpreeCmCommissioner
   module Stock
     class InventoryItemsGeneratorJob < ApplicationUniqueJob
-      def perform(variant_id:)
-        variant = Spree::Variant.find(variant_id)
+      def perform(options = {})
+        variant = Spree::Variant.find(options[:variant_id])
 
         SpreeCmCommissioner::Stock::InventoryItemsGenerator.call(variant: variant)
       end

data/app/jobs/spree_cm_commissioner/telegram_alerts/integration_sync_failure_job.rb

@@ -0,0 +1,17 @@
+module SpreeCmCommissioner
+  module TelegramAlerts
+    class IntegrationSyncFailureJob < ApplicationJob
+      queue_as :telegram_bot
+
+      # Handle error by logging and sending alert
+      # @param error_message [String] The error message
+      # @param data [Hash] Additional context data (e.g., sync_type, match_id, event_type)
+      def perform(options)
+        SpreeCmCommissioner::TelegramAlerts::IntegrationSyncFailure.call(
+          error_message: options[:error_message],
+          data: options[:data] || {}
+        )
+      end
+    end
+  end
+end

data/app/jobs/spree_cm_commissioner/transit/route_fulfilled_order_count_incrementer_job.rb

@@ -1,8 +1,8 @@
 module SpreeCmCommissioner
   module Transit
     class RouteFulfilledOrderCountIncrementerJob < ApplicationUniqueJob
-      def perform(order_id:)
-        order = Spree::Order.find(order_id)
+      def perform(options = {})
+        order = Spree::Order.find(options[:order_id])
         SpreeCmCommissioner::Routes::IncrementFulfilledOrderCount.call(order: order)
       end
     end

data/app/jobs/spree_cm_commissioner/transit/route_order_count_incrementer_job.rb

@@ -1,8 +1,8 @@
 module SpreeCmCommissioner
   module Transit
     class RouteOrderCountIncrementerJob < ApplicationUniqueJob
-      def perform(order_id:)
-        order = Spree::Order.find(order_id)
+      def perform(options = {})
+        order = Spree::Order.find(options[:order_id])
         SpreeCmCommissioner::Routes::IncrementOrderCount.call(order: order)
       end
     end

data/app/jobs/spree_cm_commissioner/transit/route_previous_trip_count_decrementer_job.rb

@@ -5,8 +5,8 @@ module SpreeCmCommissioner
     class RoutePreviousTripCountDecrementerJob < ApplicationUniqueJob
       queue_as :default
 
-      def perform(previous_route_id:)
-        SpreeCmCommissioner::Routes::DecrementPreviousTripCount.call(previous_route_id: previous_route_id)
+      def perform(options = {})
+        SpreeCmCommissioner::Routes::DecrementPreviousTripCount.call(previous_route_id: options[:previous_route_id])
       end
     end
   end

data/app/jobs/spree_cm_commissioner/transit/route_trip_count_decrementer_job.rb

@@ -1,8 +1,8 @@
 module SpreeCmCommissioner
   module Transit
     class RouteTripCountDecrementerJob < ApplicationUniqueJob
-      def perform(trip_id:)
-        trip = SpreeCmCommissioner::Trip.find(trip_id)
+      def perform(options = {})
+        trip = SpreeCmCommissioner::Trip.find(options[:trip_id])
         SpreeCmCommissioner::Routes::DecrementTripCount.call(trip: trip)
       end
     end

data/app/jobs/spree_cm_commissioner/transit/route_trip_count_incrementer_job.rb

@@ -1,8 +1,8 @@
 module SpreeCmCommissioner
   module Transit
     class RouteTripCountIncrementerJob < ApplicationUniqueJob
-      def perform(trip_id:)
-        trip = SpreeCmCommissioner::Trip.find(trip_id)
+      def perform(options = {})
+        trip = SpreeCmCommissioner::Trip.find(options[:trip_id])
         SpreeCmCommissioner::Routes::IncrementTripCount.call(trip: trip)
       end
     end

data/app/jobs/spree_cm_commissioner/vendor_creation_telegram_alert_sender_job.rb

@@ -2,8 +2,8 @@ module SpreeCmCommissioner
   class VendorCreationTelegramAlertSenderJob < ApplicationUniqueJob
     queue_as :telegram_bot
 
-    def perform(vendor_id)
-      vendor = Spree::Vendor.find(vendor_id)
+    def perform(options = {})
+      vendor = Spree::Vendor.find(options[:vendor_id])
       SpreeCmCommissioner::VendorCreationTelegramAlertSender.call(vendor: vendor)
     end
   end

data/app/jobs/spree_cm_commissioner/vendor_job.rb

@@ -1,7 +1,7 @@
 module SpreeCmCommissioner
   class VendorJob < ApplicationUniqueJob
-    def perform(vendor_id)
-      vendor = ::Spree::Vendor.find(vendor_id)
+    def perform(options = {})
+      vendor = ::Spree::Vendor.find(options[:vendor_id])
       VendorUpdater.call(vendor: vendor)
     end
   end

data/app/jobs/spree_cm_commissioner/waiting_room_session_firebase_logger_job.rb

@@ -23,7 +23,7 @@ module SpreeCmCommissioner
   class WaitingRoomSessionFirebaseLoggerJob < ApplicationUniqueJob
     retry_on StandardError, wait: :exponentially_longer, attempts: 4
 
-    def perform(options)
+    def perform(options = {})
       room_session = SpreeCmCommissioner::WaitingRoomSession.find(options[:room_session_id])
       waiting_guest_firebase_doc_id = options[:waiting_guest_firebase_doc_id]
 

data/app/models/concerns/spree_cm_commissioner/integrations/integration_mappable.rb

@@ -0,0 +1,61 @@
+module SpreeCmCommissioner
+  module Integrations
+    # IntegrationMappable provides a polymorphic mapping layer between internal records and external integration IDs.
+    #
+    # Design Rationale: Why use a separate mapping table instead of adding external_id columns directly?
+    #
+    # 1. **No Schema Changes Required**: Adding a new integration doesn't require migrations to add columns to every table.
+    #    The mapping table is reusable across all models that include this concern.
+    #
+    # 2. **Polymorphic Scalability**: A single mapping table handles multiple record types (Spree::Product, Spree::Taxon,
+    #    SeatLayout, etc.) without duplicating external_id columns across the schema.
+    #
+    # 3. **Multiple Source Support**: Records can have mappings to multiple integrations simultaneously. A single product
+    #    might be synced from StadiumXV1, LarrytaV1, and other sources. Direct columns would require one per integration.
+    #
+    # 4. **Acceptable Performance Trade-off**: While joins are slightly slower than direct column lookups, the performance
+    #    impact is negligible in practice because:
+    #    - Lookups occur primarily during background jobs (async, not blocking user requests)
+    #    - Integration sync operations (incremental, full, webhook)
+    #    - Occasional user-triggered operations (not on every page load)
+    #    The flexibility and maintainability gains far outweigh the minimal performance cost.
+    module IntegrationMappable
+      extend ActiveSupport::Concern
+
+      included do
+        has_many :integration_mappings, as: :internal, class_name: 'SpreeCmCommissioner::IntegrationMapping', dependent: :destroy
+        has_many :external_wins_integration_mappings, lambda {
+                                                        joins(:integration).where(integration: { conflict_strategy: :external_wins })
+                                                      }, as: :internal, class_name: 'SpreeCmCommissioner::IntegrationMapping'
+      end
+
+      class_methods do
+        def find_or_initialize_integration_mapping(integration_id:, external_id:)
+          IntegrationMapping.includes(:internal).find_or_initialize_by(
+            integration_id: integration_id,
+            internal_type: name,
+            external_id: external_id
+          ) do |mapping|
+            mapping.internal = new
+            mapping.external_id = external_id
+          end
+        end
+
+        def find_integration_mapping(integration_id:, external_id:)
+          IntegrationMapping.includes(:internal).find_by(
+            integration_id: integration_id,
+            internal_type: name,
+            external_id: external_id
+          )
+        end
+
+        def find_oldest_active_mapping(integration_id:)
+          IntegrationMapping.where(
+            integration_id: integration_id,
+            internal_type: name
+          ).active.order(:last_synced_at).first
+        end
+      end
+    end
+  end
+end