# Assessments Module

## Purpose
Assessments are the core testing/evaluation mechanism. They serve multiple purposes: exams, competitions, trainings, homework, assignments, and self-training. The `Assessment` model is polymorphic — its behavior changes based on the `type` and `scope` fields.

## Business Context
Assessments drive the learning evaluation process:
- **Exams** — Formal evaluations created by teachers for their students
- **Competitions** — Events where students from multiple programs/teachers compete
- **Marathon-Competitions** — Competitions within a marathon event
- **Trainings** — Practice sessions before competitions
- **Self-Training** — Student-initiated practice
- **Homework/Assignments/Group-* — Group-specific tasks

## Key Model — Assessment (`app/Models/Assessment.php`)

### Fields
- `type` (enum): `exam`, `homework`, `assignment`, `competition`, `training`, `group-exam`, `group-homework`, `group-assignment`, `self-training`, `marathon-competition`, `child-training`
- `scope` (enum): `user`, `team`, `teacher`, `program`, `system`
- `timing` (enum): `assessment`, `problems` — determines display mode
- `status` (enum): `pending`, `approved`, `rejected`
- `marathon_id` — Links to Marathon (for competition/marathon-competition types)
- `parent` — Self-referencing parent for child assessments
- `team_id` — Links to Team (for group assessments)
- `level_classification` — Links to LevelClassification
- `title`, `description`, `purpose` (json, translatable)
- `starts_at`, `ends_at`, `duration_minutes`
- `is_locked` (boolean), `show_result` (boolean), `passing_score`
- `payment_required`, `enrollment_mode` — For competitions
- `update_count` — Tracks problem edit count (used for `no_of_edits_*` features)

### Relationships
- `program()` → BelongsTo Program
- `teacher()` / `creator()` → BelongsTo User
- `marathon()` → BelongsTo Marathon
- `team()` → BelongsTo Team
- `levelClassification()` → BelongsTo LevelClassification
- `parentAssessment()` → BelongsTo Assessment (parent)
- `childAssessments()` → HasMany Assessment (children)
- `problems()` → HasMany AssessmentProblems
- `assessmentAttempts()` → HasMany AssessmentAttempt
- `myAssessmentAttempts()` → HasMany (scoped to auth user)
- `participations()` → MorphMany EventParticipation (for competition types)
- `eligibilities()` → MorphMany EventEligibility
- `pathSteps()` → HasMany TeamPathStep
- `joinRequests()` → HasMany AssessmentJoinRequest

### Lifecycle
- **Created:** Consumes feature usage based on type (via observer), dispatches `assessment.created`, checks per-marathon competition limit
- **Updated:** Syncs scope/level_classification to child assessments, dispatches `assessment.updated`
- **Deleted:** Releases feature usage (via observer)

## Related Models

### AssessmentProblems (`app/Models/AssessmentProblems.php`)
- Stores individual problems for each assessment
- Each problem includes: strategy, operations, number types, values, and answer

### AssessmentAttempt (`app/Models/AssessmentAttempt.php`)
- Tracks student attempts on assessments
- Has fields: `user_id`, `assessment_id`, `score`, `total`, `status`, `started_at`, `completed_at`
- **Feature:** Self-training attempts consume `no_of_attempts_per_self_training`

### AssessmentAttemptAnswer (`app/Models/AssessmentAttemptAnswer.php`)
- Stores individual answers for each problem in an attempt

### AssessmentJoinRequest (`app/Models/AssessmentJoinRequest.php`)
- Legacy join request model (being migrated to participation system)

## Participation Integration

For competition-type assessments (scope: system/program), the **participation system** manages teacher sign-up, eligibility, seat allocation, student enrollment, and payments.

See [Participation System](participation.md) for full details.

## Feature Entitlement

| Feature | Scope | Default Limit | Assessment Types |
|---------|-------|---------------|------------------|
| `no_of_competitions` | Teacher | 3 | competition, marathon-competition |
| `no_of_exams` | Teacher | 10 | exam |
| `no_of_trainings` | Teacher | 10 | training |
| `no_of_available_self_training` | Student | 10 | self-training |
| `no_of_attempts_per_self_training` | Student | 3 | self-training attempts |
| `no_of_allowed_homework_group` | Teacher | 10 | group-homework |
| `no_of_allowed_assignment_group` | Teacher | 10 | group-assignment |
| `no_of_allowed_exams_group` | Teacher | 5 | group-exam |
| `no_of_competition_per_marathon` | Program | 5 | competitions within marathon |
| `no_of_edits_competition_problems` | Teacher | 3 | competition problem edits |
| `no_of_edits_exam_problems` | Teacher | 3 | exam problem edits |
| `no_of_edits_training_problems` | Teacher | 3 | training problem edits |

## Assessment Types (from config/ucmas.php)
- **Strategies:** d, 5, 10, d_5, d_10, 5_10, d_5_10 (for mental math problems)
- **Operation Types:** add_sub, multiplication, division, percentage, root, power
- **Number Types:** integer, decimal
- **Division Types:** complete, with_remainder, decimal
- **Percentage Types:** complete, decimal, r_complete, r_decimal
- **Root Types:** complete, decimal

## Livewire Components
- `ChildAssessments` — Lists child assessments
- `AttemptAnswersTable` — Displays attempt answers

## Filament Resources
- `AssessmentResource` — CRUD for assessments (Program panel)
- `CompetitionResource` — CRUD for competitions

## Mental Math Timer
- A real-time assessment timer (`app/Filament/Pages/MentalMathTimer.php`)
- Routes: `/mental-math-timer`, `/assessments/attempts/save-problem`, `/assessments/attempts/finish-attempt`
- Generates problems, tracks timing, auto-submits on timeout

## Related Workflows
- **[Assessment Lifecycle Workflow](../WORKFLOWS.md#4-assessment-lifecycle-workflow)** — End-to-end assessment creation, problem management, and student attempts
- **[Participation Workflow (Shared)](../WORKFLOWS.md#6-participation-workflow-shared)** — For competition-type assessments requiring teacher sign-up and student enrollment