PRD: Helpdesk core (tickets, SLA, agents)
| Module | Helpdesk | PRD ID | PRD-TKT-001 |
| Status | Ready to dev | FEAT | TKT |
| Epic | — | Plane | BANA-1500 |
| Date | 2026-06-02 | Version | v0.1 |
| Packages | @nx/helpdesk | URD | TKT |
| Surface | Backend | ||
| Owner | Phát Nguyễn | ||
TL;DR
A first-class support desk for merchant teams: customers raise tickets, the system auto-assigns the best available agent, SLA clocks hold response and resolution times to target with warning/breach escalation, and every event fans out as real-time and email notifications. Support becomes tracked end-to-end instead of scattered across ad-hoc channels.
1. Context & Problem
Today, merchant support arrives across scattered, untracked channels - no ticket record with a controlled lifecycle, no agent tied to each request, no service-level clock. Support load, agent accountability, and SLA compliance are impossible to measure, and the gap only widens as merchants scale customer operations.
This increment stands up the Helpdesk 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 eight lifecycle states, resolve, and close - with a full audit trail; records are only archived, never permanently deleted.
- Threaded ticket messages: customer replies, agent replies, follower replies, system messages, and auto-replies, with attachments and an internal-only flag for agent-only notes.
- Ticket classification: hierarchical categories carrying routing defaults, tags, and priority levels.
- SLA management: policies with per-priority response/resolution targets, per-ticket trackers, warning/critical thresholds, a scheduled monitor, and multi-level escalation.
- Agent management: agent profiles (availability, skills, languages, workload cap), agent groups, prioritized assignment rules, and auto-assignment with multiple strategies.
- Event notifications: real-time and email alerts on ticket events, with scheduled 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, customer-satisfaction surveys, and feature requests - out of this increment. Their backend is already built and ships separately; no front-end screens yet.
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 levels 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 flow: 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 ticket scoped to one merchant organizer with subject, description, category, and priority; the reporter is customer-raised or agent-raised on behalf of a customer | URD-TKT-001..003 |
| FR-2 | Ticket follows an eight-state lifecycle - open, assigned, in progress, pending (waiting on the customer), resolved, closed, reopened, and assignment-failed - with assignment/resolution/closure details, a full audit trail, and archive-only deletion | URD-TKT-004..008,012 |
| FR-3 | Re-open on a customer reply after resolution; the customer can confirm resolution, and a resolved ticket auto-closes after a quiet period with no response | URD-TKT-009..010 |
| FR-4 | Threaded typed messages (customer reply, agent reply, follower reply, system message, auto-reply) with attachments and a tracked author; messages flagged internal are 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; priority levels (Low/Medium/High/Urgent/Critical) | URD-CAT-001..005 |
| FR-6 | SLA policies with per-priority response/resolution targets, configurable warning and critical thresholds, optional business-hours-only clock | URD-SLA-001..003 |
| FR-7 | A 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 | Multi-level escalation with typed triggers (SLA breach, manual, customer request, high impact, incident report); 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 assignment rules with multiple strategies; auto-assignment 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 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; 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 |
| Archive-only | All records are archived, never permanently deleted |
| i18n | User-facing labels, statuses, resolution notes, and email templates are bilingual (English/Vietnamese) |
8. UX & Flows
Key screens are surfaced in the merchant support workspace; ticket, message, SLA-tracker, and agent-assignment views all read from the Helpdesk support core.
9. Data & Domain
| Concept | Role |
|---|---|
| Support ticket | The support request record - merchant-organizer scope, status, priority, category, assigned agent, audit trail |
| Ticket message | A typed thread entry (customer reply, agent reply, follower reply, system message, auto-reply) with attachments, an internal-only flag, and a tracked author |
| Ticket category | Hierarchical classification carrying default priority, skills, group, and SLA policy |
| SLA policy | Per-priority response/resolution targets, thresholds, and escalation rules |
| SLA tracker | Per-ticket deadlines and elapsed time against an SLA policy |
| SLA escalation | A typed escalation raised on breach or by request |
| Agent | A user linked as a support agent - availability, skills, languages, workload cap |
| Agent group | A grouping of agents with managed membership |
| Assignment rule | A prioritized rule selecting the auto-assignment strategy |
| Notifications | Real-time/email delivery records plus the scheduled notification and SLA-monitor jobs |
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.
- 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 |
|---|---|
| No available agent at assignment time | Auto-assignment moves the ticket to an assignment-failed state and escalates to a manager when no eligible agent is found |
| SLA monitor lag could miss a tight deadline | Monitor runs on a schedule; warning and critical thresholds give headroom before breach |
| Internal-note leakage to customers | Enforced server-side - internal notes are never returned to non-agent consumers |
| Organizer vs. single-merchant scoping for agents/SLA | Resolved: SLA, agent, and ticket logic are scoped to the merchant's whole organizer |
12. Release Plan & Launch Criteria
| Aspect | Plan |
|---|---|
| Phase | P1 support core - see URD feature catalog |
| Rollout | All merchants; no feature flag |
| Migration | None (new entities; config seeded at startup) |
| Launch criteria | 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 lifecycle states: open, assigned, in progress, pending (waiting on the customer), resolved, closed, reopened, and assignment-failed.
How does a ticket get assigned? Auto-assignment 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 ahead of the deadline and breached at the deadline, creating an escalation; escalation can climb across multiple levels.
Can customers see internal notes? No - notes flagged internal are agent-only and are never returned to non-agent consumers.
Does this increment include the knowledge base or surveys? No - knowledge base, surveys, and feature requests are out of scope here. Their backend is already built in the support backend (article, survey, and feature-request endpoints); the front-end screens aren't shipped yet.
Are tickets ever permanently deleted? No - all helpdesk records are archived only.
References
- URD: Helpdesk - Tickets · Messages · Categories · SLA · Agents · Notifications
- Module: Helpdesk - URD
- Developer: @nx/helpdesk · domain model