Sathira Sri Sathara
f920ca8920
- Added models for support messages, SLA policies, tickets, ticket events, and ticket links. - Created routes for help, help admin, newsletter, recommendations, and support for both customer and admin. - Developed services for help, marketing (newsletter), and recommendations. - Introduced support service for ticket management, including creation, replies, transitions, and attachments. - Added validation schemas for support recommendations and ticket management. - Implemented a cron job for support reconciliation and recommendation cleanup. - Created migration for new support and recommendation database tables. - Added unit tests for validation and policy checks related to Phase 10 features.
2.9 KiB
Support and Help API
Phase 10 adds a permission-gated support case system and a localized help center. All routes are under /api/v1.
Customer support
POST /support/ticketscreates a self-owned ticket and initial public message in one transaction. Identity, business context, priority and status are server-derived.GET /support/ticketsandGET /support/tickets/:idare self-only; internal notes and internal attachments are excluded.POST /support/tickets/:id/messagesappends a public reply. A resolved ticket is explicitly reopened; closed/cancelled tickets reject replies.POST /support/tickets/:id/closeperforms a validated state transition.GET /support/tickets/:id/attachments/:attachmentIdauthorizes the ticket and visibility before issuing a short-lived signed S3 URL.
Ticket states are OPEN, ASSIGNED, WAITING_FOR_CUSTOMER, WAITING_FOR_SUPPORT, RESOLVED, CLOSED, and CANCELLED. Customers cannot select priority; new tickets default to NORMAL. Subjects are limited to 200 characters, messages to 10,000 characters, and five attachments per message. Attachments reuse Phase 2 uploads and allow JPEG, PNG, WebP, or PDF only.
Related resources support orders, payments, refunds, returns, shipments, loyalty redemptions, and business settlements. Creation verifies the resource against the authenticated customer or business; a resource identifier alone never grants access.
Staff support
Under /admin/support/tickets, staff can list/detail, assign or atomically claim, reply, add internal notes, change priority, resolve, reopen, close, and download attachments. Permissions are granular: support.tickets.read, .assign, .reply, .status, .priority, .internal_notes, and .escalate. Category and SLA controls use support.categories.manage and support.sla.manage.
State/assignment operations lock the ticket row. Events are append-only. SLA deadlines are snapshotted from the active priority policy at creation using clock time; a bounded five-minute reconciliation creates idempotent first-response or resolution escalations. Business-hour calendars and multi-instance cron validation remain Phase 11 work.
Help center
Public endpoints are GET /help/categories, /help/categories/:slug, /help/articles, /help/articles/:slug, and /help/search?q=. Only active categories and published articles are returned. en, si, and ta use the Phase 4 locale resolver with English fallback. Search is bounded to 2–100 query characters and at most 50 results.
Admin endpoints under /admin/help list/create categories and articles and explicitly publish/archive articles. They require help.read, help.manage, or help.publish. Article bodies are stored as plain Markdown-like text with HTML tags removed; consumers must render text/Markdown safely and must not treat it as trusted HTML.
All collection APIs use bounded pagination or bounded results and the standard { success, data, pagination? } envelope.