URD: Helpdesk

Module	CORE-13	Version	v0.3
Status	In-progress	Date	2026-06-04

Business documentation. This URD is Helpdesk's feature list - each feature below is one Functional Area (<AREA>). The same <AREA> keys the feature's PRDs (PRD-<AREA>-NNN) and tests (TC-<AREA>-NNN), and each feature is listed in the Delivery feature catalog. See the Feature Spine convention.

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. Feature Catalog

The feature list of this module. Each row is one feature (a Functional Area). Detail in §6. Mirrored in the Delivery feature catalog.

Feature ID	Feature	Phase	Status	Priority
TKT	Ticket Management	P1	In-progress	High
MSG	Ticket Messages	P1	In-progress	High
CAT	Categories, Tags & Priorities	P1	In-progress	High
SLA	SLA Management	P1	In-progress	High
AGT	Agent Management	P1	In-progress	High
KB	Knowledge Base	P2	In-progress	Medium
SRV	Surveys & Feedback	P2	In-progress	Medium
FR	Feature Requests	P2	In-progress	Medium
CMP	Compensation	P1	In-progress	Medium
NTF	Notifications	P1	In-progress	High

Status: live from Plane where mapped, otherwise registry-declared. Vocabulary mirrors Plane (state-group / phase).

6. Features

One sub-section per feature, in catalog order. Each feature keeps its description, requirements, and acceptance together. Priority = MoSCoW (Must / Should / Could / Won't).

TKT - Ticket Management In-progress

Feature ID: helpdesk/TKT · Phase: P1 · PRDs: - · Dev: @nx/helpdesk

What it does for users: customers raise support tickets and agents work them through an 8-status lifecycle, with assignment, resolution, and closure tracked alongside a full audit trail.

Requirements

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

Acceptance

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)

MSG - Ticket Messages In-progress

Feature ID: helpdesk/MSG · Phase: P1 · PRDs: - · Dev: @nx/helpdesk

What it does for users: every ticket carries a thread of typed messages - customer and agent replies, internal notes only agents can see, and system messages - each with attachments and a tracked author.

Requirements

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

Acceptance

AC-MSG-01: Internal note visibility

Given	When	Then
Agent adds an internal note on a ticket	A non-agent consumer reads the thread	The internal note is never returned
Any state transition occurs	-	A system message is auto-appended

CAT - Categories, Tags & Priorities In-progress

Feature ID: helpdesk/CAT · Phase: P1 · PRDs: - · Dev: @nx/helpdesk

What it does for users: tickets are classified by hierarchical categories that carry routing defaults (priority, skills, group, SLA), labelled with tags, and ranked across four priority levels.

Requirements

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

Acceptance

AC-CAT-01: Category defaults

Given	When	Then
A category with default priority, skills, group, and SLA policy	A ticket is classified under it	Those defaults apply to the new ticket

SLA - SLA Management In-progress

Feature ID: helpdesk/SLA · Phase: P1 · PRDs: - · Dev: @nx/helpdesk

What it does for users: response and resolution targets are defined per priority and tracked per ticket; a scheduled monitor warns before and flags after a breach, escalating across three levels.

Requirements

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

Acceptance

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

AGT - Agent Management In-progress

Feature ID: helpdesk/AGT · Phase: P1 · PRDs: - · Dev: @nx/helpdesk

What it does for users: support staff are modelled as agents with availability, skills, languages, groups, and a workload cap, and new tickets are auto-routed to the best available agent via configurable rules.

Requirements

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

Acceptance

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

KB - Knowledge Base In-progress

Feature ID: helpdesk/KB · Phase: P2 · PRDs: - · Dev: @nx/helpdesk

What it does for users: merchants publish multilingual help articles, organized in hierarchical categories, that customers can read, rate as helpful or not, and whose views are tracked.

Requirements

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

Acceptance

AC-KB-01: Article publishing

Given	When	Then
A draft article with a globally-unique slug	Published	It becomes readable; views and helpful/not-helpful counts are tracked

SRV - Surveys & Feedback In-progress

Feature ID: helpdesk/SRV · Phase: P2 · PRDs: - · Dev: @nx/helpdesk

What it does for users: merchants run CSAT, NPS, or CES surveys, auto-sent after a ticket is resolved, whose responses feed each agent's satisfaction score.

Requirements

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

Acceptance

AC-SRV-01: Post-resolution survey

Given	When	Then
A survey with post-resolution trigger	A ticket is resolved	The worker auto-sends the survey; responses are stored and feed the agent satisfaction score

FR - Feature Requests In-progress

Feature ID: helpdesk/FR · Phase: P2 · PRDs: - · Dev: @nx/helpdesk

What it does for users: customers submit and vote on feature requests that move through a product-tracking lifecycle and can be linked back to the ticket that prompted them.

Requirements

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

Acceptance

AC-FR-01: One vote per customer

Given	When	Then
A customer who has voted on a request	Votes again	The vote count is unchanged; unvote is supported

CMP - Compensation In-progress

Feature ID: helpdesk/CMP · Phase: P1 · PRDs: - · Dev: @nx/helpdesk

What it does for users: agents issue goodwill compensation - store credit, voucher, refund, discount, or free shipping - on a breached or difficult ticket, tracked through its own lifecycle.

Requirements

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

Acceptance

AC-CMP-01: Issue compensation

Given	When	Then
An SLA breach or agent decision	Compensation is issued	It is linked to the ticket and moves through pending → processing → completed

NTF - Notifications In-progress

Feature ID: helpdesk/NTF · Phase: P1 · PRDs: - · Dev: @nx/helpdesk

What it does for users: agents and customers receive real-time and email alerts on ticket events, governed by per-user preferences and customizable templates.

Requirements

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

Acceptance

AC-NTF-01: Event notifications

Given	When	Then
A ticket event occurs (creation, assignment, reply, resolution)	-	Subscribed agents and customers receive real-time notifications per their preferences

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
2026-06-04	Claude (AI pair)	Reorganize by feature (Feature Spine)	v0.3