Helpdesk Service

@nx/helpdesk là microservice hỗ trợ khách hàng cho nền tảng BANA. Nó sở hữu vòng đời ticket, theo dõi SLA và auto-escalation, phân công agent dựa trên rule, một knowledge base, khảo sát hài lòng, và thông báo đa kênh theo template. Đây là một VerifierApplication chỉ phụ thuộc vào @nx/core và xử lý công việc nền qua các worker BullMQ và một event bus in-process.

1. Tham khảo nhanh

Thuộc tính	Giá trị
Package	@nx/helpdesk
Code	SVC-00120-HELPDESK
Type	Microservice
Runtime	Bun
Base Class	VerifierApplication
Location	packages/helpdesk
Base Path	/v1/api/helpdesk
Dev Port	31130
Container Port	3000 (external 31130)
Snowflake ID	12
DB Schema	helpdesk (30 bảng)
Roles	api, worker (RUN_MODE=worker)
Binding Namespace	@nx/helpdesk
Owner	support-team

Nguồn sự thật về định danh: src/resources/app-info.json (trả về bởi getAppInfo()). Các giá trị trên đến từ đó. .env.development nay đã mang APP_ENV_APPLICATION_CODE=SVC-00120-HELPDESK khớp với app-info (va chạm SVC-00030-HELPDESK với sale đã được giải quyết). Drift còn lại cần đối chiếu: APP_ENV_SERVER_PORT=31032 và APP_ENV_SNOWFLAKE_WORKER_ID=0. Xem Cấu hình.

Vấn đề đã biết: build TypeScript của package này hiện đang fail (đường tham chiếu assignTicketUseCase chết). Xem Vận hành → Vấn đề đã biết.

2. Mục đích & Phạm vi

Bao gồm	Loại trừ
Quản lý ticket (vòng đời, message, attachment, event)	Phát JWT / identity (xử lý bởi @nx/identity)
Theo dõi SLA, cảnh báo, vi phạm, auto-escalation	Xử lý order/payment (context chỉ-đọc từ @nx/core)
Tự phân công dựa trên rule (agents, agent groups)	Logic inventory và pricing
Knowledge base (articles, categories, views, feedback)	Event bus cross-service (không đấu nối Kafka; chỉ in-process)
Khảo sát hài lòng + vote feature-request	—
Thông báo theo template, gom batch (email + WebSocket)	—

3. Tech Stack

Bên ngoài:

Thư viện	Mục đích
@venizia/ignis	IoC container, DI, base application/controller/service, components
@venizia/ignis-helpers	Redis helper, TConstValue, TNullable, tiện ích dùng chung
hono	Framework HTTP server (qua IGNIS)
drizzle-orm	Truy cập DB qua PostgresCoreDataSource
pg	Driver PostgreSQL
bullmq	Hàng đợi job nền + workers
ioredis	Client Redis (kết nối cache + BullMQ)
eventemitter3	Event bus in-process
xstate	Máy trạng thái ticket-status
nodemailer	Gửi email
slugify	Sinh slug article/category
zod	Xác thực schema request/response
lodash	Tiện ích

@platformatic/kafka được khai báo trong package.json nhưng chết — không có Kafka producer/consumer trong src/. Xem API Events.

Nội bộ:

Package	Mục đích
@nx/core	Phụ thuộc @nx/* duy nhất. Cung cấp VerifierApplication, PostgresCoreDataSource, createAppConfig, bootstrapApplication, schema/model Drizzle tập trung, ProductRepository + SaleOrderRepository (cho enrichment context), assertMerchantAccess, useRequestContext, ActorTypes, builder WebSocket/topic, enum ticket (TicketStatuses, TicketEventTypes, TicketPriorities).

4. Cấu trúc dự án

packages/helpdesk/
├── src/
│   ├── application.ts            # HelpdeskApplication (VerifierApplication)
│   ├── index.ts                  # Điểm vào → bootstrapApplication()
│   ├── migrate.ts                # Điểm vào migration → bootstrapMigration()
│   ├── application/
│   │   ├── use-cases/            # Business logic (service đăng ký DI)
│   │   ├── services/             # Service thuần (notification, compensation, …)
│   │   ├── events/               # Emitter + listener in-process
│   │   └── validators/           # AgentValidator
│   ├── components/
│   │   ├── event-bus/            # EventBusComponent (eventemitter3)
│   │   ├── queue.component.ts    # Hàng đợi BullMQ + scheduler cron SLA
│   │   ├── workers/              # 6 worker BullMQ
│   │   ├── mail/                 # NodemailerComponent
│   │   └── websocket/            # ApplicationWebSocketComponent
│   ├── controllers/              # 11 REST controller
│   ├── datasources/              # Binding PostgresCoreDataSource
│   ├── models/requests/          # Zod request schemas
│   ├── repositories/             # Lớp repository (schema nằm trong @nx/core)
│   ├── migrations/processes/     # Migration processes
│   ├── resources/                # app-info.json + email templates
│   └── shared/                   # common (keys, paths, constants), helpers, utils
├── package.json
└── tsconfig.json

5. Kiến trúc

Chi tiết: xem Kiến trúc.

6. Ảnh chụp Domain

ERD đầy đủ + bảng theo từng thực thể: xem Domain Model.

7. Tóm tắt Bề mặt

REST controllers (tham khảo đầy đủ render trực tiếp từ /v1/api/helpdesk/doc/openapi.json):

Controller	Base path (RestPaths)	Ghi chú
TicketController	/tickets	Vòng đời ticket đầy đủ, message, phân công
AgentController	/agents	Quản lý support agent
AgentGroupController	/agent-groups	Agent group + thành viên
TicketCategoryController	/ticket-categories	Category ticket
TicketTagController	/ticket-tags	Tag + ánh xạ ticket-tag
SlaController	/sla-policies	Chính sách SLA
ArticleController	(articles)	Article knowledge base
ArticleCategoryController	(article categories)	Category article
AssignmentRuleController	/assignment-rules	Rule tự phân công
FeatureRequestController	(feature requests)	Feature request + vote
SurveyController	(surveys)	Khảo sát hài lòng

Live spec: /v1/api/helpdesk/doc/openapi.json. Bảng REST cố ý không duy trì thủ công.

Bề mặt async (tham khảo đầy đủ trong API Events):

Kênh	Số lượng
Kafka in/out	0 (dep chết)
Sự kiện in-process (EventBus)	ticket created / status-changed / assigned / message-created
Hàng đợi BullMQ	6 (SLA monitor, escalation, assignment, notification, context-enrichment, survey-trigger)
Phát WebSocket	topic observation helpdesk

8. Components

Component	File	Mục đích
Cache Redis	useCacheRedis() → BindingKeys.APPLICATION_REDIS_CACHE	Redis cho cache + kết nối BullMQ
QueueComponent	src/components/queue.component.ts	Tạo 6 hàng đợi BullMQ; lên lịch cron SLA-monitor
EventBusComponent	src/components/event-bus/component.ts	Bus eventemitter3 in-process + registry handler
NodemailerComponent	src/components/mail/component.ts	Gửi email SMTP
WorkerComponent	src/components/workers/worker.component.ts	Đăng ký và chạy 6 worker BullMQ
ApplicationWebSocketComponent	src/components/websocket/component.ts	Gửi WebSocket thời gian thực

9. Services

Business logic nằm trong use-cases (src/application/use-cases/*, đăng ký làm service DI). Các service thuần dưới đây cung cấp helper xuyên suốt dùng chung.

Service	File	Mô tả một dòng
FileStorageHelper	src/shared/helpers/file-storage.helper.ts	Helper lưu trữ attachment
PermissionService	src/application/services/permission.service.ts	Kiểm tra quyền helpdesk
CompensationCalculatorService	src/application/services/compensation-calculator.service.ts	Ma trận đền bù vi phạm SLA
EscalationJobManagerService	src/application/services/escalation-job-manager.service.ts	Lên lịch/quản lý job escalation
ProcessNotificationService	src/application/services/notification/process-notification.service.ts	Phân giải + gửi thông báo
NotificationBatchService	src/application/services/notification/notification-batch.service.ts	Gom batch/digest thông báo
AgentValidator	src/application/validators/agent.validator.ts	Xác thực input agent

Use-case được nhóm theo domain: Agent, Agent Group, Assignment, Assignment Rule, Article, Article Category, Feature Request, SLA, SLA Policy, Survey, Survey Question, Ticket, Ticket Category, Ticket Tag, cộng HandleDeadLetterUseCase. Xem src/application.ts configureServices() cho tập đã đăng ký.

10. Repositories

Tất cả schema/model Drizzle được tập trung trong @nx/core (packages/core/src/models/schemas/helpdesk/). Package này chỉ khai báo lớp repository.

Nhóm	Repositories
Ticket	TicketRepository, TicketMessageRepository, TicketEventRepository, TicketAssignmentRepository, TicketCategoryRepository, TicketTagRepository, TicketTagMappingRepository
Agent	AgentRepository, AgentGroupRepository, AgentGroupMemberRepository
SLA	SlaPolicyRepository, SlaTrackerRepository, SlaEscalationRepository
Knowledge base	ArticleRepository, ArticleCategoryRepository, ArticleViewRepository, ArticleFeedbackRepository
Survey & feature	SurveyRepository, SurveyQuestionRepository, SurveyResponseRepository, FeatureRequestRepository, FeatureVoteRepository
Notification	NotificationRepository, NotificationTemplateRepository, NotificationPreferenceRepository, NotificationDeliveryLogRepository, NotificationBatchRepository
Khác	AssignmentRuleRepository, CompensationRepository, MetaLinkRepository, JobExecutionLogRepository, UserRepository, OrganizerRepository
Từ @nx/core	ProductRepository, SaleOrderRepository (enrichment context chỉ-đọc)

11. Điểm vào

File	Mục đích
src/index.ts	Điểm vào dịch vụ → bootstrapApplication({ ApplicationClass: HelpdeskApplication })
src/migrate.ts	Điểm vào migration → bootstrapMigration()
src/application.ts	HelpdeskApplication kế thừa VerifierApplication

Chế độ chạy được chọn qua RUN_MODE (startup API / worker / migrate).

12. Cấu hình

Biến env + feature flag + dữ liệu seed: xem Cấu hình.

13. Vận hành

Triển khai + observability + bảo mật + runbook + vấn đề đã biết: xem Vận hành.

14. Trang liên quan

• Kiến trúc
• Domain Model
• API Events
• Tích hợp
• Cấu hình
• Vận hành
• Quyết định
• REST endpoints — OpenAPI trực tiếp tại /v1/api/helpdesk/doc/openapi.json
• Tính năng: Ticket System · Agent & Assignment · SLA & Escalation · Knowledge Base · Notifications