# Implementation Plan: Tanzanian Standard Student Report Card Redesign

This plan outlines the redesign and high-fidelity implementation of the student report cards in the system to match the exact look and feel of the official Tanzanian O-Level Secondary School Report Card provided in the reference image.

Both the **HTML preview view** (`reports.show`) and the **PDF download view** (`reports.report_card_pdf`) will be completely overhauled with high-precision styles and layouts.

---

## Proposed Changes

### 1. View Layers

#### [MODIFY] [show.blade.php](file:///c:/xampp/htdocs/results/resources/views/reports/show.blade.php)
We will completely rewrite the web-based report card container to render a high-fidelity preview of the report card. It will use Tailwind CSS grids, borders, and custom CSS to match the image:
- **Header Section**:
  - Left: Official Coat of Arms of Tanzania (using a high-quality, stable SVG source from Wikimedia Commons).
  - Center: National ministry headings, school name (derived dynamically from the authenticated school's name), and the document title:
    - THE UNITED REPUBLIC OF TANZANIA
    - MINISTRY OF EDUCATION, SCIENCE AND TECHNOLOGY
    - SECONDARY SCHOOL REPORT CARD
    - ORDINARY LEVEL (O-LEVEL) (or fallback based on school category)
  - Right: School logo/crest (using school's logo attribute, falling back to a beautiful secondary school badge graphic if empty).
- **Section A. STUDENT INFORMATION & GRADING SYSTEM**:
  - **Left Sub-section**: List of 10 items (Student's Name, Index Number, School Name, School Code, District, Region, Date of Birth, Sex, Examination No., Examination Year) pulled dynamically. District and region will be extracted from the school's address or gracefully defaulted. Sex will be capitalized. Date of birth formatted as `dd/mm/yyyy`. Examination number dynamically formatted from student's registration number and exam year (e.g. `0234/2024`).
  - **Right Sub-section**: The official grading table (A=1/Excellent, B=2/Very Good, C=3/Good, D=4/Satisfactory, E=5/Sufficient, F=6/Fail) styled with sky-blue headers.
- **Section B. SUBJECT PERFORMANCE**:
  - Fully styled, high-fidelity table listing all subjects.
  - Generates serial numbers (`SN`), Subject Codes, Subject Names, Marks in Figures, **Marks in Words** (using a lightweight, self-contained PHP helper converting 0-100 values to text, e.g. "SEVENTY FIVE"), Grades, and Grade Points.
- **Section C. SUMMARY OF PERFORMANCE**:
  - Dynamically calculates the Number of Registered Subjects, Subjects Passed, Subjects Failed, Aggregate Points (sum of all subject grade points, e.g. 32), Average Point (aggregate divided by count, e.g. 2.67), NECTA Division (I, II, III, IV, or 0 based on Best 7 points), Position in School (e.g., "12 OUT OF 78"), and overall Remarks.
- **Section D. KEY TO SUBJECT CODES**:
  - Side-by-side key matching the exact layout of the reference image, splitting the student's subjects dynamically into two columns.
- **Footer Block**:
  - Head of school sign-off area with signature line, name, and date.
  - School stamp placeholder in the center.
  - Examination officer sign-off area on the right.
  - Validation warning at the absolute bottom: `NB: THIS REPORT CARD IS VALID WITHOUT ERASURES OR ALTERATIONS`.

#### [MODIFY] [report_card_pdf.blade.php](file:///c:/xampp/htdocs/results/resources/views/reports/report_card_pdf.blade.php)
We will completely rewrite the PDF layout to match the HTML layout exactly, utilizing nested `<table>` elements and custom inline/embedded CSS because DomPDF doesn't support CSS Flexbox or Grid.
- Traditional table layout columns (`width: 50%` or nested tables) to make sure everything fits beautifully onto a single, print-ready page.
- Same fonts and high-fidelity colors (`#dce6f1` sky blue accents, dark borders).
- Same embedded `numberToWords` helper.

---

## Core Helpers (Embedded in Blade Templates)

To keep the views clean, self-contained, and performant without bloating the backend controllers or adding heavy external dependencies, we will embed two lightweight helpers at the top of the templates:

1. **Number to Words Converter**:
   ```php
   function numberToWords($number) {
       $number = (int)$number;
       $words = [
           0 => 'ZERO', 1 => 'ONE', 2 => 'TWO', 3 => 'THREE', 4 => 'FOUR',
           5 => 'FIVE', 6 => 'SIX', 7 => 'SEVEN', 8 => 'EIGHT', 9 => 'NINE',
           10 => 'TEN', 11 => 'ELEVEN', 12 => 'TWELVE', 13 => 'THIRTEEN',
           14 => 'FOURTEEN', 15 => 'FIFTEEN', 16 => 'SIXTEEN', 17 => 'SEVENTEEN',
           18 => 'EIGHTEEN', 19 => 'NINETEEN', 20 => 'TWENTY', 30 => 'THIRTY',
           40 => 'FORTY', 50 => 'FIFTY', 60 => 'SIXTY', 70 => 'SEVENTY',
           80 => 'EIGHTY', 90 => 'NINETY', 100 => 'ONE HUNDRED'
       ];
       if ($number === 100) return 'ONE HUNDRED';
       if ($number <= 20) return $words[$number];
       $tens = (int)($number / 10) * 10;
       $ones = $number % 10;
       if ($ones > 0) return $words[$tens] . ' ' . $words[$ones];
       return $words[$tens];
   }
   ```

2. **School Address Parser (District & Region extraction)**:
   ```php
   // Splits school address by commas and extracts potential district and region, defaulting if unavailable
   $addressParts = array_map('trim', explode(',', $school->address ?? ''));
   $region = 'UNKNOWN';
   $district = 'UNKNOWN';
   if (count($addressParts) >= 2) {
       $region = strtoupper($addressParts[count($addressParts) - 2]);
       $district = count($addressParts) >= 3 ? strtoupper($addressParts[count($addressParts) - 3]) : $region;
   }
   ```

---

## Verification Plan

### Automated Verification
- We will open the browser subagent to visit the dashboard and reports page to generate a report card for a student, verify its design layout, and download/verify the PDF formatting.

### Manual Verification
- Verify that "MARKS IN WORDS" correctly says "SEVENTY FIVE" for 75, "EIGHTY" for 80, etc.
- Check that "KEY TO SUBJECT CODES" splits the list of subjects dynamically and displays code and names beautifully.
- Verify that Head of School, Examination Officer, and Stamp align perfectly.
- Ensure the total/average points match the exact math of the official Tanzanian O-Level report card.