Notification System

@nx/helpdesk ship hệ thống con thông báo riêng với gom batch digest, quiet hours, gửi đa kênh, và theo dõi đầy đủ trạng thái gửi.

Kiến trúc

Data Model

Notification

Cột	Type	Mô tả
id	bigint	Snowflake ID
eventCode	varchar	Mã loại event (ví dụ TICKET_ASSIGNED)
recipientId	bigint	ID người nhận
recipientType	enum	USER / AGENT / SYSTEM
merchantId	bigint	Phạm vi tenant
contextType	varchar	Loại thực thể context (ví dụ Ticket)
contextId	bigint	ID thực thể context
title	jsonb	Tiêu đề thông báo (i18n)
content	jsonb	Nội dung thông báo (i18n)
templateData	jsonb	Dữ liệu dùng để render template
channels	varchar[]	Kênh gửi đã chọn
status	enum	PENDING / PROCESSING / DELIVERED / PARTIALLY_DELIVERED / FAILED
isRead	boolean	Người nhận đã đọc chưa
readAt	timestamp	Mốc thời gian đọc
batchId	bigint	FK → NotificationBatch (nếu digest)
actionUrl	varchar	URL hành động khi người nhận click thông báo

NotificationTemplate

Template theo từng loại event và kênh:

Cột	Type	Mô tả
eventCode	varchar	Mã event
channel	enum	Kênh template này áp dụng
subject	jsonb	Subject email (i18n)
bodyHtml	jsonb	Body HTML (i18n)
bodyText	jsonb	Body plain-text (i18n)
isActive	boolean	Template có đang dùng không

NotificationPreference

Preference thông báo theo từng user/agent:

Cột	Type	Mô tả
userId	bigint	ID User hoặc Agent
eventCode	varchar	Loại event
channels	varchar[]	Kênh gửi ưu tiên
quietHoursStart	time	Bắt đầu quiet hours (không thông báo)
quietHoursEnd	time	Kết thúc quiet hours
digestEnabled	boolean	Gom thông báo vào một digest
digestIntervalMinutes	int	Khoảng giữa các lần gửi digest

NotificationDeliveryLog

Lịch sử gửi theo từng kênh:

Cột	Type	Mô tả
notificationId	bigint	FK → Notification
channel	varchar	Kênh gửi
status	enum	SUCCESS / FAILED
errorMessage	text	Chi tiết lỗi khi fail
sentAt	timestamp	Mốc thời gian gửi

NotificationBatch

Gom batch digest — tổng hợp nhiều thông báo thành một lần gửi:

Cột	Type	Mô tả
id	bigint	Snowflake ID
recipientId	bigint	Người nhận
status	enum	PENDING / PROCESSING / SENT
scheduledAt	timestamp	Khi digest sẽ được gửi
sentAt	timestamp	Mốc thời gian gửi thực tế
itemCount	int	Số thông báo trong batch

Kênh Gửi

Kênh	Triển khai	Mô tả
EMAIL	NodemailerComponent	SMTP với template HTML/text
WEBSOCKET	ApplicationWebSocketComponent	Thời gian thực qua dịch vụ Signal
PUSH	Push adapter	Thông báo push mobile
SMS	SMS adapter	Gửi tin nhắn text

Quiet Hours

ProcessNotificationService kiểm tra NotificationPreference.quietHoursStart/End trước khi gửi. Nếu thời gian hiện tại rơi vào quiet hours của người nhận, thông báo bị hoãn cho đến khi quiet hours kết thúc.

Gom Batch Digest

NotificationBatchService tổng hợp thông báo thành một digest:

Workers

Worker	Hàng đợi	Chức năng
notification.worker	helpdesk.notification	Xử lý mỗi thông báo, gọi ProcessNotificationService (jobs: notification, notification-batch, notification-digest)

Event Trigger Thông báo

Event	Người nhận	Mô tả
TICKET_CREATED	Agent được phân công	Ticket mới đang chờ
TICKET_ASSIGNED	Agent	Ticket đã được phân công
STATUS_CHANGED	Người báo cáo	Status ticket được cập nhật
MESSAGE_ADDED	Agent / Người báo cáo	Message mới trong ticket
SLA_WARNING	Agent	Deadline SLA sắp tới (75%)
SLA_BREACHED	Agent + Manager	SLA bị vi phạm (100%)
SLA_CRITICAL	Manager + Leadership	Vi phạm SLA critical (150%)
TICKET_RESOLVED	Người báo cáo	Ticket đã được giải quyết
TICKET_CLOSED	Agent	Khách hàng xác nhận đóng

WebSocket Rooms & Topics

ApplicationWebSocketComponent (với socket-event.service.ts) phát trên một topic helpdesk duy nhất, vào các room giới hạn theo ticket + message. Build từ helper @nx/core:

Builder	Giá trị	Mô tả
HelpdeskWebSocketTopics.HELP_DESK	observation/helpdesk	Topic observation helpdesk
HelpdeskWebSocketRooms.getHelpdeskRooms({ ticketId, messageId })	helpdesk/:ticketId/:messageId	Room theo từng ticket, từng message

Nguồn: src/components/websocket/topics.ts, src/components/websocket/rooms.ts.

Trang liên quan

• Helpdesk Service — tổng quan dịch vụ
• API Events
• Cấu hình — Mail / escalation