support_backend/specs/003-ticketing/spec.md

Feature Specification: Ticket Creation, Messages & Attachments

Feature Branch: 003-ticketing

Created: 2026-09-02

Status: Draft

Input: User description: "Phase 5 of docs/10-implementation-roadmap.md: Ticket + Problem models (kept separate), message types, attachment pipeline (object storage, scanning, expiring URLs), ticket lifecycle state machine. Per docs/04-ticketing-and-problem-management.md and docs/06-database-schema.md."

User Scenarios & Testing (mandatory)

User Story 1 - A trusted request creates a durable ticket immediately (Priority: P1)

The moment a validated inbound request (from the SaaS integration trust boundary) describes a customer's problem, SupportHub creates a durable ticket right away — before any diagnosis, before any human is involved. The ticket starts in a NEW status. If the same underlying problem recurs for the same product/tenant, the new ticket is linked to the existing Problem record rather than creating a duplicate; if it's a genuinely new problem, a new Problem record is created alongside the ticket. A retried request (same idempotency key) returns the already-created ticket instead of creating a second one.

Why this priority: This is the foundational principle of the whole product ("ticket created at the start of the journey, not after AI gives up") and everything else in this feature — and every future feature (AI, orchestration, resolution) — depends on the ticket/problem records existing first.

Independent Test: Send a valid inbound request through the trust boundary and confirm a Ticket (status NEW) and a Problem exist immediately, correctly linked to the validated product/tenant/user context; send the same request again with the same idempotency key and confirm no second ticket is created.

Acceptance Scenarios:

1. Given a validated inbound request describing a problem, When it's processed, Then a Ticket is created in NEW status and a Problem is created (or an existing one reused — see Scenario 3), both linked to the validated product/tenant/user context, before any further processing occurs.
2. Given a ticket was just created, When its record is inspected, Then it has a human-referenceable code (e.g. DQB-2026-00567-style), the originating product, and the trusted customer reference — never a raw, unvalidated value from the request.
3. Given a customer reports what is recognizably the same underlying problem again (same product, same recognizable symptoms/context) as an existing open Problem, When a new ticket is created for it, Then the new ticket links to the existing Problem record rather than creating a duplicate one.
4. Given an inbound request carries an idempotency key that was already used for a successfully created ticket, When the request is retried, Then the existing ticket is returned and no second ticket or problem is created.

---

User Story 2 - Ticket messages are typed, and internal notes are never visible to customers (Priority: P2)

A ticket accumulates a timeline of messages — from the customer, from AI (in future), from agents, from the system, and internal-only notes (investigation/solution notes, general internal notes). Every message has a type, and the API enforces — not just the UI — that customer-invisible message types can never reach a customer-scoped read.

Why this priority: Without a message timeline there's no record of the interaction to show anyone; without enforced internal-note privacy, an agent's private note becomes a customer-facing leak the moment someone builds a UI that forgets to filter client-side.

Independent Test: Post one of each message type on a ticket, then read the ticket's messages as a customer-scoped caller and confirm only customer-visible types appear; read the same messages as an agent-scoped caller and confirm all types appear.

Acceptance Scenarios:

1. Given a ticket, When a message of any defined type is posted to it, Then it's stored with its type, author reference, body, and a customer-visibility flag derived from its type (never independently settable per-message in a way that contradicts the type).
2. Given a ticket has both customer-visible and internal-only messages, When its messages are read through a customer-scoped endpoint, Then only customer-visible messages are returned — internal notes are absent from the response entirely, not merely hidden by a flag.
3. Given the same ticket, When its messages are read through an agent-scoped endpoint, Then every message, including internal notes, is returned.
4. Given a caller not authorized for a given ticket's tenant, When they attempt to read or post a message on it, Then the request is rejected regardless of message type.

---

User Story 3 - Attachments are safely stored and only ever downloaded through expiring, authorized URLs (Priority: P3)

A customer or agent can attach a file (screenshot, PDF, log, video, document) to a ticket. The file goes to object storage, never to PostgreSQL — only its metadata and a storage reference are stored in the database. It is not available for download until it has cleared a malware scan. Every download happens through a short-lived, authorization-checked URL scoped to that ticket's tenant/user context — never a permanent or unauthenticated link.

Why this priority: Attachments are common (screenshots, logs) but not required for the minimum ticket flow to work, and getting the security properties right (never in Postgres, never downloadable pre-scan, never a permanent link) matters more than shipping it first.

Independent Test: Upload a file to a ticket and confirm it's rejected for download until scan status clears; confirm a generated download URL stops working after it expires; confirm a caller outside the ticket's tenant cannot generate or use a download URL for it.

Acceptance Scenarios:

1. Given a file upload to a ticket, When it's outside the configured type/size limits, Then it's rejected before being sent to object storage.
2. Given an accepted upload, When it has not yet cleared malware scanning, Then it is not downloadable — its status is visibly pending, not silently unavailable.
3. Given a file that clears scanning, When an authorized caller requests to download it, Then they receive a time-limited URL that stops working after it expires.
4. Given a file that fails malware scanning, When anyone attempts to download it, Then the download is refused and the failure is visible on the attachment's record.
5. Given a caller outside the ticket's tenant/user context, When they attempt to generate or use a download URL for one of its attachments, Then the request is rejected.

---

Edge Cases

• What happens when two requests for the same new problem arrive concurrently (not a literal retried idempotency key, but a genuine race — e.g. a flaky client double-submits without reusing the idempotency key)? Out of scope to fully solve here beyond the idempotency-key mechanism in User Story 1 — true duplicate-problem detection beyond exact idempotency-key reuse is a knowledge/classification concern for a future AI feature, not this one.
• What happens when a ticket's status is updated by two actors at nearly the same time (e.g. a customer reopens while an agent is closing)? The update that observes a stale status MUST be rejected and retried against the current state — not silently overwrite the other actor's change (Constitution Principle VII).
• What happens when an attachment upload is interrupted mid-transfer? The attachment record MUST NOT be considered available; a resumed/retried upload is a new attempt, not a partial record left in a downloadable-looking state.
• What happens when a malware scan itself fails to run (infrastructure error, not "found malware")? The attachment MUST remain pending, never silently promoted to available.
• What happens when a message is posted with a type that doesn't exist in the defined set? The request MUST be rejected — message type is not free text.

Requirements (mandatory)

Functional Requirements

• FR-001: The system MUST create a Ticket record immediately upon processing a validated inbound request describing a problem — before any diagnosis, classification, or human involvement occurs.
• FR-002: The system MUST create or reuse a Problem record for every ticket: a new Problem when none matches, or the existing Problem when the ticket represents a recurrence of one already open for the same product/tenant context.
• FR-003: Ticket and Problem MUST remain separate, related entities — a ticket references exactly one problem; a problem may have many tickets (Constitution Principle VIII).
• FR-004: The system MUST honor the inbound request's idempotency key: a retried request carrying a previously-used key returns the already-created ticket rather than creating a new one.
• FR-005: Every ticket MUST have a human-referenceable code, unique, generated by the system — never supplied by the caller.
• FR-006: A ticket's status MUST only ever be one of the defined lifecycle states, and MUST only transition through valid state changes (an invalid transition is rejected, not silently coerced).
• FR-007: A ticket's status update MUST use optimistic concurrency control: an update based on a stale prior status is rejected, not applied on top of a change it didn't observe.
• FR-008: Every message posted to a ticket MUST have one of the defined message types, and its customer-visibility MUST be determined by its type, not independently settable in a way that contradicts the type.
• FR-009: The system MUST NOT return customer-invisible message types (internal notes, investigation notes, solution notes) through any customer-scoped read of a ticket's messages — enforced at the API/serialization layer, not left to client-side filtering.
• FR-010: The system MUST reject reading or posting on a ticket by a caller not authorized for that ticket's tenant/user context, regardless of message type or attachment involved.
• FR-011: Attachment files MUST be stored in object storage, never in PostgreSQL — the database stores only metadata and a storage reference.
• FR-012: The system MUST validate an attachment's type and size against configured limits before accepting the upload.
• FR-013: An uploaded attachment MUST NOT be downloadable until it has cleared malware scanning; its scan status MUST be visible on its record (pending / clean / infected / rejected).
• FR-014: Attachment downloads MUST only be possible through a time-limited, authorization-checked URL scoped to the ticket's tenant/user context — never a permanent or unauthenticated link.
• FR-015: The system MUST scope every ticket, message, and attachment query by the caller's validated tenant/user context — a caller-supplied identifier alone is never sufficient authorization (Constitution Principle I).

Key Entities

• Ticket: The durable, operational record of one support interaction — status, priority, severity, the product/tenant/customer it belongs to, and links to its problem, messages, attachments, and (in later features) AI sessions, assignments, and escalation events.
• Problem: The underlying issue being solved, which can outlive and span multiple tickets — statement, symptoms, impact, severity, environment. Deliberately separate from Ticket.
• Ticket Message: One entry in a ticket's timeline — typed (CUSTOMER_MESSAGE, AI_MESSAGE, AGENT_MESSAGE, INTERNAL_NOTE, SYSTEM_EVENT, INVESTIGATION_NOTE, SOLUTION_NOTE), with an author reference, body, and a visibility derived from its type.
• Ticket Attachment: Metadata for one uploaded file — storage reference (never the file itself), original filename, MIME type, size, scan status, and who uploaded it.

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: 100% of validated inbound requests result in a ticket existing before any further processing — zero requests that pass the trust boundary without a corresponding ticket.
• SC-002: A retried request using the same idempotency key never produces more than one ticket, regardless of how many times it's retried.
• SC-003: Zero internal-only messages ever appear in a customer-scoped read of a ticket's timeline, verified across every defined message type.
• SC-004: Zero attachment files are ever persisted directly in the database — 100% go to object storage with only a reference stored.
• SC-005: An attachment that hasn't cleared malware scanning is rejected for download 100% of the time it's attempted.
• SC-006: A generated attachment download URL becomes unusable after its configured expiry — verified by attempting to use it past that point.
• SC-007: Two concurrent status updates to the same ticket never both apply silently — exactly one succeeds against the state it observed, and the other is rejected and must retry.

Assumptions

• This feature covers ticket/problem creation, the message timeline, and the attachment pipeline only. It does NOT include: AI diagnosis/classification (Phase 4), investigation/root cause/solution/resolution workflows (Phase 9), orchestration/assignment/SLA (Phases 6-8), or the customer-confirmation/auto-close/reopen workflow automation (Phase 9) — though the REOPENED status itself is part of the lifecycle state machine this feature defines, since doc 04 lists it as a core ticket status.
• "Recognizably the same underlying problem" (FR-002/User Story 1 Scenario 3) is intentionally left without a precise matching algorithm here — real recurring-problem detection is a knowledge/classification capability that belongs to the AI-support feature (Phase 4). For this feature, an explicit, caller-supplied reference (e.g. a prior ticket/problem id in the inbound request's referenceIds, per docs/02 §3) is sufficient grounds to link to an existing Problem — this feature does not attempt fuzzy/semantic matching on its own.
• AI-driven status transitions (AI_ANALYZING, AI_TROUBLESHOOTING, AI_VERIFYING, AI_RESOLVED) are part of the lifecycle state machine's defined states (FR-006), but nothing in this feature automatically drives a ticket into them — that requires the AI-support feature (Phase 4), which doesn't exist yet. This feature only guarantees the state machine itself is correct and that transitions can be triggered (e.g. by an authorized caller or a future feature) without corrupting ticket state under concurrency.
• Row-level security (Postgres RLS) as a defense-in-depth layer under the application-level tenant scoping in FR-015 (per docs/11-architect-additions-gaps-and-recommendations.md §A3) is a valuable hardening step but is deliberately deferred — REQUIRES BUSINESS/PLATFORM CONFIRMATION on whether/when to adopt it, not invented here. Application-level scoping (FR-015) is the enforced control for this feature.
• Malware scanning integration specifics (which scanner/service) are a technical decision left to planning — this spec only requires that the scan gate and its visible states exist.