82d02bcdcd23b7406b231877f54df4fe69004b54
6
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
 saqib mirandClaude Sonnet 5
|
82d02bcdcd |
feat: implement AI support agent (005) — diagnosis, tools, runbooks, verification
Real Anthropic Claude integration per explicit product decision: a ticket's AI session diagnoses the problem via a structured-output call, applies a DB-configurable confidence-band policy (FR-005), and on "proceed" reasons and acts through a small permission/risk-gated tool system (FR-011/FR-012), optionally walking a matching runbook step by step with the application — never the model — owning the step index (FR-015/FR-016). Resolution requires real tool evidence, never customer claims alone (FR-018) — verifyProductResolution is a documented fail-closed placeholder mirroring the existing malware-scanner precedent, since no real per-product operational signal exists yet. AISupportSession.status mirrors onto Ticket.status through 003-ticketing's existing AI_ANALYZING/AI_TROUBLESHOOTING/AI_VERIFYING/AI_RESOLVED/ HUMAN_ESCALATION state machine, discovered during planning to have been built anticipating this exact feature. Two circular module dependencies (escalation<->sessions, tools<->sessions) were designed around rather than found as bugs: escalation is a pure summary formatter with no state dependencies of its own, and tools stays a clean leaf module with zero dependency on ai-support/sessions. Ticket creation enqueues the first diagnosis turn via the existing queue infrastructure (off the hot path of the inbound SaaS integration endpoint); a human actor changing ticket status ends the AI session via the event-bus scaffold that existed in this codebase but had never been wired to anything. A real Prisma limitation was found and fixed before it reached tests: compound-unique upsert rejects null for a nullable key column, so AIConfidencePolicy uses find-then-update/create instead, same fix class 004 already used for the same underlying limitation. Adds 9 unit tests (confidence-band, tool-policy-gate, runbook-step- advance) and 6 integration test files, including the two constitution- required standing E2E scenarios. AI-independent tests were run against real Postgres/Redis/MinIO (88 passed, 0 failed across the full suite, including every pre-existing 002/003/004 test). The AI-dependent tests compile and skip cleanly via describe.skipIf but were not run against a live model — no ANTHROPIC_API_KEY was available in this session; a real key must be supplied before this feature can actually run. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> |
||
|
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
|
55253287b3 |
feat: per-integration and per-user rate limiting (US3) + polish
Implements tasks T026-T032 from specs/002-saas-integration/tasks.md (User Story 3, P3 - the final piece of this feature) plus Polish. - New bespoke Redis fixed-window counter (checkRateLimit, src/infrastructure/cache/rate-limiter.ts) rather than @fastify/rate-limit's default onRequest-stage hook -- that hook runs before this feature's preHandler-based auth resolves the integration/user identity the limit needs to key on. A second preHandler (checkIntegrationRateLimit) runs after authenticateProductIntegration on the inbound route, checking the integration-level limit then the per-user limit independently, each throwing the existing RateLimitError (429 RATE_LIMIT_EXCEEDED) on breach. - New integration test (inbound-rate-limit.test.ts) verifies both limits are enforced independently against a real Postgres/Redis: a throttled user doesn't affect others, and the integration cap throttles even when no individual user has hit their own limit. - Docs: contracts/quickstart updated from the placeholder "RATE_LIMITED" code to the actual reused RATE_LIMIT_EXCEEDED code; cleaned up a duplicated paragraph in the admin endpoints section; added a "SaaS Integration" section to README.md documenting the inbound contract, admin routes (and their known auth-stub limitation), and how rate limits are configured. All 32 tasks in tasks.md are now complete -- all three user stories (P1 trust boundary, P2 admin lifecycle, P3 rate limiting) are implemented and covered by integration tests verified against a live database, in addition to unit tests for the crypto/token primitives. Full quality gate (typecheck/lint/format/architecture/ unit tests) passes. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> |
||
|
saqib mirandClaude Sonnet 5
|
2dffe58496 |
feat: implement CI pipeline (Jenkinsfile) for 001-ci-pipeline
Implements tasks T001-T016, T018-T022, T024-T026 from specs/001-ci-pipeline/tasks.md (T017/T023 need a real Jenkins instance to verify and are left for manual follow-up). - Add Jenkinsfile: checkout -> install -> environment validation -> typecheck -> lint (+ architecture check) -> format check -> unit -> integration -> E2E -> build -> Docker build -> publish -> deploy, matching the constitution's required stage order. Secrets are always injected from Jenkins credentials at runtime, never read from a repo-committed file. Publish/Deploy are skipped (not failed) on branches with no resolved deploy target. - Fix docker-compose.test.yml: remove fixed container_name on app/postgres/redis, which would have made concurrent CI runs collide (FR-009). Verified locally that two runs under different -p project names no longer share container/volume/network names. - Document the pipeline and local .env setup in README.md. - Mark completed tasks in specs/001-ci-pipeline/tasks.md and record the container_name/compose-down-env-file findings in the spec's requirements checklist notes. Locally verified passing: Dockerfile build, typecheck, lint, architecture check, format check, unit test suite, and the edited docker-compose.test.yml bringing up postgres/redis with isolated per-project container names. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> |
||
|
saqib mir
|
5e4ed9d64a | first commit |