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

Phase 0 Research: Product Knowledge Management & Retrieval

Decision: Versioning mechanism — new row per version, not in-place overwrite

• Decision: docs/06-database-schema.md's KnowledgeEntry/Runbook models are explicitly "conceptual/pseudo-Prisma... refine field types... during Phase 1 modeling" — their flat version Int field alone doesn't satisfy this feature's FR-004/FR-009 ("prior versions MUST remain retrievable"), since a plain in-place UPDATE overwrites history. This feature refines the schema: each edit inserts a new row sharing the same logical identifier (code for KnowledgeEntry, key+productId for Runbook) with version incremented, and exactly one row per logical identifier has isCurrentVersion: true at a time. The unique constraint moves from a bare code/key to (code, version) / (key, productId, version); a partial-unique- style application check (see next decision) keeps only one current version.
• Rationale: This is the standard "immutable version history" pattern and directly satisfies "prior versions remain retrievable by their own identity" (FR-004) without a separate audit table — the versions themselves ARE the history, consistent with Constitution Principle VI.
• Alternatives considered: A separate KnowledgeEntryVersion history table with the main row only ever holding "current" — rejected as more schema surface for the same guarantee; querying "give me version 3 of KB-DQ-102" is equally simple either way, and one-table-per-entity-type keeps retrieval queries (which only ever care about the current version) simpler.

Decision: Concurrency on edit — conditional update + insert, same class as 003-ticketing

• Decision: Creating a new version is two steps inside one transaction: (1) UPDATE ... WHERE code = ? AND version = ? AND isCurrentVersion = true SET isCurrentVersion = false (the caller's expectedVersion must match the current row) — zero rows affected means a concurrent edit already won, and this edit is rejected with 409 CONFLICT; (2) only if step 1 affected exactly one row, insert the new current-version row.
• Rationale: Directly reuses the optimistic-concurrency pattern already established in 003-ticketing's Ticket.version handling — same shape of problem (two admins editing the same entry), same solution, no new concurrency-control concept introduced into the codebase.
• Alternatives considered: Last-write-wins (no expectedVersion check) — rejected, would let one admin's edit silently clobber another's without either of them knowing, which is exactly what Constitution Principle VII's concurrency requirement exists to prevent.

Decision: Retrieval — structured filtering, no vector/embedding search

• Decision: A retrieval query is WHERE productId = ? AND isCurrentVersion = true AND status = 'published' AND (effectiveDate IS NULL OR effectiveDate <= now()) AND (feature filter if given) AND (categoryScope filter if given), ordered by validationStatus = 'validated' first, then by effectiveDate DESC (most recently published first) as a simple, defensible tiebreak.
• Rationale: Per spec.md's Assumptions and doc 11 §B1, full semantic retrieval is explicitly a future decision (embedding model, chunking, re-ranking) — this feature's job is a correct, real, filtered retrieval contract that a semantic layer can be added in front of later without changing what "correct" means (doc 11 §B1's "filters apply before the vector search" requirement is satisfied by construction, since there's no vector search yet to apply them before).
• Alternatives considered: Postgres full-text search (tsvector/tsquery) on problem/symptoms text — considered as a nearer-term relevance improvement, but deferred: it would still not be "the RAG layer" doc 03 describes, adds index/query complexity beyond what this phase's requirements (FR-011 through FR-013) actually ask for, and can be added later as a ranking refinement without a breaking contract change.

Decision: Known issue lookup by error code

• Decision: KnownIssue.errorCodeId is a nullable FK to ErrorCode; lookup is a direct WHERE errorCodeId = ? query (via the ErrorCode's own id, resolved from its code string first if the caller only has the string).
• Rationale: Matches doc 06's shape exactly (KnownIssue.errorCodeId String?) and FR-007's "retrieve a known issue directly by its error code" — a simple indexed FK lookup, no special design needed.

Decision: Module placement — new ai-support/knowledge module group

• Decision: Create src/modules/ai-support/knowledge/ now, following the standard module shape (controller/routes/schema/repository/service/types/mapper/constants/index.ts) used by every other module in this codebase. No other ai-support submodule (agents/sessions/diagnosis/troubleshooting/tools/tool-execution/verification/escalation) is created — those remain nonexistent until the Phase 4 feature that needs them, matching how identity/auth and most of orchestration/platform remain untouched placeholder stubs from the original scaffold rather than being pre-built speculatively.
• Rationale: Doc 07 explicitly places knowledge inside the ai-support group — this is the documented, correct location, not an open design choice.
• Alternatives considered: Placing it under catalog (since it's product-scoped content, similar to catalog/products/catalog/categories) — rejected; doc 07 already answers this question, and following it keeps the module layout matching the architecture doc exactly.

Decision: Admin endpoint authentication

• Decision: All admin CRUD endpoints (create/publish/unpublish/version-edit for knowledge entries and runbooks; create for error codes/known issues) are gated by the existing fastify.authenticate decorator — same known-limitation pattern as 002/003's admin routes (it doesn't perform real JWT verification yet).
• Rationale: Consistency with every other admin surface built so far; introducing a different auth mechanism just for this feature would be inconsistent without a reason to be.
• Alternatives considered: None — this follows established precedent directly.