feat: add assignment service

spec/services/auto_assignment/agent_assignment_service_spec.rb

@@ -1,5 +1,3 @@
-require 'rails_helper'
-
 RSpec.describe AutoAssignment::AgentAssignmentService do
   let!(:account) { create(:account) }
   let!(:inbox) { create(:inbox, account: account, enable_auto_assignment: false) }

spec/services/auto_assignment/assignment_service_basic_spec.rb

@@ -0,0 +1,81 @@
+require 'rails_helper'
+
+RSpec.describe AutoAssignment::AssignmentService do
+  let(:account) { create(:account) }
+  let(:inbox) { create(:inbox, account: account) }
+  let(:agent) { create(:user, account: account, role: :agent, availability: :online) }
+  let(:service) { described_class.new(inbox: inbox) }
+
+  before do
+    create(:inbox_member, inbox: inbox, user: agent)
+    allow(OnlineStatusTracker).to receive(:get_available_users)
+      .and_return({ agent.id.to_s => 'online' })
+  end
+
+  def create_test_conversation(attrs = {})
+    conversation = build(:conversation, attrs.reverse_merge(inbox: inbox, assignee: nil, status: :open))
+    allow(conversation).to receive(:run_auto_assignment).and_return(nil)
+    conversation.save!
+    conversation
+  end
+
+  describe 'basic assignment' do
+    context 'when auto assignment is enabled' do
+      before { inbox.update!(enable_auto_assignment: true) }
+
+      it 'assigns an available agent to conversation' do
+        conversation = create_test_conversation
+
+        result = service.perform_for_conversation(conversation)
+
+        expect(result).to be true
+        expect(conversation.reload.assignee).to eq(agent)
+      end
+
+      it 'returns false when no agents are online' do
+        allow(OnlineStatusTracker).to receive(:get_available_users).and_return({})
+        conversation = create_test_conversation
+
+        result = service.perform_for_conversation(conversation)
+
+        expect(result).to be false
+        expect(conversation.reload.assignee).to be_nil
+      end
+    end
+
+    context 'when auto assignment is disabled' do
+      before { inbox.update!(enable_auto_assignment: false) }
+
+      it 'does not assign any agent' do
+        conversation = create_test_conversation
+
+        result = service.perform_for_conversation(conversation)
+
+        expect(result).to be false
+        expect(conversation.reload.assignee).to be_nil
+      end
+    end
+  end
+
+  describe 'assignment conditions' do
+    before { inbox.update!(enable_auto_assignment: true) }
+
+    it 'only assigns to open conversations' do
+      resolved_conversation = create_test_conversation(status: 'resolved')
+
+      result = service.perform_for_conversation(resolved_conversation)
+
+      expect(result).to be false
+    end
+
+    it 'does not reassign already assigned conversations' do
+      other_agent = create(:user, account: account, role: :agent)
+      assigned_conversation = create_test_conversation(assignee: other_agent)
+
+      result = service.perform_for_conversation(assigned_conversation)
+
+      expect(result).to be false
+      expect(assigned_conversation.reload.assignee).to eq(other_agent)
+    end
+  end
+end

spec/services/auto_assignment/assignment_service_fair_distribution_spec.rb

@@ -0,0 +1,126 @@
+require 'rails_helper'
+
+RSpec.describe AutoAssignment::AssignmentService do
+  let(:account) { create(:account) }
+  let(:inbox) do
+    create(:inbox,
+           account: account,
+           enable_auto_assignment: true,
+           auto_assignment_config: {
+             'fair_distribution_limit' => 2,
+             'fair_distribution_window' => 3600
+           })
+  end
+  let(:service) { described_class.new(inbox: inbox) }
+  let(:agent1) { create(:user, account: account, role: :agent, availability: :online) }
+  let(:agent2) { create(:user, account: account, role: :agent, availability: :online) }
+
+  before do
+    create(:inbox_member, inbox: inbox, user: agent1)
+    create(:inbox_member, inbox: inbox, user: agent2)
+    allow(OnlineStatusTracker).to receive(:get_available_users)
+      .and_return({
+                    agent1.id.to_s => 'online',
+                    agent2.id.to_s => 'online'
+                  })
+    # Clean up Redis keys for this inbox
+    clean_redis_keys
+  end
+
+  after do
+    clean_redis_keys
+  end
+
+  def clean_redis_keys
+    # Clean up assignment keys for both agents
+    pattern1 = "assignment:#{inbox.id}:agent:#{agent1.id}:*"
+    pattern2 = "assignment:#{inbox.id}:agent:#{agent2.id}:*"
+
+    Redis::Alfred.scan_each(match: pattern1) { |key| Redis::Alfred.delete(key) }
+    Redis::Alfred.scan_each(match: pattern2) { |key| Redis::Alfred.delete(key) }
+  end
+
+  def create_test_conversation
+    conversation = build(:conversation, inbox: inbox, assignee: nil, status: :open)
+    allow(conversation).to receive(:run_auto_assignment).and_return(nil)
+    conversation.save!
+    conversation
+  end
+
+  describe 'with fair distribution enabled' do
+    it 'respects the assignment limit per agent' do
+      # Each agent can handle 2 conversations
+      conversations = Array.new(4) { create_test_conversation }
+
+      # First 4 conversations should be assigned (2 per agent)
+      conversations.each do |conv|
+        expect(service.perform_for_conversation(conv)).to be true
+      end
+
+      # Verify distribution
+      assigned_to_agent1 = conversations.count { |c| c.reload.assignee == agent1 }
+      assigned_to_agent2 = conversations.count { |c| c.reload.assignee == agent2 }
+
+      expect(assigned_to_agent1).to eq(2)
+      expect(assigned_to_agent2).to eq(2)
+
+      # Fifth conversation should fail (both agents at limit)
+      fifth_conversation = create_test_conversation
+      expect(service.perform_for_conversation(fifth_conversation)).to be false
+      expect(fifth_conversation.reload.assignee).to be_nil
+    end
+
+    it 'tracks assignments using individual Redis keys' do
+      conversation = create_test_conversation
+      service.perform_for_conversation(conversation)
+
+      # Check that assignment key exists
+      pattern = "assignment:#{inbox.id}:agent:#{conversation.reload.assignee.id}:*"
+      count = Redis::Alfred.keys_count(pattern)
+      expect(count).to eq(1)
+    end
+
+    it 'allows new assignments after window expires' do
+      # Assign 2 conversations to agent1
+      2.times do
+        conversation = create_test_conversation
+        allow(service).to receive(:round_robin_selector).and_return(
+          instance_double(AutoAssignment::RoundRobinSelector, select_agent: agent1)
+        )
+        service.perform_for_conversation(conversation)
+      end
+
+      # Agent1 is now at limit
+      rate_limiter = AutoAssignment::RateLimiter.new(inbox: inbox, agent: agent1)
+      expect(rate_limiter.within_limit?).to be false
+
+      # Clear Redis keys to simulate time window expiry
+      clean_redis_keys
+
+      # Agent1 should be available again
+      expect(rate_limiter.within_limit?).to be true
+
+      # New assignment should work
+      new_conversation = create_test_conversation
+      allow(service).to receive(:round_robin_selector).and_return(
+        instance_double(AutoAssignment::RoundRobinSelector, select_agent: agent1)
+      )
+      expect(service.perform_for_conversation(new_conversation)).to be true
+    end
+  end
+
+  describe 'without fair distribution' do
+    before do
+      inbox.update!(auto_assignment_config: {})
+    end
+
+    it 'assigns without limits' do
+      # Create more conversations than would be allowed with limits
+      5.times do
+        conversation = create_test_conversation
+        expect(service.perform_for_conversation(conversation)).to be true
+        expect(conversation.reload.assignee).not_to be_nil
+      end
+    end
+  end
+end

spec/services/auto_assignment/assignment_service_spec.rb

@@ -0,0 +1,186 @@
+require 'rails_helper'
+
+RSpec.describe AutoAssignment::AssignmentService do
+  let(:account) { create(:account) }
+  let(:inbox) { create(:inbox, account: account, enable_auto_assignment: true) }
+  let(:service) { described_class.new(inbox: inbox) }
+  let(:agent) { create(:user, account: account, role: :agent, availability: :online) }
+  let(:agent2) { create(:user, account: account, role: :agent, availability: :online) }
+
+  before do
+    create(:inbox_member, inbox: inbox, user: agent)
+  end
+
+  def create_test_conversation(attrs = {})
+    conversation = build(:conversation, attrs.reverse_merge(inbox: inbox, assignee: nil))
+    # Skip the after_save callback to test our service directly
+    allow(conversation).to receive(:run_auto_assignment).and_return(nil)
+    conversation.save!
+    conversation
+  end
+
+  describe '#perform_for_conversation' do
+    let(:conversation) { create_test_conversation }
+
+    before do
+      allow(OnlineStatusTracker).to receive(:get_available_users).and_return({ agent.id.to_s => 'online' })
+    end
+
+    context 'when auto assignment is enabled' do
+      it 'assigns conversation to available agent' do
+        expect(service.perform_for_conversation(conversation)).to be true
+        expect(conversation.reload.assignee).to eq(agent)
+      end
+
+      it 'dispatches assignee changed event' do
+        # The conversation update triggers its own event through callbacks
+        allow(Rails.configuration.dispatcher).to receive(:dispatch).and_call_original
+
+        expect(Rails.configuration.dispatcher).to receive(:dispatch).with(
+          Events::Types::ASSIGNEE_CHANGED,
+          anything,
+          hash_including(conversation: conversation, user: agent)
+        )
+
+        service.perform_for_conversation(conversation)
+      end
+
+      it 'returns false when no agents available' do
+        allow(OnlineStatusTracker).to receive(:get_available_users).and_return({})
+        expect(service.perform_for_conversation(conversation)).to be false
+      end
+    end
+
+    context 'when conversation already assigned' do
+      let(:conversation) { create_test_conversation(assignee: agent) }
+
+      it 'does not reassign' do
+        expect(service.perform_for_conversation(conversation)).to be false
+      end
+    end
+
+    context 'when conversation is not open' do
+      let(:conversation) { create_test_conversation(status: 'resolved') }
+
+      it 'does not assign' do
+        expect(service.perform_for_conversation(conversation)).to be false
+      end
+    end
+  end
+
+  describe '#perform_bulk_assignment' do
+    before do
+      allow(OnlineStatusTracker).to receive(:get_available_users).and_return({ agent.id.to_s => 'online' })
+      3.times { create_test_conversation(status: :open) }
+    end
+
+    it 'assigns multiple conversations' do
+      assigned_count = service.perform_bulk_assignment(limit: 2)
+      expect(assigned_count).to eq(2)
+    end
+
+    it 'respects the limit parameter' do
+      assigned_count = service.perform_bulk_assignment(limit: 1)
+      expect(assigned_count).to eq(1)
+      expect(inbox.conversations.unassigned.count).to eq(2)
+    end
+
+    context 'when auto assignment disabled' do
+      before { inbox.update!(enable_auto_assignment: false) }
+
+      it 'returns 0' do
+        expect(service.perform_bulk_assignment).to eq(0)
+      end
+    end
+  end
+
+  describe 'with rate limiting' do
+    let(:rate_limiter) { instance_double(AutoAssignment::RateLimiter) }
+
+    before do
+      create(:inbox_member, inbox: inbox, user: agent2)
+      allow(OnlineStatusTracker).to receive(:get_available_users).and_return({
+                                                                               agent.id.to_s => 'online',
+                                                                               agent2.id.to_s => 'online'
+                                                                             })
+      allow(inbox).to receive(:auto_assignment_config).and_return({
+                                                                    'fair_distribution_limit' => 2,
+                                                                    'fair_distribution_window' => 3600
+                                                                  })
+    end
+
+    it 'filters agents based on rate limits' do
+      # Agent 1 has reached limit
+      rate_limiter_agent1 = instance_double(AutoAssignment::RateLimiter, within_limit?: false)
+      allow(AutoAssignment::RateLimiter).to receive(:new)
+        .with(inbox: inbox, agent: agent)
+        .and_return(rate_limiter_agent1)
+
+      # Agent 2 is within limit
+      rate_limiter_agent2 = instance_double(AutoAssignment::RateLimiter, within_limit?: true, track_assignment: true)
+      allow(AutoAssignment::RateLimiter).to receive(:new)
+        .with(inbox: inbox, agent: agent2)
+        .and_return(rate_limiter_agent2)
+
+      conversation = create_test_conversation
+
+      expect(service.perform_for_conversation(conversation)).to be true
+      expect(conversation.reload.assignee).to eq(agent2)
+    end
+
+    it 'tracks assignments in Redis' do
+      conversation = create_test_conversation
+
+      rate_limiter = instance_double(AutoAssignment::RateLimiter, within_limit?: true)
+      allow(AutoAssignment::RateLimiter).to receive(:new).and_return(rate_limiter)
+
+      expect(rate_limiter).to receive(:track_assignment).with(conversation)
+
+      service.perform_for_conversation(conversation)
+    end
+  end
+
+  describe 'conversation priority' do
+    before do
+      allow(OnlineStatusTracker).to receive(:get_available_users).and_return({ agent.id.to_s => 'online' })
+    end
+
+    context 'with longest_waiting priority' do
+      let!(:old_conversation) do
+        create_test_conversation(status: :open, created_at: 2.hours.ago, last_activity_at: 2.hours.ago)
+      end
+      let!(:new_conversation) do
+        create_test_conversation(status: :open, created_at: 1.hour.ago, last_activity_at: 1.hour.ago)
+      end
+
+      before do
+        allow(inbox).to receive(:auto_assignment_config).and_return({
+                                                                      'conversation_priority' => 'longest_waiting'
+                                                                    })
+      end
+
+      it 'assigns oldest conversation first' do
+        service.perform_bulk_assignment(limit: 1)
+
+        expect(old_conversation.reload.assignee).to eq(agent)
+        expect(new_conversation.reload.assignee).to be_nil
+      end
+    end
+
+    context 'with default priority' do
+      let!(:first_created) do
+        create_test_conversation(status: :open, created_at: 2.hours.ago)
+      end
+      let!(:second_created) do
+        create_test_conversation(status: :open, created_at: 1.hour.ago)
+      end
+
+      it 'assigns by creation time' do
+        service.perform_bulk_assignment(limit: 1)
+
+        expect(first_created.reload.assignee).to eq(agent)
+        expect(second_created.reload.assignee).to be_nil
+      end
+    end
+  end
+end

spec/services/auto_assignment/inbox_round_robin_service_spec.rb

@@ -1,6 +1,4 @@
-require 'rails_helper'
-
-describe AutoAssignment::InboxRoundRobinService do
+RSpec.describe AutoAssignment::InboxRoundRobinService do
   subject(:inbox_round_robin_service) { described_class.new(inbox: inbox) }
 
   let!(:account) { create(:account) }

spec/services/auto_assignment/rate_limiter_spec.rb

@@ -0,0 +1,139 @@
+require 'rails_helper'
+
+RSpec.describe AutoAssignment::RateLimiter do
+  let(:account) { create(:account) }
+  let(:inbox) { create(:inbox, account: account) }
+  let(:agent) { create(:user, account: account, role: :agent) }
+  let(:conversation) { create(:conversation, inbox: inbox) }
+  let(:rate_limiter) { described_class.new(inbox: inbox, agent: agent) }
+
+  describe '#within_limit?' do
+    context 'when rate limiting is not enabled' do
+      before do
+        allow(inbox).to receive(:auto_assignment_config).and_return({})
+      end
+
+      it 'returns true' do
+        expect(rate_limiter.within_limit?).to be true
+      end
+    end
+
+    context 'when rate limiting is enabled' do
+      before do
+        allow(inbox).to receive(:auto_assignment_config).and_return({
+                                                                      'fair_distribution_limit' => 5,
+                                                                      'fair_distribution_window' => 3600
+                                                                    })
+      end
+
+      it 'returns true when under the limit' do
+        allow(rate_limiter).to receive(:current_count).and_return(3)
+        expect(rate_limiter.within_limit?).to be true
+      end
+
+      it 'returns false when at or over the limit' do
+        allow(rate_limiter).to receive(:current_count).and_return(5)
+        expect(rate_limiter.within_limit?).to be false
+      end
+    end
+  end
+
+  describe '#track_assignment' do
+    context 'when rate limiting is not enabled' do
+      before do
+        allow(inbox).to receive(:auto_assignment_config).and_return({})
+      end
+
+      it 'does not track the assignment' do
+        expect(Redis::Alfred).not_to receive(:set)
+        rate_limiter.track_assignment(conversation)
+      end
+    end
+
+    context 'when rate limiting is enabled' do
+      before do
+        allow(inbox).to receive(:auto_assignment_config).and_return({
+                                                                      'fair_distribution_limit' => 5,
+                                                                      'fair_distribution_window' => 3600
+                                                                    })
+      end
+
+      it 'creates a Redis key with correct expiry' do
+        expected_key = "assignment:#{inbox.id}:agent:#{agent.id}:conversation:#{conversation.id}"
+        expect(Redis::Alfred).to receive(:set).with(
+          expected_key,
+          conversation.id.to_s,
+          ex: 3600
+        )
+        rate_limiter.track_assignment(conversation)
+      end
+    end
+  end
+
+  describe '#current_count' do
+    context 'when rate limiting is not enabled' do
+      before do
+        allow(inbox).to receive(:auto_assignment_config).and_return({})
+      end
+
+      it 'returns 0' do
+        expect(rate_limiter.current_count).to eq(0)
+      end
+    end
+
+    context 'when rate limiting is enabled' do
+      before do
+        allow(inbox).to receive(:auto_assignment_config).and_return({
+                                                                      'fair_distribution_limit' => 5,
+                                                                      'fair_distribution_window' => 3600
+                                                                    })
+      end
+
+      it 'counts matching Redis keys' do
+        pattern = "assignment:#{inbox.id}:agent:#{agent.id}:*"
+        allow(Redis::Alfred).to receive(:keys_count).with(pattern).and_return(3)
+
+        expect(rate_limiter.current_count).to eq(3)
+      end
+    end
+  end
+
+  describe 'configuration' do
+    context 'with custom window' do
+      before do
+        allow(inbox).to receive(:auto_assignment_config).and_return({
+                                                                      'fair_distribution_limit' => 10,
+                                                                      'fair_distribution_window' => 7200
+                                                                    })
+      end
+
+      it 'uses the custom window value' do
+        expected_key = "assignment:#{inbox.id}:agent:#{agent.id}:conversation:#{conversation.id}"
+        expect(Redis::Alfred).to receive(:set).with(
+          expected_key,
+          conversation.id.to_s,
+          ex: 7200
+        )
+        rate_limiter.track_assignment(conversation)
+      end
+    end
+
+    context 'without custom window' do
+      before do
+        allow(inbox).to receive(:auto_assignment_config).and_return({
+                                                                      'fair_distribution_limit' => 10
+                                                                    })
+      end
+
+      it 'uses the default window value of 3600' do
+        expected_key = "assignment:#{inbox.id}:agent:#{agent.id}:conversation:#{conversation.id}"
+        expect(Redis::Alfred).to receive(:set).with(
+          expected_key,
+          conversation.id.to_s,
+          ex: 3600
+        )
+        rate_limiter.track_assignment(conversation)
+      end
+    end
+  end
+end