Files

T

saqib mirandClaude Sonnet 5 e33d86081f feat: implement product knowledge management & retrieval (004)

Implements 26 of 28 tasks from specs/004-product-knowledge/tasks.md
across all three user stories -- Phase 3 of the roadmap. First
feature to populate src/modules/ai-support/ (doc 07 places
`knowledge` there; only that submodule is built, matching this
codebase's convention of not pre-building unneeded submodules).

Schema (prisma/schema.prisma + migration):
- KnowledgeEntry, ErrorCode, KnownIssue, Runbook per docs/06,
  refining its conceptual flat `version` field into an explicit
  version-history mechanism: each edit inserts a new row
  (isCurrentVersion flag, compound unique on (code, version) /
  (key, productId, version)) instead of overwriting in place -- the
  only way "prior versions remain retrievable" (FR-004/FR-009) is
  actually true rather than aspirational.

User Story 1 -- knowledge entry authoring/publish/version (P1, MVP):
- draft -> published -> unpublished lifecycle; publish only takes
  effect from its effectiveDate.
- Editing uses the same conditional-update-then-insert optimistic
  concurrency pattern as 003-ticketing's Ticket.version (409 on a
  stale expectedVersion).
- Full version history readable via GET .../versions.

User Story 2 -- error codes, known issues, runbooks (P2):
- ErrorCode + KnownIssue with direct lookup-by-error-code.
- Runbook steps stored as an ordered JSON array, preserved exactly;
  same version-on-edit mechanism as knowledge entries; inactive
  runbooks are indistinguishable from nonexistent ones on lookup.

User Story 3 -- filtered retrieval (P3):
- GET /knowledge/retrieve: product-scoped, excludes draft/
  unpublished/not-yet-effective entries, validated entries ranked
  ahead of unvalidated. Deliberately NOT semantic/vector search --
  doc 11 gap B1 explicitly defers embedding-model choice to the
  future AI-support feature; this is real, usable structured
  filtering a semantic layer can sit in front of later.

Found and fixed one real bug before it reached tests: the retrieval
endpoint initially queried by the raw external product id instead of
resolving it to the internal Product.id first (every other endpoint
in this feature does that resolution) -- would have silently
returned zero results for every caller. Fixed with a lenient
tryResolveProductId (empty array, not 404, for an unregistered
product -- matches the "no matches, never an error" contract).

Deliberately skipped (not forgotten, see checklist notes): the two
planned mock-repository unit-test tasks (T004, T019) -- unlike
003-ticketing's state machine, this feature has no pure-logic
surface to isolate from Prisma; coverage comes entirely from
integration tests instead.

All 13 integration test files in the repo (36 tests, spanning this
feature and every prior one) verified passing together against a
real Postgres/Redis/MinIO -- no regressions. Full quality gate
(typecheck/lint/format/architecture/unit tests) passes.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

2026-09-02 15:55:18 +05:30

5.3 KiB

Raw Blame History

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/status requires expectedVersion (optimistic concurrency — a stale version is rejected with 409, never silently overwritten) and only accepts transitions defined in the state machine (400 INVALID_TRANSITION otherwise).
Messages: POST/GET /tickets/:ticketId/messages (customer-scoped — internal note types are never returned) and GET /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-url always returns 409): 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 minio service in docker-compose.development.yml / docker-compose.test.yml and the AWS_S3_ENDPOINT value in the corresponding .env.* file.

Product Knowledge

Admin CRUD for KnowledgeEntry/ErrorCode/KnownIssue/Runbook, plus GET /knowledge/retrieve — a filtered (not semantic/vector) query the future AI-support feature will call. See specs/004-product-knowledge/contracts/knowledge-contract.md for the full route list and specs/004-product-knowledge/quickstart.md for runnable scenarios.

Versioning: editing a published KnowledgeEntry or Runbook never overwrites it in place — it creates a new row (version incremented, isCurrentVersion: true), and the prior version stays queryable (GET /admin/knowledge/:code/versions). Requires expectedVersion; a stale value is rejected with 409, same concurrency pattern as ticket status updates.
Retrieval (GET /knowledge/retrieve?productId=&feature=&category=) only ever returns published, currently-effective, current-version entries scoped to the given product — validated entries are ranked ahead of unvalidated ones. An unregistered productId returns an empty array, not an error.
Full semantic/embedding-based retrieval is intentionally not implemented here — see specs/004-product-knowledge/spec.md Assumptions.

5.3 KiB Raw Blame History