fix financial and certificates

2026-06-05 01:51:08 -04:00
parent d28d11e2e5
commit ad968eaff7
94 changed files with 9654 additions and 214 deletions
@@ -0,0 +1,764 @@
+# 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.