Phase 4: Assessments

Phase 4 delivers the assessment lifecycle, score entry (including offline sync), and the scoring aggregation service.

Purpose

Manage the full assessment workflow from creation through scoring to closure. Includes the calculateWeightedScore service that aggregates scores across assessment types with configured weights.

Key Models

Model	Purpose
Assessment	Graded activity with lifecycle: DRAFT -> OPEN -> CLOSED -> ARCHIVED
AssessmentScore	One score per (assessment, student) pair
AssessmentAuditLog	Append-only log of every score change

Assessment Lifecycle

• DRAFT -> OPEN: Requires documentS3Key to be set.
• OPEN -> CLOSED: No prerequisite. Scores become read-only.
• No backward transitions allowed.

Offline Score Sync

The POST /api/admin/assessments/[id]/sync-scores endpoint handles offline batch sync:

1. Client sends { entries: [{ studentId, score, clientTimestamp }] }
2. For each entry, server compares timestamps
3. If server score is newer (server.enteredAt > clientTimestamp): reject with audit log
4. Otherwise: accept and upsert
5. Returns 207 { accepted: [...], rejected: [...] }

Scoring Service

calculateWeightedScore(classId, studentId, academicPeriodId) computes the weighted total:

1. Fetch closed assessments for the class/period where recordsForResult = true
2. Group scores by assessment type
3. For each type: (avgScore / totalMarks) * 100 * (weight / 100)
4. Sum to get weighted total

API Endpoints

Method	Path	Purpose
GET/POST	/api/admin/assessments	List / create assessments
GET/PATCH/DELETE	/api/admin/assessments/[id]	Assessment CRUD + status transitions
POST	/api/admin/assessments/[id]/document	Upload document (presigned URL)
POST	/api/admin/assessments/[id]/marking-scheme	Upload marking scheme
POST	/api/admin/assessments/[id]/rubric	Upload rubric
GET	/api/admin/assessments/[id]/scores	List all scores
PUT	/api/admin/assessments/[id]/scores/[studentId]	Enter/update single score
POST	/api/admin/assessments/[id]/sync-scores	Offline batch sync

Key Files

• src/lib/services/scoring.ts -- calculateWeightedScore
• src/app/admin/assessments/ -- Assessment management and score entry UI