spree_cm_commissioner 2.4.3 → 2.5.0.pre.pre1

data/app/models/spree_cm_commissioner/integration_mapping.rb

@@ -0,0 +1,37 @@
+module SpreeCmCommissioner
+  class IntegrationMapping < Base
+    include StoreMetadata
+
+    enum status: { active: 0, archived: 1 }
+
+    # 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
+
+    validates :external_id, presence: true, uniqueness: { scope: %i[integration_id internal_type internal_id date] }
+    validate :validate_internal_exists, if: -> { internal_type.present? && internal_id.present? }
+
+    def mark_as_archived!
+      self.status = :archived
+      self.last_synced_at = Time.zone.now
+
+      save!
+    end
+
+    def mark_as_active!(external_payload:)
+      self.external_payload = external_payload
+      self.last_synced_at = Time.zone.now
+      self.status = :active
+
+      save!
+    end
+
+    private
+
+    def validate_internal_exists
+      return if internal_type.safe_constantize&.exists?(id: internal_id)
+
+      errors.add(:internal, "record (#{internal_type}##{internal_id}) does not exist")
+    end
+  end
+end

data/app/models/spree_cm_commissioner/integration_sync_session.rb

@@ -0,0 +1,15 @@
+module SpreeCmCommissioner
+  class IntegrationSyncSession < Base
+    include StoreMetadata
+
+    enum status: { pending: 0, in_progress: 1, completed: 2, failed: 3, canceled: 4 }
+    enum :sync_type, {
+      full: 0, # on initial setup or periodic complete refresh
+      incremental: 1, # on scheduled intervals to fetch recent changes
+      webhook_triggered: 2 # immediately when an external webhook event is received
+    }, prefix: true
+
+    belongs_to :tenant, class_name: 'SpreeCmCommissioner::Tenant', optional: true
+    belongs_to :integration, class_name: 'SpreeCmCommissioner::Integration', inverse_of: :integration_sync_sessions, optional: false
+  end
+end

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

@@ -0,0 +1,21 @@
+class SpreeCmCommissioner::Integrations::StadiumXV1 < SpreeCmCommissioner::Integration
+  store_private_metadata :public_key, :string
+  store_private_metadata :private_key, :string
+  store_private_metadata :base_url, :string # e.g. 'https://api.stadiumx.com'
+
+  # override
+  def sync_manager
+    SpreeCmCommissioner::Integrations::StadiumXV1::SyncManager.new(
+      integration: self,
+      client: client
+    )
+  end
+
+  def client
+    SpreeCmCommissioner::Integrations::StadiumXV1::ExternalClient::Client.new(
+      public_key: public_key,
+      private_key: private_key,
+      base_url: base_url
+    )
+  end
+end

data/app/models/spree_cm_commissioner/inventory_item.rb

@@ -56,8 +56,12 @@ module SpreeCmCommissioner
       "inventory:#{id}"
     end
 
+    def quantity_in_redis
+      SpreeCmCommissioner.inventory_redis_pool.with { |redis| redis.get(redis_key).to_i }
+    end
+
     def adjust_quantity_in_redis(quantity)
-      SpreeCmCommissioner.redis_pool.with do |redis|
+      SpreeCmCommissioner.inventory_redis_pool.with do |redis|
         # Always update Redis cache, even if it doesn't exist yet.
         # This prevents admin adjustments from being lost when cache is later initialized.
         script = <<~LUA

data/app/models/spree_cm_commissioner/option_type_decorator.rb

@@ -22,6 +22,14 @@ module SpreeCmCommissioner
       def base.rules_option_type
         Spree::OptionType.find_by(name: RULES_OPTION_TYPE_NAME)
       end
+
+      # override
+      def base.color
+        Spree::OptionType.find_or_create_by!(name: 'color') do |ot|
+          ot.presentation = 'Color'
+          ot.kind = :variant
+        end
+      end
     end
 
     private

data/app/models/spree_cm_commissioner/option_value_decorator.rb

@@ -3,6 +3,36 @@ module SpreeCmCommissioner
     def self.prepended(base)
       base.include SpreeCmCommissioner::OptionValueAttrType
       base.has_many :option_value_vehicles, class_name: 'SpreeCmCommissioner::OptionValueVehicle', foreign_key: :option_value_id, dependent: :destroy
+
+      base.validates :name, presence: true, uniqueness: { scope: :option_type_id, case_sensitive: -> { name_case_sensitive? } }
+
+      # Ticket types: case-SENSITIVE matching (preserve external API casing)
+      # Other types: case-INSENSITIVE storage (prevent duplicates from varying API casing; presentation keeps original)
+      def base.find_or_create_by_name!(option_type, name)
+        name = name.strip
+        if option_type.ticket_type?
+          where(option_type_id: option_type.id, name: name).first_or_create! do |ov|
+            ov.option_type = option_type
+            ov.name = name
+            ov.presentation = name
+          end
+        else
+          where(option_type_id: option_type.id).where('LOWER(name) = ?', name.downcase).first_or_create! do |ov|
+            ov.option_type = option_type
+            ov.name = name.downcase
+            ov.presentation = name
+          end
+        end
+      end
+    end
+
+    # Override Spree's name validation to make it case-sensitive only for ticket-type option values.
+    # Spree's default is case-insensitive (false), but we enforce case-sensitivity (true) for ticket-types.
+    # Which means ticket type "STANDARD" and "Standard" are different option values.
+    def name_case_sensitive?
+      return true if ticket_type?
+
+      false
     end
 
     def display_icon
@@ -14,5 +44,9 @@ module SpreeCmCommissioner
 end
 
 unless Spree::OptionValue.included_modules.include?(SpreeCmCommissioner::OptionValueDecorator)
+  # remove all name validations so we can override them in the decorator.
+  Spree::OptionValue._validators.reject! { |key, _| key == :name }
+  Spree::OptionValue._validate_callbacks.each { |c| c.filter.attributes.delete(:name) if c.filter.respond_to?(:attributes) }
+
   Spree::OptionValue.prepend SpreeCmCommissioner::OptionValueDecorator
 end

data/app/models/spree_cm_commissioner/product_decorator.rb

@@ -8,6 +8,7 @@ module SpreeCmCommissioner
       base.include SpreeCmCommissioner::TenantUpdatable
       base.include SpreeCmCommissioner::ServiceType
       base.include SpreeCmCommissioner::ServiceRecommendations
+      base.include SpreeCmCommissioner::Integrations::IntegrationMappable
 
       base.has_many :variant_kind_option_types, -> { where(kind: :variant).order(:position) },
                     through: :product_option_types, source: :option_type
@@ -89,7 +90,7 @@ module SpreeCmCommissioner
                                   request_to_book: 8
                                 }
 
-      base.multi_tenant :tenant, class_name: 'SpreeCmCommissioner::Tenant'
+      base.belongs_to :tenant, class_name: 'SpreeCmCommissioner::Tenant'
       base.before_save :set_tenant
     end
 
@@ -142,7 +143,7 @@ module SpreeCmCommissioner
     end
 
     def set_event_id
-      self.event_id = taxons.select(&:event?).first&.parent_id
+      self.event_id ||= taxons.select(&:event?).first&.parent_id
     end
 
     def update_variants_vendor_id

data/app/models/spree_cm_commissioner/redis_stock/cached_inventory_items_builder.rb

@@ -12,7 +12,7 @@ module SpreeCmCommissioner
         keys = inventory_items.map { |item| "inventory:#{item.id}" }
         return [] unless keys.any?
 
-        counts = SpreeCmCommissioner.redis_pool.with { |redis| redis.mget(*keys) }
+        counts = SpreeCmCommissioner.inventory_redis_pool.with { |redis| redis.mget(*keys) }
         inventory_items.map.with_index do |inventory_item, i|
           ::SpreeCmCommissioner::CachedInventoryItem.new(
             inventory_key: keys[i],
@@ -32,7 +32,7 @@ module SpreeCmCommissioner
 
         # Use atomic SET NX to prevent race condition where multiple concurrent reads
         # initialize cache with stale values. Only the first thread wins.
-        SpreeCmCommissioner.redis_pool.with do |redis|
+        SpreeCmCommissioner.inventory_redis_pool.with do |redis|
           redis.eval(set_nx_with_expiry_script, keys: [key], argv: [inventory_item.quantity_available, inventory_item.redis_expired_in])
         end
 

data/app/models/spree_cm_commissioner/redis_stock/inventory_updater.rb

@@ -51,13 +51,13 @@ module SpreeCmCommissioner
       end
 
       def unstock(keys, quantities)
-        SpreeCmCommissioner.redis_pool.with do |redis|
+        SpreeCmCommissioner.inventory_redis_pool.with do |redis|
           redis.eval(unstock_redis_script, keys: keys, argv: quantities)
         end.positive?
       end
 
       def restock(keys, quantities)
-        SpreeCmCommissioner.redis_pool.with do |redis|
+        SpreeCmCommissioner.inventory_redis_pool.with do |redis|
           redis.eval(restock_redis_script, keys: keys, argv: quantities)
         end.positive?
       end

data/app/models/spree_cm_commissioner/taxon_decorator.rb

@@ -5,6 +5,7 @@ module SpreeCmCommissioner
       base.include SpreeCmCommissioner::TaxonKind
       base.include SpreeCmCommissioner::ParticipationTypeBitwise
       base.include SpreeCmCommissioner::EventMetadata
+      base.include SpreeCmCommissioner::Integrations::IntegrationMappable
 
       base.has_many :taxon_vendors, class_name: 'SpreeCmCommissioner::TaxonVendor'
       base.has_many :vendors, through: :taxon_vendors

data/app/models/spree_cm_commissioner/taxonomy_decorator.rb

@@ -3,9 +3,21 @@ module SpreeCmCommissioner
     def self.prepended(base)
       base.include SpreeCmCommissioner::TaxonKind
 
+      def base.events
+        ActiveRecord::Base.connected_to(role: :writing) do
+          events = Spree::Taxonomy.find_or_create_by(name: 'Events', store: Spree::Store.default)
+          events.kind = :event
+          events.save if events.changed?
+          events
+        end
+      end
+
       def base.businesses
         ActiveRecord::Base.connected_to(role: :writing) do
-          Spree::Taxonomy.find_or_create_by(name: 'Businesses', kind: 'category', store: Spree::Store.default)
+          businesses = Spree::Taxonomy.find_or_create_by(name: 'Businesses', store: Spree::Store.default)
+          businesses.kind = :category
+          businesses.save if businesses.changed?
+          businesses
         end
       end
     end

data/app/models/spree_cm_commissioner/variant_decorator.rb

@@ -5,6 +5,7 @@ module SpreeCmCommissioner
       base.include SpreeCmCommissioner::ProductDelegation
       base.include SpreeCmCommissioner::VariantOptionsConcern
       base.include SpreeCmCommissioner::KycBitwise
+      base.include SpreeCmCommissioner::Integrations::IntegrationMappable
 
       base.after_commit :update_vendor_price
       base.validate     :validate_option_types
@@ -16,10 +17,6 @@ module SpreeCmCommissioner
       base.has_one :vehicle, class_name: 'SpreeCmCommissioner::Vehicle', through: :trip
 
       base.has_many :taxons, class_name: 'Spree::Taxon', through: :product
-      base.has_many :visible_option_values, lambda {
-                                              joins(:option_type).where(spree_option_types: { hidden: false })
-                                            }, through: :option_value_variants, source: :option_value
-
       base.has_many :video_on_demands, class_name: 'SpreeCmCommissioner::VideoOnDemand', dependent: :destroy
       base.has_many :complete_line_items, -> { complete }, class_name: 'Spree::LineItem'
 
@@ -42,6 +39,12 @@ module SpreeCmCommissioner
       base.before_validation -> { self.product_type = product.product_type }, if: -> { product_type.nil? }
     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
+      public_metadata[:preload_options_text].presence || Spree::Variants::VisibleOptionsPresenter.new(self).to_sentence
+    end
+
     def delivery_required?
       delivery_option == 'delivery'
     end

data/app/models/spree_cm_commissioner/vendor_decorator.rb

@@ -9,6 +9,7 @@ module SpreeCmCommissioner
       base.include SpreeCmCommissioner::VendorPreference
       base.include SpreeCmCommissioner::TenantUpdatable
       base.include SpreeCmCommissioner::StoreMetadata
+      base.include SpreeCmCommissioner::Integrations::IntegrationMappable
 
       base.attr_accessor :service_availabilities
 

data/app/overrides/spree/admin/shared/sub_menu/_integrations/external_integrations.html.erb.deface

@@ -0,0 +1,6 @@
+<!-- insert_bottom "[data-hook='admin_integrations']" -->
+
+<%= tab :integrations,
+        match_path: '/integrations',
+        label: Spree.t('admin.external_integrations_title'),
+        if: can?(:manage, SpreeCmCommissioner::Integration) %>

data/app/presenters/spree/variants/{visable_options_presenter.rb → visible_options_presenter.rb}

@@ -1,11 +1,9 @@
 module Spree
   module Variants
-    class VisableOptionsPresenter < OptionsPresenter
-      delegate :visible_option_values, to: :variant
-
+    class VisibleOptionsPresenter < OptionsPresenter
       # override
       def to_sentence
-        options = visible_option_values
+        options = variant.option_values.reject { |ov| ov.option_type.hidden? }
         options = sort_options(options)
         options = present_options(options)
 

data/app/services/spree_cm_commissioner/integrations/base/sync_manager.rb

@@ -0,0 +1,69 @@
+module SpreeCmCommissioner::Integrations::Base
+  class SyncManager
+    def initialize(integration:, client:)
+      @integration = integration
+      @client = client
+      @sync_session = nil
+    end
+
+    # Perform a full synchronization (initial setup or complete refresh)
+    # Override in subclass and use run_execution to wrap your sync logic
+    # @return [SpreeCmCommissioner::IntegrationSyncSession] The sync session record
+    # @raise [SyncError] if sync fails
+    def sync_full!
+      raise NotImplementedError, "#{self.class.name} must implement #sync_full!"
+    end
+
+    # Perform an incremental synchronization (delta updates)
+    # Override in subclass and use run_execution to wrap your sync logic
+    # @return [SpreeCmCommissioner::IntegrationSyncSession] The sync session record
+    # @raise [SyncError] if sync fails or not supported
+    def sync_incremental!
+      raise NotImplementedError, "#{self.class.name} must implement #sync_incremental!"
+    end
+
+    # Perform a webhook-triggered synchronization (real-time event)
+    # Override in subclass and use run_execution to wrap your sync logic
+    # @param event_type [String] The type of event (e.g., 'match.updated', 'ticket.created')
+    # @param event_data [Hash] The event payload
+    # @return [SpreeCmCommissioner::IntegrationSyncSession] The sync session record
+    # @raise [SyncError] if sync fails or not supported
+    def sync_webhook!(event_type:, event_data:)
+      raise NotImplementedError, "#{self.class.name} must implement #sync_webhook!"
+    end
+
+    protected
+
+    # Wrapper for sync execution that handles session creation and persistence
+    # Strategies handle errors internally and always return a SyncResult object
+    # This method never throws errors - it always returns a sync session
+    #
+    # @param sync_type [Symbol] The type of sync (:full, :incremental, :webhook_triggered)
+    # @yield Block containing the actual sync logic, must return a SyncResult object
+    # @return [SpreeCmCommissioner::IntegrationSyncSession] The sync session record
+    def run_execution(sync_type)
+      @sync_session = create_sync_session(sync_type)
+      sync_result = yield
+
+      @sync_session.update!(
+        status: sync_result.success? ? :completed : :failed,
+        ended_at: Time.zone.now,
+        sync_result: sync_result.to_h
+      )
+
+      @sync_session
+    end
+
+    private
+
+    def create_sync_session(sync_type)
+      SpreeCmCommissioner::IntegrationSyncSession.create!(
+        integration: @integration,
+        tenant: @integration.tenant,
+        status: :in_progress,
+        started_at: Time.zone.now,
+        sync_type: sync_type
+      )
+    end
+  end
+end

data/app/services/spree_cm_commissioner/integrations/base/sync_result.rb

@@ -0,0 +1,183 @@
+module SpreeCmCommissioner::Integrations::Base
+  # Base class for sync results
+  # Provides standardized tracking methods for API calls and record changes
+  #
+  # Persists to database as JSONB in CmIntegrationSyncSession#sync_result column
+  # Enables comprehensive sync monitoring and debugging:
+  #   - Track success/failure status
+  #   - Monitor API call counts and patterns
+  #   - Audit record creation/update counts
+  #   - Capture error details with automatic error codes
+  #   - Generate sync performance reports
+  #   - Identify patterns in failed syncs
+  #
+  # Example persisted results:
+  #
+  # Success:
+  #   {
+  #     "metrics": { "match": { "created": 2, "updated": 1, "total": 3 } },
+  #     "api_calls": { "get_matches": 1, "get_match_details": 3 }
+  #   }
+  #
+  # Failure:
+  #   {
+  #     "metrics": { "match": { "created": 1, "total": 1 } },
+  #     "api_calls": { "get_matches": 1 },
+  #     "error": { "message": "Failed to sync matches: Connection timeout", "code": "ExternalClientError" }
+  #   }
+  class SyncResult
+    def initialize
+      @metrics = {}
+      @api_calls = {}
+      @error = nil
+    end
+
+    # Track API call with block
+    # Automatically increments the call count and executes the block
+    # Failed calls (exceptions) are not counted
+    #
+    # @param call_name [String] Name of the API call (e.g., 'get_matches', 'get_zones')
+    # @yield Block containing the API call
+    # @return Result of the block
+    #
+    # Example:
+    #   external_matches = track_api_call('get_matches') { @client.get_matches! }
+    def track_api_call(call_name)
+      @api_calls[call_name] = (@api_calls[call_name] || 0) + 1
+      yield
+    end
+
+    # Track synced record with block
+    # Automatically detects if record was created or updated based on new_record? and saved_changes
+    #
+    # @param type [Symbol, String] Type of record (e.g., :match, :zone)
+    # @param record [Object] The record being synced (must respond to new_record? and saved_changes)
+    # @yield Block containing the save/update logic
+    # @return Result of the block
+    #
+    # Example:
+    #   track_synced_record(:match, match_taxon) do
+    #     match_taxon.assign_attributes(name: 'ISI Dangkorsenchey FC vs ANGKOR TIGER FC')
+    #     match_taxon.save!
+    #   end
+    def track_synced_record(type, record)
+      was_new = record.new_record?
+      result = yield
+
+      if was_new
+        increment_metric(type, :created)
+      elsif record.saved_changes.any?
+        increment_metric(type, :updated)
+      end
+
+      result
+    end
+
+    # Track and sync record with explicit tracker object
+    # Provides a tracker object with helper methods for explicit save/tracking operations
+    #
+    # @param type [Symbol, String] Type of record (e.g., :league, :match, :zone, :variant)
+    # @param record [Object] The record being synced (must respond to new_record? and saved_changes)
+    # @yield Block receiving tracker object for explicit operations
+    # @return Result of the block
+    #
+    # Example:
+    #   track(:zone, product) do |tracker|
+    #     product.assign_attributes(name: 'Zone A', price: 100)
+    #     tracker.save_if_changed!(product)
+    #   end
+    def track(type, record)
+      tracker = RecordTracker.new(self, type, record)
+      yield tracker
+      tracker
+    end
+
+    # Helper class for explicit record tracking and saving
+    class RecordTracker
+      def initialize(sync_result, type, record)
+        @sync_result = sync_result
+        @type = type
+        @record = record
+        @was_new = record.new_record?
+      end
+
+      # Save record if it's new or has changes, and track the operation
+      # Automatically detects create vs update based on initial state
+      #
+      # @param record [Object] The record to save (defaults to the tracked record)
+      def save_if_changed!(record = @record)
+        return unless record.new_record? || record.changed?
+
+        record.save!
+
+        # Track based on initial state
+        if @was_new
+          @sync_result.increment_metric(@type, :created)
+        else
+          @sync_result.increment_metric(@type, :updated)
+        end
+      end
+    end
+
+    # Increment a metric counter
+    # Useful for tracking actions that don't fit the created/updated pattern
+    #
+    # @param type [Symbol, String] Type of metric (e.g., :match, :inventory)
+    # @param action [Symbol, String] Action performed (e.g., :archived, :adjustments)
+    # @param amount [Integer] Amount to increment by (default: 1)
+    #
+    # Example:
+    #   increment_metric(:match, :archived)                              # increment by 1
+    #   increment_metric(:inventory, :total_quantity_adjusted, 50)       # increment by 50
+    def increment_metric(type, action, amount = 1)
+      @metrics[type.to_sym] ||= {}
+      @metrics[type.to_sym][action.to_sym] ||= 0
+      @metrics[type.to_sym][action.to_sym] += amount
+
+      update_metric_total(type)
+    end
+
+    # Record error
+    # @param error [StandardError] The error that occurred
+    def record_error(error)
+      @error = {
+        message: error.message,
+        code: error.class.name.split('::').last
+      }
+    end
+
+    # Check if sync was successful
+    # @return [Boolean] True if no error, false otherwise
+    def success?
+      @error.nil?
+    end
+
+    # Serialize to hash for JSONB persistence
+    # @return [Hash] Serialized representation
+    def to_h
+      {
+        metrics: @metrics,
+        api_calls: @api_calls,
+        error: @error
+      }.tap do |hash|
+        hash.delete(:error) if @error.nil?
+        hash.delete(:metrics) if @metrics.empty?
+        hash.delete(:api_calls) if @api_calls.empty?
+      end
+    end
+
+    private
+
+    # Update total for a metric type
+    # Sums all numeric values in the metric hash
+    def update_metric_total(type)
+      metric = @metrics[type.to_sym]
+      return unless metric.is_a?(Hash)
+
+      # Calculate total from numeric values only
+      numeric_values = metric.select { |k, v| v.is_a?(Integer) && k != :total }
+      total = numeric_values.values.sum
+      metric[:total] = total if total.positive?
+    end
+  end
+end

data/app/services/spree_cm_commissioner/integrations/polling.rb

@@ -0,0 +1,70 @@
+module SpreeCmCommissioner
+  module Integrations
+    class Polling
+      def call(integration:, sync_type:, event_type: nil, event_data: nil)
+        sync_manager = integration.sync_manager
+
+        case sync_type.to_sym
+        when :full
+          perform_full_sync!(sync_manager, integration)
+        when :incremental
+          perform_incremental_sync!(sync_manager, integration)
+        when :webhook_triggered
+          perform_webhook_sync!(sync_manager, integration, event_type, event_data)
+        else
+          raise ArgumentError, "Unknown sync type: #{sync_type}"
+        end
+      end
+
+      private
+
+      # Perform a full sync
+      # @param sync_manager [Object] The integration's sync manager
+      # @param integration [SpreeCmCommissioner::Integration]
+      def perform_full_sync!(sync_manager, integration)
+        CmAppLogger.log(
+          label: 'Integrations::IntegrationPullJob#perform_full_sync! Starting full sync',
+          data: {
+            integration_id: integration.id,
+            integration_type: integration.class.name
+          }
+        ) do
+          sync_manager.sync_full!
+        end
+      end
+
+      # Perform an incremental sync
+      # @param sync_manager [Object] The integration's sync manager
+      # @param integration [SpreeCmCommissioner::Integration]
+      def perform_incremental_sync!(sync_manager, integration)
+        CmAppLogger.log(
+          label: 'Integrations::IntegrationPullJob#perform_incremental_sync! Starting incremental sync',
+          data: {
+            integration_id: integration.id,
+            integration_type: integration.class.name
+          }
+        ) do
+          sync_manager.sync_incremental!
+        end
+      end
+
+      # Perform a webhook-triggered sync
+      # @param sync_manager [Object] The integration's sync manager
+      # @param integration [SpreeCmCommissioner::Integration]
+      # @param event_type [String] The event type
+      # @param event_data [Hash] The event data
+      def perform_webhook_sync!(sync_manager, integration, event_type, event_data)
+        CmAppLogger.log(
+          label: 'Integrations::IntegrationPullJob#perform_webhook_sync! Starting webhook sync',
+          data: {
+            integration_id: integration.id,
+            integration_type: integration.class.name,
+            event_type: event_type
+          }
+        ) do
+          sync_manager.sync_webhook!(event_type: event_type, event_data: event_data)
+        end
+      end
+    end
+  end
+end