feat: Make state change tracker a configurable class

Currently we always enqueues a ActiveJob, but some stores
maybe want to inline the state changes or add more information
to the state change record. This allows to set your own state
change tracker class. It defaults to the current behavior.

Author: tvdeyen

core/app/models/concerns/spree/state_change_tracking.rb

@@ -15,11 +15,11 @@ def enqueue_state_change_tracking
       previous_state, current_state = saved_changes['state']
 
       # Enqueue the job to track this state change
-      StateChangeTrackingJob.perform_later(
-        self,
-        previous_state,
-        current_state,
-        Time.current
+      Spree::Config.state_change_tracking_class.call(
+        stateful: self,
+        previous_state:,
+        current_state:,
+        transition_timestamp: Time.current
       )
     end
   end

core/app/models/spree/state_change_tracker.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Spree
+  # Configurable class to enqueue state change tracking jobs
+  # Configure your custom logic by setting Spree::Config.state_change_tracking_class
+  # @example Spree::Config.state_change_tracking_class = MyCustomTracker
+  class StateChangeTracker
+    # @param stateful [Object] The stateful object to track changes for
+    # @param previous_state [String] The previous state of the order
+    # @param current_state [String] The current state of the order
+    # @param transition_timestamp [Time] When the state transition occurred
+    # @param stateful_name [String] The element name of the state transition being
+    #   tracked. It defaults to the `stateful` model element name.
+    def self.call(
+      stateful:,
+      previous_state:,
+      current_state:,
+      transition_timestamp:,
+      stateful_name: stateful.class.model_name.element
+    )
+      # Enqueue a background job to track this state change
+      StateChangeTrackingJob.perform_later(
+        stateful,
+        previous_state,
+        current_state,
+        transition_timestamp,
+        stateful_name
+      )
+    end
+  end
+end

core/lib/spree/app_configuration.rb

@@ -549,6 +549,13 @@ def payment_canceller
                                                           product: '680x680>',
                                                           large: '1200x1200>' }
 
+    # Allows to provide your own class for tracking state changes of stateful models
+    #
+    # @!attribute [rw] state_change_tracking_class
+    # @return [Class] a class with the same public interfaces as
+    #   Spree::StateChangeTracker.
+    class_name_attribute :state_change_tracking_class, default: "Spree::StateChangeTracker"
+
     # Allows providing your own class for prioritizing store credit application
     # to an order.
     #

core/spec/lib/spree/app_configuration_spec.rb

@@ -44,6 +44,10 @@
     expect(prefs.variant_price_selector_class).to eq Spree::Variant::PriceSelector
   end
 
+  it "uses state change tracker class by default" do
+    expect(prefs.state_change_tracking_class).to eq Spree::StateChangeTracker
+  end
+
   it "uses core's promotion configuration class by default" do
     expect(prefs.promotions).to be_a Spree::Core::NullPromotionConfiguration
   end

core/spec/models/spree/order_spec.rb

@@ -2175,7 +2175,8 @@ def validate(line_item)
         order,
         'cart',
         'address',
-        kind_of(Time)
+        kind_of(Time),
+        'order'
       )
     end
 
@@ -2195,7 +2196,8 @@ def validate(line_item)
           order,
           'cart',
           'address',
-          kind_of(Time)
+          kind_of(Time),
+        'order'
         )
       end
     end

core/spec/models/spree/payment_spec.rb

@@ -1344,7 +1344,8 @@
         payment,
         'checkout',
         'completed',
-        kind_of(Time)
+        kind_of(Time),
+        'payment'
       )
     end
 

core/spec/models/spree/shipment_spec.rb

@@ -959,7 +959,8 @@
         shipment,
         'pending',
         'shipped',
-        kind_of(Time)
+        kind_of(Time),
+        'shipment'
       )
     end
 

core/spec/models/spree/state_change_tracker_spec.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+
+RSpec.describe Spree::StateChangeTracker, type: :model do
+  let(:order) { create(:order) }
+  let(:transition_timestamp) { Time.current }
+
+  describe "#call" do
+    it "enqueues a StateChangeTrackingJob with correct arguments" do
+      expect {
+        described_class.call(
+          stateful: order,
+          previous_state: "cart",
+          current_state: "address",
+          transition_timestamp: transition_timestamp,
+          stateful_name: "order"
+        )
+      }.to have_enqueued_job(Spree::StateChangeTrackingJob).with(
+        order,
+        "cart",
+        "address",
+        transition_timestamp,
+        "order"
+      )
+    end
+  end
+end