# Strong Grading System Plan

## Purpose

This document defines a stronger grading-system plan for the Alrahma Sunday School API. It is intentionally a planning document, not an implementation patch.

The goal is to move the grading system from a functional calculator into a fair, explainable, auditable, backward-compatible, and policy-driven gradebook.

The current system already has a useful foundation: a centralized semester score service, separated score-entry flows, grading locks, and missing-score override tracking. However, the current scoring model still allows too much ambiguity around blank scores, missing work, validation, and finalization.

The strongest first move is not to redesign every formula. The strongest first move is to kill ambiguity while keeping old data readable and old calculations explainable.

---

## Core Principles

A strong grading system must be:

1. **Fair**  
   Missing work must not accidentally improve a student's grade.

2. **Explainable**  
   Every final score must be traceable to category scores, weights, attendance, exam score, and policy rules.

3. **Auditable**  
   Locked or finalized scores must preserve the exact inputs and formula used at the time.

4. **Policy-driven**  
   Grading policy should live in services, configuration, and grading profiles, not scattered controller logic.

5. **Safe**  
   Invalid scores must be rejected before they reach averages or semester calculations.

6. **Backward-compatible**  
   Old data must remain readable, displayable, and explainable under the legacy policy that created it.

7. **Additive, not destructive**  
   The new grading system must be introduced beside the old one first. Existing historical scores must not be silently recalculated, reclassified, hidden, or overwritten.

---

## Non-Negotiable Backward Compatibility Requirement

The system must preserve old data display.

Historical grades must remain visible exactly as they were calculated under the legacy system. The new strong grading system must not reinterpret old blanks, old averages, or old semester scores as if they were created under the new policy.

This is the hard rule:

```text
Old data must remain readable, displayable, and explainable exactly as it was calculated under the legacy system.
```

The new system must support two modes:

| Mode | Purpose | Formula Source | Data Behavior |
|---|---|---|---|
| Legacy display mode | Show old/historical grades | Existing stored semester values and legacy formula | Do not reinterpret blanks or statuses |
| Strong scoring mode | Calculate future grades under stronger rules | New scoring service/profile | Uses statuses, max points, snapshots, and finalization validation |

Legacy records must show stored values from the existing `semester_scores` table, such as:

```text
homework_avg
quiz_avg
project_avg
participation_score
attendance_score
ptap_score
midterm_exam_score
final_exam_score
semester_score
```

Legacy displays should include a visible label:

```text
Legacy Calculation
```

And a short explanation:

```text
This score was calculated under the legacy grading policy. Blank scores were ignored in category averages, PTAP used legacy dynamic weighting, attendance included one-absence grace, and the semester exam used the legacy 60% weighting.
```

This is not optional. Without this, the system risks showing old data through new rules and creating disputes that nobody can cleanly answer. Software should not gaslight the gradebook. Humans already do enough of that.

---

## Historical Data Protection Rules

Historical grades must not be automatically recalculated under the new scoring policy.

Rules:

1. Existing `semester_scores` rows stay in place.
2. Existing historical rows are marked as legacy.
3. Legacy rows are displayed from stored aggregate values.
4. Legacy rows are not forced into the new status model.
5. Legacy blanks are not automatically converted to `missing`.
6. Legacy scores are not recalculated unless an authorized admin explicitly starts a recalculation job.
7. If recalculation is ever allowed, the original legacy score must be preserved beside the new-policy result.

Recommended display if a historical record is later recalculated for comparison:

```text
legacy_semester_score: 91.4
new_policy_semester_score: 87.2
displayed_score: 91.4 unless admin explicitly chooses otherwise
```

The default behavior must protect the original displayed score.

---

## Recommended Compatibility Metadata

Do not replace the existing `semester_scores` table. Keep it.

Add nullable metadata columns:

```text
calculation_mode
calculation_policy_version
snapshot_id nullable
```

Suggested values:

```text
calculation_mode = legacy | strong
calculation_policy_version = legacy_v1 | strong_v1
```

Backfill existing rows as:

```text
calculation_mode = legacy
calculation_policy_version = legacy_v1
snapshot_id = null
```

New strong-system finalized rows should be saved with:

```text
calculation_mode = strong
calculation_policy_version = strong_v1
snapshot_id = related semester_score_snapshots row
```

This keeps old grade display stable while allowing new scores to become audit-proof.

---

## Display Resolver Requirement

Create a display resolver instead of forcing every grade display through the new scoring engine.

Recommended service:

```php
App\Services\Grading\GradeCalculationDisplayResolver
```

Responsibilities:

```text
If calculation_mode is legacy:
    Load and display existing semester_scores fields.
    Show Legacy Calculation badge.
    Do not apply new status or profile rules.

If calculation_mode is strong:
    Load snapshot and/or strong calculation breakdown.
    Show Strong Calculation badge.
    Display status-aware category breakdown.
```

The display layer must not recalculate legacy scores just to show them. It should show the stored values. Recalculating old scores on display is a terrible idea, and yet somehow tempting to developers who enjoy turning page loads into historical revisionism.

---

## Important Policy Clarification: Attendance Grace

The attendance grace rule is school policy.

The current formula effectively gives students one absence before attendance points are reduced:

```text
attendance_score = ((total_days + 1 - absences) / total_days) * 100
```

This is policy-compliant, but the formula hides the intent. It should be rewritten more explicitly:

```text
grace_absences = 1
effective_absences = max(0, absences - grace_absences)
attendance_score = ((total_days - effective_absences) / total_days) * 100
```

This keeps the same policy while making the rule clear. Future developers should not have to decode a `+1` and wonder whether it is a bug wearing a tiny policy hat.

---

## Phase 0: Lock the Grading Policy Before Writing Code

Before implementation, these policy decisions must be explicit.

| Question | Recommended Decision |
|---|---|
| Are old/historical grades still displayed? | Yes. Always. |
| Are old/historical grades recalculated automatically? | No. Never silently. |
| Are old blanks converted to missing? | No. Old blanks remain legacy behavior unless explicitly migrated by admin workflow. |
| Are scores always out of 100? | No. Add `max_points`, then normalize to percentages for strong scoring. |
| What does a blank score mean in the new system? | Nothing final. It means pending or unresolved. |
| Does missing work count as zero in the new system? | Yes, unless explicitly excused. |
| Does excused work affect the average? | No. Excused work is excluded from the denominator. |
| Can a class be locked with pending scores in the new system? | No. |
| Can a class be locked with missing work in the new system? | Yes, but missing work counts as zero unless excused. |
| Does attendance have one absence grace? | Yes. This is school policy. |
| Should final scores keep an audit trail? | Yes. Store a calculation snapshot when locking/finalizing new strong scores. |

These decisions are non-negotiable if the system needs to be defensible.

---

## Phase 1: Stabilize the Current Legacy System

Do not start with grading profiles. That is architecture candy. It looks mature, but it does not fix the most dangerous problem first.

The first goal is to stop bad data, protect current behavior with tests, and keep legacy grade display working.

### 1. Add Tests for Existing Legacy Formulas

Before changing calculation behavior, freeze the current formulas in tests.

Test coverage should include:

```text
homework average ignores blanks
quiz average ignores blanks
project average ignores blanks
participation missing returns null
PTAP with no quiz/project
PTAP with quiz only
PTAP with project only
PTAP with all categories
Fall semester formula
Spring semester formula
attendance with 0 absences = 100
attendance with 1 absence = 100
attendance with 2 absences = reduced score
legacy semester_scores display from stored values
legacy rows are not recalculated on display
```

This creates a safety net. Without it, every refactor becomes a guessing game with grades, which is exactly as bad as it sounds.

### 2. Add Central Score Validation

Create one central validator used by every score write path.

Validation rules:

```text
score may be null
score must be numeric when present
score must be >= 0
score must be <= max_points
max_points must be > 0
```

For the first pass, use `max_points = 100` by default.

Example service shape:

```php
final class ScoreValueValidator
{
    public function normalizeOrFail(mixed $value, float $maxPoints = 100.0): ?float
    {
        if ($value === null || (is_string($value) && trim($value) === '')) {
            return null;
        }

        if (!is_numeric($value)) {
            throw new InvalidArgumentException('Score must be numeric.');
        }

        $score = (float) $value;

        if ($score < 0 || $score > $maxPoints) {
            throw new InvalidArgumentException("Score must be between 0 and {$maxPoints}.");
        }

        return $score;
    }
}
```

Use this validator in all score-entry paths:

```text
HomeworkScoreService
QuizScoreService
ProjectScoreService
ParticipationScoreService
ExamScoreService
GradingScoreService
```

This should reject impossible new values without changing how existing historical rows are displayed.

### 3. Make Attendance Grace Explicit

Refactor the attendance calculation without changing its result.

Replace hidden arithmetic:

```text
(total_days + 1 - absences) / total_days
```

With named policy logic:

```text
grace_absences = 1
effective_absences = max(0, absences - grace_absences)
attendance_score = ((total_days - effective_absences) / total_days) * 100
```

Add tests:

| Total Days | Absences | Expected Attendance Score |
|---:|---:|---:|
| 10 | 0 | 100 |
| 10 | 1 | 100 |
| 10 | 2 | 90 |
| 10 | 10 | 10 |
| 10 | 11+ | 0 |

### 4. Add Legacy Display Badge

Before introducing strong scoring, make the UI able to label old records.

For legacy rows, show:

```text
Policy: Legacy Calculation
```

Example display:

```text
Semester Score: 91.4
Policy: Legacy Calculation
Attendance: 100.0
PTAP: 88.5
Midterm: 92.0

Note: This score was calculated under the legacy policy. Blank scores were ignored in averages.
```

This prevents users from assuming legacy and strong scores use the same rules.

---

## Phase 2: Make Missing Scores Explicit for New/Strong Scoring

This phase applies to the new strong scoring path. It must not automatically rewrite old historical records.

Right now, a blank score can mean too many things:

```text
not graded yet
student missing work
student excused
teacher forgot
assignment not applicable
```

A grading system cannot be fair if the data refuses to say what it means.

### 1. Add Score Statuses

Every new strong score-bearing record should have both a numeric score and a status.

Minimum statuses:

| Status | Meaning | Counts in Average? | Blocks Finalization? |
|---|---|---:|---:|
| `pending` | Teacher has not resolved the item | No | Yes |
| `scored` | Valid numeric score exists | Yes | No |
| `missing` | Student did not submit | Yes, as 0 | No |
| `excused` | Approved exclusion | No | No |
| `not_assigned` | Does not apply | No | No |

Recommended columns for homework, quiz, project, participation, midterm, and final tables:

```text
status
max_points
excused_reason
locked_at
locked_by
```

### 2. Migrate Existing Data Carefully

Do not blindly turn old blanks into missing work. That would punish students for old system ambiguity.

Initial migration mapping for active, not-yet-finalized records:

| Existing Data | Initial Status |
|---|---|
| Numeric score exists | `scored` |
| Blank/null score | `pending` |
| Missing override exists and is allowed | `excused` or `not_assigned`, depending policy meaning |

For historical finalized legacy records, do not require full status migration just to display them. Keep them as legacy display records.

After migration, teachers/admins must resolve pending items before final lock for strong-scoring sections.

---

## Phase 3: Change Calculation Semantics for Strong Scoring

Once statuses exist, strong category calculations should stop relying on blank/null behavior.

New score handling:

| Status | Calculation Behavior |
|---|---|
| `scored` | Include normalized score |
| `missing` | Include 0 |
| `excused` | Exclude from denominator |
| `not_assigned` | Exclude from denominator |
| `pending` | Block finalization |

Normalize every scored item:

```text
normalized_score = (raw_score / max_points) * 100
```

Then calculate the category average:

```text
category_average = average(all included normalized scores)
```

This prevents missing work from silently improving a student's grade.

Legacy records must still display legacy stored values. Do not apply this status-aware calculation to historical rows unless an admin explicitly opts into a recalculation workflow.

---

## Phase 4: Add Finalization Validation

Locking a strong-scoring class should not simply flip a flag. It should prove the gradebook is complete enough to finalize.

Create a validator service:

```php
App\Services\Grading\GradebookFinalizationValidator
```

It should validate:

```text
No pending required scores
All numeric scores are within range
Required categories are present
Required exam score exists
Required participation score exists
Attendance can be calculated
Missing items are either counted as zero or excused
Every student has a calculable final score
```

If validation fails, return a structured report:

```text
student
category
item
problem
required_action
```

Example:

```text
Student: Ahmed Ali
Category: Homework
Item: Homework #4
Problem: Pending score
Required action: Mark as scored, missing, excused, or not assigned before locking.
```

The lock button should become a gate, not a decorative suggestion.

Legacy historical records do not need to pass the new finalization validator just to be displayed.

---

## Phase 5: Add Calculation Snapshots for Strong Scores

When strong grades are finalized or locked, store exactly how the final score was produced.

Create table:

```text
semester_score_snapshots
```

Recommended fields:

```text
id
student_id
class_section_id
semester
school_year
grading_policy_version
input_json
calculation_json
semester_score
calculated_by
calculated_at
```

The snapshot should include:

```text
raw scores used
score statuses used
max points used
normalized scores
category averages
category weights
attendance grace policy
exam score
final formula
final score
```

This protects the school when someone disputes a grade later.

The current `semester_scores` table can show the latest aggregate. The snapshot proves what was true at finalization.

Legacy historical grades may have no snapshot. That is acceptable as long as they are clearly labeled `legacy_v1` and displayed from stored values.

---

## Phase 6: Replace Hardcoded PTAP With Grading Profiles

Only after validation, statuses, legacy display protection, and snapshots are in place should hardcoded weighting be replaced.

Current PTAP behavior changes based on data availability:

```text
No tests and no projects
Tests but no projects
Projects but no tests
All categories exist
```

That is flexible, but dangerous. It lets missing or unentered data affect the formula.

### Recommended Tables

```text
grading_profiles
```

Fields:

```text
id
name
school_year
semester
class_section_id nullable
is_default
version
created_by
created_at
updated_at
```

```text
grading_profile_categories
```

Fields:

```text
id
grading_profile_id
category_key
weight
required
redistribute_if_missing
```

### Example Profile

| Category | Weight | Required | Redistribute If Unused |
|---|---:|---:|---:|
| homework | 15 | Yes | No |
| quiz | 15 | Configurable | Yes |
| project | 15 | Configurable | Yes |
| participation | 15 | Yes | No |
| attendance | 10 | Yes | No |
| exam | 30 | Yes | No |

Important distinction:

```text
Category not used by profile -> redistribute its weight
Category assigned but scores pending -> block lock
Category assigned but student missing -> count as zero
Category excused -> exclude according to policy
```

Do not redistribute weight just because a teacher forgot to enter grades. That would be grading by accident, which is somehow worse than grading by spreadsheet.

Legacy rows continue using legacy PTAP display and must not be forced into grading profiles.

---

## Phase 7: Opt-In Activation Strategy

Strong scoring should be activated by class section, semester, and school year. It should not globally replace legacy behavior in one switch.

Recommended activation metadata:

```text
class_section_id
school_year
semester
calculation_mode = legacy | strong
grading_profile_id nullable
activated_by
activated_at
```

Activation rules:

1. Existing historical records remain `legacy`.
2. Current active sections may remain `legacy` until admins choose migration.
3. New future sections can default to `strong` once the system is ready.
4. A class section using `legacy` must continue calculating and displaying using the legacy service.
5. A class section using `strong` must use statuses, max points, finalization validation, and snapshots.
6. Switching a section from legacy to strong should require an admin confirmation and a preflight report.

Preflight report should show:

```text
number of numeric scores that will become scored
number of blanks that will become pending
number of overrides requiring review
students blocked from finalization until pending items are resolved
```

No quiet migrations. Quiet migrations are where data integrity goes to disappear.

---

## Phase 8: Refactor Controllers Last

Controllers should not contain grading policy.

Final desired flow:

```text
Controller receives request
Request validates input shape
Application service saves score/status
Scoring mode resolver selects legacy or strong path
Scoring service recalculates draft score
Finalization validator blocks or allows lock for strong mode
Snapshot service records locked strong calculation
Display resolver shows legacy or strong breakdown
```

Controllers should not know formulas. They should not decide whether missing counts. They should not know category redistribution rules.

Controllers are traffic cops, not education philosophers.

---

## Recommended Implementation Order

| Step | Work | Risk Reduced |
|---:|---|---|
| 1 | Add tests for current legacy formulas and legacy display | Prevent accidental formula/display drift |
| 2 | Add compatibility metadata to `semester_scores` | Preserve old records clearly |
| 3 | Add legacy/strong display resolver | Keep old data visible |
| 4 | Add central score validation | Stop impossible new scores |
| 5 | Make attendance grace explicit | Preserve policy and improve clarity |
| 6 | Add `max_points` columns | Enable normalization |
| 7 | Add `status` columns | Remove blank-score ambiguity for strong scoring |
| 8 | Build category calculator using statuses | Fix missing-score fairness |
| 9 | Add finalization validator | Stop invalid strong locks |
| 10 | Add calculation snapshots | Audit-proof locked strong grades |
| 11 | Add grading profiles | Remove hardcoded weights for strong mode |
| 12 | Add opt-in activation by class/semester | Prevent disruptive rollout |
| 13 | Refactor controllers | Clean architecture after behavior is safe |

---

## MVP Strong Upgrade

The smallest serious upgrade is:

```text
1. Keep current legacy formulas.
2. Keep old data display from stored semester_scores values.
3. Add calculation_mode and calculation_policy_version metadata.
4. Add legacy display badge.
5. Add central score validation for new writes.
6. Make attendance grace explicit without changing results.
7. Add score statuses for active/future strong-scoring sections.
8. Treat missing as zero, excused as excluded, and pending as blocking lock in strong mode only.
9. Add a lock validation report for strong mode.
10. Add calculation snapshots on strong-mode lock.
```

This improves fairness and auditability without breaking old records or immediately changing all weights.

After that, replace PTAP branching with grading profiles.

---

## Hard Safety Rules

1. Do not change formulas and database semantics in the same step without tests.
2. Do not silently recalculate historical scores.
3. Do not convert old blanks to missing for historical records.
4. Do not hide legacy data because it lacks new statuses.
5. Do not activate strong scoring globally without class/semester-level opt-in.
6. Do not display a strong-policy explanation for a legacy-policy score.
7. Do not let a lock action become the first time the system discovers incomplete data.

That is how a school ends up unable to explain whether grades changed because of policy, migration, code, or a null-handling goblin hiding in the service layer.

---

## Final Recommendation

Do not begin by building grading profiles.

Begin by making legacy display safe and every new score state explicit.

The strongest first milestone is:

```text
Old grades remain visible under Legacy Calculation, and future strong-mode grades cannot be locked until every score is classified as scored, missing, excused, pending, or not assigned.
```

Once that is true, the grading system becomes defensible. Until that is true, every formula is built on fog.
