Ticket & State Machine

Ticket là thực thể trung tâm của @nx/helpdesk. Mỗi ticket có một vòng đời được quản lý bởi máy trạng thái XState v5 với 10 trạng thái, một audit trail event đầy đủ, và enrichment context bất đồng bộ.

Trạng thái Ticket

Trạng thái	Code	Mô tả
Open	OPEN	Ticket mới tạo, chưa được phân công
Assigned	ASSIGNED	Đã phân công cho một agent cụ thể
In Progress	IN_PROGRESS	Agent đang tích cực xử lý
Waiting for User	WAITING_USER	Cần phản hồi từ người báo cáo
Waiting Internal	WAITING_INTERNAL	Phụ thuộc team hoặc bộ phận khác
Escalated	ESCALATED	Escalate lên tier cao hơn
Resolved	RESOLVED	Agent đánh dấu đã giải quyết, chờ xác nhận
Closed	CLOSED	Khách hàng xác nhận — hoàn thành đầy đủ
Reopened	REOPENED	Khách hàng mở lại sau khi đóng
Waiting Agent	WAITING_AGENT	Chờ một agent được phân công
Pending	PENDING	Giữ chỗ / chưa phân loại
Assignment Failed	ASSIGNMENT_FAILED	Auto-assignment không tìm thấy agent đủ điều kiện

Enum có thẩm quyền: TicketStatuses trong packages/core/src/models/schemas/helpdesk/ticket/schema.ts (12 giá trị).

Máy trạng thái (XState v5)

Data Model

Ticket

Cột	Type	Mô tả
id	bigint	Snowflake ID
merchantId	bigint	Phạm vi tenant
reporterId	bigint	Người báo cáo (userId hoặc agentId)
reporterType	enum	USER / AGENT
category	bigint	FK → TicketCategory
priority	smallint	100 LOW / 200 NORMAL / 300 HIGH / 400 URGENT
status	enum	10 trạng thái (xem bảng trên)
subject	varchar	Tiêu đề ngắn
description	text	Mô tả chi tiết
context	jsonb	Dữ liệu context phong phú (order, product, …)
deletedAt	timestamp	Soft delete

TicketMessage

Cột	Type	Mô tả
id	bigint	Snowflake ID
ticketId	bigint	FK → Ticket
senderId	bigint	ID người gửi
senderType	enum	USER / AGENT / SYSTEM
messageType	enum	TEXT / IMAGE / FILE / SYSTEM_NOTE
content	text	Nội dung message
attachments	jsonb	Danh sách file đính kèm
isInternal	boolean	Note nội bộ (ẩn khỏi khách hàng)

TicketEvent (Event Sourcing)

Mọi hành động trên một ticket được ghi vào TicketEvent, xây dựng một audit trail đầy đủ:

Event	Mô tả
TICKET_CREATED	Ticket đã được tạo
STATUS_CHANGED	Chuyển đổi status
ASSIGNED	Agent đã được phân công
MESSAGE_ADDED	Message mới
TAG_ADDED / TAG_REMOVED	Thay đổi tag
SLA_WARNING / SLA_BREACHED	Event SLA
ESCALATED	Escalation kích hoạt
RESOLVED / CLOSED	Kết thúc vòng đời

REST API

Tickets (/tickets), gồm message, chuyển đổi status, phân công, xác nhận giải quyết, tag, và attachment — 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

Ticket

Use Case	Mô tả
CreateTicketUseCase	Tạo ticket, phát event TICKET_CREATED
ListTicketsUseCase	Tìm kiếm và phân trang ticket
GetTicketUseCase	Lấy chi tiết một ticket
UpdateTicketStatusUseCase	Chuyển đổi status qua máy trạng thái
AssignTicketUseCase	Phân công ticket cho một agent
AddMessageUseCase	Thêm message vào một ticket
GetTicketMessagesUseCase	Phân trang message dựa-trên-cursor
ConfirmResolutionUseCase	Xác nhận giải quyết → chuyển sang CLOSED
EnrichTicketContextUseCase	Enrich context (order, product) bất đồng bộ
AddAttachmentsToMessageUseCase	Đính kèm file vào một message

Context Enrichment Worker

Khi một ticket được tạo, context-enrichment.worker chạy bất đồng bộ để điền cột JSONB context:

Dữ liệu được fetch từ ProductRepository và SaleOrderRepository (cả hai từ @nx/core) và lưu trong cột context để agent có context đầy đủ mà không truy vấn dịch vụ khác.

Luồng Event-Driven khi Tạo Ticket

Trang liên quan

• Helpdesk Service — tổng quan dịch vụ
• Kiến trúc — Máy trạng thái Ticket
• Domain Model
• API Events