feat: enhance agent management and validation logic

- Updated AGENTS.md to clarify agent account restrictions and permissions.
- Implemented checks in AgentNodeAdminUserStoreController and AgentNodeRoleStoreController to restrict admin user and role creation to the agent's own node.
- Enhanced validation in AdminPlayerStoreController and AdminPlayerUpdateController to enforce credit limit and rebate rate rules based on player funding mode.
- Refactored various request classes to utilize shared admin account field rules for consistency.
- Improved error handling in services related to credit allocation and rebate limits to ensure proper validation and messaging.

tests/Feature/AgentSettlementFinancialConsistencyTest.php

@@ -16,6 +16,7 @@ uses(RefreshDatabase::class);
 
 beforeEach(function (): void {
     $this->artisan('lottery:admin-auth-sync')->assertExitCode(0);
+    ensureRootAgentProfileSeeded();
 });
 
 test('record payment rejects bill that is not confirmed', function (): void {
@@ -59,6 +60,47 @@ test('record payment rejects bill that is not confirmed', function (): void {
     expect(DB::table('payment_records')->where('settlement_bill_id', $billId)->exists())->toBeFalse();
 });
 
+test('record payment rejects amount above unpaid balance', function (): void {
+    $siteId = (int) DB::table('admin_sites')->where('is_default', true)->value('id');
+    $periodId = (int) DB::table('settlement_periods')->insertGetId([
+        'admin_site_id' => $siteId,
+        'period_start' => now()->subWeek(),
+        'period_end' => now(),
+        'status' => 'closed',
+        'created_at' => now(),
+        'updated_at' => now(),
+    ]);
+
+    $billId = (int) DB::table('settlement_bills')->insertGetId([
+        'settlement_period_id' => $periodId,
+        'bill_type' => 'player',
+        'owner_type' => 'player',
+        'owner_id' => 1,
+        'counterparty_type' => 'agent',
+        'counterparty_id' => 1,
+        'net_amount' => 500,
+        'unpaid_amount' => 500,
+        'paid_amount' => 0,
+        'status' => 'confirmed',
+        'created_at' => now(),
+        'updated_at' => now(),
+    ]);
+
+    $admin = AdminUser::query()->create([
+        'username' => 'pay_over_super',
+        'name' => 'PayOver',
+        'email' => null,
+        'password' => Hash::make('secret-strong'),
+        'status' => 0,
+    ]);
+    grantSuperAdminRole($admin);
+
+    expect(fn () => app(SettlementPaymentService::class)->recordPayment($billId, 600, (int) $admin->id))
+        ->toThrow(ValidationException::class);
+
+    expect(DB::table('payment_records')->where('settlement_bill_id', $billId)->exists())->toBeFalse();
+});
+
 test('settlement reports scope player win loss to agent subtree', function (): void {
     $siteId = (int) DB::table('admin_sites')->where('is_default', true)->value('id');
     $siteCode = (string) DB::table('admin_sites')->where('id', $siteId)->value('code');