saqib mirandClaude Sonnet 5
2edfbacf82
Implements all 39 tasks from specs/003-ticketing/tasks.md across all
three user stories -- Phase 5 of the roadmap.
Schema (prisma/schema.prisma + migration):
- Ticket (code, status, version for optimistic concurrency,
idempotencyKey, customerId FK), Problem, TicketMessage,
TicketAttachment per docs/06, with Product/Category/
CustomerReference back-relations.
User Story 1 -- ticket/problem creation (P1, MVP):
- Explicit 12-state lifecycle adjacency table
(ticket-state-machine.ts), not "any transition allowed."
- Ticket code generation (<PRODUCT_CODE>-<YEAR>-<SEQUENCE>) scoped
by the actual code prefix, not productId -- see the collision bug
fixed below.
- Idempotency-key enforcement via atomic create-then-catch-conflict
(never a read-then-write race), completing the FR-012 placeholder
from 002-saas-integration.
- Explicit-reference-only recurring-problem linking (no fuzzy
matching -- that's a future AI-support concern).
- POST /v1/support/requests (002-saas-integration) now creates a
real ticket instead of echoing context back.
- PATCH /tickets/:id/status with expectedVersion-based optimistic
concurrency (409 on stale version, 400 on an invalid transition).
User Story 2 -- typed messages (P2):
- Message type -> visibleToCustomer mapping is a fixed constant map,
never caller-supplied; customer-scoped reads filter at the query
layer so an internal note is never fetched, not just hidden.
- POST/GET /tickets/:id/messages (customer-scoped) and
GET /agent/tickets/:id/messages (agent-scoped).
User Story 3 -- attachment pipeline (P3):
- Presigned-PUT upload (new getPresignedUploadUrl on the existing
storageService) -- file bytes never transit this API.
- A MalwareScanner interface with a fail-closed placeholder
(UnimplementedPlaceholderScanner) since no scanner exists in this
stack -- it always reports 'infected', never silently 'clean'.
- The existing attachments-queue job stub now actually calls the
scanner and updates scanStatus; registerAttachmentWorker() is
wired into bootstrapQueue() (previously defined but never called).
- Downloads are gated on scanStatus === 'clean' -- currently always
refused until a real scanner replaces the placeholder.
- MinIO added to docker-compose.{test,development}.yml for local/CI
S3-compatible storage, matching doc 04's explicit guidance.
Two real bugs found and fixed via integration testing against a
live Postgres/Redis/MinIO (not just typechecked):
- Ticket codes could collide across different products: the
sequence counter was scoped by internal productId, but the code
column's uniqueness is global, and deriveProductCode's 4-character
truncation means different products can share a prefix. Fixed by
counting against the actual code prefix instead.
- Three existing 002-saas-integration integration tests' cleanup
started failing an FK RESTRICT check once ticket creation was
wired in (deleting a Product before the Ticket/Problem that now
reference it). Fixed their afterAll ordering.
All 9 integration test files (24 tests, spanning this feature and
the pre-existing suite) verified passing against real Postgres,
Redis, and MinIO, including a genuine presigned-PUT/GET round trip.
Full quality gate (typecheck/lint/format/architecture/unit tests)
passes.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Development
docker compose --env-file .env.development -f docker-compose.development.yml up -d --build
Test
docker compose --env-file .env.test -f docker-compose.test.yml up --build
Production
docker compose --env-file .env.prod -f docker-compose.prod.yml up --build -d
Stop
docker compose -f docker-compose.prod.yml down
Local environment setup
.env.development, .env.test, and .env.prod are gitignored (they hold real credentials) —
copy .env.example to the one you need and fill in real values before running any command above.
CI/CD
Every push/PR triggers the Jenkins pipeline defined in Jenkinsfile. Stage order:
checkout → install → environment validation → typecheck → lint → format check → unit test →
integration test → E2E test → build → Docker build → publish → deploy. Publish/deploy only run
on branches with a configured deploy target (main → prod, develop/test → test); other
branches validate and build only. Pipeline run status and per-stage logs are visible in the
Jenkins UI for the relevant job — see specs/001-ci-pipeline/quickstart.md for how to validate
the pipeline itself, and specs/001-ci-pipeline/contracts/pipeline-stage-contract.md for the
guarantees each stage makes.
Required Jenkins credentials (see the header comment in Jenkinsfile for exact IDs): per target
environment (test, prod) a Postgres password, Redis password, JWT secret, and AWS access
key/secret, plus one shared Docker registry username/password. None of these are ever read from
a file in this repository.
SaaS Integration
POST /v1/support/requests is the trust boundary a registered SaaS product calls through — every
request must carry a Authorization: Bearer <signed-token> header (HMAC-SHA256, signed with the
integration's own secret) and a body matching the inbound contract. See
specs/002-saas-integration/contracts/inbound-request-contract.md for the full validation order
and error codes, and specs/002-saas-integration/quickstart.md for runnable scenarios.
Admins manage integrations under /admin/products/:externalProductId/integration (register) and
/admin/integrations/:integrationId/{rotate,revoke,status,audit-trail}. These admin routes are
not yet actually access-controlled — fastify.authenticate is a stub pending the identity/auth
module; don't expose them outside a trusted network until that's implemented.
Rate limits (rateLimitPerMinute, rateLimitPerUserPerMinute) are set per integration at
registration time and enforced via a Redis-backed fixed-window counter, independent of the
global @fastify/rate-limit floor already applied to every route.
Ticketing
A validated inbound request (see "SaaS Integration" above) creates a Ticket and Problem
immediately — before any diagnosis. See specs/003-ticketing/contracts/ticket-lifecycle-contract.md
for the full lifecycle state machine, message-visibility rules, and attachment pipeline, and
specs/003-ticketing/quickstart.md for runnable scenarios.
- Status transitions:
PATCH /tickets/:ticketId/statusrequiresexpectedVersion(optimistic concurrency — a stale version is rejected with409, never silently overwritten) and only accepts transitions defined in the state machine (400 INVALID_TRANSITIONotherwise). - Messages:
POST/GET /tickets/:ticketId/messages(customer-scoped — internal note types are never returned) andGET /agent/tickets/:ticketId/messages(agent-scoped — everything). A message's customer-visibility is always derived from its type, never caller-supplied. - Attachments: presigned-PUT upload (
POST .../attachments/upload-url→POST .../attachments/confirm) against MinIO/S3 — file bytes never transit this API. Nothing is downloadable yet (GET .../attachments/:attachmentId/download-urlalways returns409): the malware scanner is a placeholder that fails closed until a real one (src/modules/ticketing/attachments/mapper/malware-scanner.ts) replaces it. - Local/test object storage is MinIO — see the
minioservice indocker-compose.development.yml/docker-compose.test.ymland theAWS_S3_ENDPOINTvalue in the corresponding.env.*file.