General-Purpose Support Ticket System

[Abidoyesimze]

Problem Statement

There's no structured way for a user to raise an issue and have it tracked through to resolution. Alerts, compliance cases, and DSAR requests (#371) all have their own well-defined workflows for their specific domains, but a general "my deposit hasn't shown up" or "I have a question about my tax report" has nowhere to go except an ad hoc external channel (email, WhatsApp free text) with no ticket record, no SLA, no assignment, no resolution history the user or support can refer back to. This issue adds a lightweight, general-purpose support ticket system, structurally similar to the compliance-case model (#373) but user-initiated and non-confidential.

Current State

• src/compliance/cases.ts (Sanctions Screening Case Management & SAR Workflow #373) — the closest structural precedent: a case model, append-only event timeline, status state machine, assignment, SLA — but that system is compliance-specific, admin-initiated, and deliberately invisible to the user (no tipping-off). A support ticket is the opposite in that last respect: fully visible and collaborative with the user.
• src/whatsapp/handler.ts, src/telegram/handler.ts — existing user-facing channels that could optionally create/reply-to tickets, though the primary interface should be the REST API first.
• No SupportTicket model exists (confirmed).

Proposed Solution

1. SupportTicket: userId, subject, category (ACCOUNT | TRANSACTION | TAX | TECHNICAL | OTHER), status (OPEN → IN_PROGRESS → AWAITING_USER → RESOLVED → CLOSED), priority, assignedTo, createdAt, resolvedAt.
2. TicketMessage: append-only thread (ticketId, author (user or admin), body, attachmentRefs?, createdAt, internal: boolean for admin-only notes not visible to the user — mirroring the visible/internal distinction that's natural in any support tool).
3. POST /api/v1/support/tickets (+ optional context auto-attachment: if raised from a specific transaction/report view, the client can pass a reference id so support starts with relevant context already attached, reducing back-and-forth).
4. GET /api/v1/support/tickets, GET /:id, POST /:id/reply — user-facing thread view/reply.
5. Admin side: GET /api/v1/admin/support/tickets (queue, filterable by status/category/assignee/SLA), PATCH /:id (status/assignment/priority), POST /:id/reply (internal or user-visible).
6. SLA timers per priority (config), surfaced in the admin queue (reuse the SLA-breach-flagging pattern already established for compliance cases).

Edge Cases & Failure Modes

• Ticket references sensitive financial data: fine — this is the user's own data about their own account, unlike the compliance-case confidentiality requirement; standard owner-scoping applies, not the stricter no-tipping-off rule.
• User replies after RESOLVED: automatically reopens to IN_PROGRESS (a resolved-but-not-actually-resolved ticket shouldn't require the user to know to click a separate "reopen" action).
• Abusive/spam ticket content: basic rate limiting on creation; no need for heavier moderation infrastructure at this scope.
• Ticket about a specific transaction/tax report that's later corrected by a real bug fix: the ticket thread stays as the historical record; no automatic tie-in to a code-deploy tracking system (out of scope).
• Internal admin notes accidentally exposed: the internal flag must be enforced server-side on every read path a user hits, not just hidden client-side.

Security & Privacy Considerations

• Owner-scoped for the user's own tickets; admin access requires the appropriate admin scope, audit-logged for sensitive actions (status changes, assignment).
• internal: true messages are never returned to the user-facing read endpoints, enforced at the query level, not just response filtering (a common class of bug: filtering client-side or too late in the pipeline).
• Attachment references (if implemented) should reuse whatever secure-file-upload pattern already exists elsewhere in the codebase, not invent a new one.

Out of Scope

• Live chat / real-time support (async ticket threading only, v1).
• SLA-based automated escalation to a specific human beyond surfacing the breach (compliance-case-style escalation is heavier machinery than a general support queue needs initially).
• Integration with a third-party helpdesk platform (native, in-repo implementation).

Suggested Implementation Plan

1. SupportTicket, TicketMessage models + migration/rollback.
2. User-facing create/list/view/reply endpoints; category + optional context-reference attachment.
3. Admin queue + status/assignment/priority management + SLA-breach flagging (reusing the compliance-case pattern).
4. Auto-reopen on user reply after resolution; internal-note visibility enforced at the query level.
5. Rate limiting on ticket creation; docs/ support doc + docs/openapi.yaml.

Acceptance Criteria

• Users can create, list, view, and reply to their own support tickets; admin has a filterable, SLA-aware queue with assignment and status management
• TicketMessage.internal notes are never returned on any user-facing read path, enforced at the query level
• A user reply on a RESOLVED ticket automatically reopens it to IN_PROGRESS
• Ticket creation is rate-limited; optional context-reference attachment lets a client pre-populate relevant transaction/report context
• Status changes and assignment actions on the admin side are audit-logged
• docs/openapi.yaml + a short support-system doc added; unit + integration tests green

[byteMara]

@byteMara has applied to work on this issue as part of the Stellar Wave Program's 9th wave.

Hello, I investigated the affected functionality and understand the changes needed to achieve the expected result. I can take this issue and ensure the implementation is reliable.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @byteMara to this issue.

[AminMG044]

@AminMG044 has applied to work on this issue as part of the Stellar Wave Program's 9th wave.

Hello, I explored the affected functionality and have identified a practical way to implement the requested behavior. I'd be happy to work on this and submit a tested PR.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @AminMG044 to this issue.

[Andreas2410]

@Andreas2410 has applied to work on this issue as part of the Stellar Wave Program's 9th wave.

I'd like to work on this issue

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Andreas2410 to this issue.

[NovaLabs4324]

@NovaLabs4324 has applied to work on this issue as part of the Stellar Wave Program's 9th wave.

Hello Maintainer, I've carefully gone through the issue and understand the expected result. I'd like to work on it.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @NovaLabs4324 to this issue.

[xeladev4]

@xeladev4 has applied to work on this issue as part of the Stellar Wave Program's 9th wave.

Hey there maintainer, I am a software engineer with a lot of blockchain experience. I have read through the Issue description and with my experience in stellar projects can get this delivered ASAP.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @xeladev4 to this issue.

[OkonkwoEmeka]

@OkonkwoEmeka has applied to work on this issue as part of the Stellar Wave Program's 9th wave.

hi maintainer, please i'd like to work on this. i understand the core issue is creating a user-visible ticket workflow while keeping internal admin notes completely isolated from user read paths. as a professional backend developer, i can implement the ticket/message models, owner-scoped api, admin queue, sla handling, and auto-reopen flow on time, with query-level internal-note protection and the required tests.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @OkonkwoEmeka to this issue.

[YoungBoss04]

@YoungBoss04 has applied to work on this issue as part of the Stellar Wave Program's 9th wave.

Hi, I’d like to work on this issue. I’ve reviewed the requirements and understand what needs to be implemented. I’ll first inspect the existing code, make the necessary changes, add or update tests where appropriate, and submit a clean, well-documented PR. I’m ready to start immediately.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @YoungBoss04 to this issue.