spree_cm_commissioner 2.4.3 → 2.5.0.pre.pre1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5f580394367847906251ac52666c73ae79bb1a117948805217616c0a83f9300a
-  data.tar.gz: e8b7ae961151a074aab2084e7600b55da2969405143cf1b9e4cd1b95fcd7040b
+  metadata.gz: 766f3c96b11b0771314a8713c96706a97aaa777879fc7de568c6cde2d45a69b3
+  data.tar.gz: 61425d946b1b97f4d56f385fa3fef1e32482d00537b5ed4de2ace0bb7a66a41d
 SHA512:
-  metadata.gz: 35e303df725eb93bb52a3eceb55672668cea800d77dd7c4e4d938b9caf0585477044e20fe646f2a2a7da5209a4ceff6c78ccf8e6adb862378373a66bd1525d19
-  data.tar.gz: f91afe8506292cf778cfb3b8bfdc87f5d2545c2e079abdf5f5d881441c3ae758f218bcbb6798756f860734b5c3af82be30250c2c0a2f5a9e2aea96782d7623ed
+  metadata.gz: 0f76688e91c61895340e65c38dc8defe2e92eb2d96a8011cb6064d97811b982a26102aa217b257aee237af25cc9eace91fbafa97bd3d0199da1451ea46b2089c
+  data.tar.gz: ccb93229d83dbed6f5196b461dfa006f1be936e9a41b2a7226ba2fbbe3f63ca17425bbe5c1e22da66116ecef6f43402808e4ea1a649447c6ab5df7c5c292dd5d

data/.github/workflows/test_and_build_gem.yml

@@ -10,7 +10,7 @@ on:
       - reopened
     branches:
       - develop
-      - milestone-77-scalable-design
+      - 3114-external-integration-milestone
   push:
     tags:
       - "*"

data/.tool-versions

@@ -1 +1 @@
-ruby 3.3.5
+ruby 3.2.0

data/Gemfile.lock

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

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

@@ -0,0 +1,21 @@
+module Spree
+  module Admin
+    class IntegrationMappingsController < Spree::Admin::BaseController
+      helper SpreeCmCommissioner::ExternalIntegrationsHelper
+      before_action :load_integration
+
+      def index
+        @mappings = @integration.integration_mappings
+                                .order(updated_at: :desc)
+                                .page(params[:page])
+                                .per(params[:per_page] || 25)
+      end
+
+      private
+
+      def load_integration
+        @integration ||= SpreeCmCommissioner::Integration.find(params[:integration_id])
+      end
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+module Spree
+  module Admin
+    class IntegrationSessionsController < Spree::Admin::BaseController
+      helper SpreeCmCommissioner::ExternalIntegrationsHelper
+      before_action :load_integration
+
+      def index
+        @sync_sessions = @integration.integration_sync_sessions
+                                     .order(created_at: :desc)
+                                     .page(params[:page])
+                                     .per(params[:per_page] || 25)
+      end
+
+      private
+
+      def load_integration
+        @integration ||= SpreeCmCommissioner::Integration.find(params[:integration_id])
+      end
+    end
+  end
+end

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

@@ -0,0 +1,83 @@
+module Spree
+  module Admin
+    class IntegrationsController < Spree::Admin::ResourceController
+      helper SpreeCmCommissioner::ExternalIntegrationsHelper
+      before_action :load_form_collections, only: %i[new create edit update]
+      before_action :load_integration, only: %i[enqueue_polling]
+
+      def index
+        @integrations = model_class.all
+      end
+
+      def enqueue_polling
+        sync_type = params[:sync_type].presence || :full
+
+        if @integration.active?
+          SpreeCmCommissioner::Integrations::PollingJob.perform_later(
+            integration_id: @integration.id,
+            sync_type: sync_type
+          )
+          flash[:success] = Spree.t('admin.integration_sync_enqueued')
+        else
+          flash[:error] = Spree.t('admin.integration_inactive')
+        end
+
+        redirect_to admin_integration_sessions_path(@integration)
+      end
+
+      # override
+      def model_class
+        SpreeCmCommissioner::Integration
+      end
+
+      # override
+      def collection_url(options = {})
+        admin_integrations_url(options)
+      end
+
+      private
+
+      def permitted_resource_params
+        params.require(:spree_cm_commissioner_integration).permit(
+          :name,
+          :type,
+          :status,
+          :conflict_strategy,
+          :incremental_sync_interval_seconds,
+          :full_sync_interval_hours,
+          :tenant_id,
+          :vendor_id,
+          public_metadata: {},
+          private_metadata: {}
+        )
+      end
+
+      def load_integration
+        @integration ||= SpreeCmCommissioner::Integration.find(params[:id])
+      end
+
+      def load_form_collections
+        @integration_type_options ||= integration_type_options
+        @status_options ||= enum_to_options(SpreeCmCommissioner::Integration.statuses)
+        @conflict_strategy_options ||= enum_to_options(SpreeCmCommissioner::Integration.conflict_strategies)
+        @tenants ||= SpreeCmCommissioner::Tenant.select(:id, :name).order(:name)
+        @vendors ||= Spree::Vendor.select(:id, :name).order(:name)
+      end
+
+      def enum_to_options(enum_hash)
+        enum_hash.keys.map { |key| [key.humanize, key] }
+      end
+
+      def integration_type_options
+        files = Dir[SpreeCmCommissioner::Engine.root.join('app/models/spree_cm_commissioner/integrations/*.rb')]
+
+        return [[Spree.t(:type), 'SpreeCmCommissioner::Integration']] if files.blank?
+
+        files.map do |path|
+          class_name = "SpreeCmCommissioner::Integrations::#{File.basename(path, '.rb').camelize}"
+          [class_name, class_name]
+        end.sort_by(&:first)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,15 @@
+module Spree
+  module Api
+    module V2
+      module Storefront
+        class EventMatchesController < TaxonsController
+          private
+
+          def collection_finder
+            SpreeCmCommissioner::Events::FindMatches
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,10 @@
+module SpreeCmCommissioner::Integrations
+  class ExternalClientError < StandardError
+    attr_reader :status_code
+
+    def initialize(message, status_code = nil)
+      super(message)
+      @status_code = status_code
+    end
+  end
+end

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

@@ -0,0 +1,4 @@
+module SpreeCmCommissioner::Integrations
+  class SyncError < StandardError
+  end
+end

data/app/finders/spree_cm_commissioner/events/find_matches.rb

@@ -0,0 +1,15 @@
+module SpreeCmCommissioner
+  module Events
+    class FindMatches < ::Spree::BaseFinder
+      # currently, there is no way to determine if an event is a match yet.
+      # this finder returns all events that have active integration mappings (synced from external systems like StadiumX)
+      # as a temporary workaround to filter out non-match events.
+      def execute
+        scope.joins(:integration_mappings).where(
+          kind: :event,
+          integration_mappings: { status: :active }
+        ).distinct
+      end
+    end
+  end
+end

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/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,10 @@ 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)
+        params = { variant_id: variant_id, quantity: quantity }
+
+        CmAppLogger.log(label: "#{self.class.name}#adjust_inventory_items_async", data: params) do
+          SpreeCmCommissioner::Stock::InventoryItemsAdjusterJob.perform_later(**params)
         end
       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/stock/inventory_items_adjuster_job.rb

@@ -1,10 +1,11 @@
 module SpreeCmCommissioner
   module Stock
-    class InventoryItemsAdjusterJob < ApplicationUniqueJob
-      def perform(variant_id:, quantity:)
-        variant = Spree::Variant.find(variant_id)
+    class InventoryItemsAdjusterJob < ApplicationJob
+      # :variant_id, :quantity
+      def perform(options)
+        variant = Spree::Variant.find(options[:variant_id])
 
-        SpreeCmCommissioner::Stock::InventoryItemsAdjuster.call(variant: variant, quantity: quantity)
+        SpreeCmCommissioner::Stock::InventoryItemsAdjuster.call(variant: variant, quantity: options[:quantity])
       end
     end
   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/models/concerns/spree_cm_commissioner/integrations/integration_mappable.rb

@@ -0,0 +1,58 @@
+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
+      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

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

@@ -45,7 +45,8 @@ module SpreeCmCommissioner
       'color' => 'color',
       'ticket-type' => 'string',
       'seat-type' => 'string',
-      'intercity-taxi' => 'string'
+      'intercity-taxi' => 'string',
+      'rules' => 'string'
     }.freeze
 
     included do
@@ -56,7 +57,7 @@ module SpreeCmCommissioner
 
       validate :ensure_name_is_not_changed, on: :update
 
-      before_validation :set_reverved_options_attributes, if: :reserved_option?
+      before_validation :set_reserved_options_attributes, if: :reserved_option?
 
       after_save :sort_date_time_option_values, if: -> { attr_type == 'date' || attr_type == 'time' }
       after_save :update_variants_metadata, if: :saved_change_to_name?
@@ -68,6 +69,17 @@ module SpreeCmCommissioner
       end
     end
 
+    class_methods do
+      def rules_option_type = find_by(name: 'rules')
+
+      def ticket_type
+        Spree::OptionType.find_or_create_by!(name: 'ticket-type') do |ot|
+          ot.presentation = 'Ticket Type'
+          ot.kind = :variant
+        end
+      end
+    end
+
     def reserved_option?
       return name_was.in?(RESERVED_OPTIONS.keys) if name_changed?
 
@@ -78,7 +90,7 @@ module SpreeCmCommissioner
       name == 'ticket-type'
     end
 
-    def set_reverved_options_attributes
+    def set_reserved_options_attributes
       self.attr_type = RESERVED_OPTIONS[name]
       self.kind = :variant
     end

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

@@ -13,6 +13,7 @@
 # - integer
 # - array
 # - datetime
+# - hash
 #
 # Example usage:
 # ```
@@ -22,6 +23,7 @@
 #   store_public_metadata :completed, :boolean, default: true
 #   store_public_metadata :count, :integer, default: 5
 #   store_public_metadata :tags, :array, default: []
+#   store_public_metadata :tags, :hash
 #   store_private_metadata :app_token, :string,  default: "XYZ"
 #   store_public_metadata :scheduled_at, :datetime, default: Time.now
 # end
@@ -92,7 +94,7 @@ module SpreeCmCommissioner
       # - Return default if nil
       # - Cast to correct type
       # - Add `?` predicate for booleans
-      def define_metadata_reader(column_name, key, type, default)
+      def define_metadata_reader(column_name, key, type, default) # rubocop:disable Metrics/CyclomaticComplexity
         define_method(key) do
           metadata = send(column_name) || {}
           raw_value = metadata[key.to_s]
@@ -109,6 +111,8 @@ module SpreeCmCommissioner
             Array(raw_value)
           when :datetime
             Time.zone.parse(raw_value.to_s)
+          when :hash
+            raw_value.is_a?(Hash) ? raw_value : {}
           else
             raw_value
           end
@@ -118,7 +122,7 @@ module SpreeCmCommissioner
       end
 
       # Validates only new assignments (raw JSON values) for type safety
-      def define_metadata_validation(column_name, key, type) # rubocop:disable Metrics/CyclomaticComplexity,Metrics/MethodLength,Metrics/PerceivedComplexity
+      def define_metadata_validation(column_name, key, type) # rubocop:disable Metrics/CyclomaticComplexity,Metrics/MethodLength,Metrics/PerceivedComplexity,Metrics/AbcSize
         case type
         when :boolean
           validates key, inclusion: { in: [true, false] }, allow_nil: true
@@ -160,6 +164,14 @@ module SpreeCmCommissioner
               errors.add(key, 'is not a valid datetime')
             end
           end
+        when :hash
+          validate do
+            metadata = send(column_name) || {}
+            raw_value = metadata[key.to_s]
+            next if raw_value.nil?
+
+            errors.add(key, 'must be a hash') unless raw_value.is_a?(Hash)
+          end
         end
       end
     end

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

@@ -35,12 +35,6 @@ module SpreeCmCommissioner
                to: :options
     end
 
-    # Override variant.rb to return cached formatted options text, avoiding repeated database queries.
-    # Falls back to database queries & computing the format if preload data is unavailable.
-    def options_text
-      @options_text ||= public_metadata[:preload_options_text].presence || Spree::Variants::VisableOptionsPresenter.new(self).to_sentence
-    end
-
     def options
       @options ||= VariantOptions.new(self)
     end
@@ -111,7 +105,7 @@ module SpreeCmCommissioner
       # Precomputes the human-readable format (e.g., "Red, 256GB") to avoid
       # repeated formatting and association queries.
       # Example: {"color" => "red", "storage" => "256GB"} - option_type_name => option_value_name pairs
-      self.public_metadata[:preload_options_text] = Spree::Variants::VisableOptionsPresenter.new(self).to_sentence
+      self.public_metadata[:preload_options_text] = Spree::Variants::VisibleOptionsPresenter.new(self).to_sentence
     end
 
     def set_options_to_public_metadata!

data/app/models/spree_cm_commissioner/integration.rb

@@ -0,0 +1,21 @@
+module SpreeCmCommissioner
+  class Integration < Base
+    include StoreMetadata
+
+    enum status: { inactive: 0, active: 1, paused: 2 }
+    enum conflict_strategy: { newest_wins: 0, internal_wins: 1, external_wins: 2, manual_resolution: 3 }
+
+    belongs_to :tenant, class_name: 'SpreeCmCommissioner::Tenant', optional: true
+    belongs_to :vendor, class_name: 'Spree::Vendor', optional: false
+
+    has_many :integration_mappings, class_name: 'SpreeCmCommissioner::IntegrationMapping', dependent: :destroy, inverse_of: :integration
+    has_many :integration_sync_sessions, class_name: 'SpreeCmCommissioner::IntegrationSyncSession', dependent: :destroy, inverse_of: :integration
+
+    validates :incremental_sync_interval_seconds, presence: true, numericality: { only_integer: true, greater_than: 0, less_than_or_equal_to: 3600 }
+    validates :full_sync_interval_hours, presence: true, numericality: { only_integer: true, greater_than: 0, less_than_or_equal_to: 168 }
+
+    def sync_manager
+      raise NotImplementedError, 'Subclasses must implement the sync_manager method'
+    end
+  end
+end