feat: Assignment service (v2) (#12320)

## Linear Link

 
## Description

This PR introduces a new robust auto-assignment system for conversations
in Chatwoot. The system replaces the existing round-robin assignment
with a more sophisticated service-based architecture that supports
multiple assignment strategies, rate limiting, and Enterprise features
like capacity-based assignment and balanced distribution.

## Type of change

- [ ] New feature (non-breaking change which adds functionality)

## How Has This Been Tested?

- Unit test cases
- Test conversations getting assigned on status change to open
- Test the job directly via rails console

## Checklist:

- [ ] My code follows the style guidelines of this project
- [ ] I have performed a self-review of my code
- [ ] I have commented on my code, particularly in hard-to-understand
areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my
feature works
- [ ] New and existing unit tests pass locally with my changes
- [ ] Any dependent changes have been merged and published in downstream
modules

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> Adds a new service-based auto-assignment system with scheduled jobs,
rate limiting, enterprise capacity/balanced selection, and wiring via
inbox/handler; includes Redis helpers and comprehensive tests.
> 
> - **Auto-assignment v2 (core services)**:
> - Add `AutoAssignment::AssignmentService` with bulk assignment,
configurable conversation priority, RR selection, and per-agent rate
limiting via `AutoAssignment::RateLimiter`.
>   - Add `AutoAssignment::RoundRobinSelector` for agent selection.
> - **Jobs & scheduling**:
> - Add `AutoAssignment::AssignmentJob` (per-inbox bulk assign;
env-based limit) and `AutoAssignment::PeriodicAssignmentJob` (batch over
accounts/inboxes).
> - Schedule periodic run in `config/schedule.yml`
(`periodic_assignment_job`).
> - **Model/concerns wiring**:
> - Include `InboxAgentAvailability` in `Inbox`; add
`Inbox#auto_assignment_v2_enabled?`.
> - Update `AutoAssignmentHandler` to trigger v2 job when
`auto_assignment_v2_enabled?`, else fallback to legacy.
> - **Enterprise extensions**:
> - Add `Enterprise::InboxAgentAvailability` (capacity-aware filtering)
and `Enterprise::Concerns::Inbox` association `inbox_capacity_limits`.
> - Extend service via `Enterprise::AutoAssignment::AssignmentService`
(policy-driven config, capacity filtering, exclusion rules) and add
selectors/services: `BalancedSelector`, `CapacityService`.
> - **Infrastructure**:
> - Enhance `Redis::Alfred` with `expire`, key scan/count, and extended
ZSET helpers (`zadd`, `zcount`, `zcard`, `zrangebyscore`).
> - **Tests**:
> - Add specs for jobs, core service, rate limiter, RR selector, and
enterprise features (capacity, balanced selection, exclusions).
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
0ebe187c8aea73765b0122a44b18d6f465c2477f. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

---------

Co-authored-by: Muhsin Keloth <muhsinkeramam@gmail.com>
Co-authored-by: Shivam Mishra <scm.mymail@gmail.com>
This commit is contained in:
Tanmay Deep Sharma
2025-11-17 10:08:25 +05:30
committed by GitHub
parent 2c4e65d68e
commit c9823d9409
24 changed files with 1622 additions and 5 deletions

View File

@@ -0,0 +1,310 @@
require 'rails_helper'
RSpec.describe AutoAssignment::AssignmentService do
let(:account) { create(:account) }
let(:assignment_policy) { create(:assignment_policy, account: account, enabled: true) }
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) }
let(:conversation) { create(:conversation, inbox: inbox, assignee: nil) }
before do
# Enable assignment_v2 feature for the account
allow(account).to receive(:feature_enabled?).with('assignment_v2').and_return(true)
# Link inbox to assignment policy
create(:inbox_assignment_policy, inbox: inbox, assignment_policy: assignment_policy)
create(:inbox_member, inbox: inbox, user: agent)
end
describe '#perform_bulk_assignment' do
context 'when auto assignment is enabled' do
let(:rate_limiter) { instance_double(AutoAssignment::RateLimiter) }
before do
allow(OnlineStatusTracker).to receive(:get_available_users).and_return({ agent.id.to_s => 'online' })
# Mock RoundRobinSelector to return the agent
round_robin_selector = instance_double(AutoAssignment::RoundRobinSelector)
allow(AutoAssignment::RoundRobinSelector).to receive(:new).and_return(round_robin_selector)
allow(round_robin_selector).to receive(:select_agent).and_return(agent)
# Mock RateLimiter to allow all assignments by default
allow(AutoAssignment::RateLimiter).to receive(:new).and_return(rate_limiter)
allow(rate_limiter).to receive(:within_limit?).and_return(true)
allow(rate_limiter).to receive(:track_assignment)
end
it 'assigns conversations to available agents' do
# Create conversation and ensure it's unassigned
conv = create(:conversation, inbox: inbox, status: 'open')
conv.update!(assignee_id: nil)
assigned_count = service.perform_bulk_assignment(limit: 1)
expect(assigned_count).to eq(1)
expect(conv.reload.assignee).to eq(agent)
end
it 'returns 0 when no agents are online' do
allow(OnlineStatusTracker).to receive(:get_available_users).and_return({})
assigned_count = service.perform_bulk_assignment(limit: 1)
expect(assigned_count).to eq(0)
expect(conversation.reload.assignee).to be_nil
end
it 'respects the limit parameter' do
3.times do
conv = create(:conversation, inbox: inbox, status: 'open')
conv.update!(assignee_id: nil)
end
assigned_count = service.perform_bulk_assignment(limit: 2)
expect(assigned_count).to eq(2)
expect(inbox.conversations.unassigned.count).to eq(1)
end
it 'only assigns open conversations' do
conversation # ensure it exists
conversation.update!(assignee_id: nil)
resolved_conversation = create(:conversation, inbox: inbox, status: 'resolved')
resolved_conversation.update!(assignee_id: nil)
service.perform_bulk_assignment(limit: 10)
expect(conversation.reload.assignee).to eq(agent)
expect(resolved_conversation.reload.assignee).to be_nil
end
it 'does not reassign already assigned conversations' do
conversation # ensure it exists
conversation.update!(assignee_id: nil)
assigned_conversation = create(:conversation, inbox: inbox, assignee: agent)
unassigned_conversation = create(:conversation, inbox: inbox, status: 'open')
unassigned_conversation.update!(assignee_id: nil)
assigned_count = service.perform_bulk_assignment(limit: 10)
expect(assigned_count).to eq(2) # conversation + unassigned_conversation
expect(assigned_conversation.reload.assignee).to eq(agent)
expect(unassigned_conversation.reload.assignee).to eq(agent)
end
it 'dispatches assignee changed event' do
conversation # ensure it exists
conversation.update!(assignee_id: nil)
# The conversation model also dispatches a conversation.updated event
allow(Rails.configuration.dispatcher).to receive(:dispatch)
expect(Rails.configuration.dispatcher).to receive(:dispatch).with(
Events::Types::ASSIGNEE_CHANGED,
anything,
hash_including(conversation: conversation, user: agent)
)
service.perform_bulk_assignment(limit: 1)
end
end
context 'when auto assignment is disabled' do
before { assignment_policy.update!(enabled: false) }
it 'returns 0 without processing' do
assigned_count = service.perform_bulk_assignment(limit: 10)
expect(assigned_count).to eq(0)
expect(conversation.reload.assignee).to be_nil
end
end
context 'with conversation priority' do
let(:rate_limiter) { instance_double(AutoAssignment::RateLimiter) }
before do
allow(OnlineStatusTracker).to receive(:get_available_users).and_return({ agent.id.to_s => 'online' })
# Mock RoundRobinSelector to return the agent
round_robin_selector = instance_double(AutoAssignment::RoundRobinSelector)
allow(AutoAssignment::RoundRobinSelector).to receive(:new).and_return(round_robin_selector)
allow(round_robin_selector).to receive(:select_agent).and_return(agent)
# Mock RateLimiter to allow all assignments by default
allow(AutoAssignment::RateLimiter).to receive(:new).and_return(rate_limiter)
allow(rate_limiter).to receive(:within_limit?).and_return(true)
allow(rate_limiter).to receive(:track_assignment)
end
context 'when priority is longest_waiting' do
before do
allow(inbox).to receive(:auto_assignment_config).and_return({ 'conversation_priority' => 'longest_waiting' })
end
it 'assigns conversations with oldest last_activity_at first' do
old_conversation = create(:conversation,
inbox: inbox,
status: 'open',
created_at: 2.hours.ago,
last_activity_at: 2.hours.ago)
old_conversation.update!(assignee_id: nil)
new_conversation = create(:conversation,
inbox: inbox,
status: 'open',
created_at: 1.hour.ago,
last_activity_at: 1.hour.ago)
new_conversation.update!(assignee_id: nil)
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 'when priority is default' do
it 'assigns conversations by created_at' do
old_conversation = create(:conversation, inbox: inbox, status: 'open', created_at: 2.hours.ago)
old_conversation.update!(assignee_id: nil)
new_conversation = create(:conversation, inbox: inbox, status: 'open', created_at: 1.hour.ago)
new_conversation.update!(assignee_id: nil)
service.perform_bulk_assignment(limit: 1)
expect(old_conversation.reload.assignee).to eq(agent)
expect(new_conversation.reload.assignee).to be_nil
end
end
end
context 'with fair distribution' do
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'
})
end
context 'when fair distribution is enabled' do
before do
allow(inbox).to receive(:auto_assignment_config).and_return({
'fair_distribution_limit' => 2,
'fair_distribution_window' => 3600
})
end
it 'respects the assignment limit per agent' do
# Mock RoundRobinSelector to select agent2
round_robin_selector = instance_double(AutoAssignment::RoundRobinSelector)
allow(AutoAssignment::RoundRobinSelector).to receive(:new).and_return(round_robin_selector)
allow(round_robin_selector).to receive(:select_agent).and_return(agent2)
# Mock agent1 at limit, agent2 not at limit
agent1_limiter = instance_double(AutoAssignment::RateLimiter)
agent2_limiter = instance_double(AutoAssignment::RateLimiter)
allow(AutoAssignment::RateLimiter).to receive(:new).with(inbox: inbox, agent: agent).and_return(agent1_limiter)
allow(AutoAssignment::RateLimiter).to receive(:new).with(inbox: inbox, agent: agent2).and_return(agent2_limiter)
allow(agent1_limiter).to receive(:within_limit?).and_return(false)
allow(agent2_limiter).to receive(:within_limit?).and_return(true)
allow(agent2_limiter).to receive(:track_assignment)
unassigned_conversation = create(:conversation, inbox: inbox, status: 'open')
unassigned_conversation.update!(assignee_id: nil)
service.perform_bulk_assignment(limit: 1)
expect(unassigned_conversation.reload.assignee).to eq(agent2)
end
it 'tracks assignments in Redis' do
conversation # ensure it exists
conversation.update!(assignee_id: nil)
# Mock RoundRobinSelector
round_robin_selector = instance_double(AutoAssignment::RoundRobinSelector)
allow(AutoAssignment::RoundRobinSelector).to receive(:new).and_return(round_robin_selector)
allow(round_robin_selector).to receive(:select_agent).and_return(agent)
limiter = instance_double(AutoAssignment::RateLimiter)
allow(AutoAssignment::RateLimiter).to receive(:new).and_return(limiter)
allow(limiter).to receive(:within_limit?).and_return(true)
expect(limiter).to receive(:track_assignment)
service.perform_bulk_assignment(limit: 1)
end
it 'allows assignments after window expires' do
# Mock RoundRobinSelector
round_robin_selector = instance_double(AutoAssignment::RoundRobinSelector)
allow(AutoAssignment::RoundRobinSelector).to receive(:new).and_return(round_robin_selector)
allow(round_robin_selector).to receive(:select_agent).and_return(agent, agent2)
# Mock RateLimiter to allow all
limiter = instance_double(AutoAssignment::RateLimiter)
allow(AutoAssignment::RateLimiter).to receive(:new).and_return(limiter)
allow(limiter).to receive(:within_limit?).and_return(true)
allow(limiter).to receive(:track_assignment)
# Simulate time passing for rate limit window
freeze_time do
2.times do
conversation_new = create(:conversation, inbox: inbox, status: 'open')
conversation_new.update!(assignee_id: nil)
service.perform_bulk_assignment(limit: 1)
expect(conversation_new.reload.assignee).not_to be_nil
end
end
# Move forward past the window
travel_to(2.hours.from_now) do
new_conversation = create(:conversation, inbox: inbox, status: 'open')
new_conversation.update!(assignee_id: nil)
service.perform_bulk_assignment(limit: 1)
expect(new_conversation.reload.assignee).not_to be_nil
end
end
end
context 'when fair distribution is disabled' do
it 'assigns without rate limiting' do
5.times do
conv = create(:conversation, inbox: inbox, status: 'open')
conv.update!(assignee_id: nil)
end
# Mock RoundRobinSelector
round_robin_selector = instance_double(AutoAssignment::RoundRobinSelector)
allow(AutoAssignment::RoundRobinSelector).to receive(:new).and_return(round_robin_selector)
allow(round_robin_selector).to receive(:select_agent).and_return(agent)
# Mock RateLimiter to allow all
limiter = instance_double(AutoAssignment::RateLimiter)
allow(AutoAssignment::RateLimiter).to receive(:new).and_return(limiter)
allow(limiter).to receive(:within_limit?).and_return(true)
allow(limiter).to receive(:track_assignment)
assigned_count = service.perform_bulk_assignment(limit: 5)
expect(assigned_count).to eq(5)
end
end
context 'with round robin assignment' do
it 'distributes conversations evenly among agents' do
conversations = Array.new(4) { create(:conversation, inbox: inbox, assignee: nil) }
service.perform_bulk_assignment(limit: 4)
agent1_count = conversations.count { |c| c.reload.assignee == agent }
agent2_count = conversations.count { |c| c.reload.assignee == agent2 }
# Should be distributed evenly (2 each) or close to even (3 and 1)
expect([agent1_count, agent2_count].sort).to eq([2, 2]).or(eq([1, 3]))
end
end
end
end
end

View File

@@ -0,0 +1,167 @@
require 'rails_helper'
RSpec.describe AutoAssignment::RateLimiter do
# Stub Math methods for testing when assignment_policy is nil
# rubocop:disable RSpec/BeforeAfterAll, RSpec/InstanceVariable
before(:all) do
@math_had_positive = Math.respond_to?(:positive?)
Math.define_singleton_method(:positive?) { false } unless @math_had_positive
end
after(:all) do
Math.singleton_class.send(:remove_method, :positive?) unless @math_had_positive
end
# rubocop:enable RSpec/BeforeAfterAll, RSpec/InstanceVariable
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(:assignment_policy).and_return(nil)
end
it 'returns true' do
expect(rate_limiter.within_limit?).to be true
end
end
context 'when rate limiting is enabled' do
let(:assignment_policy) do
instance_double(AssignmentPolicy,
fair_distribution_limit: 5,
fair_distribution_window: 3600)
end
before do
allow(inbox).to receive(:assignment_policy).and_return(assignment_policy)
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(:assignment_policy).and_return(nil)
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
let(:assignment_policy) do
instance_double(AssignmentPolicy,
fair_distribution_limit: 5,
fair_distribution_window: 3600)
end
before do
allow(inbox).to receive(:assignment_policy).and_return(assignment_policy)
end
it 'creates a Redis key with correct expiry' do
expected_key = format(Redis::RedisKeys::ASSIGNMENT_KEY, inbox_id: inbox.id, agent_id: agent.id, conversation_id: 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(:assignment_policy).and_return(nil)
end
it 'returns 0' do
expect(rate_limiter.current_count).to eq(0)
end
end
context 'when rate limiting is enabled' do
let(:assignment_policy) do
instance_double(AssignmentPolicy,
fair_distribution_limit: 5,
fair_distribution_window: 3600)
end
before do
allow(inbox).to receive(:assignment_policy).and_return(assignment_policy)
end
it 'counts matching Redis keys' do
pattern = format(Redis::RedisKeys::ASSIGNMENT_KEY_PATTERN, inbox_id: inbox.id, agent_id: 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
let(:assignment_policy) do
instance_double(AssignmentPolicy,
fair_distribution_limit: 10,
fair_distribution_window: 7200)
end
before do
allow(inbox).to receive(:assignment_policy).and_return(assignment_policy)
end
it 'uses the custom window value' do
expected_key = format(Redis::RedisKeys::ASSIGNMENT_KEY, inbox_id: inbox.id, agent_id: agent.id, conversation_id: 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
let(:assignment_policy) do
instance_double(AssignmentPolicy,
fair_distribution_limit: 10,
fair_distribution_window: nil)
end
before do
allow(inbox).to receive(:assignment_policy).and_return(assignment_policy)
end
it 'uses the default window value of 24 hours' do
expected_key = format(Redis::RedisKeys::ASSIGNMENT_KEY, inbox_id: inbox.id, agent_id: agent.id, conversation_id: conversation.id)
expect(Redis::Alfred).to receive(:set).with(
expected_key,
conversation.id.to_s,
ex: 86_400
)
rate_limiter.track_assignment(conversation)
end
end
end
end

View File

@@ -0,0 +1,78 @@
require 'rails_helper'
RSpec.describe AutoAssignment::RoundRobinSelector do
let(:account) { create(:account) }
let(:inbox) { create(:inbox, account: account) }
let(:selector) { 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) }
let(:agent3) { create(:user, account: account, role: :agent, availability: :online) }
let(:round_robin_service) { instance_double(AutoAssignment::InboxRoundRobinService) }
let(:member1) do
allow(AutoAssignment::InboxRoundRobinService).to receive(:new).and_return(round_robin_service)
allow(round_robin_service).to receive(:add_agent_to_queue)
create(:inbox_member, inbox: inbox, user: agent1)
end
let(:member2) do
allow(AutoAssignment::InboxRoundRobinService).to receive(:new).and_return(round_robin_service)
allow(round_robin_service).to receive(:add_agent_to_queue)
create(:inbox_member, inbox: inbox, user: agent2)
end
let(:member3) do
allow(AutoAssignment::InboxRoundRobinService).to receive(:new).and_return(round_robin_service)
allow(round_robin_service).to receive(:add_agent_to_queue)
create(:inbox_member, inbox: inbox, user: agent3)
end
before do
# Mock the round robin service to avoid Redis calls
allow(AutoAssignment::InboxRoundRobinService).to receive(:new).and_return(round_robin_service)
allow(round_robin_service).to receive(:add_agent_to_queue)
allow(round_robin_service).to receive(:reset_queue)
allow(round_robin_service).to receive(:validate_queue?).and_return(true)
end
describe '#select_agent' do
context 'when agents are available' do
let(:available_agents) { [member1, member2, member3] }
it 'returns an agent from the available list' do
allow(round_robin_service).to receive(:available_agent).and_return(agent1)
selected_agent = selector.select_agent(available_agents)
expect(selected_agent).not_to be_nil
expect([agent1, agent2, agent3]).to include(selected_agent)
end
it 'uses round robin service for selection' do
expect(round_robin_service).to receive(:available_agent).with(
allowed_agent_ids: [agent1.id.to_s, agent2.id.to_s, agent3.id.to_s]
).and_return(agent1)
selected_agent = selector.select_agent(available_agents)
expect(selected_agent).to eq(agent1)
end
end
context 'when no agents are available' do
it 'returns nil' do
selected_agent = selector.select_agent([])
expect(selected_agent).to be_nil
end
end
context 'when one agent is available' do
it 'returns that agent' do
allow(round_robin_service).to receive(:available_agent).and_return(agent1)
selected_agent = selector.select_agent([member1])
expect(selected_agent).to eq(agent1)
end
end
end
end