apply the school year concept

app/Controllers/Administrator/SchoolYearClosingController.php

@@ -12,9 +12,12 @@ class SchoolYearClosingController extends BaseController
     {
         try {
             $targetId = $this->normalizeInt($this->request->getGet('target_school_year_id'));
+            $preview = service('schoolYearClosing')->preview($id, $targetId);
+            $promotionTable = $this->promotionTablePayload($preview['promotion']['rows'] ?? []);
 
             return view('school_years/closing_preview', [
-                'preview' => service('schoolYearClosing')->preview($id, $targetId),
+                'preview' => $preview,
+                'promotionTable' => $promotionTable,
                 'latestBatch' => service('schoolYearClosing')->latestBatch($id),
                 'schoolYears' => (new SchoolYearModel())->orderBy('name', 'DESC')->findAll(),
             ]);
@@ -32,7 +35,7 @@ class SchoolYearClosingController extends BaseController
             }
 
             service('schoolYearClosing')->start($id, $targetId, $this->userId());
-            return redirect()->to('/administrator/school-years/' . $id . '/closing/preview')->with('success', 'Closing started.');
+            return redirect()->to('/administrator/school-years/' . $id . '/closing/preview')->with('success', 'End-year process started.');
         } catch (Throwable $e) {
             return redirect()->back()->with('error', $e->getMessage());
         }
@@ -42,7 +45,7 @@ class SchoolYearClosingController extends BaseController
     {
         try {
             service('schoolYearClosing')->execute($id, $this->userId());
-            return redirect()->to('/administrator/school-years/' . $id . '/closing/preview')->with('success', 'Carry-forward batch executed.');
+            return redirect()->to('/administrator/school-years/' . $id . '/closing/preview')->with('success', 'Carry-forward confirmed.');
         } catch (Throwable $e) {
             return redirect()->back()->with('error', $e->getMessage());
         }
@@ -52,7 +55,7 @@ class SchoolYearClosingController extends BaseController
     {
         try {
             service('schoolYearClosing')->complete($id, $this->userId());
-            return redirect()->to('/administrator/school-years')->with('success', 'School year closed.');
+            return redirect()->to('/administrator/school-years')->with('success', 'School year ended and closed.');
         } catch (Throwable $e) {
             return redirect()->back()->with('error', $e->getMessage());
         }
@@ -62,7 +65,7 @@ class SchoolYearClosingController extends BaseController
     {
         try {
             service('schoolYearClosing')->cancel($id, $this->userId());
-            return redirect()->to('/administrator/school-years')->with('success', 'Closing cancelled.');
+            return redirect()->to('/administrator/school-years')->with('success', 'End-year process cancelled.');
         } catch (Throwable $e) {
             return redirect()->back()->with('error', $e->getMessage());
         }
@@ -73,6 +76,89 @@ class SchoolYearClosingController extends BaseController
         return is_numeric($value) && (int) $value > 0 ? (int) $value : null;
     }
 
+    private function promotionTablePayload(array $rows): array
+    {
+        $allowedSorts = ['student', 'school_id', 'class', 'year_score', 'decision', 'source', 'queue', 'target', 'status'];
+        $sort = (string) ($this->request->getGet('sort') ?? 'class');
+        $sort = in_array($sort, $allowedSorts, true) ? $sort : 'class';
+        $order = strtolower((string) ($this->request->getGet('order') ?? 'asc')) === 'desc' ? 'desc' : 'asc';
+        $page = max(1, (int) ($this->request->getGet('page') ?? 1));
+        $perPage = (int) ($this->request->getGet('per_page') ?? 25);
+        $allowedPerPage = [10, 25, 50, 100];
+        $perPage = in_array($perPage, $allowedPerPage, true) ? $perPage : 25;
+
+        usort($rows, function (array $a, array $b) use ($sort, $order): int {
+            $comparison = $this->comparePromotionRows($a, $b, $sort);
+            if ($comparison === 0 && $sort !== 'class') {
+                $comparison = $this->comparePromotionRows($a, $b, 'class');
+            }
+            if ($comparison === 0 && $sort !== 'student') {
+                $comparison = $this->comparePromotionRows($a, $b, 'student');
+            }
+            if ($comparison === 0) {
+                $comparison = ((int) ($a['student_id'] ?? 0)) <=> ((int) ($b['student_id'] ?? 0));
+            }
+
+            return $order === 'desc' ? -$comparison : $comparison;
+        });
+
+        $total = count($rows);
+        $pageCount = max(1, (int) ceil($total / $perPage));
+        $page = min($page, $pageCount);
+        $offset = ($page - 1) * $perPage;
+
+        return [
+            'rows' => array_slice($rows, $offset, $perPage),
+            'sort' => $sort,
+            'order' => $order,
+            'page' => $page,
+            'perPage' => $perPage,
+            'total' => $total,
+            'pageCount' => $pageCount,
+            'allowedPerPage' => $allowedPerPage,
+            'from' => $total === 0 ? 0 : $offset + 1,
+            'to' => min($offset + $perPage, $total),
+        ];
+    }
+
+    private function comparePromotionRows(array $a, array $b, string $sort): int
+    {
+        $aValue = $this->promotionSortValue($a, $sort);
+        $bValue = $this->promotionSortValue($b, $sort);
+
+        if ($sort === 'year_score') {
+            if ($aValue === null && $bValue === null) {
+                return 0;
+            }
+            if ($aValue === null) {
+                return 1;
+            }
+            if ($bValue === null) {
+                return -1;
+            }
+
+            return $aValue <=> $bValue;
+        }
+
+        return strnatcasecmp((string) $aValue, (string) $bValue);
+    }
+
+    private function promotionSortValue(array $row, string $sort): mixed
+    {
+        return match ($sort) {
+            'student' => (string) ($row['student_name'] ?? ''),
+            'school_id' => (string) ($row['school_id'] ?? ''),
+            'class' => (string) ($row['class_section_name'] ?? ''),
+            'year_score' => is_numeric($row['year_score'] ?? null) ? (float) $row['year_score'] : null,
+            'decision' => (string) ($row['decision'] ?? ''),
+            'source' => (string) ($row['source'] ?? ''),
+            'queue' => (string) ($row['queue_status'] ?? ''),
+            'target' => trim((string) ($row['target_section'] ?? '') . ' ' . (string) ($row['target_class'] ?? '')),
+            'status' => (string) ($row['status'] ?? ''),
+            default => '',
+        };
+    }
+
     private function userId(): ?int
     {
         $id = session('user_id') ?? session('id');

app/Controllers/Administrator/SchoolYearController.php

@@ -51,6 +51,8 @@ class SchoolYearController extends BaseController
             'closingYear' => $closingYear,
             'archivedCount' => $archivedCount,
             'latestTransitions' => service('schoolYearManagement')->latestTransitionByYear(),
+            'yearVerification' => $this->verificationByYear($schoolYears),
+            'schoolYearNamesById' => array_column($schoolYears, 'name', 'id'),
         ]);
     }
 
@@ -124,4 +126,91 @@ class SchoolYearController extends BaseController
 
         return is_numeric($id) ? (int) $id : null;
     }
+
+    private function verificationByYear(array $schoolYears): array
+    {
+        $db = db_connect();
+        $verification = [];
+
+        $hasStudentClass = $db->tableExists('student_class');
+        $hasStudentDecisions = $db->tableExists('student_decisions');
+        $hasPromotionQueue = $db->tableExists('promotion_queue');
+        $hasInvoices = $db->tableExists('invoices');
+        $hasClosingBatches = $db->tableExists('school_year_closing_batches');
+
+        foreach ($schoolYears as $year) {
+            $id = (int) ($year['id'] ?? 0);
+            $name = (string) ($year['name'] ?? '');
+            if ($id <= 0 || $name === '') {
+                continue;
+            }
+
+            $summary = [
+                'students' => 0,
+                'decisions' => 0,
+                'promoted' => 0,
+                'queued' => 0,
+                'carry_forward_balance' => 0.0,
+                'positive_balance' => 0.0,
+                'credit_balance' => 0.0,
+                'closing_status' => '',
+            ];
+
+            if ($hasStudentClass && $db->fieldExists('school_year', 'student_class')) {
+                $row = $db->table('student_class')
+                    ->select('COUNT(DISTINCT student_id) AS total', false)
+                    ->where('school_year', $name)
+                    ->get()
+                    ->getRowArray();
+                $summary['students'] = (int) ($row['total'] ?? 0);
+            }
+
+            if ($hasStudentDecisions && $db->fieldExists('school_year', 'student_decisions')) {
+                $row = $db->table('student_decisions')
+                    ->select('COUNT(DISTINCT student_id) AS decisions', false)
+                    ->select("COUNT(DISTINCT CASE WHEN LOWER(decision) = 'pass' THEN student_id END) AS promoted", false)
+                    ->where('school_year', $name)
+                    ->get()
+                    ->getRowArray();
+                $summary['decisions'] = (int) ($row['decisions'] ?? 0);
+                $summary['promoted'] = (int) ($row['promoted'] ?? 0);
+            }
+
+            if ($hasPromotionQueue && $db->fieldExists('school_year_from', 'promotion_queue')) {
+                $row = $db->table('promotion_queue')
+                    ->select('COUNT(DISTINCT student_id) AS total', false)
+                    ->where('school_year_from', $name)
+                    ->get()
+                    ->getRowArray();
+                $summary['queued'] = (int) ($row['total'] ?? 0);
+            }
+
+            if ($hasInvoices && $db->fieldExists('school_year', 'invoices')) {
+                $row = $db->table('invoices')
+                    ->select('COALESCE(SUM(balance), 0) AS carry_forward_balance')
+                    ->select('COALESCE(SUM(CASE WHEN balance > 0 THEN balance ELSE 0 END), 0) AS positive_balance', false)
+                    ->select('COALESCE(SUM(CASE WHEN balance < 0 THEN ABS(balance) ELSE 0 END), 0) AS credit_balance', false)
+                    ->where('school_year', $name)
+                    ->get()
+                    ->getRowArray();
+                $summary['carry_forward_balance'] = round((float) ($row['carry_forward_balance'] ?? 0), 2);
+                $summary['positive_balance'] = round((float) ($row['positive_balance'] ?? 0), 2);
+                $summary['credit_balance'] = round((float) ($row['credit_balance'] ?? 0), 2);
+            }
+
+            if ($hasClosingBatches) {
+                $batch = $db->table('school_year_closing_batches')
+                    ->select('status')
+                    ->where('source_school_year_id', $id)
+                    ->orderBy('id', 'DESC')
+                    ->get(1)
+                    ->getRowArray();
+                $summary['closing_status'] = (string) ($batch['status'] ?? '');
+            }
+
+            $verification[$id] = $summary;
+        }
+
+        return $verification;
+    }
 }