support_backend/specs/003-ticketing/research.md

# Phase 0 Research: Ticket Creation, Messages & Attachments

## Decision: Ticket code format

- **Decision**: `<PRODUCT_CODE>-<YEAR>-<SEQUENCE>`, e.g. `DQB-2026-00567` (matches doc 01/04's own
  example exactly). `PRODUCT_CODE` is derived from the `Product.externalProductId` (first
  alphabetic segment, uppercased, max 4 chars, falling back to a generic prefix if the external
  id doesn't yield one cleanly) and `SEQUENCE` is a per-product-per-year monotonic counter.
- **Rationale**: Doc 01/04 use this exact shape as the running example throughout the guide;
  matching it keeps generated codes recognizable against the spec's own illustrations. A
  per-product-per-year counter (not a global one) keeps codes short and stable even as ticket
  volume grows across many products.
- **Alternatives considered**: A UUID-derived short code — rejected, not human-referenceable the
  way doc 01's own example implies support agents need ("DQB-2026-00567" is meant to be readable
  and speakable, not just unique).

## Decision: Ticket lifecycle state machine

- **Decision**: States, exactly as doc 04 §1 and doc 06's `Ticket.status` comment list them:
  `NEW, AI_ANALYZING, AI_TROUBLESHOOTING, AI_VERIFYING, AI_RESOLVED, HUMAN_ESCALATION,
  IN_PROGRESS, WAITING_FOR_CUSTOMER, RESOLUTION_PENDING_CUSTOMER, RESOLVED, CLOSED, REOPENED`.
  Valid transitions are defined as an explicit adjacency table (not "anything can go anywhere"):
  - `NEW` → `AI_ANALYZING`, `HUMAN_ESCALATION`
  - `AI_ANALYZING` → `AI_TROUBLESHOOTING`, `HUMAN_ESCALATION`
  - `AI_TROUBLESHOOTING` → `AI_VERIFYING`, `HUMAN_ESCALATION`
  - `AI_VERIFYING` → `AI_RESOLVED`, `HUMAN_ESCALATION`
  - `AI_RESOLVED` → `RESOLUTION_PENDING_CUSTOMER`, `RESOLVED`, `HUMAN_ESCALATION` (verification
    failure re-escalating, per doc 04 §7)
  - `HUMAN_ESCALATION` → `IN_PROGRESS`
  - `IN_PROGRESS` → `WAITING_FOR_CUSTOMER`, `RESOLUTION_PENDING_CUSTOMER`, `HUMAN_ESCALATION`
    (re-escalation)
  - `WAITING_FOR_CUSTOMER` → `IN_PROGRESS`
  - `RESOLUTION_PENDING_CUSTOMER` → `RESOLVED`, `IN_PROGRESS` (customer disputes, reopens
    investigation per doc 04 §7)
  - `RESOLVED` → `CLOSED`, `REOPENED`
  - `CLOSED` → `REOPENED`
  - `REOPENED` → `IN_PROGRESS`, `AI_ANALYZING`
- **Rationale**: An explicit table is what makes FR-006 ("only valid transitions") actually
  enforceable and testable, rather than a status field anyone can set to anything. The specific
  edges are read directly off doc 04's described flows (§1 happy path, §3 human flow, §7
  verification-failure branches, §9 resolve/close/reopen).
- **Alternatives considered**: No enforced table (any transition allowed) — rejected, directly
  contradicts FR-006; a generic workflow-engine library — rejected as disproportionate for a
  fixed, spec-defined state set with no per-tenant customization need at this phase.

## Decision: Ticket status optimistic concurrency

- **Decision**: `Ticket` gains an `Int` `version` column (default `1`, matching doc 06's general
  guidance to add this to mutable shared-state tables). A status update runs
  `UPDATE tickets SET status = ?, version = version + 1 WHERE id = ? AND version = ?`; zero rows
  affected means the caller's view was stale, and the update is rejected (`409 CONFLICT`, caller
  must re-read and retry).
- **Rationale**: This is the standard optimistic-locking pattern and satisfies FR-007/SC-007
  without needing row-level locks or a distributed lock service — Postgres's own atomic
  `UPDATE ... WHERE` already guarantees exactly one concurrent writer wins.
- **Alternatives considered**: `SELECT ... FOR UPDATE` pessimistic locking — rejected, holds a
  transaction open across what could be a slow caller round-trip; optimistic locking only holds
  the lock for the single atomic statement.

## Decision: Idempotency-key enforcement

- **Decision**: `Ticket` gains a nullable, unique-per-product `idempotencyKey` column
  (`@@unique([productId, idempotencyKey])`, nullable values excluded from the constraint per
  Postgres's standard NULL-handling). Ticket creation is an atomic
  `INSERT ... ON CONFLICT (productId, idempotencyKey) DO NOTHING RETURNING *`-style upsert; a
  conflict means the key was already used, and the existing ticket is looked up and returned
  instead.
- **Rationale**: Same atomic-upsert pattern already used for `CustomerReference.findOrCreate` in
  002-saas-integration — proven, race-safe under concurrent retries, no separate idempotency-key
  cache/table needed. Scoped per-product (not globally unique) because two different products'
  clients could coincidentally generate the same key value.
- **Alternatives considered**: A separate `IdempotencyKey` tracking table — rejected as
  unnecessary indirection when the key can live directly on the row it's deduplicating.

## Decision: Recurring-problem linking

- **Decision**: Per spec.md's Assumptions, this feature links to an existing `Problem` only when
  the inbound request's `referenceIds` (docs/02 §3) or the ticket-creation call explicitly
  supplies a known prior ticket/problem id; otherwise a new `Problem` is always created. No
  fuzzy/semantic matching is attempted here.
- **Rationale**: Real recurring-problem detection needs product-aware understanding of symptoms —
  that's the AI-support feature's job (Phase 4), not this one's. Building a heuristic here would
  either be too naive to be useful or scope-creep into Phase 4's actual responsibility.
- **Alternatives considered**: Simple text-similarity matching on `Problem.statement` — rejected,
  would produce false-positive links (different problems, similar wording) with no way to correct
  them until Phase 4 exists to do it properly.

## Decision: Message type → visibility mapping

- **Decision**: A single source-of-truth constant map (not per-message logic):
  ```
  CUSTOMER_MESSAGE: true, AI_MESSAGE: true, AGENT_MESSAGE: true, SYSTEM_EVENT: true,
  INTERNAL_NOTE: false, INVESTIGATION_NOTE: false, SOLUTION_NOTE: false
  ```
  `TicketMessage.visibleToCustomer` (doc 06's own field) is *set from this map at write time*,
  never accepted as caller input — and customer-scoped reads filter `WHERE visibleToCustomer =
  true` at the repository/query layer, not by trimming the response after fetching everything.
- **Rationale**: Directly satisfies FR-008 (visibility derived from type, not independently
  settable) and FR-009 (enforced at the query layer, so a serialization bug can't leak a note that
  was never fetched in the first place).
- **Alternatives considered**: Accepting `visibleToCustomer` as an API input — rejected outright,
  this is exactly the "trust the client" mistake FR-008 exists to prevent.

## Decision: Attachment pipeline shape

- **Decision**: Two-phase upload — (1) caller requests a presigned PUT URL for a given
  filename/content-type (`storageService` already has the S3 client wired, needs a presigned-PUT
  method added alongside its existing presigned-GET `getPresignedUrl`); (2) caller PUTs the file
  directly to object storage, then confirms the upload, which creates the `TicketAttachment` row
  (`scanStatus: pending`) and enqueues a scan job on the existing `attachments-queue`
  (`src/jobs/attachments/index.ts`, currently a log-only stub). Downloads use the existing
  `storageService.getPresignedUrl` (GET), but only after the repository confirms
  `scanStatus: clean` — the presigned URL is never generated for a `pending`/`infected`/`rejected`
  attachment.
- **Rationale**: A presigned-PUT upload means file bytes never transit the Fastify process at all
  (satisfies FR-011 more strongly than a server-side proxy-upload would, and avoids adding
  multipart-body handling to this feature). The existing `attachments-queue` scaffold is exactly
  where the scan step belongs per doc 07's own module layout.
- **Alternatives considered**: Server-side proxy upload (client → Fastify → S3) — rejected as
  unnecessary complexity/latency when presigned PUT achieves the same security properties with
  less code.

## Decision: Malware scanning — no scanner exists in this stack yet

- **Decision**: Define a small `MalwareScanner` interface (`scan(objectKey): Promise<'clean' |
  'infected'>`) and ship one implementation now: a clearly-named
  `UnimplementedPlaceholderScanner` that always returns `'infected'` (fails closed, never
  `'clean'`) and logs a loud warning — so attachments are correctly gated as never-downloadable
  until a real scanner (e.g. ClamAV via a sidecar, or a cloud provider's scanning API) is wired
  in as a follow-up. The job worker calls whichever implementation is bound at startup.
- **Rationale**: No antivirus/scanning service exists anywhere in this codebase or its
  dependencies, and standing one up (e.g. deploying ClamAV) is real infrastructure work outside
  this feature's scope. The alternative — a scanner that always returns `'clean'` — would satisfy
  the code path but silently defeat FR-013's actual security purpose; failing closed means the
  pipeline is honest about "attachments aren't actually safe to download yet" rather than
  pretending they are. This mirrors the same honesty principle as the credential-storage
  placeholder decision in 002-saas-integration's research.md.
- **Alternatives considered**: Always-`'clean'` stub — rejected, defeats the feature's own
  purpose and would be easy to forget to replace since nothing would ever surface the gap.
  Skipping the scan step's implementation entirely (leave the job as its current log-only stub)
  — rejected, FR-013 requires attachments be gated on scan status, and a permanently-`pending`
  attachment (nothing ever calls the job) makes attachments unusable rather than correctly gated.

## Decision: Local/test object storage — add MinIO to Docker Compose

- **Decision**: Add a `minio` service to `docker-compose.test.yml` and
  `docker-compose.development.yml`, and set `AWS_S3_ENDPOINT` in `.env.test`/`.env.development`
  to point at it. `storageClient.ts` already branches on `storageConfig.endpoint` being set
  (`forcePathStyle: true` for MinIO compatibility) — no client code changes needed, only compose
  wiring and env values.
- **Rationale**: Doc 04 explicitly calls for "MinIO for local dev," and the client already
  anticipated this (the `endpoint`/`forcePathStyle` branch exists in code that predates this
  feature) — this decision just finishes wiring what was already half-built.
- **Alternatives considered**: Mocking S3 calls in tests instead of running real MinIO — rejected,
  this feature's whole point includes verifying presigned URLs actually work and expire, which a
  mock can't meaningfully verify.