9586b872b7d5f03273a506eee8fd725d60b3da00
4
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
 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> |
||
|
saqib mirandClaude Sonnet 5
|
2edfbacf82 |
feat: implement ticket creation, messages & attachments (003-ticketing)
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>
|
||
|
saqib mirandClaude Sonnet 5
|
8d5731340d |
feat: implement SaaS product integration trust boundary (US1 MVP)
Implements tasks T001-T020 from specs/002-saas-integration/tasks.md (Setup, Foundational, and User Story 1 - the P1 MVP: every inbound request is authenticated and trusted before anything happens). User Story 2 (admin onboarding/rotation/revocation) and User Story 3 (rate limiting) are not yet implemented (T021-T032 remain). Schema (prisma/schema.prisma + initial migration): - Replace the placeholder Product model (leftover starter-template scaffolding: code/description/ProductStatus enum) with the real docs/06-database-schema.md shape (externalProductId, supportEnabled, status). - Add ProductIntegration (credential ref, rotation/revocation state, allowed scope, per-integration/per-user rate limits) and CustomerReference models. - Align AuditLog to docs/06's shape (actor/actorType/entityType/ entityId/reason/metadata) -- the placeholder shape had no fields to satisfy this feature's audit requirements. Auth: - HMAC-signed short-lived tokens (issue/verify) with jti-based replay defense via Redis and a bounded clock-skew tolerance. - Credential secrets are AES-256-GCM encrypted at rest (new required INTEGRATION_CREDENTIAL_ENCRYPTION_KEY env var) since no secret manager exists in this stack yet -- see research.md "Credential storage". - New product-integration-auth.plugin.ts Fastify plugin runs the validation order in contracts/inbound-request-contract.md and populates request.reqContext only on full success; every attempt (success or failure) is audit-logged without ever persisting the raw token/credential. Unregistered product and invalid credential return an identical response (FR-010). - New POST /v1/support/requests endpoint exercises the boundary end-to-end (ticket creation itself is a future feature). Also: - Fix docker-compose.test.yml's container_name collisions -- discovered while testing this change concurrently is now covered by an app-level regression test (separate commit). - Fix test:unit to scope to tests/unit only (it was running the entire tests/** glob including integration tests) -- this feature's new integration test makes real Prisma/Redis calls, unlike the prior instantiation-only checks, so the existing glob-scoping gap became actually harmful. - Update Jenkinsfile with the new required credential. Verified: full quality gate (typecheck/lint/format/architecture/ unit tests) passes; all of User Story 1's quickstart scenarios manually verified end-to-end against a live server + Postgres + Redis; the new integration test suite verified against a live database (not run as part of `npm test`, matches existing test:integration convention). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> |
||
|
saqib mir
|
5e4ed9d64a | first commit |