fix apply the plan docs/alrahma_api_fix_plan_school_year_only_v7

2026-07-07 01:52:29 -04:00
parent 58726ee0e9
commit 031e499819
35 changed files with 5633 additions and 182 deletions
@@ -45,7 +45,7 @@ class ClassProgressControllerTest extends TestCase
        $this->assertCount(2, $response->json('data.items'));
    }

-    public function test_admin_grouped_index_accepts_school_year_id_and_includes_legacy_rows(): void
+    public function test_admin_grouped_index_uses_school_year_name_and_includes_legacy_rows(): void
    {
        $admin = $this->createUser('admin@example.com');
        $this->assignRole($admin->id, 'administrator');
@@ -54,8 +54,9 @@ class ClassProgressControllerTest extends TestCase
            'semester' => '',
            'school_year' => null,
        ]);
-        $schoolYearId = DB::table('school_years')->insertGetId([
+        DB::table('school_years')->updateOrInsert([
            'name' => '2025-2026',
+        ], [
            'start_date' => '2025-08-01',
            'end_date' => '2026-07-31',
            'status' => 'active',
@@ -74,21 +75,30 @@ class ClassProgressControllerTest extends TestCase

        Sanctum::actingAs($admin);

-        $response = $this->getJson('/api/v1/class-progress?school_year_id='.$schoolYearId.'&group_by_week=1');
+        $response = $this->getJson('/api/v1/class-progress?school_year=2025-2026&group_by_week=1');

        $response->assertOk();
        $response->assertJsonPath('status', true);
        $this->assertCount(1, $response->json('data.items'));

-        $administratorAlias = $this->getJson('/api/v1/administrator/progress?school_year_id='.$schoolYearId.'&group_by_week=1');
+        $administratorAlias = $this->getJson('/api/v1/administrator/progress?school_year=2025-2026&group_by_week=1');
        $administratorAlias->assertOk();
        $this->assertCount(1, $administratorAlias->json('data.items'));

-        $adminAlias = $this->getJson('/api/v1/admin/progress?school_year_id='.$schoolYearId.'&group_by_week=1');
+        $adminAlias = $this->getJson('/api/v1/admin/progress?school_year=2025-2026&group_by_week=1');
        $adminAlias->assertOk();
        $this->assertCount(1, $adminAlias->json('data.items'));
    }

+    public function test_index_rejects_school_year_id_context(): void
+    {
+        $user = $this->createUser();
+        Sanctum::actingAs($user);
+
+        $this->getJson('/api/v1/class-progress?school_year_id=1')
+            ->assertStatus(422);
+    }
+
    public function test_parent_progress_returns_reports_for_enrolled_sections(): void
    {
        $parent = $this->createUser('parent@example.com');
@@ -196,6 +206,7 @@ class ClassProgressControllerTest extends TestCase
            'unit_islamic' => ['Unit 1'],
            'chapter_islamic' => ['Chapter A'],
            'flags' => ['needs_support'],
+            'school_year' => '2025-2026',
        ];

        $response = $this->postJson('/api/v1/class-progress', $payload);
@@ -246,6 +257,7 @@ class ClassProgressControllerTest extends TestCase

        $response = $this->patchJson('/api/v1/class-progress/'.$report->id, [
            'status' => 'behind',
+            'school_year' => '2025-2026',
        ]);

        $response->assertOk();
@@ -266,7 +278,7 @@ class ClassProgressControllerTest extends TestCase

        Sanctum::actingAs($user);

-        $response = $this->deleteJson('/api/v1/class-progress/'.$report->id);
+        $response = $this->deleteJson('/api/v1/class-progress/'.$report->id.'?school_year=2025-2026');

        $response->assertOk();
        $this->assertDatabaseMissing('class_progress_reports', [
@@ -328,6 +340,17 @@ class ClassProgressControllerTest extends TestCase

    private function seedClassSection(): void
    {
+        DB::table('school_years')->updateOrInsert([
+            'name' => '2025-2026',
+        ], [
+            'start_date' => '2025-08-01',
+            'end_date' => '2026-07-31',
+            'status' => 'active',
+            'is_current' => 1,
+            'created_at' => now(),
+            'updated_at' => now(),
+        ]);
+
        DB::table('classSection')->insert([
            'id' => 1,
            'class_id' => 1,
@@ -118,6 +118,15 @@ class FamilyAdminControllerTest extends TestCase

    private function seedUser(int $id): User
    {
+        $roleId = DB::table('roles')->insertGetId([
+            'name' => 'admin',
+            'slug' => 'admin',
+            'priority' => 1,
+            'is_active' => 1,
+            'created_at' => now(),
+            'updated_at' => now(),
+        ]);
+
        DB::table('users')->insert([
            'id' => $id,
            'firstname' => 'Parent',
@@ -134,6 +143,13 @@ class FamilyAdminControllerTest extends TestCase
            'semester' => 'Fall',
            'school_year' => '2025-2026',
            'status' => 'Active',
+            'is_verified' => 1,
+            'is_suspended' => 0,
+        ]);
+
+        DB::table('user_roles')->insert([
+            'user_id' => $id,
+            'role_id' => $roleId,
        ]);

        return User::query()->findOrFail($id);
@@ -219,6 +235,7 @@ class FamilyAdminControllerTest extends TestCase
            'total_amount' => 100,
            'paid_amount' => 0,
            'balance' => 100,
+            'school_year' => '2025-2026',
            'issue_date' => now()->toDateString(),
            'due_date' => now()->addDays(10)->toDateString(),
            'created_at' => now(),
@@ -238,6 +255,7 @@ class FamilyAdminControllerTest extends TestCase
            'payment_method' => 'cash',
            'payment_date' => now()->toDateString(),
            'status' => 'completed',
+            'school_year' => '2025-2026',
            'created_at' => now(),
            'updated_at' => now(),
        ]);
@@ -0,0 +1,199 @@
+<?php
+
+namespace Tests\Feature\Api\V1\ParentProfiles;
+
+use App\Models\User;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Illuminate\Support\Facades\DB;
+use Laravel\Sanctum\Sanctum;
+use Tests\TestCase;
+
+class ParentProfileAdminControllerTest extends TestCase
+{
+    use RefreshDatabase;
+
+    public function test_parent_profiles_index_requires_admin(): void
+    {
+        Sanctum::actingAs($this->createUser('teacher'));
+
+        $this->getJson('/api/v1/parent-profiles?school_year=2025-2026')
+            ->assertForbidden();
+    }
+
+    public function test_parent_profiles_rejects_school_year_id_context(): void
+    {
+        Sanctum::actingAs($this->createUser('admin'));
+
+        $this->getJson('/api/v1/parent-profiles?school_year_id=1')
+            ->assertStatus(422);
+    }
+
+    public function test_parent_profiles_index_lists_only_selected_year_relevant_parents(): void
+    {
+        Sanctum::actingAs($this->createUser('admin'));
+        $selectedParent = $this->createUser('parent', 'selected@example.com');
+        $otherParent = $this->createUser('parent', 'other@example.com');
+        $this->createStudentFamily($selectedParent->id, 'Amina', 'Selected', '2025-2026');
+        $this->createStudentFamily($otherParent->id, 'Omar', 'Other', '2024-2025');
+
+        $response = $this->getJson('/api/v1/parent-profiles?school_year=2025-2026');
+
+        $response->assertOk();
+        $this->assertSame(['selected@example.com'], array_column($response->json('data.parents'), 'email'));
+    }
+
+    public function test_parent_profile_show_returns_selected_year_siblings_and_finance_only(): void
+    {
+        Sanctum::actingAs($this->createUser('admin'));
+        $parent = $this->createUser('parent', 'parent@example.com');
+        $this->createStudentFamily($parent->id, 'Amina', 'Sibling', '2025-2026');
+        $this->createStudentFamily($parent->id, 'Yusuf', 'Sibling', '2025-2026');
+        $this->createStudentFamily($parent->id, 'Old', 'Student', '2024-2025');
+
+        $selectedInvoice = DB::table('invoices')->insertGetId([
+            'parent_id' => $parent->id,
+            'invoice_number' => 'INV-2025',
+            'status' => 'open',
+            'total_amount' => 100,
+            'paid_amount' => 25,
+            'balance' => 75,
+            'school_year' => '2025-2026',
+            'issue_date' => now()->toDateString(),
+            'due_date' => now()->addDays(5)->toDateString(),
+            'created_at' => now(),
+            'updated_at' => now(),
+        ]);
+        DB::table('invoices')->insert([
+            'parent_id' => $parent->id,
+            'invoice_number' => 'INV-2024',
+            'status' => 'open',
+            'total_amount' => 80,
+            'paid_amount' => 0,
+            'balance' => 80,
+            'school_year' => '2024-2025',
+            'issue_date' => now()->subYear()->toDateString(),
+            'due_date' => now()->subYear()->addDays(5)->toDateString(),
+            'created_at' => now(),
+            'updated_at' => now(),
+        ]);
+        DB::table('payments')->insert([
+            'parent_id' => $parent->id,
+            'invoice_id' => $selectedInvoice,
+            'total_amount' => 100,
+            'paid_amount' => 25,
+            'balance' => 75,
+            'number_of_installments' => 1,
+            'payment_method' => 'cash',
+            'payment_date' => now()->toDateString(),
+            'status' => 'completed',
+            'school_year' => '2024-2025',
+            'created_at' => now(),
+            'updated_at' => now(),
+        ]);
+        DB::table('emergency_contacts')->insert([
+            'parent_id' => $parent->id,
+            'emergency_contact_name' => 'Emergency One',
+            'relation' => 'uncle',
+            'cellphone' => '5555555555',
+            'semester' => 'Fall',
+            'school_year' => '2025-2026',
+            'created_at' => now(),
+            'updated_at' => now(),
+        ]);
+
+        $response = $this->getJson('/api/v1/parent-profiles/'.$parent->id.'?school_year=2025-2026');
+
+        $response->assertOk();
+        $this->assertSame(['Amina', 'Yusuf'], array_column($response->json('data.students'), 'firstname'));
+        $this->assertSame(['INV-2025'], array_column($response->json('data.invoices'), 'invoice_number'));
+        $this->assertEquals(75.0, $response->json('data.finance_summary.positive_unpaid_balance'));
+        $this->assertCount(1, $response->json('data.payments'));
+        $this->assertCount(1, $response->json('data.emergency_contacts'));
+    }
+
+    private function createUser(string $roleName, ?string $email = null): User
+    {
+        DB::table('school_years')->updateOrInsert(
+            ['name' => '2025-2026'],
+            [
+                'start_date' => '2025-09-01',
+                'end_date' => '2026-06-30',
+                'status' => 'active',
+                'is_current' => 1,
+                'updated_at' => now(),
+                'created_at' => now(),
+            ],
+        );
+
+        $roleId = DB::table('roles')->insertGetId([
+            'name' => $roleName,
+            'priority' => 1,
+            'is_active' => 1,
+        ]);
+
+        $user = User::query()->create([
+            'firstname' => ucfirst($roleName),
+            'lastname' => 'User',
+            'email' => $email ?? ($roleName.uniqid().'@example.com'),
+            'cellphone' => '5555555555',
+            'address_street' => '123 Main',
+            'city' => 'City',
+            'state' => 'ST',
+            'zip' => '12345',
+            'accept_school_policy' => 1,
+            'status' => 'Active',
+            'is_verified' => 1,
+            'is_suspended' => 0,
+            'password' => bcrypt('secret'),
+            'semester' => 'Fall',
+            'school_year' => '2025-2026',
+        ]);
+
+        DB::table('user_roles')->insert([
+            'user_id' => $user->id,
+            'role_id' => $roleId,
+        ]);
+
+        return $user;
+    }
+
+    private function createStudentFamily(int $parentId, string $firstname, string $lastname, string $schoolYear): void
+    {
+        $familyId = DB::table('families')->insertGetId([
+            'family_code' => uniqid('fam_', true),
+            'household_name' => $lastname.' Household',
+            'is_active' => 1,
+            'created_at' => now(),
+            'updated_at' => now(),
+        ]);
+
+        $studentId = DB::table('students')->insertGetId([
+            'firstname' => $firstname,
+            'lastname' => $lastname,
+            'is_active' => 1,
+            'parent_id' => $parentId,
+            'school_year' => $schoolYear,
+            'created_at' => now(),
+            'updated_at' => now(),
+        ]);
+
+        DB::table('family_guardians')->insert([
+            'family_id' => $familyId,
+            'user_id' => $parentId,
+            'relation' => 'parent',
+            'is_primary' => 1,
+            'receive_emails' => 1,
+            'receive_sms' => 0,
+            'created_at' => now(),
+            'updated_at' => now(),
+        ]);
+
+        DB::table('family_students')->insert([
+            'family_id' => $familyId,
+            'student_id' => $studentId,
+            'is_primary_home' => 1,
+            'created_at' => now(),
+            'updated_at' => now(),
+        ]);
+    }
+}
@@ -41,6 +41,33 @@ class SchoolYearControllerTest extends TestCase
        $this->assertSame('promote', $response->json('data.promotion_preview.rows.0.promotion_action'));
    }

+    public function test_name_based_school_year_management_routes_use_school_year_query(): void
+    {
+        $this->seedClosureData();
+
+        $this->actingAs(User::query()->findOrFail(1), 'api');
+
+        $this->getJson('/api/v1/school-years/summary?school_year=2025-2026')
+            ->assertOk()
+            ->assertJsonPath('data.school_year.name', '2025-2026');
+
+        $this->getJson('/api/v1/school-years/promotion-preview?school_year=2025-2026&to_school_year=2026-2027')
+            ->assertOk()
+            ->assertJsonPath('data.current_school_year', '2025-2026')
+            ->assertJsonPath('data.target_school_year', '2026-2027');
+
+        $this->postJson('/api/v1/school-years/preview-close?school_year=2025-2026', [
+            'new_school_year' => [
+                'name' => '2026-2027',
+                'start_date' => '2026-09-01',
+                'end_date' => '2027-06-30',
+            ],
+            'transfer_unpaid_balances' => true,
+        ])->assertOk()
+            ->assertJsonPath('data.school_year.name', '2025-2026')
+            ->assertJsonPath('data.parent_balances.summary.total_old_unpaid_balance', 200);
+    }
+
    public function test_preview_close_excludes_zero_invoice_balance_parent_even_when_parent_account_is_stale(): void
    {
        $this->seedClosureData();
@@ -73,6 +100,146 @@ class SchoolYearControllerTest extends TestCase
        );
    }

+    public function test_positive_balance_is_not_hidden_by_credit_balance(): void
+    {
+        $this->seedClosureData();
+
+        DB::table('invoices')->insert([
+            'id' => 502,
+            'parent_id' => 10,
+            'invoice_number' => 'INV-502-CREDIT',
+            'total_amount' => 0,
+            'balance' => -200,
+            'paid_amount' => 200,
+            'has_discount' => 0,
+            'issue_date' => '2026-05-11',
+            'due_date' => '2026-06-10',
+            'status' => 'credit',
+            'description' => 'Credit balance',
+            'school_year' => '2025-2026',
+            'created_at' => now(),
+            'updated_at' => now(),
+            'updated_by' => 1,
+            'semester' => 'Fall',
+        ]);
+
+        $this->actingAs(User::query()->findOrFail(1), 'api');
+
+        $response = $this->postJson('/api/v1/school-years/preview-close?school_year=2025-2026', [
+            'new_school_year' => [
+                'name' => '2026-2027',
+                'start_date' => '2026-09-01',
+                'end_date' => '2027-06-30',
+            ],
+            'transfer_unpaid_balances' => true,
+        ]);
+
+        $response->assertOk()
+            ->assertJsonPath('data.parent_balances.summary.parents_with_positive_balance', 1)
+            ->assertJsonPath('data.parent_balances.summary.total_positive_unpaid_balance', 200)
+            ->assertJsonPath('data.parent_balances.summary.parents_with_credit_balance', 1)
+            ->assertJsonPath('data.parent_balances.summary.total_credit_balance', 200)
+            ->assertJsonPath('data.parent_balances.summary.net_balance_impact', 0);
+
+        $row = collect($response->json('data.parent_balances.rows'))
+            ->first(fn (array $row): bool => (int) $row['parent_id'] === 10);
+
+        $this->assertSame(200.0, (float) $row['positive_unpaid_balance']);
+        $this->assertSame(200.0, (float) $row['credit_balance']);
+        $this->assertSame(0.0, (float) $row['net_balance']);
+        $this->assertSame(200.0, (float) $row['amount_to_transfer']);
+        $this->assertSame([500], $row['positive_invoice_ids']);
+        $this->assertSame([502], $row['credit_invoice_ids']);
+    }
+
+    public function test_credit_only_parent_is_reported_as_credit_not_unpaid_carryover(): void
+    {
+        $this->seedClosureData();
+        $this->seedParent(12, 'Credit', 'Only', 'credit@example.com');
+
+        DB::table('invoices')->insert([
+            'id' => 503,
+            'parent_id' => 12,
+            'invoice_number' => 'INV-503-CREDIT',
+            'total_amount' => 0,
+            'balance' => -50,
+            'paid_amount' => 50,
+            'has_discount' => 0,
+            'issue_date' => '2026-05-11',
+            'due_date' => '2026-06-10',
+            'status' => 'credit',
+            'description' => 'Credit only',
+            'school_year' => '2025-2026',
+            'created_at' => now(),
+            'updated_at' => now(),
+            'updated_by' => 1,
+            'semester' => 'Fall',
+        ]);
+
+        $this->actingAs(User::query()->findOrFail(1), 'api');
+
+        $response = $this->getJson('/api/v1/school-years/parent-balances?school_year=2025-2026&to_school_year=2026-2027');
+
+        $response->assertOk()
+            ->assertJsonPath('data.summary.parents_with_positive_balance', 1)
+            ->assertJsonPath('data.summary.parents_with_credit_balance', 1)
+            ->assertJsonPath('data.summary.total_positive_unpaid_balance', 200)
+            ->assertJsonPath('data.summary.total_credit_balance', 50);
+
+        $creditRow = collect($response->json('data.rows'))
+            ->first(fn (array $row): bool => (int) $row['parent_id'] === 12);
+
+        $this->assertNotNull($creditRow);
+        $this->assertSame(0.0, (float) $creditRow['positive_unpaid_balance']);
+        $this->assertSame(50.0, (float) $creditRow['credit_balance']);
+        $this->assertSame(0.0, (float) $creditRow['amount_to_transfer']);
+        $this->assertSame([503], $creditRow['credit_invoice_ids']);
+    }
+
+    public function test_pending_or_draft_invoice_blocks_close_but_is_not_transferred(): void
+    {
+        $this->seedClosureData();
+
+        DB::table('invoices')->insert([
+            'id' => 504,
+            'parent_id' => 10,
+            'invoice_number' => 'INV-504-DRAFT',
+            'total_amount' => 100,
+            'balance' => 100,
+            'paid_amount' => 0,
+            'has_discount' => 0,
+            'issue_date' => '2026-05-11',
+            'due_date' => '2026-06-10',
+            'status' => 'draft',
+            'description' => 'Draft invoice',
+            'school_year' => '2025-2026',
+            'created_at' => now(),
+            'updated_at' => now(),
+            'updated_by' => 1,
+            'semester' => 'Fall',
+        ]);
+
+        $this->actingAs(User::query()->findOrFail(1), 'api');
+
+        $response = $this->postJson('/api/v1/school-years/preview-close?school_year=2025-2026', [
+            'new_school_year' => [
+                'name' => '2026-2027',
+                'start_date' => '2026-09-01',
+                'end_date' => '2027-06-30',
+            ],
+            'transfer_unpaid_balances' => true,
+        ]);
+
+        $response->assertOk()
+            ->assertJsonPath('data.validation.can_close', false)
+            ->assertJsonPath('data.parent_balances.summary.total_positive_unpaid_balance', 200);
+
+        $this->assertStringContainsString(
+            'invoices are still in draft status',
+            implode(' ', $response->json('data.validation.errors'))
+        );
+    }
+
    public function test_close_school_year_does_not_transfer_zero_invoice_balance_parent_even_when_parent_account_is_stale(): void
    {
        $this->seedClosureData();
@@ -111,6 +278,79 @@ class SchoolYearControllerTest extends TestCase
        ]);
    }

+    public function test_close_does_not_mutate_old_year_parent_account(): void
+    {
+        $this->seedClosureData();
+
+        DB::table('parent_accounts')->insert([
+            'parent_id' => 10,
+            'school_year' => '2025-2026',
+            'opening_balance' => 55,
+            'current_balance' => 77,
+            'created_at' => now(),
+            'updated_at' => now(),
+        ]);
+
+        $this->actingAs(User::query()->findOrFail(1), 'api');
+
+        $this->postJson('/api/v1/school-years/close?school_year=2025-2026', [
+            'new_school_year' => [
+                'name' => '2026-2027',
+                'start_date' => '2026-09-01',
+                'end_date' => '2027-06-30',
+            ],
+            'transfer_unpaid_balances' => true,
+            'confirmation' => 'CLOSE 2025-2026',
+        ])->assertOk();
+
+        $this->assertDatabaseHas('parent_accounts', [
+            'parent_id' => 10,
+            'school_year' => '2025-2026',
+            'opening_balance' => 55,
+            'current_balance' => 77,
+        ]);
+
+        $this->assertDatabaseHas('parent_accounts', [
+            'parent_id' => 10,
+            'school_year' => '2026-2027',
+            'opening_balance' => 200,
+            'current_balance' => 200,
+        ]);
+    }
+
+    public function test_existing_balance_transfer_conflict_is_visible_in_preview_and_blocks_close(): void
+    {
+        $this->seedClosureData();
+
+        DB::table('parent_balance_transfers')->insert([
+            'parent_id' => 10,
+            'from_school_year' => '2025-2026',
+            'to_school_year' => '2026-2027',
+            'amount' => 200,
+            'status' => 'transferred',
+            'source_summary_json' => json_encode(['source_invoice_ids' => [500]]),
+            'created_by' => 1,
+            'created_at' => now(),
+            'updated_at' => now(),
+        ]);
+
+        $this->actingAs(User::query()->findOrFail(1), 'api');
+
+        $response = $this->postJson('/api/v1/school-years/preview-close?school_year=2025-2026', [
+            'new_school_year' => [
+                'name' => '2026-2027',
+                'start_date' => '2026-09-01',
+                'end_date' => '2027-06-30',
+            ],
+            'transfer_unpaid_balances' => true,
+        ]);
+
+        $response->assertOk()
+            ->assertJsonPath('data.validation.can_close', false)
+            ->assertJsonPath('data.parent_balances.summary.existing_transfer_conflicts', 1)
+            ->assertJsonPath('data.parent_balances.rows.0.existing_transfer_conflict', true);
+    }
+
    public function test_parent_cannot_close_school_year(): void
    {
        $this->seedClosureData();
@@ -231,6 +471,41 @@ class SchoolYearControllerTest extends TestCase
        ]);
    }

+    public function test_admin_can_update_school_year_by_name_via_api(): void
+    {
+        $this->seedClosureData();
+        DB::table('school_years')->insert([
+            'id' => 2,
+            'name' => '2027-2028',
+            'start_date' => '2027-09-01',
+            'end_date' => '2028-06-30',
+            'status' => 'draft',
+            'is_current' => 0,
+            'created_at' => now(),
+            'updated_at' => now(),
+        ]);
+
+        $this->actingAs(User::query()->findOrFail(1), 'api');
+
+        $response = $this->patchJson('/api/v1/school-years/selected?school_year=2027-2028', [
+            'name' => '2028-2029',
+            'start_date' => '2028-09-01',
+            'end_date' => '2029-06-30',
+            'school_year' => '2027-2028',
+        ]);
+
+        $response->assertOk()
+            ->assertJsonPath('data.name', '2028-2029')
+            ->assertJsonPath('data.start_date', '2028-09-01');
+
+        $this->assertDatabaseHas('school_years', [
+            'id' => 2,
+            'name' => '2028-2029',
+            'start_date' => '2028-09-01 00:00:00',
+            'end_date' => '2029-06-30 00:00:00',
+        ]);
+    }
+
    public function test_close_school_year_creates_new_active_year_enrollment_and_balance_transfer(): void
    {
        $this->seedClosureData();
@@ -379,6 +654,35 @@ class SchoolYearControllerTest extends TestCase
        ]);
    }

+    private function seedParent(int $id, string $firstname, string $lastname, string $email): void
+    {
+        DB::table('users')->insert([
+            'id' => $id,
+            'school_id' => $id,
+            'firstname' => $firstname,
+            'lastname' => $lastname,
+            'cellphone' => '5555555555',
+            'email' => $email,
+            'address_street' => '123 Main',
+            'city' => 'City',
+            'state' => 'ST',
+            'zip' => '12345',
+            'accept_school_policy' => 1,
+            'is_verified' => 1,
+            'status' => 'Active',
+            'is_suspended' => 0,
+            'failed_attempts' => 0,
+            'password' => bcrypt('secret'),
+            'semester' => 'Fall',
+            'school_year' => '2025-2026',
+        ]);
+
+        DB::table('user_roles')->insert([
+            'user_id' => $id,
+            'role_id' => 2,
+        ]);
+    }
+
    private function seedClosureData(): void
    {
        DB::table('configuration')->insert([
@@ -99,7 +99,7 @@ class StaffControllerTest extends TestCase
            'school_year' => '2025-2026',
        ]);

-        $response = $this->patchJson('/api/v1/staff/'.$staff->id, [
+        $response = $this->patchJson('/api/v1/staff/'.$staff->id.'?school_year=2025-2026', [
            'firstname' => 'Updated',
        ]);

@@ -127,7 +127,7 @@ class StaffControllerTest extends TestCase
            'school_year' => '2025-2026',
        ]);

-        $response = $this->deleteJson('/api/v1/staff/'.$staff->id);
+        $response = $this->deleteJson('/api/v1/staff/'.$staff->id.'?school_year=2025-2026');

        $response->assertOk();
        $this->assertDatabaseMissing('staff', [
@@ -137,6 +137,18 @@ class StaffControllerTest extends TestCase

    private function createUser(string $roleName, ?string $email = null): User
    {
+        DB::table('school_years')->updateOrInsert(
+            ['name' => '2025-2026'],
+            [
+                'start_date' => '2025-09-01',
+                'end_date' => '2026-06-30',
+                'status' => 'active',
+                'is_current' => 1,
+                'updated_at' => now(),
+                'created_at' => now(),
+            ],
+        );
+
        $roleId = DB::table('roles')->insertGetId([
            'name' => $roleName,
            'priority' => 1,
@@ -154,6 +166,8 @@ class StaffControllerTest extends TestCase
            'zip' => '12345',
            'accept_school_policy' => 1,
            'status' => 'Active',
+            'is_verified' => 1,
+            'is_suspended' => 0,
            'password' => bcrypt('secret'),
            'semester' => 'Fall',
            'school_year' => '2025-2026',
@@ -20,6 +20,7 @@ class FamilyFinanceServiceTest extends TestCase
            'total_amount' => 100,
            'paid_amount' => 20,
            'balance' => 80,
+            'school_year' => '2025-2026',
            'issue_date' => now()->toDateString(),
            'due_date' => now()->addDays(5)->toDateString(),
            'created_at' => now(),
@@ -36,16 +37,90 @@ class FamilyFinanceServiceTest extends TestCase
            'payment_method' => 'cash',
            'payment_date' => now()->toDateString(),
            'status' => 'completed',
+            'school_year' => '2024-2025',
            'created_at' => now(),
            'updated_at' => now(),
        ]);

        $service = new FamilyFinanceService;
-        $result = $service->loadFinancialsForParents([1]);
+        $result = $service->loadFinancialsForParents([1], '2025-2026');

        $this->assertSame(1, $result['summary']['invoices_count']);
        $this->assertSame(100.0, $result['summary']['total_amount']);
+        $this->assertSame(80.0, $result['summary']['positive_unpaid_balance']);
+        $this->assertSame(0.0, $result['summary']['credit_balance']);
        $this->assertNotEmpty($result['invoices']);
        $this->assertNotEmpty($result['payments']);
    }
+
+    public function test_load_financials_filters_invoices_and_payments_by_selected_year(): void
+    {
+        DB::table('invoices')->insert([
+            [
+                'id' => 10,
+                'parent_id' => 1,
+                'invoice_number' => 'INV-2025',
+                'status' => 'open',
+                'total_amount' => 100,
+                'paid_amount' => 0,
+                'balance' => 100,
+                'school_year' => '2025-2026',
+                'issue_date' => now()->toDateString(),
+                'due_date' => now()->addDays(5)->toDateString(),
+                'created_at' => now(),
+                'updated_at' => now(),
+            ],
+            [
+                'id' => 11,
+                'parent_id' => 1,
+                'invoice_number' => 'INV-2024',
+                'status' => 'open',
+                'total_amount' => 75,
+                'paid_amount' => 0,
+                'balance' => -25,
+                'school_year' => '2024-2025',
+                'issue_date' => now()->subYear()->toDateString(),
+                'due_date' => now()->subYear()->addDays(5)->toDateString(),
+                'created_at' => now(),
+                'updated_at' => now(),
+            ],
+        ]);
+
+        DB::table('payments')->insert([
+            [
+                'parent_id' => 1,
+                'invoice_id' => 10,
+                'total_amount' => 100,
+                'paid_amount' => 50,
+                'balance' => 50,
+                'number_of_installments' => 1,
+                'payment_method' => 'cash',
+                'payment_date' => now()->toDateString(),
+                'status' => 'completed',
+                'school_year' => '2025-2026',
+                'created_at' => now(),
+                'updated_at' => now(),
+            ],
+            [
+                'parent_id' => 1,
+                'invoice_id' => 11,
+                'total_amount' => 75,
+                'paid_amount' => 75,
+                'balance' => -25,
+                'number_of_installments' => 1,
+                'payment_method' => 'cash',
+                'payment_date' => now()->subYear()->toDateString(),
+                'status' => 'completed',
+                'school_year' => '2025-2026',
+                'created_at' => now(),
+                'updated_at' => now(),
+            ],
+        ]);
+
+        $service = new FamilyFinanceService;
+        $result = $service->loadFinancialsForParents([1], '2025-2026');
+
+        $this->assertSame(['INV-2025'], array_column($result['invoices'], 'invoice_number'));
+        $this->assertSame([10], array_column($result['payments'], 'invoice_id'));
+    }
 }
@@ -7,6 +7,7 @@ use App\Models\User;
 use App\Services\Staff\StaffCommandService;
 use App\Services\System\GlobalConfigService;
 use Illuminate\Foundation\Testing\RefreshDatabase;
+use Illuminate\Support\Facades\DB;
 use Tests\TestCase;

 class StaffCommandServiceTest extends TestCase
@@ -15,6 +16,7 @@ class StaffCommandServiceTest extends TestCase

    public function test_create_requires_user(): void
    {
+        $this->seedRole('teacher');
        $service = new StaffCommandService(new GlobalConfigService);

        $this->expectException(\RuntimeException::class);
@@ -28,6 +30,7 @@ class StaffCommandServiceTest extends TestCase

    public function test_create_with_user_id(): void
    {
+        $this->seedRole('teacher');
        $user = User::query()->create([
            'firstname' => 'Test',
            'lastname' => 'User',
@@ -57,4 +60,18 @@ class StaffCommandServiceTest extends TestCase
        $this->assertInstanceOf(Staff::class, $staff);
        $this->assertSame($user->id, $staff->user_id);
    }
+
+    private function seedRole(string $name): void
+    {
+        DB::table('roles')->updateOrInsert(
+            ['name' => $name],
+            [
+                'slug' => $name,
+                'priority' => 1,
+                'is_active' => 1,
+                'created_at' => now(),
+                'updated_at' => now(),
+            ]
+        );
+    }
 }