Spec: F58 — Internal Support Ticketing System

Status: 🚧 Partial implementation; API and web surfaces exist, but notification, tenant-boundary, browser, and environment proof gaps remain

Current truth (2026-07-16): The former spec-only audit was stale. backend/apps/support/, /api/support/tickets/, authenticated frontend routes, and backend tests are present. This does not establish browser execution, live notification delivery, production behavior, or a tenant-isolated staff queue. See the implementation audit and Contract Graph gaps.

Current repository truth: this document is the product proposal and target contract, not shipped evidence. The checked acceptance criteria below describe the intended build. See the current implementation audit and contracts/features/F58.cue for the explicit implementation gap.

1. Problem & CEO Job

Job: Trust the signal.

When a pulse will not submit, the Brief will not generate, or an approval is stuck, the CEO has no channel to tell Lumi. There is no path from “something is wrong” to “Lumi fixed it” beyond struggling silently or emailing someone they hope still works here.

This spec builds Lumi’s support channel: users submit issues; Lumi staff triage, respond, and resolve them; users receive status updates. It is not a tenant workflow.

2. User Stories & Acceptance Criteria

User — Submit Ticket

• As a Lumi user (any role), I want to submit a support ticket with a subject and description, so that the Lumi team knows what’s broken.
  • Given any org member, when I navigate to /support/new, then I see a form with: subject, description (textarea), category dropdown, priority selector, optional file attachment. (SupportCreatePage.tsx)
  • Given the form, when I submit with a non-empty subject and description, then a Ticket is created with status open and I’m redirected to /support/<ticket_id>.
  • Given the form, when I submit with an empty subject, then I see a validation error and nothing is created.
  • Given the form, when I click “Attach file”, then a file picker opens; supported types: images, PDFs, plain text (max 10 MB per file, max 3 files per ticket). Backend: POST /attach/ enforces 3-file cumulative limit, 10 MB via UPLOAD_MAX_SIZE.

User — View My Tickets

• As a user, I want to see all my tickets in one list, so that I can track what I’ve reported.
  • Given /support, the page shows a list of my tickets (created by me) ordered by most recent update. (SupportListPage.tsx)
  • Each ticket row shows: id, subject, status badge, priority badge, category, last updated timestamp.
  • Clicking a ticket row navigates to /support/<ticket_id>.

User — Ticket Detail & Messages

• As a user, I want to see the full conversation on a ticket, so that I know what the Lumi team has said and can reply.
  • Given /support/<ticket_id>, the page shows: subject, status banner, description (original), and a chronological message thread. (SupportDetailPage.tsx)
  • Each message shows: author name, timestamp, body, and attachments if any.
  • Messages from Lumi staff are visually distinct (badge “Lumi Team” with brand color).
  • Given the ticket is not closed, I can add a reply via a textarea at the bottom of the thread.
  • Given a reply, when I submit, then the message is appended, the ticket’s updated_at refreshes, and the status changes to waiting_on_staff (auto-reopens if previously waiting_on_user).

User — Close Ticket

• As a user, I want to close my own ticket when the issue is resolved, so that the Lumi team knows I’m satisfied.
  • Given an open or in-progress ticket, a “Close ticket” button is visible to the ticket creator.
  • Given a click on “Close ticket”, then status changes to closed and a confirmation toast appears.

Staff — Ticket Dashboard

• As a Lumi staff member (is_staff=True), I want a dashboard of all tickets, so that I can triage and resolve issues.
  • Given /hq/support (inside the HQ console, staff-gated by HqLayout), the staff dashboard shows all tickets across all users, filterable by status (open, in_progress, resolved, closed), priority, and category. (pages/hq/HqSupportPage.tsx; legacy /support/manage redirects here)
  • The dashboard shows a summary bar: open count, in-progress count, unresolved older than 48h. (Added 2026-06-14)
  • Clicking a ticket navigates to /support/<ticket_id> with full staff controls.
  • Non-staff users on /hq/support are redirected out by HqLayout (/work/today); the manage API returns 403.

Staff — Assign & Update Status

• As a Lumi staff member, I want to assign tickets to myself and update their status, so that the team knows who owns each issue.
  • Given /support/<ticket_id>, a staff-only panel shows: assignee dropdown, status dropdown, priority dropdown. (SupportDetailPage.tsx staff controls panel, added 2026-06-14)
  • Given “Assign to me” click, the ticket’s assigned_to is set to the current staff user.
  • Status transitions: open → in_progress → resolved → closed. A ticket can be reopened from resolved to in_progress.
  • Given status changes to resolved, the ticket creator’s next visit shows a “Was this resolved?” feedback prompt (thumbs up/down).

Staff — Internal Notes

• As a Lumi staff member, I want to add internal notes visible only to staff, so that we can discuss the issue without confusing the user.
  • Given /support/<ticket_id>, a staff-only “Internal note” button toggles a separate textarea. (Added 2026-06-14)
  • Internal notes are rendered in the thread with a ”🔒 Internal” badge and are invisible to the ticket creator.
  • Internal notes do not change the ticket’s waiting_on state.

Notifications

• As a user, I want to be notified when my ticket status changes or a staff member replies, so that I don’t have to keep checking.
  • Given a staff reply or status change on my ticket, a push notification is sent (F36) and a bell badge increments.
  • Given a staff reply, an email notification is sent to the ticket creator’s registered email (via F35 email infrastructure).
  • The notification includes the ticket subject and a deep link to /support/<ticket_id>.

3. Scope Boundaries

• In:
  • Ticket CRUD for users (create, view own, reply, close).
  • Staff dashboard with full ticket management.
  • Assignee system (staff self-assign).
  • Status workflow (open → in_progress → resolved → closed).
  • Internal notes (staff-only).
  • File attachments on tickets (via F34 upload infra).
  • Email + push notifications on ticket updates.
  • Ticket feedback prompt on resolve (thumbs up/down).
  • Both en + vi localization for all UI.
• Out:
  • SLA or escalation rules.
  • CSAT surveys beyond thumbs up/down.
  • Knowledge base / FAQ (separate future feature).
  • Public-facing status page.
  • Bulk ticket operations.
  • Third-party helpdesk integration (Zendesk, Freshdesk, etc.).
  • Per-org ticket visibility (tickets belong to individual users, not orgs).
  • Chat/copilot for support (ticket-based async only).

4. Data Model

4.1 Ticket

class Ticket(UUIDModel):
    TICKET_STATUS_CHOICES = [
        ("open", "Open"),
        ("in_progress", "In Progress"),
        ("waiting_on_staff", "Waiting on Staff"),
        ("waiting_on_user", "Waiting on User"),
        ("resolved", "Resolved"),
        ("closed", "Closed"),
    ]
    PRIORITY_CHOICES = [
        ("low", "Low"),
        ("medium", "Medium"),
        ("high", "High"),
        ("critical", "Critical"),
    ]
    CATEGORY_CHOICES = [
        ("bug", "Bug / Error"),
        ("feature_request", "Feature Request"),
        ("billing", "Billing / Payment"),
        ("account", "Account / Login"),
        ("integration", "Integration / Connector"),
        ("other", "Other"),
    ]

    subject = models.CharField(max_length=200)
    description = models.TextField()
    category = models.CharField(max_length=30, choices=CATEGORY_CHOICES, default="other")
    priority = models.CharField(max_length=20, choices=PRIORITY_CHOICES, default="medium")
    status = models.CharField(max_length=20, choices=TICKET_STATUS_CHOICES, default="open")

    created_by = models.ForeignKey(User, on_delete=CASCADE, related_name="tickets")
    assigned_to = models.ForeignKey(User, on_delete=SET_NULL, null=True, blank=True, related_name="assigned_tickets")

    # Feedback on resolve
    resolved_satisfied = models.BooleanField(null=True, blank=True)  # True = thumbs up

    created_at = models.DateTimeField(auto_now_add=True)
    updated_at = models.DateTimeField(auto_now=True)

    class Meta:
        db_table = "support_tickets"
        ordering = ["-updated_at"]

4.2 TicketMessage

class TicketMessage(UUIDModel):
    ticket = models.ForeignKey(Ticket, on_delete=CASCADE, related_name="messages")
    author = models.ForeignKey(User, on_delete=CASCADE)
    body = models.TextField()
    is_internal = models.BooleanField(default=False)  # Staff-only internal note
    attachments = models.ManyToManyField("uploads.Upload", blank=True)  # F34

    created_at = models.DateTimeField(auto_now_add=True)

    class Meta:
        db_table = "support_ticket_messages"
        ordering = ["created_at"]

4.3 No Organization FK

Tickets are cross-tenant. They belong to individual users, not organizations. The created_by FK is on accounts.User, not OrganizationMember, so the user retains access to their tickets even if they leave an org or have multiple orgs.

5. API Contract

The shipped management read is contract-owned as F58.AC002.MANAGE_API, and the ticket detail read is contract-owned as F58.AC001.DETAIL_API. Its staff queue remains subject to the unresolved tenant-boundary gap recorded in the implementation audit and Contract Graph; this ownership entry does not imply tenant isolation or runtime execution evidence.

The exact POST /api/support/tickets/ creation surface is owned by TicketViewSet.create with collected proof F58.AC001.HAPPY; guarded backend execution remains explicit in F58.GAP006.

The exact POST /api/support/tickets/{id}/attach/ surface is owned by TicketViewSet.attach with collected proof F58.AC003.ATTACH_HAPPY; guarded backend execution remains explicit in F58.GAP007.

The exact POST /api/support/tickets/{id}/close/ surface is owned by TicketViewSet.close with collected proof F58.AC001.CLOSE_HAPPY; guarded backend execution remains explicit in F58.GAP008.

The exact POST /api/support/tickets/{id}/feedback/ surface is owned by TicketViewSet.feedback with collected proof F58.AC001.FEEDBACK_HAPPY; guarded backend execution remains explicit in F58.GAP009.

The exact POST /api/support/tickets/{id}/messages/ surface is owned by TicketViewSet.add_message with collected proof F58.AC001.MESSAGE_HAPPY; guarded backend execution remains explicit in F58.GAP010.

The exact POST /api/support/tickets/{id}/reopen/ surface is owned by TicketViewSet.reopen with collected proof F58.AC002.REOPEN_HAPPY; guarded backend execution remains explicit in F58.GAP011.

Tenant scoping: Tickets are NOT tenant-scoped. They are user-scoped. A user sees only their own tickets. Staff (is_staff=True) see all tickets.

6. UI / UX

6.1 Support Entry Points

• Sidebar — A “Support” link in the Admin nav group (always visible to all roles) or a dedicated entry in Settings.
• Global nav — A ”?” icon or “Help” dropdown in the top bar with “Submit a ticket” option.

6.2 My Tickets Page (/support)

┌─ Support ─────────────────────────────────────────────────┐
│                                                           │
│  [Submit New Ticket]                                      │
│                                                           │
│  My Tickets                                               │
│                                                           │
│  ┌──────────────────────────────────────────────────────┐ │
│  │ #T-042 │🔴 Can't submit pulse today         │ 🟢 │ │
│  │        │ Bug     High    2 hours ago        │ Open │ │
│  ├──────────────────────────────────────────────────────┤ │
│  │ #T-041 │🟡 Brief not generating on time     │ 🟡 │ │
│  │        │ Bug     Medium   yesterday         │ In..│ │
│  ├──────────────────────────────────────────────────────┤ │
│  │ #T-039 │✅ Add Telegram connector            │ ✅ │ │
│  │        │ Featur  Low      3 days ago        │ Clo..│ │
│  └──────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────┘

6.3 Ticket Detail (/support/<id>)

┌─ Ticket #T-042 ──────────────────────────────────────────┐
│                                                           │
│  🔴 Open · 🐛 Bug · High Priority                         │
│                                                           │
│  Can't submit pulse today                                 │
│  ─────────────────────────────────────────────            │
│  I've been trying to submit my pulse since 8 AM but       │
│  the form keeps showing a blank page after I click        │
│  "Submit". I've tried on Chrome and Safari.               │
│                                                           │
│  Attachments: screenshot-1.png                            │
│                                                           │
│  ─── Replies ───                                          │
│                                                           │
│  [Lumi Team] Hi, thanks for reporting! Can you check      │
│  if your browser console shows any errors?                │
│  10 minutes ago                                           │
│                                                           │
│  You: I checked — here's what I see: [screenshot]         │
│  5 minutes ago                                            │
│                                                           │
│  ┌────────────────────────────────────────────────────┐   │
│  │ Type your reply here...                [Send]      │   │
│  └────────────────────────────────────────────────────┘   │
│                                                           │
│  [Close Ticket]                                           │
└──────────────────────────────────────────────────────────┘

6.4 Staff Dashboard (/hq/support)

┌─ Support Dashboard ───────────────────────────────────────┐
│                                                           │
│  🟢 12 Open  🟡 8 In Progress  🔴 3 Unresolved >48h     │
│                                                           │
│  [All] [Open] [In Progress] [Resolved] [Closed]           │
│  [All Priorities] [All Categories]                        │
│                                                           │
│  ┌────┬────────────┬──────────┬────────┬────────┬──────┐ │
│  │ ID │ Subject    │ User     │ Status │ Pri    │ Age  │ │
│  ├────┼────────────┼──────────┼────────┼────────┼──────┤ │
│  │042 │ Can't sub..│ ceo@d.. │ 🟢open  │ 🔴high │ 2h  │ │
│  │041 │ Brief not..│ admin@..│ 🟡in.. │ 🟡med  │ 26h │ │
│  └────┴────────────┴──────────┴────────┴────────┴──────┘ │
└──────────────────────────────────────────────────────────┘

6.5 i18n

New namespace: support. All keys in both en/support.json and vi/support.json.

Page heading keys:

Form keys:

Status badges:

Category labels:

Priority labels:

Thread/reply keys:

Staff dashboard keys:

Feedback keys:

Notification keys:

Validation/error keys:

7. Test Plan

Coverage note (2026-06-14): Support tests live in backend/tests/test_support.py with classes TestTicketCreate, TestTicketListScoping, TestTicketDetail, TestStaffOnly, TestMessages, TestInternalNotes, TestClosePermission, TestStatusWorkflow, TestFeedback, TestTicketIdFormat, TestStaffReopenTicket, TestAttachmentLimits. Rows below use original per-case naming; the file is authoritative.

8. Current Behavior

Partial implementation. apps/support/ contains Ticket + TicketMessage models, TicketViewSet, staff gates, display IDs, F34 attachment M2M, reopen and feedback endpoints. Frontend support pages and routes exist. The current audit does not claim a separate TicketMessageViewSet, live notification dispatch, tenant-isolated staff access, browser execution, or production behavior.

9. Error States

10. Diagrams & Docs Touched

• backend/DIAGRAMS.md — add SupportTicket model + status state machine.
• GLOSSARY.md — entry for “Ticket”, “Staff”, “Internal Note”.

11. Implementation Audit

Edge Cases Catalog (formerly §9, 2026-06-14; 17 items): ticket creator account deletion (creator_email preserved), staff member loses is_staff (assigned tickets auto-unassigned), multiple close/reopen cycles (feedback prompt resets), race condition on simultaneous staff+user reply (last-write-wins), file upload failure (message saved without attachment), email notification failure (message saved, retry once after 5m), wrong category (staff can change), long ticket thread (paginated 20/page), anonymous user 401 redirect, weekend reply auto-status, notification infra down (ticket saved regardless), internal note does not change waiting state, staff user creates own ticket (normal ticket not auto-assigned), message with no body but attachment (valid), XSS sanitization via markdown sanitizer (F28), multiple staff assign (last-write-wins), status transition rules backend-enforced. Full catalog in git history.

11.1 Key Design Constraints

12. Open Questions / Decisions

1. Display ID format. Auto-increment T-{id} vs UUID for ticket list. Decision: UI shows T-{id}, PK stays UUID.

2. File storage for attachments. Reuse F34 (pre-signed S3 uploads) or accept direct uploads. Decision: reuse F34 infrastructure — consistent, already audited.

3. Ticket deletion. Should users be able to delete their own tickets? Decision: no. Tickets are immutable audit records once created. Users can close them.

4. Staff flag vs dedicated permission model. Use Django’s built-in User.is_staff or create a separate support_staff group. Decision: use is_staff for v1. It’s already available, tested in HQ routes. A dedicated support role can be added later if needed.

13. Bug / Change Log

2026-07-02 — §5/§11 audit drift: PATCH gate, TicketMessageViewSet (docs-only)

Type: Documentation

Summary:

• §5 PATCH row: auth column corrected “creator or staff” → “staff only”; errors column corrected “403 if non-staff sets assigned_to” → “403 for non-staff (blanket)”. Verified: partial_update in backend/apps/support/views.py (~L87–88) returns 403 for all non-staff unconditionally — not just when assigned_to is set.
• §11 row 3: removed false TicketMessageViewSet claim; corrected to TicketViewSet only with message creation via add_message @action(url_path="messages") at views.py line 124. No TicketMessageViewSet class exists in the file.
• No code changes.

2026-07-02 — Fix stale path: backend/apps/support/permissions.py (batch 3)

Type: Documentation

Summary:

• §11 row 4 referenced backend/apps/support/permissions.py as the evidence for the User.is_staff permission gate. This file does not exist — ls backend/apps/support/ confirms no permissions.py. The is_staff checks are inline in backend/apps/support/views.py (multiple methods in TicketViewSet and TicketMessageViewSet).
• Updated the evidence cell to point at backend/apps/support/views.py with the specific method list.
• No code changes.

2026-06-14 — Spec restructured to TEMPLATE.md canonical order (§1–§13)

Type: Documentation Change

Summary:

• §9 Edge Cases (17 items, 9.1–9.17) absorbed into §11 Implementation Audit EC note.
• §10 Error States → §9, §11 Diagrams & Docs Touched → §10, §12 Implementation Audit → §11 (canonical 4-col table, 11 rows, all ✅ match).
• §12.1 Key Design Constraints (h2 subheading, non-standard) → ### 11.1 Key Design Constraints (h3 under §11).
• §13 Open Questions → §12, §14 Bug / Change Log → §13.

Reason:

• Align with TEMPLATE.md canonical section order per SP fleet restructuring pass.

Impact:

• Spec authors and future implementation agents.

2026-06-13 — Spec refinement: numbered edge cases, detailed error matrix, expanded test plan

Type: Documentation Change

Summary:

• Added §9 with 9 numbered edge cases (9.1–9.9) covering: account deletion, staff revocation, multiple close/reopen cycles, race conditions on reply, file upload failure, email notification failure, wrong category, long threads, and unauthenticated access.
• Replaced §10 error states with 12-row detailed matrix (user-visible/internal/log/retry), adding coverage for file types, feedback state validation, creator deletion, and staff demotion.
• Expanded §7 test plan from 11 to 24 test cases, adding coverage for optional fields, cross-staff notes, reopen transitions, attachment limits, feedback prompt, email/push notifications, and cross-tenant isolation.
• Updated spec status from draft to agreed.

Reason:

• Spec needed hardening per implementation audit. Edge cases were absent, test plan was thin, error states lacked structured detail.

Impact:

• Spec authors and future implementation agents.

Tests:

• Spec-only change — no code tests affected.

2026-06-14 — Confirmed no backend support app exists; updated §12

Type: Documentation Change

Summary:

• Updated §12 Implementation Audit with concrete scan results: no apps/support/ directory, no support in INSTALLED_APPS, no Ticket/TicketMessage models found.
• No AC, API, or model changes needed — spec already thorough from round 1 hardening.

Reason:

• Per T4-G round 2 task: verify support app backend completeness. Found empty — documented for implementation agents.

Impact:

• Implementation agents must create apps/support/ from scratch per §4 data model. Tenant isolation checks (TestSupportIsolation) will pass only after the model exists.

Tests:

• Spec-only change — no code tests affected.

2026-06-14 — Attachment limits, reopen action, all rework items closed

Type: Feature

Summary:

• Added Ticket.attachments = ManyToManyField("uploads.Upload", ...) + migration 0002_add_ticket_attachments.
• Added POST /api/support/tickets/<id>/attach/ action: enforces cumulative ≤3 file limit, requires status=completed, returns 400 on violation.
• Added POST /api/support/tickets/<id>/reopen/ action: staff-only, ticket must be closed, transitions to open.
• TicketDetailSerializer now includes attachments as embedded upload summaries (id, filename, public_url, content_type, byte_size).
• All 4 rework items struck — display_id and feedback were already implemented; attachment limits and reopen are new.

Tests:

• TestAttachmentLimits (5 tests): single attach, too-many-in-one-request, cumulative limit exceeded, pending upload rejected, non-creator-non-staff blocked.
• TestStaffReopenTicket (3 tests): staff reopen success, non-staff 403, non-closed 400.