API Events

Không Kafka. @platformatic/kafka được khai báo trong package.json nhưng không có đấu nối producer/consumer trong src/. Tất cả eventing là in-process (EventBus eventemitter3) fan out tới hàng đợi BullMQ, với fan-out thời gian thực qua WebSocket. Xem ADR-0001.

1. Inbound — Kafka

Không. Dịch vụ không tiêu thụ topic Kafka nào.

2. Outbound — Kafka

Không. Dịch vụ không produce topic Kafka nào.

3. Sự kiện in-process (EventBus)

EventBus (eventemitter3) — phát bởi TicketEmitter, xử lý bởi listener trong src/application/events/listeners/. Loại event là TicketEventTypes (chuỗi có dấu chấm) từ @nx/core. Đồng bộ trong API process; lỗi listener được bắt và log (không bao giờ crash emitter).

Loại event	Method emitter	Listener(s)	Side effect
ticket.created	TicketEmitter.ticketCreated	TicketCreatedListener	Tăng số đếm category/tag; enqueue job context-enrichment + assignment
ticket.status_changed	TicketEmitter.ticketChangedStatus	TicketStatusChangedListener	Side effect status (thông báo, trigger survey)
ticket.assigned	TicketEmitter.ticketAssigned	TicketAssignedListener	Thông báo phân công
ticket.message.created	TicketEmitter.ticketMessageCreated	TicketMessageCreatedListener	Thông báo trả lời, đánh dấu first-response SLA

4. Inbound — BullMQ

Hàng đợi được tạo bởi QueueComponent; tiêu thụ bởi worker trong src/components/workers/ (worker process, RUN_MODE=worker). Concurrency từ WORKER_CONFIG.

Hàng đợi	Tên job	Producer	Worker → Use-case	Concurrency	Retries
helpdesk.sla-monitor	sla-monitor	Cron (lặp lại) + trigger thủ công	sla-monitor.worker → RunSlaMonitorUseCase	1	2, cố định 60s
helpdesk.escalation	escalation, escalation-batch	sla-monitor / escalation manager	escalation.worker → ProcessEscalationUseCase	5	3, exp 5s (priority 1)
helpdesk.assignment	assign	TicketCreatedListener	assignment.worker → AutoAssignTicketUseCase	5	3, exp 5s
helpdesk.notification	notification, notification-batch, notification-digest	nhiều	notification.worker → ProcessNotificationService	10	5, exp 5s (priority 10)
helpdesk.context-enrichment	enrich	TicketCreatedListener	context-enrichment.worker → EnrichTicketContextUseCase	30	3, exp 5s
helpdesk.survey-trigger	survey-trigger	luồng status-changed	survey-trigger.worker → TriggerSurveyUseCase	3	3, exp 10s

Một tên hàng đợi helpdesk.analytics-update (ANALYTICS_UPDATE) tồn tại trong QUEUE_NAME, nhưng không có worker/queue nào được đấu nối cho nó. Job thất bại route tới HandleDeadLetterUseCase qua dlq.helper.ts.

5. Outbound — BullMQ

Job được enqueue qua JobDispatcherHelper (publish / publishAll) và các builder job có kiểu trong src/shared/helpers/jobs/.

Builder job	Hàng đợi	Trigger
ContextEnrichmentJob.enrich	context-enrichment	Ticket tạo với context
AssignmentJob.assign	assignment	Ticket tạo (chiến lược LOAD_BALANCED)
NotificationJob.*	notification	Cảnh báo/vi phạm SLA, phân công, trả lời, escalation
EscalationJob.*	escalation	Vi phạm SLA bởi sla-monitor
SurveyTriggerJob.*	survey-trigger	Ticket resolved/closed
Cron SLA monitor	sla-monitor	QueueComponent.scheduleSlaMonitoring() (jobId sla-monitor-cron)

6. Phát WebSocket

Gửi bởi ApplicationWebSocketComponent + socket-event.service.ts. Topic/room được build từ helper @nx/core.

Topic	Room	Trigger
HelpdeskWebSocketTopics.HELP_DESK (observation/helpdesk)	HelpdeskWebSocketRooms.getHelpdeskRooms({ ticketId, messageId }) (helpdesk/:ticketId/:messageId)	Message mới / thay đổi status / phân công / event SLA

7. Schema Payload

Payload event in-process là interface TS trong src/shared/common/interfaces/ (không phải hợp đồng message tập trung, vì không có Kafka). Hình dạng đại diện:

// ticket.created — ITicketCreatedEventData
interface ITicketCreatedEventData {
  ticketId: string;
  merchantId: string;
  categoryId: string;
  priority: TTicketPriorities;
  context?: Record<string, unknown>;
  categoryRouting?: unknown;
  metadata: { tagIds: string[]; [k: string]: unknown };
}

8. Idempotency & Thứ tự

Kênh	Đảm bảo	Thứ tự	Phục hồi
EventBus	in-process, at-most-once	thứ tự emit, đồng bộ	không — lỗi listener được log, không retry
BullMQ jobs	at-least-once (retry theo hàng đợi)	theo hàng đợi, không thứ tự toàn cục	retry kèm backoff → DLQ qua HandleDeadLetterUseCase; helper idempotency worker de-dup
SLA cron	đúng một lịch	n/a	jobId: 'sla-monitor-cron' cố định ngăn lặp lại trùng

9. Trang liên quan

• Tích hợp
• Kiến trúc — Kịch bản Runtime
• ADR-0001 — EventBus in-process + BullMQ