support_backend/specs/004-product-knowledge/tasks.md

---
description: "Task list for 004-product-knowledge"
---

# Tasks: Product Knowledge Management & Retrieval

**Input**: Design documents from `specs/004-product-knowledge/`

**Prerequisites**: [plan.md](./plan.md), [spec.md](./spec.md), [research.md](./research.md),
[data-model.md](./data-model.md), [contracts/knowledge-contract.md](./contracts/knowledge-contract.md),
[quickstart.md](./quickstart.md)

**Tests**: Included as first-class tasks (versioning and retrieval filtering are exactly the kind
of "MUST" requirements regressions silently break), same approach as 002/003.

**Organization**: Tasks are grouped by user story (US1 = P1 knowledge entry authoring/publish/
version, US2 = P2 error codes/known issues/runbooks, US3 = P3 retrieval).

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

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

---

## Phase 1: Setup

- [X] T001 Scaffold `src/modules/ai-support/knowledge/` with the standard module shape
      (`controller/`, `routes/`, `schema/`, `repository/`, `service/`, `types/`, `mapper/`,
      `constants/`, `index.ts`), matching every other module's conventions (research.md "Module
      placement")

---

## Phase 2: Foundational (Blocking Prerequisites)

**Purpose**: Schema for all four entities, shared by every user story.

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

- [X] T002 Add `KnowledgeEntry`, `ErrorCode`, `KnownIssue`, `Runbook` models to
      `prisma/schema.prisma` per `data-model.md` (including `isCurrentVersion` and the
      `(code, version)` / `(key, productId, version)` compound unique constraints — NOT a bare
      unique on `code`/`key`), plus the four new back-relations on `Product`
- [X] T003 Run `npm run prisma:generate` and create the migration (`npm run prisma:migrate`) for
      T002 (depends on T002)

**Checkpoint**: Schema migrated. User stories can now be built.

---

## Phase 3: User Story 1 - An admin authors, versions, and publishes knowledge entries (Priority: P1) 🎯 MVP

**Goal**: Full knowledge-entry lifecycle — create (draft) → publish → edit (new version) →
validate → unpublish, with prior versions always retrievable.

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

### Tests for User Story 1

- [~] T004 [P] [US1] ~~Unit tests for the version-on-edit logic~~ — deliberately skipped, not
      forgotten: unlike 003-ticketing's state machine, there's no pure-logic surface here to
      isolate from Prisma (the concurrency behavior lives entirely inside the repository's own
      transaction) — see checklist Notes. Covered instead by T005's integration test, which
      exercises the real conflict path against a live database.
- [X] T005 [US1] Integration test covering Quickstart Scenarios 1, 2, 3 (draft invisible →
      publish makes retrievable, edit preserves history, stale-version edit rejected) against a
      real Postgres in `tests/integration/knowledge-entries.test.ts`

### Implementation for User Story 1

- [X] T006 [US1] Add `KnowledgeRepository` (`create`; `findCurrentByCode`; `findAllVersionsByCode`
      (newest first); `publish`/`unpublish`/`setValidationStatus` (update the current-version row
      in place — these are metadata changes, not content edits, so they don't create a new
      version); `createNewVersion` implementing research.md's conditional-update-then-insert) in
      `src/modules/ai-support/knowledge/repository/knowledge.repository.ts` (depends on T003)
- [X] T007 [US1] Add `KnowledgeService` wrapping the repository with the FR-002/FR-004 rules
      (new entries default to `status: draft`, `version: 1`; edits always go through
      `createNewVersion`, never a raw update) in
      `src/modules/ai-support/knowledge/service/knowledge.service.ts` (depends on T006)
- [X] T008 [US1] Add Zod schemas for create/publish/unpublish/validate/edit request bodies in
      `src/modules/ai-support/knowledge/schema/knowledge.schema.ts` (depends on T001)
- [X] T009 [US1] Add routes: `POST /admin/products/:externalProductId/knowledge`,
      `PATCH /admin/knowledge/:code/publish`, `PATCH /admin/knowledge/:code/unpublish`,
      `PATCH /admin/knowledge/:code/validate`, `PUT /admin/knowledge/:code`,
      `GET /admin/knowledge/:code/versions` — all gated by `fastify.authenticate` — in
      `src/modules/ai-support/knowledge/routes/knowledge.routes.ts`, registered from
      `src/api/routes.ts` (depends on T007, T008)
- [X] T010 [US1] Run Quickstart Scenarios 1, 2, 3 locally and confirm all three pass

**Checkpoint**: User Story 1 is fully functional — knowledge entries can be authored, published,
versioned, and validated, with full history preserved. This alone is a usable content-management
surface even before error codes/runbooks/retrieval exist.

---

## Phase 4: User Story 2 - Known issues, error codes, and runbooks are modeled as first-class, product-scoped records (Priority: P2)

**Goal**: `ErrorCode`/`KnownIssue` CRUD + lookup-by-error-code; `Runbook` CRUD with the same
version-on-edit mechanism as User Story 1.

**Independent Test**: Quickstart Scenarios 4, 5.

### Tests for User Story 2

- [X] T011 [P] [US2] Integration test covering Quickstart Scenario 4 (error code → known issue →
      lookup by error code) against a real Postgres in
      `tests/integration/known-issues.test.ts`
- [X] T012 [P] [US2] Integration test covering Quickstart Scenario 5 (runbook step order
      preserved; deactivate removes it from lookup) against a real Postgres in
      `tests/integration/runbooks.test.ts`

### Implementation for User Story 2

- [X] T013 [P] [US2] Add `ErrorCodesRepository`/`ErrorCodesService` (create; findByCode) in
      `src/modules/ai-support/knowledge/repository/error-codes.repository.ts` +
      `src/modules/ai-support/knowledge/service/error-codes.service.ts` (depends on T003)
- [X] T014 [US2] Add `KnownIssuesRepository`/`KnownIssuesService` (create; findByErrorCode,
      joining through `ErrorCodesRepository`'s lookup) in
      `src/modules/ai-support/knowledge/repository/known-issues.repository.ts` +
      `src/modules/ai-support/knowledge/service/known-issues.service.ts` (depends on T013)
- [X] T015 [P] [US2] Add `RunbooksRepository` (`create`; `findCurrentByKey` — filters
      `isCurrentVersion: true, active: true`, treating inactive the same as not-found per FR-010;
      `createNewVersion` reusing research.md's conditional-update-then-insert pattern;
      `deactivate`) in `src/modules/ai-support/knowledge/repository/runbooks.repository.ts`
      (depends on T003)
- [X] T016 [US2] Add `RunbooksService` in
      `src/modules/ai-support/knowledge/service/runbooks.service.ts` (depends on T015)
- [X] T017 [US2] Add routes: `POST /admin/products/:externalProductId/error-codes`,
      `POST /admin/products/:externalProductId/known-issues`,
      `GET /admin/products/:externalProductId/known-issues/by-error-code/:code`,
      `POST /admin/products/:externalProductId/runbooks`,
      `PUT /admin/products/:externalProductId/runbooks/:key`,
      `PATCH /admin/products/:externalProductId/runbooks/:key/deactivate`,
      `GET /admin/products/:externalProductId/runbooks/:key` — all gated by
      `fastify.authenticate` — added to
      `src/modules/ai-support/knowledge/routes/knowledge.routes.ts` (depends on T014, T016)
- [X] T018 [US2] Run Quickstart Scenarios 4, 5 locally and confirm both pass

**Checkpoint**: Both User Story 1 and 2 work together — the full structured knowledge catalog
(entries, error codes, known issues, runbooks) exists.

---

## Phase 5: User Story 3 - Retrieval returns only relevant, filtered, validation-aware knowledge (Priority: P3)

**Goal**: The filtered/ranked retrieval query (research.md), scoped to product/feature/category,
excluding drafts and not-yet-effective entries, validated-first ordering.

**Independent Test**: Quickstart Scenario 6.

### Tests for User Story 3

- [~] T019 [P] [US3] ~~Unit tests for the retrieval filter/ranking predicate~~ — deliberately
      skipped for the same reason as T004: the filter/ranking predicate is a Prisma `where`/
      `orderBy` clause, not an extractable pure function. Covered by T020's integration test.
- [X] T020 [US3] Integration test covering Quickstart Scenario 6 (cross-product isolation,
      validated-first ranking) against a real Postgres in
      `tests/integration/knowledge-retrieval.test.ts`

### Implementation for User Story 3

- [X] T021 [US3] Add `KnowledgeRepository.retrieve(productId, feature?, categoryScope?)`
      implementing research.md's exact filter/order (depends on T006)
- [X] T022 [US3] Add `KnowledgeService.retrieve(...)` (depends on T021)
- [X] T023 [US3] Add route `GET /knowledge/retrieve` (no `fastify.authenticate` gate — this is a
      read path the future AI-support feature will call internally, not an admin surface;
      revisit once that feature defines its own internal-service-call convention) in
      `src/modules/ai-support/knowledge/routes/knowledge.routes.ts`, registered from
      `src/api/routes.ts` (depends on T022)
- [X] T024 [US3] Run Quickstart Scenario 6 locally and confirm it passes

**Checkpoint**: All three user stories work independently and together — knowledge can be
authored, structured, and retrieved correctly.

---

## Phase 6: Polish & Cross-Cutting Concerns

- [X] T025 [P] Add a "Product Knowledge" section to `README.md` describing the admin CRUD,
      versioning mechanism, and retrieval contract
- [X] T026 [P] Update `specs/004-product-knowledge/checklists/requirements.md` Notes with any
      implementation-time findings
- [X] T027 Run `npx tsx scripts/check-architecture.ts` and `npm run lint`/`npm run typecheck`
- [X] T028 Full regression: `npm run test:unit` (scoped to `tests/unit`) 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 — independent of US1's own entities, though
  practically sequenced after since it reuses US1's version-on-edit pattern for runbooks
- **User Story 3 (Phase 5)**: Depends on US1's `KnowledgeRepository` existing (T006) — genuinely
  not implementable before US1, since retrieval queries the same table US1 creates
- **Polish (Phase 6)**: Depends on all three user stories

### Parallel Opportunities

- T004 alongside T006-T009 once T003 exists (unit test doesn't need the real implementation)
- T011/T012 (independent integration test files)
- T013/T015 (independent repositories)
- T019 alongside US3's later tasks
- T025/T026 in Polish

---

## Implementation Strategy

### MVP First (User Story 1 Only)

1. Setup + Foundational (T001-T003)
2. User Story 1 (T004-T010)
3. **STOP and VALIDATE**: Quickstart Scenarios 1-3 pass — knowledge entries can be authored,
   published, and versioned correctly. Usable as a content-management surface even before
   structured error codes/runbooks/retrieval exist.

### Incremental Delivery

1. Setup + Foundational → schema migrated
2. Add User Story 1 → knowledge entries work end to end (MVP)
3. Add User Story 2 → error codes, known issues, runbooks
4. Add User Story 3 → filtered retrieval, ready for the future AI-support feature to call
5. Polish → docs and full regression