Vận hành
1. Triển khai
| Thuộc tính | Giá trị |
|---|---|
| Image | registry/helpdesk:<tag> |
| Processes | API (RUN_MODE=startup) + Worker (RUN_MODE=worker) + Migration một lần (RUN_MODE=migrate) |
| Container Port | 3000 (external 31130) |
| Snowflake node id | 12 |
| Probes | GET /healthz (live), GET /readyz (ready) — mặc định IGNIS |
| Chế độ migration | job chạy một lần (bun run migrate) |
API và Worker dùng chung một image; vai trò được chọn bởi
RUN_MODE. Worker process phải chạy để giám sát SLA, assignment, escalation, thông báo, enrichment context, và trigger survey hoạt động.
Traefik labels
labels:
- "traefik.enable=true"
- "traefik.http.routers.helpdesk.rule=PathPrefix(`/v1/api/helpdesk`)"
- "traefik.http.services.helpdesk.loadbalancer.server.port=3000"2. Observability
| Tín hiệu | Nguồn | Xem ở đâu |
|---|---|---|
| Logs | stdout, tiền tố [ComponentName] (ví dụ [QueueComponent], [ProcessEscalation]) qua console.log/console.error | kubectl logs <pod> / Loki |
| Metrics | Mặc định IGNIS nếu được phơi bày | Grafana |
| Traces | Không đấu nối | — |
| Health | GET /healthz, GET /readyz | Cổng gateway |
| Độ sâu hàng đợi | BullMQ (Redis) | Bull board / kiểm tra Redis |
Marker log chính
| Marker | Ý nghĩa |
|---|---|
[QueueComponent] SLA Monitor cron job scheduled | Worker đã boot cron SLA |
[ProcessEscalation] Reassigning ticket … | Đường tái phân công escalation (xem Vấn đề đã biết) |
[EventHandlerRegistry] Handler failed for <event> | Lỗi listener in-process (được bắt) |
Logging là
console.*không có cấu trúc (không có logger key-value trong worker/listener). Lan truyền request-id cross-service chỉ áp dụng ở lớp HTTP IGNIS.
3. Bảo mật
| Mối quan tâm | Giảm thiểu |
|---|---|
| AuthN | JWT (ES256) được xác thực với JWKS của identity — VerifierApplication |
| AuthZ | Phạm vi theo merchant qua assertMerchantAccess() + useRequestContext(); PermissionService helpdesk cho kiểm tra mịn hơn. Không có decorator @authenticate theo route — controller thực thi truy cập trong handler |
| Secrets | Env (APP_ENV_*) gồm password SMTP + Redis; không bao giờ trong code. .env.development chứa secret dev trông như thật — xoay vòng trước bất kỳ dùng non-dev nào |
| Tenancy | Tất cả truy vấn ticket được giới hạn theo merchantId / organizerId |
| Soft-delete | deletedAt — không hard-delete mặc định |
| Note nội bộ/riêng tư | TicketMessage.isInternal ẩn note khỏi người báo cáo |
4. Runbook
4.1 Phân loại cảnh báo
| Cảnh báo | Kích hoạt | Kiểm tra | Sửa | Leo thang |
|---|---|---|---|---|
helpdeskWorkerDown | Không có log cron SLA-monitor | Trạng thái worker pod | Restart worker (RUN_MODE=worker) | on-call backend |
helpdeskQueueLag | BullMQ pending cao | Độ sâu hàng đợi Redis | Scale worker / kiểm tra lỗi | on-call SRE |
helpdeskNotificationFail | Job notification chạm max retry (5) | Credential SMTP / notification-delivery-log | Sửa SMTP, replay DLQ | on-call backend |
helpdeskSlaBreachSpike | Tỷ lệ vi phạm tăng | Số đếm status SlaTracker | Kiểm tra nhân sự agent / chính sách | support-team |
4.2 Thao tác thường gặp
| Thao tác | Lệnh / hành động |
|---|---|
| Tail log API | kubectl logs -n <ns> -f deploy/helpdesk-api |
| Tail log worker | kubectl logs -n <ns> -f deploy/helpdesk-worker |
| Trigger kiểm tra SLA | QueueComponent.triggerSlaCheck({ ticketId? }) (job thủ công, priority HIGH) |
| Reset cron SLA | Restart worker đăng ký lại sla-monitor-cron (gỡ lặp lại cũ) |
| Chạy migration | bun run migrate:dev (theo từng package; không bao giờ chạy bởi agent) |
| Replay job dead-letter | qua HandleDeadLetterUseCase / dlq.helper.ts |
5. Vấn đề đã biết
⚠ Build TypeScript của
@nx/helpdeskhiện đang fail. TheoAGENTS.mdcủa package, nguyên nhân là đường tham chiếuassignTicketUseCasechết. Cuộc gọi tái phân công escalation Level-2+ (this.assignTicketUseCase.execute(...)) trongsrc/application/use-cases/sla-policy/process-escalation.use-case.tsbị comment out — use-case đó không được inject vàoProcessEscalationUseCase, nên escalation SLA không tái phân công ticket cho senior agent; nó chỉ gửi thông báo escalation-assignment. Không sửa source như một phần công việc tài liệu.
| Tác động | Chi tiết |
|---|---|
| Build | bun run rebuild / tsc fail; không thể tạo artifact triển khai cho đến khi sửa |
| Tái phân công escalation | Bị tắt — tái phân công senior-agent ở Level 2/3 là no-op (chỉ thông báo) |
| Drift định danh | .env.development mang SVC-00030 / 31032 / 0 cũ; đối chiếu về app-info.json (SVC-00120 / 31130 / 12) khi build được sửa (xem Cấu hình) |
| Dependency chết | @platformatic/kafka được khai báo nhưng không dùng — ứng viên để gỡ |
6. Trang liên quan
- Cấu hình
- API Events
/runbook/— runbook trung tâm cho sự cố cross-service- Quyết định