feat(analytics): add GET /analytics/puzzles/:id/stats route, PuzzleAn…

[sublime247]

Closes #531

Description

Adds the GET /analytics/puzzles/:id/stats controller route to expose detailed single-puzzle statistics (total attempts, successful vs failed attempts, success rate percentage, average time spent, and unique users). Implements PuzzleAnalyticsProvider, validates query parameters with DateRangeDto, restricts access with AnalyticsAdminGuard, and provides full end-to-end (e2e) test coverage.

Key Changes

• Response DTOs & Export Metric:
  • Added PuzzleStatsResult response class to analytics-metric-result.dto.ts.
  • Added PUZZLE_STATS = 'puzzle_stats' to ExportMetric in analytics-query.dto.ts.
• Analytics Provider:
  • Implemented PuzzleAnalyticsProvider in puzzle-analytics.provider.ts (re-exported via puzzle-analytics.entity.ts).
  • Queries AnalyticsEvent repository for puzzle_attempted and first_puzzle_attempted events filtered by :id and date range window.
• Controller Route & Module:
  • Exposed GET /analytics/puzzles/:id/stats in AnalyticsController guarded by AnalyticsAdminGuard and annotated with Swagger metadata.
  • Registered PuzzleAnalyticsProvider in AnalyticsModule.
• Testing:
  • Created unit tests in puzzle-analytics.provider.spec.ts.
  • Added describe('GET /analytics/puzzles/:id/stats (e2e)') test suite to backend/test/analytics.e2e-spec.ts.

Acceptance Criteria Checklist

• GET /analytics/puzzles/:id/stats returns 200 OK with the documented response shape for admin callers.
• Invalid query parameters return 400 Bad Request with clear validation error messages.
• Route requires an authenticated admin role via AnalyticsAdminGuard (returns 403 otherwise).
• Route is fully covered by e2e tests in backend/test/analytics.e2e-spec.ts.

Verification & Testing Performed

Unit Tests (10/10 Passed)

npx jest src/analytics/providers/puzzle-analytics.provider.spec.ts src/analytics/providers/export-csv.provider.spec.ts

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
mind-block-app-frontend	Skipped		Jul 25, 2026 7:46am

[sublime247]

@A6dulmalik kindly review

@phertyameen