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>
3.9 KiB
3.9 KiB
Specification Quality Checklist: Ticket Creation, Messages & Attachments
Purpose: Validate specification completeness and quality before proceeding to planning Created: 2026-09-02 Feature: spec.md
Content Quality
- No implementation details (languages, frameworks, APIs)
- Focused on user value and business needs
- Written for non-technical stakeholders
- All mandatory sections completed
Requirement Completeness
- No [NEEDS CLARIFICATION] markers remain
- Requirements are testable and unambiguous
- Success criteria are measurable
- Success criteria are technology-agnostic (no implementation details)
- All acceptance scenarios are defined
- Edge cases are identified
- Scope is clearly bounded
- Dependencies and assumptions identified
Feature Readiness
- All functional requirements have clear acceptance criteria
- User scenarios cover primary flows
- Feature meets measurable outcomes defined in Success Criteria
- No implementation details leak into specification
Notes
- Scope is deliberately Phase 5 only (per docs/10-implementation-roadmap.md): ticket/problem creation, messages, attachments, lifecycle state machine. Investigation/root cause/solution/ resolution (Phase 9) and AI diagnosis (Phase 4) are explicitly out of scope — see Assumptions.
- Recurring-problem matching is intentionally left to an explicit caller-supplied reference for this feature; real fuzzy/semantic matching is deferred to the future AI-support feature.
- Malware-scanner choice and RLS adoption are left to
/speckit-plan/ business confirmation respectively, not decided here. - All items pass; no revision iterations were needed.
Implementation notes (added during /speckit-implement)
- Found and fixed a real cross-product ticket-code collision bug:
deriveProductCodetruncates to 4 alphabetic characters, so different products can legitimately derive the same prefix (e.g. every test product in this repo's own test suite starts withTEST..., all deriving"TEST"). The initial sequence-counting query (countForProductAndYear) was scoped by internalproductId, but thecodecolumn's uniqueness is global — two different products sharing a prefix would each independently compute sequence1and collide. Fixed by rescoping the count to the actual code prefix (countForCodePrefix,WHERE code LIKE 'PREFIX-YEAR-%'), which correctly reflects what the unique constraint actually guards. The existing retry-on- conflict loop (isTicketCodeConflict,MAX_CODE_RETRIES) still exists as the concurrency backstop for the rare race between two concurrent creates computing the same count-based sequence simultaneously — confirmed exercising this retry path for real during the verification run below (visible as caught-and-retriedP2002errors in the test log, not test failures). - Found and fixed a second-order issue this feature introduces for the existing 002-saas-
integration test suite: three of its integration tests'
afterAllcleanup deletedProductIntegrationthenProductdirectly. Now that a successful/v1/support/requestscall also creates aTicket/Problem(this feature), deleting theProductfirst failed on theproblems_productId_fkeyRESTRICT constraint. Fixed by addingticketMessage/ticket/problemcleanup before the existing steps intests/integration/product-integration-auth.test.ts,tests/integration/product-integrations-admin.test.ts, andtests/integration/inbound-rate-limit.test.ts. - All 9 integration test files (24 tests total, spanning both this feature and the pre-existing 002-saas-integration suite) were run and passed against a real Postgres, Redis, and MinIO (temporary Docker containers) — including a real presigned-PUT upload and presigned-GET download round-trip against MinIO, not a mock.