Analytics Service API

Current Endpoints

• GET /healthz
• GET /readyz
• GET /v1
• GET /v1/analytics/results
• PUT /v1/analytics/results/{attemptId}/snapshot
• GET /v1/analytics/weak-topics
• GET /v1/analytics/exams/{examId}/summary
• GET /v1/analytics/classrooms/{classroomId}/summary
• GET /v1/analytics/students/{studentId}/summary
• POST /v1/analytics/events
• GET /v1/analytics/events

Native Analytics Foundation

Phase 9 starts analytics-service with event ingestion and small result projections. Public /api/analytics*, /api/students*, /api/parents*, /api/exams/*/analytics, and classroom report routes remain legacy-proxied until gateway adapters can hydrate user/classroom/exam/question details and enforce the current role checks.

Legacy evidence:

• apps/api/src/modules/analytics/analytics.controller.ts:14-139 maps analytics result, weak-topic, exam, classroom, student, parent, and export routes.
• apps/api/src/modules/analytics/analytics.service.ts:7-51 delegates all analytics reads to AppDataService.
• apps/api/src/modules/app-data/app-data.exams-analytics.ts:173-355 implements analyticsResults and weakTopics from graded attempts, answers, exams, classroom assignments, subjects, topics, and chapters.
• apps/api/src/modules/app-data/app-data.progress-overview.ts:4-317 implements classroom progress, parent child listing, student progress, and parent progress by joining attempts, classroom membership, learning progress, notifications, assignments, and result visibility rules.
• apps/api/src/modules/progress/progress.controller.ts:11-49 records lesson/video/material progress.
• apps/api/src/modules/app-data/app-data.learning-progress.ts:20-154 clamps progress, maps status, auto-completes video at 95 percent, and upserts material views.
• apps/api/prisma/schema.prisma:868-923 defines classroom lesson/material/video progress tables.
• apps/api/prisma/schema.prisma:1080-1210 defines course progress, material view, video progress, and StudentMastery.
• apps/api/prisma/schema.prisma:2448-2534 defines ExamAttempt, ExamAttemptQuestion, ExamAnswer, and ExamEvent.
• apps/web/app/teacher/analytics/page.tsx:52-53 consumes /analytics/results?limit=80 and /analytics/weak-topics.
• apps/web/app/teacher/results/page.tsx:232-261 consumes filtered analytics result and weak-topic endpoints.
• apps/web/app/parent/dashboard/page.tsx:70-75 and apps/web/app/parent/children/[id]/progress/page.tsx:28-33 consume parent progress endpoints.

Native contract:

• PUT /v1/analytics/results/{attemptId}/snapshot upserts an already-hydrated attempt result projection from attempt-service/gateway/backfill. Analytics-service stores references and display snapshots only; it does not query exam, attempt, user, classroom, or question databases.
• GET /v1/analytics/results supports classroomId, examId, subjectId, gradeLevel, topic, from, to, page, and limit. Page defaults to 1, limit defaults to 20, and limit is clamped to 1..100.
• Result rows preserve the frontend-facing legacy shape: attemptId, student, optional classroom, exam, score, correctCount, wrongCount, durationSeconds, status, submittedAt, and weakTopics.
• GET /v1/analytics/weak-topics mirrors the legacy derivation from the first 100 matching analytics results: each topic in a result row increments wrongCount and attemptCount; accuracy is max(0, 1 - wrongCount / attemptCount); shouldAlert is true when wrongCount >= 2 or accuracy < 0.6.
• Summary endpoints compute attemptCount, averageScore, correctCount, wrongCount, and weak topics from the service-owned result projection.
• POST /v1/analytics/events records service-local audit/analytics events. These are not admin audit logs and do not replace admin-service ownership.
• Actor/RBAC checks stay at gateway adapters for public cutover. Native endpoints accept X-Actor-* headers for future adapters but P9-002 treats result snapshots as internal service data.

Database:

• services/analytics-service/migrations/000002_analytics_foundation.sql creates analytics_attempt_results and analytics_events.
• Cross-service ids such as organization_id, student_id, classroom_id, exam_id, and subject_id are stored as public ids only.
• StudentMastery remains a later rebuild/projection slice; P9-002 does not claim course mastery parity.

Gateway route rehearsal:

The default gateway route table keeps /api/analytics*, /api/exams*, /api/classrooms*, /api/students*, and /api/parents* traffic on legacy.

Use deploy/gateway/routes.analytics-read-native-example.json for Compose or deploy/gateway/routes.analytics-read-native-localhost-example.json for local go run rehearsal. The non-default table rewrites only:

• GET /api/analytics/results to /v1/analytics/results.
• GET /api/analytics/weak-topics to /v1/analytics/weak-topics.

Both routes require gateway auth, global ADMIN/TEACHER role checks, and an organization id. Snapshot/event writes, exam/classroom/student/parent analytics, classroom export, and all broad analytics/exam/classroom/student/ parent route families remain legacy-proxied until the missing adapters are explicit.

Rollback:

• Keep /api/analytics*, /api/students*, /api/parents*, /api/exams/*/results, /api/exams/*/analytics, /api/classrooms/*/analytics, and /api/classrooms/*/report/export routed to legacy.
• Disable gateway callers for /v1/analytics*.
• Drop analytics-service local tables with the migration down step if local test data must be reset.

Non-goals for P9-002:

• Public gateway cutover.
• Parent progress full parity.
• Classroom report export.
• Course mastery/recommendation.
• Direct joins to exam, attempt, question-bank, user, classroom, notification, or school service databases.