URD: Helpdesk
| Module | CORE-13 | Version | v0.2 |
|---|---|---|---|
| Status | In-progress | Date | 2026-05-29 |
1. Purpose
Define the user-facing requirements for the Helpdesk module — support ticket management, agent routing, SLA enforcement, knowledge base, satisfaction surveys, and feature-request tracking — so a merchant's support team can resolve customer issues within committed service levels.
Build status: the backend exists but does not currently compile, so requirements below describe intended behavior. Until the build is repaired no requirement should be treated as verified-shipped. See the module overview.
2. Scope
| Included | Excluded |
|---|---|
| Support ticket lifecycle (CRUD + state machine) | AI-assisted reply suggestions (future) |
| Threaded messages (customer / agent / internal notes) | Predictive SLA breach (future) |
| File attachments on messages | Omni-channel intake (email, Zalo, Messenger) |
| Ticket categories, priorities, tags | Customer self-service portal (future) |
| SLA policies + per-ticket tracking + multi-level escalation | SLA reporting dashboards (Reports module) |
| Agent management (profiles, groups, rules) and auto-assignment | Issuing user accounts (User Management) |
| Knowledge base articles, categories, feedback, view tracking | |
| CSAT / NPS / CES surveys; feature-request voting | |
| Compensation issuance (credit, voucher, refund, …) | |
| Real-time + email notifications and preferences |
3. Definitions
| Term | Definition |
|---|---|
| Ticket | A tracked customer support request with a lifecycle status |
| Agent | A merchant user who works tickets, with availability, skills, and a workload cap |
| SLA | Service Level Agreement — committed first-response and resolution time per priority |
| SLA tracker | Per-ticket record of deadlines and elapsed time against an SLA policy |
| Escalation | Routing a breached or critical ticket to a higher support level |
| Internal note | A message visible only to agents, never to the customer |
| CSAT / NPS / CES | Customer Satisfaction / Net Promoter / Customer Effort survey types |
4. Conceptual Model
Conceptual only — the full schema lives in the developer domain model.
5. Functional Requirements
One table per functional area.
<AREA>codes match the test-case IDs. Priority = MoSCoW (Must / Should / Could / Won't).
5.1 Ticket Management (TKT)
| ID | P | Requirement |
|---|---|---|
| URD-TKT-001 | M | Create a ticket with subject, description, category, and priority |
| URD-TKT-002 | M | A ticket is always scoped to a single merchant |
| URD-TKT-003 | M | Reporter type: customer-raised or agent-raised on behalf of a customer |
| URD-TKT-004 | M | Ticket follows the 8-status lifecycle: OPEN → ASSIGNED → IN_PROGRESS → WAITING_USER / WAITING_INTERNAL → ESCALATED → RESOLVED → CLOSED |
| URD-TKT-005 | M | Assign a ticket to an agent, manually or automatically |
| URD-TKT-006 | M | Record assignment, resolution, and closure details (who, when, resolution note) |
| URD-TKT-007 | M | Store ticket context for enrichment from related services |
| URD-TKT-008 | M | Maintain a full audit trail of every state change and action |
| URD-TKT-009 | S | Re-open a ticket if the customer replies after it was marked resolved |
| URD-TKT-010 | S | Customer confirms resolution; ticket auto-closes after 48h with no response |
| URD-TKT-011 | S | Enrichment annotates a ticket with merchant/order context automatically |
| URD-TKT-012 | S | Tickets are soft-deleted only |
5.2 Ticket Messages (MSG)
| ID | P | Requirement |
|---|---|---|
| URD-MSG-001 | M | Add messages of type comment, customer reply, agent reply, internal note, system message, or auto-reply |
| URD-MSG-002 | M | Internal notes are visible only to agents, never to the customer |
| URD-MSG-003 | M | Messages support file attachments |
| URD-MSG-004 | M | Track the author and author type (customer / agent) of each message |
| URD-MSG-005 | S | System auto-appends a system message on each state transition |
5.3 Categories, Tags & Priorities (CAT)
| ID | P | Requirement |
|---|---|---|
| URD-CAT-001 | M | Hierarchical ticket categories (parent/child) with icon and color |
| URD-CAT-002 | M | A category defines default priority, required skills, default group, and SLA policy |
| URD-CAT-003 | M | Manage ticket tags (create, edit, remove) |
| URD-CAT-004 | S | Add and remove tags on a ticket |
| URD-CAT-005 | M | Four priority levels: Low, Medium, High, Critical |
5.4 SLA Management (SLA)
| ID | P | Requirement |
|---|---|---|
| URD-SLA-001 | M | Define SLA policies with response time and resolution time per priority |
| URD-SLA-002 | M | Configure warning (default 75%) and critical (default 90%) thresholds |
| URD-SLA-003 | M | Optionally restrict the SLA clock to business hours only |
| URD-SLA-004 | M | Create an SLA tracker at ticket creation with response and resolution deadlines |
| URD-SLA-005 | M | A scheduled monitor marks warning and breached states automatically |
| URD-SLA-006 | M | Record first-response time and time-to-resolution |
| URD-SLA-007 | M | Support three escalation levels (L1, L2, L3) |
| URD-SLA-008 | M | Escalation types: SLA breach, manual, customer request, high impact, incident report |
| URD-SLA-009 | S | Escalation rules are configurable within an SLA policy |
| URD-SLA-010 | S | A ticket category's SLA policy overrides the global default |
5.5 Agent Management (AGT)
| ID | P | Requirement |
|---|---|---|
| URD-AGT-001 | M | Link a user account as an agent within a merchant (one agent per user) |
| URD-AGT-002 | M | Agent availability status: online, away, offline, busy |
| URD-AGT-003 | M | Agent defines skills, languages, and a max concurrent ticket cap |
| URD-AGT-004 | M | Group agents and manage group membership |
| URD-AGT-005 | M | Configure prioritized assignment rules per merchant |
| URD-AGT-006 | M | Assignment strategies: round robin, skill-based, skill-based round robin, load-balanced, manual, best experience, fastest resolution |
| URD-AGT-007 | M | An auto-assignment worker evaluates rules and selects the best available agent |
| URD-AGT-008 | S | Track agent performance: avg response/resolution time, SLA compliance, satisfaction score |
| URD-AGT-009 | S | Agent schedule for business-hours availability |
| URD-AGT-010 | M | Skip an agent already at their max concurrent ticket cap |
5.6 Knowledge Base (KB)
| ID | P | Requirement |
|---|---|---|
| URD-KB-001 | S | Create and manage multilingual articles (title, content, excerpt) |
| URD-KB-002 | S | Article lifecycle: draft → published → archived |
| URD-KB-003 | S | Articles have category, author, locale, globally-unique slug, and tags |
| URD-KB-004 | S | Track view, helpful, and not-helpful counts per article |
| URD-KB-005 | S | Hierarchical article categories |
| URD-KB-006 | C | Customers submit helpful / not-helpful feedback |
| URD-KB-007 | C | View tracking records individual article views |
5.7 Surveys & Feedback (SRV)
| ID | P | Requirement |
|---|---|---|
| URD-SRV-001 | S | Create surveys of type CSAT, NPS, or CES |
| URD-SRV-002 | S | Trigger modes: post-resolution, post-close, or periodic |
| URD-SRV-003 | S | Add and reorder survey questions |
| URD-SRV-004 | S | A worker auto-sends the survey to the customer after resolution |
| URD-SRV-005 | S | Capture and store survey responses |
| URD-SRV-006 | S | Response data feeds the agent satisfaction score |
5.8 Feature Requests (FR)
| ID | P | Requirement |
|---|---|---|
| URD-FR-001 | S | Customers submit feature requests with title, description, category, tags |
| URD-FR-002 | S | Lifecycle: submitted → under review → planned → in development → completed / declined / duplicate |
| URD-FR-003 | S | One vote per customer; unvote supported |
| URD-FR-004 | S | A feature request may be linked to a source ticket |
| URD-FR-005 | C | Internal and resolution notes for the product team |
5.9 Compensation (CMP)
| ID | P | Requirement |
|---|---|---|
| URD-CMP-001 | S | Issue compensation on SLA breach or at agent discretion |
| URD-CMP-002 | S | Types: store credit, voucher, refund, discount, free shipping |
| URD-CMP-003 | S | Lifecycle: pending → processing → completed / failed / cancelled / expired |
| URD-CMP-004 | S | Link compensation to a ticket and, optionally, an escalation |
5.10 Notifications (NTF)
| ID | P | Requirement |
|---|---|---|
| URD-NTF-001 | M | Real-time notifications to agents and customers on ticket events |
| URD-NTF-002 | S | Email notifications on creation, assignment, reply, and resolution |
| URD-NTF-003 | S | Per-user notification preferences (opt-in per event type) |
| URD-NTF-004 | S | Customizable notification templates per event |
| URD-NTF-005 | S | Batched delivery with a per-recipient delivery log |
6. Acceptance Criteria
AC-TKT-01: Ticket Creation
| Given | When | Then |
|---|---|---|
| Authenticated customer | Creates a ticket with required fields | Ticket saved as OPEN; SLA tracker initialized with deadlines |
| Assignment rules configured | Ticket created | Auto-assignment runs within 2 minutes; status → ASSIGNED |
AC-TKT-02: State Transitions
| Given | When | Then |
|---|---|---|
| OPEN ticket | Agent assigned | Status → ASSIGNED |
| ASSIGNED ticket | Agent sends first reply | Status → IN_PROGRESS; first-response time recorded |
| IN_PROGRESS ticket | Agent awaits customer info | Status → WAITING_USER |
| WAITING_USER ticket | Customer replies | Status → IN_PROGRESS |
| IN_PROGRESS ticket | Agent marks resolved | Status → RESOLVED; resolution details recorded |
| RESOLVED ticket | Customer confirms | Status → CLOSED |
| RESOLVED ticket | Customer replies | Status → IN_PROGRESS (re-opened) |
AC-SLA-01: SLA Enforcement
| Given | When | Then |
|---|---|---|
| SLA policy applied | Ticket created | First-response deadline = now + response time |
| 75% of deadline elapsed | Monitor runs | SLA status = warning; agent notified |
| 100% of deadline elapsed | Monitor runs | SLA status = breached; L1 escalation created |
| Agent responds in time | Before deadline | First-response status = OK; time-to-first-response recorded |
AC-AGT-01: Assignment
| Given | When | Then |
|---|---|---|
| Rule = round robin | Ticket arrives | Next agent in rotation assigned |
| Rule = skill-based; category needs "billing" | Auto-assignment runs | Agent with that skill and lowest load selected |
| Agent at max concurrent tickets | Auto-assignment runs | Agent skipped; next eligible agent chosen |
| No available agents | Auto-assignment runs | Escalated to manager |
7. Constraints & Non-Goals
Constraints
| ID | Constraint |
|---|---|
| C-01 | Tickets are always scoped to a merchant |
| C-02 | One SLA tracker per ticket; immutable after breach |
| C-03 | Internal notes are never returned to non-agent consumers |
| C-04 | Article slug is globally unique |
| C-05 | One agent profile per user |
| C-06 | One feature-request vote per customer per request |
| C-07 | All records use soft-delete |
| C-08 | A resolved ticket auto-closes 48h after resolution if unconfirmed |
Non-Goals
- AI-powered reply suggestions
- Predictive SLA breach warning
- Omni-channel intake (email, Zalo OA, Facebook Messenger)
- Customer-facing self-service ticket portal
- SLA reporting dashboards (Reports module)
8. Version History
| Date | Author | Description | Ver |
|---|---|---|---|
| 2026-05-07 | GitHub Copilot | Initial draft from schema and system-design exploration | v0.1 |
| 2026-05-29 | Docs migration | Restructured to module convention; status set to In-progress (build broken); area codes aligned with test cases | v0.2 |