PRD: Knowledge base, surveys & feedback
| Module | Helpdesk (CORE-13) | PRD ID | PRD-KB-001 |
| Status | In-progress | Owner | Helpdesk squad |
| Date | 2026-06-02 | Version | v0.1 |
| Packages | @nx/helpdesk · @nx/core | URD | KB · SRV · FR · CMP |
TL;DR
Gives a merchant's support team a self-service and feedback layer on top of the ticketing core: a multilingual knowledge base to deflect tickets, CSAT/NPS/CES surveys auto-sent after resolution to measure quality, a feature-request channel with one-vote-per-customer, and an agent-issued compensation path to make good on breaches. The result: customers resolve issues without an agent, support quality becomes measurable, and product demand and goodwill are both captured against the ticket that prompted them.
1. Context & Problem
The ticketing core lets agents work tickets through a lifecycle with SLA enforcement, but it stops at the point of resolution. There is no way for a customer to self-serve before raising a ticket, no signal on whether the support that was given actually satisfied them, no channel to capture the product demand that surfaces inside support conversations, and no controlled way for an agent to compensate a customer after a breach. Without these, ticket volume stays high, support quality is invisible, customer demand is lost, and goodwill gestures are ad-hoc and untracked.
This layer builds on the existing ticket → message → SLA → agent core to close the loop: deflect with a knowledge base, measure with surveys, capture demand with feature requests, and recover trust with compensation.
2. Goals & Non-Goals
Goals
- A multilingual knowledge base: articles (title, content, excerpt) with a
draft → published → archivedlifecycle, hierarchical categories, a globally-unique slug, author/locale/tags, and view + helpful + not-helpful tracking. - Surveys & feedback: CSAT / NPS / CES surveys with ordered questions, a post-resolution / post-close / periodic trigger, a worker that auto-sends after resolution, response capture, and a feed into each agent's satisfaction score.
- Feature requests: customer-submitted requests through a product-tracking lifecycle, one vote per customer (with unvote), and an optional link back to the source ticket.
- Compensation: agent-issued goodwill (store credit, voucher, refund, discount, free shipping) on a breach or at discretion, with its own
pending → processing → completedlifecycle, linked to a ticket and optionally an escalation.
Non-Goals
- AI-assisted reply suggestions and predictive SLA breach (URD future).
- Omni-channel intake (email, Zalo OA, Messenger) and a customer-facing self-service ticket portal.
- SLA reporting dashboards - owned by the Reports module.
3. Success Metrics
| Metric | Target / signal |
|---|---|
| Ticket deflection | Published articles accrue views and helpful ratings; article reads correlate with lower ticket creation |
| Survey coverage | Resolved tickets that trigger and capture a survey response |
| Satisfaction signal | Survey responses feed a per-agent satisfaction score with no orphaned responses |
| Demand capture | Feature requests submitted and voted, each with at most one vote per customer |
| Goodwill traceability | 100% of compensations linked to a ticket; none stuck outside the pending → completed lifecycle |
4. Personas & Use Cases
| Persona | Goal in this feature |
|---|---|
| Customer | Read help articles to self-serve, rate them, answer a post-resolution survey, submit and vote on feature requests |
| Support Agent | Issue goodwill compensation on a difficult or breached ticket |
| Support Manager | Author and publish knowledge-base articles, configure surveys, triage feature requests |
Core scenarios: a customer reads a published article and rates it helpful → after a ticket resolves, the survey worker auto-sends a CSAT/NPS/CES survey whose response feeds the agent's satisfaction score → a customer submits a feature request and others vote → an agent issues compensation on a breached ticket and it moves through its lifecycle.
5. User Stories
- As a support manager, I want to write multilingual articles in hierarchical categories with a draft → published → archived lifecycle, so customers can self-serve in their language.
- As a customer, I want to read a published article and mark it helpful or not, so the merchant knows which content works.
- As a support manager, I want a survey auto-sent after a ticket resolves, so I can measure support quality without manual effort.
- As a customer, I want to answer a CSAT/NPS/CES survey, so my feedback reaches the team that helped me.
- As a customer, I want to submit a feature request and vote on others (once), so the product team sees real demand.
- As a support agent, I want to issue goodwill compensation on a breached ticket, so I can recover customer trust with a tracked gesture.
6. Functional Requirements
| # | Requirement | URD ref |
|---|---|---|
| FR-1 | Create and manage multilingual articles (title, content, excerpt) with draft → published → archived lifecycle | URD-KB-001..002 |
| FR-2 | Articles carry category, author, locale, a globally-unique slug, and tags; categories are hierarchical | URD-KB-003 · URD-KB-005 |
| FR-3 | Track view, helpful, and not-helpful counts per article; customers submit helpful/not-helpful feedback; views are recorded individually | URD-KB-004 · URD-KB-006..007 |
| FR-4 | Create surveys of type CSAT, NPS, or CES with ordered, reorderable questions | URD-SRV-001 · URD-SRV-003 |
| FR-5 | Trigger modes - post-resolution, post-close, periodic; a worker auto-sends the survey after a ticket resolves | URD-SRV-002 · URD-SRV-004 |
| FR-6 | Capture and store survey responses; responses feed the agent satisfaction score | URD-SRV-005..006 |
| FR-7 | Customers submit feature requests (title, description, category, tags) through a product-tracking lifecycle | URD-FR-001..002 |
| FR-8 | One vote per customer per request, with unvote; a request may link to a source ticket; internal/resolution notes | URD-FR-003..005 |
| FR-9 | Issue compensation on SLA breach or at discretion; types: store credit, voucher, refund, discount, free shipping | URD-CMP-001..002 |
| FR-10 | Compensation follows pending → processing → completed / failed / cancelled / expired, linked to a ticket and optionally an escalation | URD-CMP-003..004 |
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 | Article slug is globally unique; one vote per customer per request is enforced; survey responses never orphan from their agent score |
| Tenancy & authz | All operations scoped per merchant (x-merchant-id); gated by helpdesk permissions (route-level permission check) |
| Soft-delete | All records use soft-delete; corrections never hard-delete history |
| Reliability | Post-resolution survey send runs in a worker (survey-trigger), decoupled from the resolving request |
| i18n | Article content and user-facing labels are bilingual ({ en, vi }) |
8. UX & Flows
Key screens (in the support workspace): article + category management, the survey builder, the feature-request board with voting, and the compensation issuance flow on a ticket.
9. Data & Domain
| Entity | Role |
|---|---|
Article · ArticleCategory | Knowledge-base content and its hierarchical category |
ArticleView · ArticleFeedback | Per-view tracking and helpful/not-helpful feedback |
Survey · SurveyQuestion · SurveyResponse | Survey definition, ordered questions, and captured responses |
FeatureRequest · FeatureVote | Customer requests and one-vote-per-customer records |
Compensation | Agent-issued goodwill with its own lifecycle, linked to a ticket/escalation |
Conceptual only - full schema and invariants in the helpdesk domain model. Schemas live in the centralized
core/models/schemas/helpdeskset.
10. Dependencies & Assumptions
Depends on
- Ticket core (URD-TKT · URD-SLA) - resolution drives the survey trigger; breaches drive compensation.
- Agents (URD-AGT) - survey responses feed each agent's satisfaction score.
- User Management (
@nx/core) - customer and agent identities behind feedback, votes, and authorship.
Assumptions
- A resolution event is emitted that the
survey-triggerworker can consume. - Customers are identifiable so a one-vote-per-customer rule and per-customer feedback can be enforced.
- A survey exists with a post-resolution trigger for the auto-send path to fire.
11. Risks & Open Questions
| Risk / question | Mitigation / status |
|---|---|
| Package does not currently compile (dead reference) | Tracked at the module level; blocks verified-shipped, not scope |
| Duplicate or abusive votes inflate demand | One-vote-per-customer per request enforced at the data layer (C-06), with unvote |
| Survey send failing silently after resolution | Runs in a dedicated worker, decoupled and retryable, not inline with the resolve request |
| Compensation issued but never fulfilled | Lifecycle includes failed / cancelled / expired; every compensation links to a ticket |
| Article slug collisions across merchants | Slug is globally unique (C-04) |
12. Release Plan & Launch Criteria
| Aspect | Plan |
|---|---|
| Phase | P2 (KB, SRV, FR) · P1 (CMP) - see URD feature catalog |
| Rollout | All merchants once the package build is repaired; no feature flag |
| Migration | None - new entities in core/models/schemas/helpdesk; survey config authored per merchant |
| Launch criteria | Article publish → read → rate verified; survey auto-send → response → agent-score verified; one-vote-per-customer enforced; compensation lifecycle verified end-to-end |
| Monitoring | Article views/helpful ratios, survey send + response rate, feature-request votes, compensation completion rate |
13. FAQ
Can the same article slug be reused across merchants? No - the slug is globally unique. Each article needs a distinct slug.
When is a survey sent? When a ticket resolves (or closes, or on a periodic schedule, depending on the trigger mode). A survey-trigger worker auto-sends it; it is not sent inline with the agent's resolve action.
Can a customer vote on a feature request more than once? No - one vote per customer per request. Unvote is supported, so a customer can withdraw their vote.
Does issuing compensation pay the customer immediately? Not necessarily - compensation moves through pending → processing → completed, and can also end in failed / cancelled / expired. Issuing it records the intent and tracks fulfilment.
Where do feedback and survey responses go? Helpful/not-helpful feedback is tracked per article; survey responses are stored and feed the responsible agent's satisfaction score.
References
- URD: Helpdesk - Knowledge Base · Surveys & Feedback · Feature Requests · Compensation
- Builds on: Ticket Management · SLA Management · Agent Management
- Module: Helpdesk - overview + traceability
- Developer: @nx/helpdesk · domain model