Handoff: SVC-022-mastery-projection-fixtures analytics-service mastery projection fixtures

Scope

• Service/area: analytics-service
• Task pack: docs/agents/service-tasks/analytics-service.md
• Goal: accept the bounded SVC-022 slice for mastery projection fixture evidence from existing producer events, while keeping analytics-service as a projection/read-model owner rather than a source of truth for exam, attempt, course, question, classroom, or profile state.
• Non-goals: public /api/analytics* route promotion, browser/runtime parity, owner-service database joins, canonical StudentMastery parity, live Postgres migration proof, or changes to legacy source under /Users/velikho/Desktop/WORKING/HOCTAPAZ/.

Docs Read

• go-platform/docs/architecture/service-responsibility-matrix.md
• go-platform/docs/architecture/legacy-api-map.md
• go-platform/docs/agents/service-agent-execution-queue.json
• go-platform/docs/agents/service-agent-closeout-ledger.json
• go-platform/docs/agents/service-tasks/analytics-service.md
• go-platform/docs/agents/agent-handoff-format.md
• go-platform/docs/api/analytics-service.md
• go-platform/docs/qa/service-agent-goal-completion-audit.md
• go-platform/docs/qa/service-agent-readiness-smoke.md

Legacy Evidence Read

• /Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/api/src/modules/analytics/analytics.service.ts
• /Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/api/src/modules/analytics/analytics.controller.ts
• /Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/api/src/modules/app-data/app-data.exams-analytics.ts
• /Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/api/src/modules/app-data/app-data.progress-overview.ts
• /Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/api/src/modules/app-data/app-data.learning-progress.ts
• /Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/api/src/modules/progress/progress.controller.ts
• /Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/api/src/modules/exams/exam-core.service.ts
• /Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/api/src/modules/attempts/attempts.controller.ts
• /Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/api/prisma/schema.prisma
• Legacy source was read-only evidence only; no canonical mastery storage or public analytics route parity is claimed.

Files Changed

• go-platform/docs/agents/handoffs/SVC-022-mastery-projection-fixtures.md
• go-platform/docs/agents/service-agent-closeout-ledger.json
• go-platform/docs/agents/service-agent-closeout-ledger.md

Behavior Implemented

• none in this handoff.
• Existing audited analytics-service code stores service-local projections and events in analytics_attempt_results, analytics_events, and analytics_rebuild_reports.
• Existing audited producer events from attempt-service and course-service include attempt result/question references, course/lesson/topic snapshots, source service, and source event ids that are sufficient fixture inputs for the bounded projection slice without reading owner databases.
• Existing audited docs keep StudentMastery as a later rebuild/projection slice and state that analytics-service never reads exam, attempt, question-bank, course, classroom, profile, or notification databases directly.

Tests And Verification

• Command: GOTOOLCHAIN=go1.25.11 go test ./services/analytics-service/...
• Result: passed.
• Evidence: analytics-service packages passed for result projections, event ingestion, rebuild reports, repository behavior, and HTTP routes.
• Command: make test-analytics-routes
• Result: passed.
• Evidence: analytics route guard confirmed the default gateway keeps analytics/exam/classroom/student/parent route families legacy-proxied while non-default examples rehearse only exact native read routes.
• Command: bash scripts/test/service-agent-execution-queue-coverage.sh
• Result: passed.
• Evidence: execution queue still names docs/agents/handoffs/SVC-022-mastery-projection-fixtures.md as the required handoff path.

Route State

• Legacy route: /api/analytics*, /api/exams*, /api/classrooms*, /api/students*, /api/parents*, and fallback routes remain on the default legacy gateway table.
• Native route: non-default examples rehearse only exact GET /api/analytics/results and GET /api/analytics/weak-topics as native analytics-service reads.
• Gateway state: make test-analytics-routes requires auth, ADMIN or TEACHER, organization scope, exact routes, and default legacy state.
• Rollback: keep deploy/gateway/routes.json as the active route table; do not promote analytics routes until access adapters, browser/runtime proof, response parity, and rollback evidence are attached.

Data Notes

• Tables touched: none in this handoff run; verification used package tests and route guards.
• Migration run: none.
• Validation report: not applicable because no live data was migrated or backfilled.

Risks / Blockers

• Dependencies SVC-009, SVC-010, and SVC-021 now have accepted bounded evidence, but all remain not-complete.
• Public analytics route promotion still needs parent/teacher/admin visibility adapters, legacy filter parity evidence, browser/runtime proof, and rollback notes.
• Canonical course mastery parity remains deferred; this handoff accepts projection fixture evidence only.
• No live Postgres integration or production-like rebuild proof was run for this handoff.

Next Step

• Add a focused mastery projection worker/backfill slice only after the producer event contract and owner-service rebuild source are named, then attach route/runtime proof before any default analytics cutover.