Agent & Assignment

@nx/helpdesk quản lý đội ngũ support agent với một hệ thống phân công kép: phân công thủ công qua API và tự phân công qua AutoAssignTicketUseCase chạy trên một worker BullMQ.

Data Model

Agent

Cột	Type	Mô tả
id	bigint	Snowflake ID
merchantId	bigint	Phạm vi tenant
userId	bigint	Liên kết unique tới một User trong @nx/identity
status	enum	ONLINE / AWAY / OFFLINE / BUSY
isAvailable	boolean	Agent có nhận ticket mới không
skills	varchar[]	Kỹ năng (ví dụ ['billing', 'technical'])
languages	varchar[]	Ngôn ngữ hỗ trợ (mặc định ['vi'])
maxConcurrentTickets	smallint	Giới hạn ticket đồng thời (mặc định 10)
currentTicketCount	int	Số ticket đang active hiện tại
averageResponseTime	int	Thời gian first-response trung bình (phút)
averageResolutionTime	int	Thời gian resolution trung bình (phút)
slaComplianceRate	decimal	Tỷ lệ tuân thủ SLA (0.0 − 1.0)
customerSatisfactionScore	decimal	Điểm CSAT
schedule	jsonb	Lịch làm việc (giờ/ngày nghỉ)

AgentGroup

Nhóm agent được tổ chức theo bộ phận hoặc bộ kỹ năng.

Cột	Type	Mô tả
id	bigint	Snowflake ID
merchantId	bigint	Phạm vi tenant
name	jsonb	Tên group (i18n: {en, vi})
description	jsonb	Mô tả group
isActive	boolean	Cờ active

AgentGroupMember

Bảng junction liên kết Agent ↔ AgentGroup.

REST API

Agents (/agents), agent group (/agent-groups), và assignment rule (/assignment-rules) — tham khảo endpoint đầy đủ render trực tiếp từ /v1/api/helpdesk/doc/openapi.json. Bảng endpoint cố ý không duy trì thủ công.

Use Cases

Agent

Use Case	Mô tả
CreateAgentUseCase	Tạo agent, liên kết tới userId
UpdateAgentUseCase	Cập nhật kỹ năng, status, lịch
DeleteAgentUseCase	Soft-delete agent
GetAgentByIdUseCase	Lấy chi tiết theo ID
GetAgentByUserIdUseCase	Lấy agent theo userId
ListAgentsUseCase	Danh sách agent phân trang
GetAgentTicketsUseCase	Fetch ticket theo agent

Auto-Assignment

Use Case	Mô tả
AutoAssignTicketUseCase	Điều phối tìm agent khả dụng tốt nhất
FindBestAgentUseCase	Chọn agent theo kỹ năng + khối lượng thấp nhất
FindSeniorAgentUseCase	Tìm một senior agent cho escalation

Luồng Auto-Assignment

Tiêu chí Chọn Agent (FindBestAgentUseCase)

1. isAvailable = true và status != OFFLINE/BUSY
2. currentTicketCount < maxConcurrentTickets — không quá tải
3. Khớp kỹ năng với kỹ năng yêu cầu của ticket.category (khi áp dụng)
4. currentTicketCount thấp nhất trong các agent đủ điều kiện — cân bằng tải

AssignmentRule

Rule có thể cấu hình ghi đè logic phân công mặc định:

Tiêu chí	Mô tả
categoryId	Chỉ áp dụng cho một category ticket cụ thể
priority	Mức priority ticket
keywords	Từ khóa trong subject/description
targetAgentId	Phân công trực tiếp cho một agent cụ thể
targetGroupId	Phân công cho một agent group

Worker liên quan

Worker	Hàng đợi	Chức năng
assignment.worker	helpdesk.assignment	Chạy AutoAssignTicketUseCase
escalation.worker	helpdesk.escalation	Chạy FindSeniorAgentUseCase khi vi phạm SLA Level 2+

Trang liên quan

• Helpdesk Service — tổng quan dịch vụ
• Domain Model
• SLA & Escalation
• API Events