Knowledge Base & Surveys
@nx/helpdesk provides a knowledge base so customers can self-resolve issues, a CSAT survey system triggered automatically when tickets close, and a feature-request board with voting.
Knowledge Base
Data Model
ArticleCategory
| Column | Type | Description |
|---|---|---|
id | bigint | Snowflake ID |
merchantId | bigint | Tenant scope |
name | jsonb | Category name (i18n: {en, vi}) |
slug | varchar | URL-friendly slug (slugified) |
parentId | bigint | FK → ArticleCategory (hierarchical) |
isActive | boolean | Visibility flag |
sortOrder | smallint | Display order |
Article
| Column | Type | Description |
|---|---|---|
id | bigint | Snowflake ID |
merchantId | bigint | Tenant scope |
categoryId | bigint | FK → ArticleCategory |
title | jsonb | Title (i18n: {en, vi}) |
slug | varchar | URL-friendly slug |
content | jsonb | Body content (i18n, rich text) |
status | enum | DRAFT / PUBLISHED / ARCHIVED |
viewCount | int | Total view count |
helpfulCount | int | "Helpful" feedback count |
notHelpfulCount | int | "Not helpful" feedback count |
publishedAt | timestamp | Publication timestamp |
ArticleView
Tracks individual article views:
| Column | Type | Description |
|---|---|---|
articleId | bigint | FK → Article |
userId | bigint | Viewer (null if anonymous) |
sessionId | varchar | Session ID for anonymous tracking |
viewedAt | timestamp | View timestamp |
ArticleFeedback
| Column | Type | Description |
|---|---|---|
articleId | bigint | FK → Article |
userId | bigint | Feedback author |
isHelpful | boolean | true = helpful, false = not helpful |
comment | text | Optional comment |
REST API
Articles and article categories — full endpoint reference rendered live from /v1/api/helpdesk/doc/openapi.json. Served by ArticleController and ArticleCategoryController. Endpoint tables are intentionally not hand-maintained.
Use Cases — Articles
| Use Case | Description |
|---|---|
CreateArticleUseCase | Create article with DRAFT status |
UpdateArticleUseCase | Update content/metadata |
PublishArticleUseCase | Transition to PUBLISHED |
DeleteArticleUseCase | Soft-delete |
GetArticleUseCase | Fetch details + record view |
ListArticlesUseCase | Search and filter |
SubmitArticleFeedbackUseCase | Submit helpful/not-helpful feedback |
RecordArticleViewUseCase | Record a view event |
CreateArticleCategoryUseCase | Create a category |
UpdateArticleCategoryUseCase | Update a category |
DeleteArticleCategoryUseCase | Remove a category |
ListArticleCategoriesUseCase | List hierarchical categories |
CSAT Surveys
Satisfaction surveys are triggered automatically when a ticket closes.
Data Model
Survey
| Column | Type | Description |
|---|---|---|
id | bigint | Snowflake ID |
merchantId | bigint | Tenant scope |
name | jsonb | Survey name (i18n) |
triggerEvent | enum | Trigger event (e.g. TICKET_CLOSED) |
isActive | boolean | Active flag |
SurveyQuestion
| Column | Type | Description |
|---|---|---|
surveyId | bigint | FK → Survey |
questionText | jsonb | Question text (i18n) |
questionType | enum | RATING / TEXT / MULTIPLE_CHOICE |
options | jsonb | Choices (for MULTIPLE_CHOICE) |
isRequired | boolean | Whether answer is mandatory |
sortOrder | smallint | Display order |
SurveyResponse
| Column | Type | Description |
|---|---|---|
surveyId | bigint | FK → Survey |
ticketId | bigint | Related ticket |
respondentId | bigint | Respondent ID |
answers | jsonb | Submitted answers (questionId → answer map) |
submittedAt | timestamp | Submission timestamp |
REST API
Surveys, questions, and responses — full endpoint reference rendered live from /v1/api/helpdesk/doc/openapi.json. Served by SurveyController. Endpoint tables are intentionally not hand-maintained.
Survey Worker
survey-trigger.worker (helpdesk.survey-trigger queue) runs TriggerSurveyUseCase when a ticket reaches a terminal state and dispatches CSAT surveys to the customer via the configured notification channel.
Feature Requests
Data Model
FeatureRequest
| Column | Type | Description |
|---|---|---|
id | bigint | Snowflake ID |
merchantId | bigint | Tenant scope |
title | varchar | Request title |
description | text | Detailed description |
status | enum | OPEN / UNDER_REVIEW / PLANNED / COMPLETED / REJECTED |
voteCount | int | Total vote count |
requesterId | bigint | Creator's ID |
FeatureVote
Junction table recording one vote per user per request (unique per user + request):
| Column | Type | Description |
|---|---|---|
featureRequestId | bigint | FK → FeatureRequest |
userId | bigint | Voter |
votedAt | timestamp | Vote timestamp |
REST API
Feature requests and voting — full endpoint reference rendered live from /v1/api/helpdesk/doc/openapi.json. Served by FeatureRequestController. Endpoint tables are intentionally not hand-maintained.
Related Pages
- Helpdesk Service — service overview
- Domain Model
- Notification System