Amaresh taking over for Linh - Student Evaluation Results Backend APIs

[linh2020]

Description

This PR adds backend support for the Student Viewing Evaluation Results feature by implementing secure API endpoints for students to view their evaluation data and check for new results. It introduces reusable calculation logic for performance metrics, dynamic score aggregation, and notification tracking to enable students to access their academic progress seamlessly.

These APIs provide structured data for:

Overall evaluation summary (scores, performance levels, submission stats)
Category-wise breakdown of results
Detailed task-level results with submission status
Notification state for new/unread evaluation results
This work enables the frontend to consume consistent, server-side calculated evaluation insights instead of duplicating logic in the UI, ensuring secure access and real-time updates.

Implements:
(PHASE 4 - Backend Tasks-Student Viewing Evaluation Results)

Related PRs (if any):

Main Changes Explained

Main Changes Explained

• Added new models: Created studentEvaluation.js and evaluationTask.js for storing evaluation categories and task details, with proper schemas, indexes, and validation.
• Enhanced existing models: Updated notification.js to include type and metadata fields for evaluation-specific notifications, plus a new index for efficient querying. Modified userProfile.js to add lastEvaluationResultsViewedAt in the student education profile for tracking viewed timestamps.
• Added new service: Implemented studentEvaluationResultsService.js with reusable utilities for calculating performance colors, aggregating scores/stats (e.g., on-time/late submissions), validating students, and managing notifications.
• Updated routes: Modified educatorRouter.js to add the /evaluation-results/publish POST endpoint. Created studentEvaluationResultsRouter.js for the new GET endpoints (/student/evaluation-results and /student/evaluation-results/notifications). Registered the new router in startup/routes.js.
• Added testing and utilities: Included unit tests (educatorController.spec.js, studentEvaluationResultsController.spec.js, studentEvaluationResultsService.spec.js),
• Database logic: Ensured secure student identity validation, dynamic calculation of average scores and submission stats, and performance color mapping for visual indicators. On publishing, inserts/updates evaluation data and creates notification records.

How to Test

Check out this branch: linh_student_eval_clean
Run: npm install, npm run dev (or equivalent backend start command)
Clear site data/cache if needed.
Example checks:
• Publish Results (Educator): POST /api/educator/evaluation-results/publish → Returns 201 with published categories
• Get Evaluation Results (Student): GET /api/student/evaluation-results → Returns summary, categories, and task results
• Check Notifications (Student): GET /api/student/evaluation-results/notifications → Returns hasNewResults, unreadCount, etc.

Note:

[sonarqubecloud]

Quality Gate passed

Issues
2 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[pixelpix13]

Reviewed and tested locally on branch linh_student_eval_clean against hgnData_dev using npm run dev on port 4500.

Unit Tests

• studentEvaluationResultsController.spec.js — 5/5 passed
• studentEvaluationResultsService.spec.js — 4/4 passed

Manual API Flow

Verified:

• POST /api/educator/evaluation-results/publish returns 201, upserts categories/tasks, and creates an evaluation_results notification.
• GET /api/student/evaluation-results/notifications returns correct hasNewResults / unreadCount values before and after viewing results.
• GET /api/student/evaluation-results returns summary, categories, and task results with the expected weighted score 82.8 and submission stats.
• Viewing results marks evaluation results as viewed.
• Re-publishing updates the data and re-triggers notifications.

Auth / Validation Checks

Verified:

• 401 when no token is provided.
• 403 when a student attempts to publish results.
• 400 for invalid publish payload.
• 404 when no educationProfiles.student record exists.

What Looks Good

• Clear separation between models, service, controllers, and routes.
• Student endpoints are JWT-scoped and do not expose studentId in the URL.
• Publish flow correctly resets lastEvaluationResultsViewedAt and creates typed notifications.
• Weighted score aggregation and on-time/late submission logic work as expected.

Minor Notes

• PR description mentions educatorController.spec.js, but that file does not appear to be included in the diff. I only saw the student evaluation controller and service specs.
• Service tests mainly cover ObjectId sanitization; scoring and notification behavior are covered through manual testing but could benefit from unit-level coverage.
• educatorController.js has a large diff, so it may be worth a quick sanity check to confirm existing educator routes were not affected.

No blocking issues found from my testing.