support_backend/specs/003-ticketing/tasks.md

description

description
Task list for 003-ticketing

Tasks: Ticket Creation, Messages & Attachments

Input: Design documents from specs/003-ticketing/

Prerequisites: plan.md, spec.md, research.md, data-model.md, contracts/ticket-lifecycle-contract.md, quickstart.md

Tests: Included as first-class tasks (state machine, idempotency, and visibility enforcement are exactly the kind of "MUST" requirements regressions silently break), same approach as 002-saas-integration.

Organization: Tasks are grouped by user story (US1 = P1 ticket/problem creation, US2 = P2 messages, US3 = P3 attachments).

Format: [ID] [P?] [Story] Description

All file paths are relative to supporthub-api/ (repo root).

---

Phase 1: Setup

• T001 Add a minio service to docker-compose.test.yml and docker-compose.development.yml (image minio/minio, console + API ports), and set AWS_S3_ENDPOINT/AWS_S3_BUCKET/AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY in .env.test/.env.development to point at it (research.md "local/test object storage")
• T002 [P] Add getPresignedUploadUrl(objectName, contentType, expirySeconds?) to src/infrastructure/storage/storage.service.ts, mirroring the existing getPresignedUrl/PutObjectCommand pattern already used by uploadFile

Checkpoint: Object storage is reachable locally/in CI; the service can mint both upload and download presigned URLs.

---

Phase 2: Foundational (Blocking Prerequisites)

Purpose: Schema and shared primitives (state machine, visibility map, scanner interface) every user story depends on.

⚠️ CRITICAL: No user-story stage work can begin until this phase is complete.

• T003 Add Ticket, Problem, TicketMessage, TicketAttachment models to prisma/schema.prisma per data-model.md (including Ticket.version, Ticket.idempotencyKey, Ticket.customerId FK to the existing CustomerReference, Ticket.categoryId FK to the existing Category)
• T004 Run npm run prisma:generate and create the migration (npm run prisma:migrate) for T003 (depends on T003)
• T005 [P] Define the 12-state adjacency table and a pure isValidTransition(from, to): boolean function in src/modules/ticketing/tickets/mapper/ticket-state-machine.ts per research.md's exact edge list
• T006 [P] Define the message type→visibility constant map and a pure isVisibleToCustomer(type): boolean function in src/modules/ticketing/messages/mapper/message-visibility.ts per research.md
• T007 [P] Define the MalwareScanner interface and the fail-closed UnimplementedPlaceholderScanner in src/modules/ticketing/attachments/mapper/malware-scanner.ts per research.md — logs a loud warning on every call
• T008 [P] Add a ticket-code generator (generateTicketCode(externalProductId, sequence): string) in src/modules/ticketing/tickets/mapper/ticket-code.ts per research.md's format

Checkpoint: Schema migrated; state machine, visibility map, scanner interface, and code generator exist and are independently unit-testable. User stories can now be built.

---

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

Goal: POST /v1/support/requests (002-saas-integration) creates a real Ticket+Problem instead of echoing context back; ticket status transitions are validated and concurrency-safe.

Independent Test: Quickstart Scenarios 1, 2, 3, 6.

Tests for User Story 1

• T009 [P] [US1] Unit tests for ticket-state-machine.ts (every valid edge accepted, a sample of invalid edges rejected) in tests/unit/ticketing/ticket-state-machine.test.ts
• T010 [P] [US1] Unit tests for ticket-code.ts (format, per-product-per-year sequencing) in tests/unit/ticketing/ticket-code.test.ts
• T011 [US1] Integration test covering Quickstart Scenarios 1, 2, 3, 6 (creation, idempotent retry, recurring-problem linking via referenceIds, concurrent status-update rejection) against a real Postgres in tests/integration/ticket-creation.test.ts

Implementation for User Story 1

• T012 [US1] Add ProblemsRepository (create; find-by-reference using an explicit prior ticket/problem id — research.md's explicit-reference-only rule) in src/modules/ticketing/tickets/repository/problems.repository.ts (depends on T004)
• T013 [US1] Add TicketsRepository (atomic create with idempotency-key upsert per data-model.md's @@unique([productId, idempotencyKey]); findById; findByCode; updateStatus using the version-based optimistic-concurrency UPDATE ... WHERE version = ? from research.md) in src/modules/ticketing/tickets/repository/tickets.repository.ts, replacing the old placeholder findAllProducts-style stub (depends on T004)
• T014 [US1] Add TicketMessagesRepository.create (used internally for the SYSTEM_EVENT creation/transition record — full messages CRUD is User Story 2) in src/modules/ticketing/messages/repository/messages.repository.ts (depends on T004, T006)
• T015 [US1] Add TicketsService.createFromInboundRequest(reqContext, body): resolves/creates the Problem (T012), creates/fetches the Ticket (T013), writes the creation SYSTEM_EVENT message (T014) — all synchronous within one request (FR-001) — in src/modules/ticketing/tickets/service/tickets.service.ts (depends on T012, T013, T014)
• T016 [US1] Add TicketsService.updateStatus(ticketId, newStatus, expectedVersion, actor): validates the transition via isValidTransition (T005), calls the repository's optimistic update, writes a SYSTEM_EVENT message on success, throws 409 CONFLICT on version mismatch and 400 INVALID_TRANSITION on an invalid edge (depends on T005, T013, T014)
• T017 [US1] Replace src/modules/catalog/products/routes/inbound-request.routes.ts's stub handler: call TicketsService.createFromInboundRequest and respond with { ticketId, code, status, problemId } instead of echoing reqContext back (depends on T015)
• T018 [US1] Add PATCH /tickets/:ticketId/status (body { status, expectedVersion }) and GET /tickets/:ticketId routes, tenant-scoped per FR-015, in src/modules/ticketing/tickets/routes/tickets.routes.ts, replacing the old placeholder GET /tickets list stub; register the module's routes from src/api/routes.ts (depends on T016)
• T019 [US1] Run Quickstart Scenarios 1, 2, 3, 6 locally and confirm all four pass

Checkpoint: User Story 1 is fully functional — every trusted inbound request produces a real, concurrency-safe, idempotent ticket. This is a deployable/demoable increment even before messages/attachments exist.

---

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

Goal: Full message CRUD with visibility enforced at the query layer.

Independent Test: Quickstart Scenario 4.

Tests for User Story 2

• T020 [P] [US2] Unit tests for message-visibility.ts (every type maps correctly, including that the mapping can't be overridden by caller input at the type level) in tests/unit/ticketing/message-visibility.test.ts
• T021 [US2] Integration test covering Quickstart Scenario 4 (post one of each type; confirm customer-scoped read excludes internal types entirely; confirm agent-scoped read includes all) against a real Postgres in tests/integration/ticket-messages.test.ts

Implementation for User Story 2

• T022 [US2] Extend TicketMessagesRepository with findVisibleToCustomer(ticketId) (WHERE visibleToCustomer = true, per data-model.md's index) and findAll(ticketId) (agent-scope) — both tenant-scoped per FR-015 (depends on T014)
• T023 [US2] Add MessagesService.post(ticketId, actor, type, body) (sets visibleToCustomer from isVisibleToCustomer(type) — never from request input, FR-008) and .listForCustomer/.listForAgent in src/modules/ticketing/messages/service/messages.service.ts (depends on T006, T022)
• T024 [US2] Add routes in src/modules/ticketing/messages/routes/messages.routes.ts: POST /tickets/:ticketId/messages (customer/agent both post, gated by fastify.authenticate), GET /tickets/:ticketId/messages (customer-scoped), GET /agent/tickets/:ticketId/messages (agent-scoped) — register from src/api/routes.ts (depends on T023)
• T025 [US2] Run Quickstart Scenario 4 locally and confirm it passes

Checkpoint: Both User Story 1 and 2 work together — a created ticket now has a real, correctly-scoped message timeline.

---

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

Goal: Presigned-PUT upload → confirm → async scan → scan-gated presigned-GET download.

Independent Test: Quickstart Scenario 5.

Tests for User Story 3

• T026 [P] [US3] Unit tests for UnimplementedPlaceholderScanner (always resolves 'infected', never throws) in tests/unit/ticketing/malware-scanner.test.ts
• T027 [US3] Integration test covering Quickstart Scenario 5 (upload-url → confirm → download refused while pending → download refused after the placeholder scanner marks infected) against a real Postgres/Redis/MinIO in tests/integration/ticket-attachments.test.ts

Implementation for User Story 3

• T028 [US3] Add AttachmentsRepository (create with scanStatus: 'pending'; findById; updateScanStatus) in src/modules/ticketing/attachments/repository/attachments.repository.ts (depends on T004)
• T029 [US3] Add AttachmentsService.requestUploadUrl(ticketId, fileName, mimeType, sizeBytes): validates type/size against configured limits (FR-012) before calling storageService.getPresignedUploadUrl (T002) — depends on T002
• T030 [US3] Add AttachmentsService.confirmUpload(ticketId, storageKey, fileName, mimeType, sizeBytes, uploadedBy): creates the TicketAttachment row (T028) and enqueues a job on QueueName.ATTACHMENTS via the existing queueManager (depends on T028)
• T031 [US3] Add AttachmentsService.requestDownloadUrl(ticketId, attachmentId): returns storageService.getPresignedUrl only when scanStatus === 'clean', else throws 409 with the current status (FR-013/FR-014) — depends on T028
• T032 [US3] Replace the log-only stub in src/jobs/attachments/index.ts: call the bound MalwareScanner (T007), then AttachmentsRepository.updateScanStatus with the result — depends on T007, T028
• T033 [US3] Wire registerAttachmentWorker() into src/bootstrap/queue.bootstrap.ts (it's currently defined but never called anywhere) — depends on T032
• T034 [US3] Add routes in src/modules/ticketing/attachments/routes/attachments.routes.ts: POST /tickets/:ticketId/attachments/upload-url, POST /tickets/:ticketId/attachments/:attachmentId/confirm, GET /tickets/:ticketId/attachments/:attachmentId/download-url — register from src/api/routes.ts (depends on T029, T030, T031)
• T035 [US3] Run Quickstart Scenario 5 locally and confirm it passes

Checkpoint: All three user stories work independently and together — a ticket now has creation, a message timeline, and a securely-gated attachment pipeline.

---

Phase 6: Polish & Cross-Cutting Concerns

• T036 [P] Add a "Ticketing" section to README.md describing the inbound-to-ticket flow, the status-transition contract, and the attachment pipeline (including that downloads are permanently blocked until a real MalwareScanner replaces the placeholder)
• T037 [P] Update specs/003-ticketing/checklists/requirements.md Notes with any implementation-time findings (e.g. concurrency edge cases discovered while testing T011)
• T038 Run npx tsx scripts/check-architecture.ts and npm run lint/npm run typecheck to confirm the new modules respect existing module-boundary rules
• T039 Full regression: npm run test:unit (scoped to tests/unit, per 001/002's fix) to confirm nothing broke elsewhere

---

Dependencies & Execution Order

Phase Dependencies

• Setup (Phase 1): No dependencies
• Foundational (Phase 2): Depends on Setup — BLOCKS all user stories
• User Story 1 (Phase 3): Depends on Foundational — no dependency on US2/US3
• User Story 2 (Phase 4): Depends on Foundational + a Ticket existing to attach messages to — practically sequenced after US1, though its own repository/service/routes are independent code
• User Story 3 (Phase 5): Depends on Foundational + a Ticket existing — independent of US2
• Polish (Phase 6): Depends on all three user stories

Parallel Opportunities

• T001/T002 (Setup)
• T005/T006/T007/T008 (independent Foundational primitives)
• T009/T010 (independent unit test files)
• T020 alongside US1's later tasks once T006 exists
• T026 alongside US1/US2's later tasks once T007 exists
• T036/T037 in Polish

---

Implementation Strategy

MVP First (User Story 1 Only)

1. Setup + Foundational (T001-T008)
2. User Story 1 (T009-T019)
3. STOP and VALIDATE: Quickstart Scenarios 1, 2, 3, 6 pass — every trusted request now produces a real, durable, idempotent, concurrency-safe ticket. This alone is a meaningful product milestone even before messages/attachments exist.

Incremental Delivery

1. Setup + Foundational → schema migrated, primitives tested
2. Add User Story 1 → tickets are real (MVP)
3. Add User Story 2 → tickets have a correctly-scoped conversation timeline
4. Add User Story 3 → tickets support secure attachments
5. Polish → docs and full regression