PRD: Helpdesk core (ticket, SLA, agent)
| Module | Hỗ trợ khách hàng (CORE-13) | PRD ID | PRD-TKT-001 |
| Status | In-progress | Owner | Helpdesk squad |
| Date | 2026-06-02 | Version | v0.1 |
| Packages | @nx/helpdesk | URD | TKT · MSG · CAT · SLA · AGT · NTF |
TL;DR
Mang lại cho đội hỗ trợ của merchant một cách thức hạng nhất để tiếp nhận, định tuyến và giải quyết yêu cầu của khách hàng trong mức dịch vụ đã cam kết. Khách hàng tạo ticket, hệ thống tự phân công cho agent phù hợp nhất đang sẵn sàng, policy SLA giữ thời gian phản hồi và giải quyết đúng cam kết với leo thang khi cảnh báo/vi phạm, và mọi sự kiện được phát đi dưới dạng notification thời gian thực và email. Kết quả: hỗ trợ được theo dõi toàn trình thay vì rải rác trên các kênh tạm thời.
1. Context & Problem
Merchant của KICKO chưa có cách thức hạng nhất để tiếp nhận, định tuyến và giải quyết yêu cầu hỗ trợ khách hàng trong mức dịch vụ đã cam kết. Hỗ trợ đến từ các kênh rời rạc, không được theo dõi: không có tài liệu ticket với vòng đời được kiểm soát, không có cách gắn một yêu cầu với agent chịu trách nhiệm, và không có đồng hồ mức dịch vụ để giữ thời gian phản hồi và giải quyết đúng cam kết. Điều này khiến tải hỗ trợ, trách nhiệm của agent và mức tuân thủ SLA không thể đo lường - một khoảng trống đối với các merchant mà KICKO phục vụ khi họ mở rộng hoạt động chăm sóc khách hàng.
Phần tăng tiến này dựng backend Helpdesk thành một package IGNIS mới và cung cấp phần lõi hỗ trợ: vòng đời ticket, tin nhắn theo luồng, phân loại, thực thi SLA, định tuyến agent, và notification theo sự kiện.
2. Goals & Non-Goals
Goals
- Vòng đời ticket hỗ trợ: tạo, phân loại, phân công, chuyển trạng thái qua máy trạng thái 8 trạng thái, giải quyết và đóng - kèm audit trail đầy đủ và soft-delete.
- Tin nhắn ticket theo luồng: phản hồi của khách hàng/agent, ghi chú nội bộ (chỉ agent), tin nhắn hệ thống, và file đính kèm.
- Phân loại ticket: category phân cấp mang theo các giá trị mặc định để định tuyến, tag, và bốn mức độ ưu tiên.
- Quản lý SLA: policy với chỉ tiêu phản hồi/giải quyết theo từng mức ưu tiên, tracker theo từng ticket, ngưỡng cảnh báo/vi phạm, một monitor theo lịch, và leo thang ba cấp.
- Quản lý agent: hồ sơ agent (trạng thái sẵn sàng, kỹ năng, ngôn ngữ, giới hạn khối lượng công việc), nhóm agent, quy tắc phân công theo độ ưu tiên, và một worker phân công tự động với nhiều chiến lược.
- Notification theo sự kiện: cảnh báo thời gian thực (WebSocket) và email trên các sự kiện ticket, với giao nhận do worker điều phối và template.
Non-Goals
- Gợi ý phản hồi hỗ trợ bởi AI và cảnh báo vi phạm SLA mang tính dự báo.
- Tiếp nhận đa kênh (email, Zalo OA, Facebook Messenger).
- Cổng tự phục vụ ticket hướng tới khách hàng.
- Dashboard báo cáo SLA - thuộc về module Báo cáo.
- Cơ sở tri thức (
KB), khảo sát (SRV), và yêu cầu tính năng (FR) - các area P2 này nằm ngoài phần tăng tiến lõi này.
3. Success Metrics
| Metric | Chỉ tiêu / tín hiệu |
|---|---|
| Khả năng truy vết | 100% yêu cầu hỗ trợ đi qua một ticket được theo dõi, không qua kênh tạm thời |
| Thời gian phản hồi đầu tiên | Đáp ứng deadline phản hồi đầu tiên trong chỉ tiêu SLA theo từng mức ưu tiên |
| Độ phủ phân công tự động | Ticket mới được tự định tuyến tới một agent đủ điều kiện trong vòng 2 phút |
| Tuân thủ SLA | Tỷ lệ ticket được giải quyết trước khi vi phạm có xu hướng tăng; cảnh báo phát trước khi vi phạm |
| Sức khỏe leo thang | Ticket vi phạm/nghiêm trọng leo thang qua L1→L3 mà không cần đôn đốc thủ công |
4. Personas & Use Cases
| Persona | Mục tiêu trong tính năng này |
|---|---|
| Khách hàng | Tạo yêu cầu, nhận phản hồi, xác nhận đã giải quyết |
| Agent hỗ trợ | Xử lý ticket được phân công, phản hồi, thêm ghi chú nội bộ, giải quyết trong SLA |
| Quản lý hỗ trợ | Cấu hình policy SLA, quy tắc phân công, category; xử lý leo thang |
Core scenarios: khách hàng tạo ticket → hệ thống mở ticket, khởi động đồng hồ SLA, và tự phân công cho agent phù hợp nhất đang sẵn sàng → agent phản hồi và xử lý vòng đời → SLA được theo dõi với leo thang khi cảnh báo/vi phạm → ticket được giải quyết và đóng, với notification ở mỗi bước.
5. User Stories
- Là khách hàng, tôi muốn tạo một ticket hỗ trợ với tiêu đề, category, và độ ưu tiên, để yêu cầu của tôi được theo dõi.
- Là agent hỗ trợ, tôi muốn ticket mới được tự phân công cho tôi dựa trên kỹ năng và tải, để tôi xử lý đúng ticket mà không cần phân loại thủ công.
- Là agent hỗ trợ, tôi muốn phản hồi, thêm ghi chú nội bộ, và đính kèm file, để tôi có thể phối hợp và giải quyết ticket.
- Là agent hỗ trợ, tôi muốn ticket di chuyển qua một vòng đời trạng thái rõ ràng, để trạng thái của nó luôn rõ ràng.
- Là quản lý hỗ trợ, tôi muốn policy SLA với chỉ tiêu phản hồi/giải quyết theo từng mức ưu tiên, để đội ngũ được giữ đúng mức dịch vụ đã cam kết.
- Là quản lý hỗ trợ, tôi muốn ticket vi phạm hoặc nghiêm trọng leo thang qua các cấp, để không gì bị bỏ sót.
- Là khách hàng, tôi muốn cảnh báo thời gian thực và email trên ticket của tôi, để tôi biết khi agent phản hồi.
6. Functional Requirements
| # | Yêu cầu | URD ref |
|---|---|---|
| FR-1 | Tạo một ticket trong scope merchant với tiêu đề, mô tả, category, và độ ưu tiên; người báo là khách hàng-tạo hoặc agent-tạo thay mặt khách hàng | URD-TKT-001..003 |
| FR-2 | Ticket tuân theo vòng đời 8 trạng thái OPEN → ASSIGNED → IN_PROGRESS → WAITING_USER / WAITING_INTERNAL → ESCALATED → RESOLVED → CLOSED, kèm chi tiết phân công/giải quyết/đóng, một audit trail đầy đủ, và chỉ soft-delete | URD-TKT-004..008,012 |
| FR-3 | Mở lại khi khách hàng phản hồi sau khi đã giải quyết; khách hàng xác nhận đã giải quyết và một ticket đã giải quyết tự đóng sau 48h nếu không có phản hồi | URD-TKT-009..010 |
| FR-4 | Tin nhắn có kiểu theo luồng (comment, phản hồi khách hàng/agent, ghi chú nội bộ, hệ thống, auto-reply) kèm file đính kèm và tác giả được theo dõi; ghi chú nội bộ không bao giờ trả về cho người không phải agent; một tin nhắn hệ thống được tự thêm vào ở mỗi lần chuyển trạng thái | URD-MSG-001..005 |
| FR-5 | Category ticket phân cấp mang theo độ ưu tiên, kỹ năng, nhóm, và policy SLA mặc định; tag ticket; bốn mức độ ưu tiên (Low/Medium/High/Critical) | URD-CAT-001..005 |
| FR-6 | Policy SLA với chỉ tiêu phản hồi/giải quyết theo từng mức ưu tiên, ngưỡng cảnh báo (75%) và nghiêm trọng (90%) cấu hình được, đồng hồ tùy chọn chỉ-trong-giờ-làm-việc | URD-SLA-001..003 |
| FR-7 | Tracker SLA theo từng ticket được tạo lúc tạo ticket; một monitor theo lịch tự đánh dấu cảnh báo/vi phạm và ghi lại thời gian phản hồi đầu tiên cùng thời gian-đến-giải-quyết | URD-SLA-004..006 |
| FR-8 | Ba cấp leo thang (L1/L2/L3) với trigger có kiểu (vi phạm SLA, thủ công, khách hàng yêu cầu, tác động cao, sự cố); quy tắc cấu hình được trong một policy; SLA của category ghi đè giá trị mặc định toàn cục | URD-SLA-007..010 |
| FR-9 | Hồ sơ agent (một hồ sơ mỗi user) với trạng thái sẵn sàng, kỹ năng, ngôn ngữ, và giới hạn đồng thời tối đa; nhóm agent với quản lý thành viên | URD-AGT-001..004 |
| FR-10 | Quy tắc phân công theo độ ưu tiên trong từng merchant với nhiều chiến lược; một worker phân công tự động chọn agent phù hợp nhất đang sẵn sàng và bỏ qua agent đã ở giới hạn | URD-AGT-005..007,010 |
| FR-11 | Theo dõi hiệu suất agent (phản hồi/giải quyết trung bình, tuân thủ SLA, mức hài lòng) và một lịch sẵn sàng theo giờ làm việc | URD-AGT-008..009 |
| FR-12 | Notification thời gian thực (WebSocket) và email trên các sự kiện ticket, tùy chọn theo từng user, template tùy chỉnh được, và giao nhận theo lô với một log theo từng người nhận | URD-NTF-001..005 |
Toàn văn yêu cầu và tiêu chí chấp nhận nằm trong URD Helpdesk. PRD này tham chiếu tới chúng thay vì lặp lại.
7. Non-Functional Requirements
| Area | Yêu cầu |
|---|---|
| Data integrity | Một tracker SLA mỗi ticket, không thể thay đổi sau khi vi phạm; mọi thay đổi trạng thái và hành động được ghi vào audit trail |
| Immutability | Ghi chú nội bộ không bao giờ trả về cho người không phải agent; tin nhắn hệ thống được tự thêm vào, không sửa tại chỗ |
| Tenancy & authz | Ticket luôn thuộc scope một merchant duy nhất (scope theo organizer); hành động của agent so với quản lý được gate bằng permission của helpdesk |
| Performance / scale | Phân công tự động chạy trong vòng 2 phút kể từ khi tạo ticket; monitor SLA chạy theo lịch độc lập với lưu lượng request |
| Soft-delete | Mọi record chỉ soft-delete |
| i18n | Nhãn hiển thị, trạng thái, ghi chú giải quyết, và template email là song ngữ ({ en, vi }) |
8. UX & Flows
Các màn hình chính được phục vụ bởi API của backend Helpdesk và hiển thị trong không gian làm việc hỗ trợ của merchant; các view ticket, tin nhắn, tracker SLA, và phân công agent đều đọc từ @nx/helpdesk.
9. Data & Domain
| Entity | Vai trò |
|---|---|
Ticket | Tài liệu yêu cầu hỗ trợ - scope merchant, trạng thái, độ ưu tiên, category, agent được phân công, audit trail |
TicketMessage | Một mục luồng có kiểu (phản hồi khách hàng/agent, ghi chú nội bộ, hệ thống, auto-reply) kèm file đính kèm và tác giả được theo dõi |
TicketCategory | Phân loại phân cấp mang theo độ ưu tiên, kỹ năng, nhóm, và policy SLA mặc định |
SlaPolicy | Chỉ tiêu phản hồi/giải quyết theo từng mức ưu tiên, ngưỡng, và quy tắc leo thang |
SlaTracker | Deadline và thời gian đã trôi qua theo từng ticket so với một policy SLA |
SlaEscalation | Một leo thang có kiểu (L1/L2/L3) được phát khi vi phạm hoặc theo yêu cầu |
Agent | Một user được liên kết làm agent hỗ trợ - trạng thái sẵn sàng, kỹ năng, ngôn ngữ, giới hạn khối lượng công việc |
AgentGroup | Một nhóm agent với quản lý thành viên |
| Quy tắc phân công | Quy tắc theo độ ưu tiên trong từng merchant chọn chiến lược phân công tự động |
| Notification + worker | Record giao nhận thời gian thực/email và các worker theo lịch notification/monitor SLA |
Chỉ mang tính khái niệm - toàn bộ schema và bất biến nằm trong domain model helpdesk.
10. Dependencies & Assumptions
Phụ thuộc vào
- Quản lý người dùng (CORE-01) - tài khoản khách hàng và agent; một agent là một user được liên kết với một merchant.
- Commerce (CORE-03) - scope merchant và ngữ cảnh đơn hàng/sản phẩm dùng để làm giàu một ticket.
- Signal (thời gian thực) - giao các cập nhật ticket trực tiếp tới agent và khách hàng qua WebSocket.
- Báo cáo (CORE-11) - bên tiêu thụ phía sau cho dữ liệu tuân thủ SLA và mức hài lòng.
Giả định
- Merchant có ít nhất một agent và một policy SLA được cấu hình (hoặc một giá trị mặc định được áp dụng).
- Quy tắc phân công được cấu hình để phân công tự động chạy; nếu không, ticket ở trạng thái chưa phân công để nhận thủ công.
11. Risks & Open Questions
| Rủi ro / câu hỏi | Giảm thiểu / trạng thái |
|---|---|
| Backend hiện chưa biên dịch sạch | Sửa build là cổng chặn trước khi bất kỳ yêu cầu nào được xem là đã-kiểm-chứng-shipped; theo dõi như known issue của module |
| Không có agent sẵn sàng tại thời điểm phân công | Phân công tự động leo thang tới một quản lý khi không tìm thấy agent đủ điều kiện |
| Độ trễ của monitor SLA có thể bỏ lỡ một deadline sát | Monitor chạy theo lịch; các ngưỡng (75%/90%) cho khoảng đệm cảnh báo trước khi vi phạm |
| Rò rỉ ghi chú nội bộ tới khách hàng | Cưỡng chế phía server - ghi chú nội bộ không bao giờ trả về cho người không phải agent |
| Scope theo organizer so với merchant cho agent/SLA | Đã giải quyết: logic SLA/agent/ticket theo scope organizer (organizerId, nullable) |
12. Release Plan & Launch Criteria
| Aspect | Kế hoạch |
|---|---|
| Phase | Phần lõi hỗ trợ P1 - xem danh mục tính năng URD |
| Rollout | Tất cả merchant; không feature flag |
| Migration | Không (package và entity mới; cấu hình được seed lúc khởi động) |
| Launch criteria | Package biên dịch sạch; tạo→phân công→phản hồi→giải quyết→đóng được kiểm chứng toàn trình; cảnh báo/vi phạm/leo thang SLA phát theo lịch; notification được giao |
| Monitoring | Khối lượng ticket theo từng merchant, tỷ lệ phân công tự động thành công, số đếm cảnh báo/vi phạm SLA, log giao nhận notification |
13. FAQ
Các trạng thái ticket là gì? Tám: OPEN → ASSIGNED → IN_PROGRESS → WAITING_USER / WAITING_INTERNAL → ESCALATED → RESOLVED → CLOSED.
Ticket được phân công như thế nào? Một worker phân công tự động đánh giá các quy tắc theo độ ưu tiên và chọn agent phù hợp nhất đang sẵn sàng theo chiến lược (round robin, theo kỹ năng, cân bằng tải, và hơn nữa), bỏ qua bất kỳ agent nào đã ở giới hạn đồng thời; quản lý cũng có thể phân công thủ công.
Điều gì xảy ra khi một SLA sắp vi phạm? Một monitor theo lịch đánh dấu tracker là cảnh báo tại 75% deadline và vi phạm tại 100%, tạo một leo thang L1; leo thang có thể lên L2 và L3.
Khách hàng có thấy ghi chú nội bộ không? Không - ghi chú nội bộ chỉ dành cho agent và không bao giờ trả về cho người không phải agent.
Phần tăng tiến này có gồm cơ sở tri thức hay khảo sát không? Không - KB, SRV, và FR thuộc P2 và nằm ngoài scope lõi này; chỉ có khung worker của chúng (ví dụ worker kích hoạt khảo sát) tồn tại ở đây.
Ticket có bao giờ bị hard-delete không? Không - mọi record của helpdesk chỉ soft-delete.
References
- URD: Helpdesk - Ticket · Tin nhắn · Category · SLA · Agent · Notification
- Module: Hỗ trợ khách hàng - tổng quan + truy vết
- Developer: @nx/helpdesk · domain model