PRD: Helpdesk core (tickets, SLA, agents)
| Module | Helpdesk (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
Gives a merchant's support team a first-class way to receive, route, and resolve customer requests within committed service levels. Customers raise tickets, the system auto-assigns them to the best available agent, SLA policies keep response and resolution times honest with warning/breach escalation, and every event fans out as real-time and email notifications. The result: support is tracked end-to-end instead of scattered across ad-hoc channels.
1. Context & Problem
KICKO merchants have no first-class way to receive, route, and resolve customer support requests within committed service levels. Support arrives across scattered, untracked channels: there is no ticket document with a controlled lifecycle, no way to tie a request to a responsible agent, and no service-level clock to keep response and resolution times honest. This makes support load, agent accountability, and SLA compliance impossible to measure - a gap for the merchants KICKO serves as they scale customer operations.
This increment stands up the Helpdesk backend as a new IGNIS package and delivers the support core: ticket lifecycle, threaded messages, classification, SLA enforcement, agent routing, and event notifications.
2. Goals & Non-Goals
Goals
- A support ticket lifecycle: create, classify, assign, transition through the 8-status state machine, resolve, and close - with a full audit trail and soft-delete.
- Threaded ticket messages: customer/agent replies, internal notes (agent-only), system messages, and attachments.
- Ticket classification: hierarchical categories carrying routing defaults, tags, and four priority levels.
- SLA management: policies with per-priority response/resolution targets, per-ticket trackers, warning/breach thresholds, a scheduled monitor, and three-level escalation.
- Agent management: agent profiles (availability, skills, languages, workload cap), agent groups, prioritized assignment rules, and an auto-assignment worker with multiple strategies.
- Event notifications: real-time (WebSocket) and email alerts on ticket events, with worker-driven delivery and templates.
Non-Goals
- AI-assisted reply suggestions and predictive SLA-breach warning.
- Omni-channel intake (email, Zalo OA, Facebook Messenger).
- Customer-facing self-service ticket portal.
- SLA reporting dashboards - owned by the Reports module.
- Knowledge base (
KB), surveys (SRV), and feature requests (FR) - those P2 areas are out of this core increment.
3. Success Metrics
| Metric | Target / signal |
|---|---|
| Traceability | 100% of support requests flow through a tracked ticket, not ad-hoc channels |
| First-response time | First-response deadline met within the SLA target per priority |
| Auto-assignment coverage | New tickets auto-routed to an eligible agent within 2 minutes |
| SLA compliance | Share of tickets resolved before breach trends up; warning fires before breach |
| Escalation health | Breached/critical tickets escalate across L1→L3 without manual chasing |
4. Personas & Use Cases
| Persona | Goal in this feature |
|---|---|
| Customer | Raise a request, get replies, confirm resolution |
| Support Agent | Work assigned tickets, reply, add internal notes, resolve within SLA |
| Support Manager | Configure SLA policies, assignment rules, categories; handle escalations |
Core scenarios: a customer raises a ticket → the system opens it, starts the SLA clock, and auto-assigns the best available agent → the agent replies and works the lifecycle → SLA is tracked with warning/breach escalation → the ticket is resolved and closed, with notifications at every step.
5. User Stories
- As a customer, I want to raise a support ticket with a subject, category, and priority, so my request is tracked.
- As a support agent, I want new tickets auto-assigned to me based on skills and load, so I work the right tickets without manual triage.
- As a support agent, I want to reply, add internal notes, and attach files, so I can collaborate and resolve the ticket.
- As a support agent, I want the ticket to move through a clear status lifecycle, so its state is always unambiguous.
- As a support manager, I want SLA policies with response/resolution targets per priority, so the team is held to committed service levels.
- As a support manager, I want breached or critical tickets to escalate across levels, so nothing falls through the cracks.
- As a customer, I want real-time and email alerts on my ticket, so I know when an agent responds.
6. Functional Requirements
| # | Requirement | URD ref |
|---|---|---|
| FR-1 | Create a merchant-scoped ticket with subject, description, category, and priority; reporter is customer-raised or agent-raised on behalf of a customer | URD-TKT-001..003 |
| FR-2 | Ticket follows the 8-status lifecycle OPEN → ASSIGNED → IN_PROGRESS → WAITING_USER / WAITING_INTERNAL → ESCALATED → RESOLVED → CLOSED, with assignment/resolution/closure details, a full audit trail, and soft-delete only | URD-TKT-004..008,012 |
| FR-3 | Re-open on customer reply after resolution; customer confirms resolution and a resolved ticket auto-closes 48h after with no response | URD-TKT-009..010 |
| FR-4 | Threaded typed messages (comment, customer/agent reply, internal note, system, auto-reply) with attachments and tracked author; internal notes never returned to non-agents; a system message is auto-appended on each transition | URD-MSG-001..005 |
| FR-5 | Hierarchical ticket categories carrying default priority, skills, group, and SLA policy; ticket tags; four priority levels (Low/Medium/High/Critical) | URD-CAT-001..005 |
| FR-6 | SLA policies with per-priority response/resolution targets, configurable warning (75%) and critical (90%) thresholds, optional business-hours-only clock | URD-SLA-001..003 |
| FR-7 | Per-ticket SLA tracker created at ticket creation; a scheduled monitor marks warning/breached automatically and records first-response and time-to-resolution | URD-SLA-004..006 |
| FR-8 | Three escalation levels (L1/L2/L3) with typed triggers (SLA breach, manual, customer request, high impact, incident); rules configurable in a policy; a category SLA overrides the global default | URD-SLA-007..010 |
| FR-9 | Agent profiles (one per user) with availability, skills, languages, and a max concurrent cap; agent groups with membership management | URD-AGT-001..004 |
| FR-10 | Prioritized per-merchant assignment rules with multiple strategies; an auto-assignment worker selects the best available agent and skips agents at their cap | URD-AGT-005..007,010 |
| FR-11 | Track agent performance (avg response/resolution, SLA compliance, satisfaction) and a business-hours availability schedule | URD-AGT-008..009 |
| FR-12 | Real-time (WebSocket) and email notifications on ticket events, per-user preferences, customizable templates, and batched delivery with a per-recipient log | URD-NTF-001..005 |
Full requirement text and acceptance criteria live in the Helpdesk URD. This PRD references them rather than restating them.
7. Non-Functional Requirements
| Area | Requirement |
|---|---|
| Data integrity | One SLA tracker per ticket, immutable after breach; every state change and action recorded in the audit trail |
| Immutability | Internal notes are never returned to non-agent consumers; system messages are auto-appended, not edited in place |
| Tenancy & authz | Tickets are always scoped to a single merchant (organizer-scoped); agent vs. manager actions gated by helpdesk permissions |
| Performance / scale | Auto-assignment runs within 2 minutes of ticket creation; the SLA monitor runs on a schedule independent of request traffic |
| Soft-delete | All records soft-deleted only |
| i18n | User-facing labels, statuses, resolution notes, and email templates are bilingual ({ en, vi }) |
8. UX & Flows
Key screens are served by the Helpdesk backend's APIs and surfaced in the merchant support workspace; ticket, message, SLA-tracker, and agent-assignment views all read from @nx/helpdesk.
9. Data & Domain
| Entity | Role |
|---|---|
Ticket | The support request document - merchant scope, status, priority, category, assigned agent, audit trail |
TicketMessage | A typed thread entry (customer/agent reply, internal note, system, auto-reply) with attachments and tracked author |
TicketCategory | Hierarchical classification carrying default priority, skills, group, and SLA policy |
SlaPolicy | Per-priority response/resolution targets, thresholds, and escalation rules |
SlaTracker | Per-ticket deadlines and elapsed time against an SLA policy |
SlaEscalation | A typed escalation (L1/L2/L3) raised on breach or by request |
Agent | A user linked as a support agent - availability, skills, languages, workload cap |
AgentGroup | A grouping of agents with managed membership |
| Assignment rule | Prioritized per-merchant rule selecting the auto-assignment strategy |
| Notification + worker | Real-time/email delivery records and the scheduled notification/SLA-monitor workers |
Conceptual only - full schema and invariants in the helpdesk domain model.
10. Dependencies & Assumptions
Depends on
- User Management (CORE-01) - customer and agent accounts; an agent is a user linked to a merchant.
- Commerce (CORE-03) - merchant scope and order/product context used to enrich a ticket.
- Signal (real-time) - delivers live ticket updates to agents and customers over WebSocket.
- Reports (CORE-11) - downstream consumer of SLA-compliance and satisfaction data.
Assumptions
- The merchant has at least one agent and a configured SLA policy (or a default applies).
- Assignment rules are configured for auto-assignment to run; otherwise tickets stay unassigned for manual pickup.
11. Risks & Open Questions
| Risk / question | Mitigation / status |
|---|---|
| Backend does not currently compile cleanly | Build repair is the gate before any requirement is treated as verified-shipped; tracked as the module's known issue |
| No available agent at assignment time | Auto-assignment escalates to a manager when no eligible agent is found |
| SLA monitor lag could miss a tight deadline | Monitor runs on a schedule; thresholds (75%/90%) give warning headroom before breach |
| Internal-note leakage to customers | Enforced server-side - internal notes are never returned to non-agent consumers |
| Organizer vs. merchant scoping for agents/SLA | Resolved: SLA/agent/ticket logic is organizer-scoped (organizerId, nullable) |
12. Release Plan & Launch Criteria
| Aspect | Plan |
|---|---|
| Phase | P1 support core - see URD feature catalog |
| Rollout | All merchants; no feature flag |
| Migration | None (new package and entities; config seeded at startup) |
| Launch criteria | Package builds cleanly; create→assign→reply→resolve→close verified end-to-end; SLA warning/breach/escalation fires on schedule; notifications delivered |
| Monitoring | Ticket volume per merchant, auto-assignment success rate, SLA warning/breach counts, notification delivery log |
13. FAQ
What are the ticket statuses? Eight: OPEN → ASSIGNED → IN_PROGRESS → WAITING_USER / WAITING_INTERNAL → ESCALATED → RESOLVED → CLOSED.
How does a ticket get assigned? An auto-assignment worker evaluates prioritized rules and picks the best available agent by strategy (round robin, skill-based, load-balanced, and more), skipping any agent at their concurrent cap; a manager can also assign manually.
What happens when an SLA is about to breach? A scheduled monitor marks the tracker as warning at 75% of the deadline and breached at 100%, creating an L1 escalation; escalation can climb to L2 and L3.
Can customers see internal notes? No - internal notes are agent-only and are never returned to non-agent consumers.
Does this increment include the knowledge base or surveys? No - KB, SRV, and FR are P2 and out of this core scope; only their worker scaffolding (e.g. the survey-trigger worker) exists here.
Are tickets ever hard-deleted? No - all helpdesk records are soft-deleted only.
References
- URD: Helpdesk - Tickets · Messages · Categories · SLA · Agents · Notifications
- Module: Helpdesk - overview + traceability
- Developer: @nx/helpdesk · domain model