fix all issues before deploy

app/Services/EnrollmentTransitionService.php

@@ -62,7 +62,10 @@ final class EnrollmentTransitionService
             $this->addBlocker($evaluation, 'TARGET_YEAR_NOT_FOUND', 'Target school year configuration was not found.');
         }
 
-        if ($sourceSchoolYear === '' || $this->sourceAssignment($studentId, $sourceSchoolYear) === null) {
+        if (
+            empty($evaluation['first_enrollment'])
+            && ($sourceSchoolYear === '' || $this->sourceAssignment($studentId, $sourceSchoolYear) === null)
+        ) {
             $this->addBlocker($evaluation, 'SOURCE_YEAR_NOT_FOUND', 'Student does not belong to the closing school year.');
         }
 
@@ -77,7 +80,7 @@ final class EnrollmentTransitionService
             $this->addBlocker($evaluation, $code, 'Student has a target-year enrollment status that requires administration review.');
         }
 
-        $this->applyHouseholdLastNameRule($evaluation, $parentId);
+        $this->applyHouseholdLastNameRule($evaluation, $parentId, $sourceSchoolYear);
         $this->applyFinancialRule($evaluation, $parentId, $sourceSchoolYear, $targetSchoolYear);
         $this->applyCarriedForwardLastNameException($evaluation, $parentId, $studentId, $sourceSchoolYear, $targetSchoolYear);
         $this->deriveAcademicRuleCodes($evaluation);
@@ -250,6 +253,7 @@ final class EnrollmentTransitionService
         $decisionRow = $this->decisionRow($studentId, $sourceSchoolYear);
         $decision = DeliberationDecision::normalize($decisionRow['deliberation_decision_standard'] ?? null)
             ?? DeliberationDecision::normalize($decisionRow['decision'] ?? null);
+        $rawDecision = trim((string) ($decisionRow['deliberation_decision_standard'] ?? $decisionRow['decision'] ?? ''));
 
         $result = [
             'student_id' => $studentId,
@@ -312,6 +316,24 @@ final class EnrollmentTransitionService
         }
 
         if ($sourceAssignment === null) {
+            if ($this->isFirstEnrollmentStudent($studentId, $student, $targetSchoolYear)) {
+                $result = array_replace($result, $this->firstEnrollmentPlacement($student, $targetSchoolYear));
+                $result['first_enrollment'] = true;
+                $result['decision_label'] = 'New student registration';
+                $result['academic_eligible'] = true;
+                $result['parent_enrollment_allowed'] = true;
+                $result['student_self_enrollment_allowed'] = false;
+
+                $this->applyRegistrationWindow($result, $targetYear, $now, $actorRole);
+                $this->applyAgeRules($result, $targetSchoolYear, $age);
+
+                if ($result['blockers'] !== [] && $actorRole === 'parent') {
+                    $result['parent_enrollment_allowed'] = false;
+                }
+
+                return $result;
+            }
+
             $result['blockers'][] = 'Student does not belong to the closing school year.';
             return $result;
         }
@@ -322,7 +344,18 @@ final class EnrollmentTransitionService
             return $result;
         }
 
-        if ($decisionRow === null || $decision === null) {
+        if (($decisionRow === null || $decision === null) && $sourceAssignment !== null) {
+            $kgDecision = $this->decisionForKgWithoutFinalDecision($sourceAssignment, $age, $rawDecision);
+            if ($kgDecision !== null) {
+                $decision = $kgDecision;
+                $result['deliberation_decision'] = $decision;
+                $result['decision_label'] = 'KG age placement';
+                $result['kg_missing_decision_eligible'] = true;
+                $result['warnings'][] = EnrollmentEligibility::KG_MISSING_DECISION_ELIGIBLE_MESSAGE;
+            }
+        }
+
+        if ($decision === null) {
             $result['blockers'][] = EnrollmentEligibility::MISSING_DECISION_MESSAGE;
             $result['flags'][] = $this->flag('DEFERRED_DELIBERATION', 'high', [
                 'rule_code' => $decisionRow === null ? 'NO_FINAL_DECISION' : 'UNRECOGNIZED_DECISION',
@@ -472,20 +505,12 @@ final class EnrollmentTransitionService
                 }
             }
 
-            $flags = [];
-            if ($targetSection === null) {
-                $flags[] = $this->flag('CLASS_REASSIGNMENT_REQUIRED', 'normal', [
-                    'previous_class_section_name' => $sourceSectionName,
-                    'previous_class_section_id' => $sourceSectionId > 0 ? $sourceSectionId : null,
-                ]);
-            }
-
             return [
                 'assigned_grade_id' => $targetSection['class_id'] ?? $this->sameClassInTargetYear($sourceClassName, $targetSchoolYear)['id'] ?? ($sourceClassId ?: null),
                 'assigned_grade_name' => $this->classNameForId((int) ($targetSection['class_id'] ?? 0)) ?? $sourceClassName,
                 'assigned_class_section_id' => $targetSection['class_section_id'] ?? null,
                 'placement_status' => $targetSection === null ? 'manual_class_required' : 'same_class_assigned',
-                'flags' => $flags,
+                'flags' => [],
             ];
         }
 
@@ -509,6 +534,17 @@ final class EnrollmentTransitionService
         return ['assigned_grade_id' => null, 'assigned_class_section_id' => null, 'placement_status' => 'not_created', 'flags' => []];
     }
 
+    private function decisionForKgWithoutFinalDecision(array $sourceAssignment, ?int $age, string $rawDecision): ?string
+    {
+        if ($rawDecision !== '' || $this->classBaseName((string) ($sourceAssignment['class_name'] ?? $sourceAssignment['class_section_name'] ?? '')) !== 'KG') {
+            return null;
+        }
+
+        return $age !== null && $age >= 6
+            ? DeliberationDecision::PASSED
+            : DeliberationDecision::REPEAT_CLASS;
+    }
+
     private function applyRegistrationWindow(array &$result, ?array $targetYear, DateTimeImmutable $now, string $actorRole): void
     {
         if ($targetYear === null) {
@@ -638,14 +674,42 @@ final class EnrollmentTransitionService
 
     private function student(int $studentId): ?array
     {
+        $select = ['id', 'firstname', 'lastname', 'dob', 'parent_id', 'registration_grade'];
+        if ($this->db->fieldExists('school_year', 'students')) {
+            $select[] = 'school_year';
+        }
+
         return $this->db->table('students')
-            ->select('id, firstname, lastname, dob, parent_id')
+            ->select(implode(', ', $select))
             ->where('id', $studentId)
             ->limit(1)
             ->get()
             ->getRowArray() ?: null;
     }
 
+    private function isFirstEnrollmentStudent(int $studentId, array $student, string $targetSchoolYear): bool
+    {
+        if ($studentId <= 0 || $targetSchoolYear === '') {
+            return false;
+        }
+
+        if ($this->db->tableExists('student_year_status')) {
+            $row = $this->db->table('student_year_status')
+                ->select('is_new')
+                ->where('student_id', $studentId)
+                ->where('school_year', $targetSchoolYear)
+                ->limit(1)
+                ->get()
+                ->getRowArray();
+
+            if (is_array($row)) {
+                return (int) ($row['is_new'] ?? 1) === 1;
+            }
+        }
+
+        return trim((string) ($student['school_year'] ?? '')) === $targetSchoolYear;
+    }
+
     private function schoolYearByName(string $schoolYear): ?array
     {
         if (! $this->db->tableExists('school_years')) {
@@ -730,6 +794,42 @@ final class EnrollmentTransitionService
             ->getRowArray() ?: null;
     }
 
+    private function firstEnrollmentPlacement(array $student, string $targetSchoolYear): array
+    {
+        $grade = $this->classBaseName((string) ($student['registration_grade'] ?? ''));
+        $targetClass = $grade !== '' ? $this->classByName($grade, $targetSchoolYear) : null;
+        $targetSection = is_array($targetClass)
+            ? $this->baseSectionForClass((int) ($targetClass['id'] ?? 0), $targetSchoolYear)
+            : null;
+
+        return [
+            'assigned_grade_id' => $targetClass['id'] ?? null,
+            'assigned_grade_name' => $targetClass['class_name'] ?? ($grade !== '' ? $grade : null),
+            'assigned_class_section_id' => $targetSection['class_section_id'] ?? null,
+            'placement_status' => $targetSection === null ? 'manual_class_required' : 'same_class_assigned',
+            'flags' => [],
+        ];
+    }
+
+    private function baseSectionForClass(int $classId, string $targetSchoolYear): ?array
+    {
+        if ($classId <= 0 || ! $this->db->tableExists('classSection')) {
+            return null;
+        }
+
+        $builder = $this->db->table('classSection')
+            ->select('class_section_id, class_id, class_section_name')
+            ->where('class_id', $classId)
+            ->where("class_section_name NOT LIKE '%-%'", null, false)
+            ->orderBy('id', 'ASC');
+
+        if ($this->db->fieldExists('school_year', 'classSection')) {
+            $builder->where('school_year', $targetSchoolYear);
+        }
+
+        return $builder->limit(1)->get()->getRowArray() ?: null;
+    }
+
     private function classNameForId(int $classId): ?string
     {
         if ($classId <= 0 || ! $this->db->tableExists('classes')) {
@@ -1033,6 +1133,7 @@ final class EnrollmentTransitionService
         $written += $this->syncSiblingLastNameFlags($students, $enrolledIds, $bypassCodesByStudent, $targetSchoolYear, $sourceSchoolYear, $performedBy);
         $written += $this->syncFinancialFlags($students, $enrolledIds, $bypassCodesByStudent, $targetSchoolYear, $sourceSchoolYear, $performedBy);
         $written += $this->syncRepeatClassReassignmentFlags($targetSchoolYear, $sourceSchoolYear, $performedBy);
+        $this->retireClassReassignmentFlags($targetSchoolYear);
         $this->retireClassCapacityExceptionFlags($targetSchoolYear);
 
         return $written;
@@ -1063,7 +1164,7 @@ final class EnrollmentTransitionService
         }
 
         $flagType = (string) ($flag['flag_type'] ?? '');
-        if ($flagType === '' || $flagType === 'CLASS_CAPACITY_EXCEPTION_REQUIRED') {
+        if ($flagType === '' || in_array($flagType, ['CLASS_CAPACITY_EXCEPTION_REQUIRED', 'CLASS_REASSIGNMENT_REQUIRED'], true)) {
             return false;
         }
 
@@ -1113,6 +1214,26 @@ final class EnrollmentTransitionService
             ]);
     }
 
+    private function retireClassReassignmentFlags(string $targetSchoolYear): void
+    {
+        if (! $this->db->tableExists('enrollment_flags')) {
+            return;
+        }
+
+        $builder = $this->db->table('enrollment_flags')
+            ->where('flag_type', 'CLASS_REASSIGNMENT_REQUIRED')
+            ->where('status', 'open');
+        if ($targetSchoolYear !== '') {
+            $builder->where('school_year', $targetSchoolYear);
+        }
+
+        $builder->update([
+            'status' => 'resolved',
+            'resolved_at' => date('Y-m-d H:i:s'),
+            'resolution_notes' => 'Class reassignment flags are no longer used for registration emails.',
+        ]);
+    }
+
     private function retireClassCapacityExceptionFlags(string $targetSchoolYear): void
     {
         if (! $this->db->tableExists('enrollment_flags')) {
@@ -1886,9 +2007,22 @@ final class EnrollmentTransitionService
             || EnrollmentEligibility::isMarkedWithdrawn($enrollment);
     }
 
-    private function applyHouseholdLastNameRule(array &$evaluation, int $parentId): void
+    private function applyHouseholdLastNameRule(array &$evaluation, int $parentId, ?string $sourceSchoolYear = null): void
     {
+        if (! empty($evaluation['first_enrollment'])) {
+            $evaluation['family_name_check_ok'] = true;
+            return;
+        }
+
         $students = $this->linkedStudentsForParent($parentId);
+        $sourceSchoolYear = trim((string) $sourceSchoolYear);
+        if ($sourceSchoolYear !== '') {
+            $students = array_values(array_filter(
+                $students,
+                fn (array $student): bool => $this->sourceAssignment((int) ($student['id'] ?? 0), $sourceSchoolYear) !== null
+            ));
+        }
+
         if (count($students) <= 1) {
             $evaluation['family_name_check_ok'] = true;
             return;