feat: enhance agent settlement features and improve data access controls

- Added new section in AGENTS.md detailing learned workspace facts for better understanding of settlement processes.
- Updated AgentNodeDestroyController to remove unnecessary checks for admin users.
- Enhanced AgentSettlement controllers to assert permissions for finance adjustments and bill operations.
- Improved query scopes in AgentSettlement services to ensure proper data access based on admin roles.
- Refactored methods in SettlementPartyEnrichment for better bill row enrichment and data handling.
- Introduced new methods in AdminAgentSettlementScope for managing agent node visibility and finance adjustments.

tests/Feature/AgentSettlementListsApiTest.php

@@ -7,8 +7,25 @@ use Illuminate\Support\Facades\Hash;
 
 uses(RefreshDatabase::class);
 
+beforeEach(function (): void {
+    $this->artisan('lottery:admin-auth-sync')->assertExitCode(0);
+});
+
 test('settlement payments and adjustments index return items', function (): void {
     $siteId = (int) DB::table('admin_sites')->where('is_default', true)->value('id');
+    $rootId = (int) DB::table('agent_nodes')->where('admin_site_id', $siteId)->where('depth', 0)->value('id');
+    $playerId = (int) DB::table('players')->insertGetId([
+        'site_code' => (string) DB::table('admin_sites')->where('id', $siteId)->value('code'),
+        'site_player_id' => 'lists-player',
+        'auth_source' => 'lottery_native',
+        'funding_mode' => 'credit',
+        'username' => 'lists_player',
+        'default_currency' => 'NPR',
+        'status' => 0,
+        'agent_node_id' => $rootId,
+        'created_at' => now(),
+        'updated_at' => now(),
+    ]);
     $periodId = (int) DB::table('settlement_periods')->insertGetId([
         'admin_site_id' => $siteId,
         'period_start' => now()->subWeek(),
@@ -22,9 +39,9 @@ test('settlement payments and adjustments index return items', function (): void
         'settlement_period_id' => $periodId,
         'bill_type' => 'player',
         'owner_type' => 'player',
-        'owner_id' => 1,
+        'owner_id' => $playerId,
         'counterparty_type' => 'agent',
-        'counterparty_id' => 1,
+        'counterparty_id' => $rootId,
         'net_amount' => 1000,
         'unpaid_amount' => 0,
         'paid_amount' => 1000,
@@ -36,9 +53,9 @@ test('settlement payments and adjustments index return items', function (): void
     DB::table('payment_records')->insert([
         'settlement_bill_id' => $billId,
         'payer_type' => 'player',
-        'payer_id' => 1,
+        'payer_id' => $playerId,
         'payee_type' => 'agent',
-        'payee_id' => 1,
+        'payee_id' => $rootId,
         'amount' => 1000,
         'method' => 'cash',
         'status' => 'confirmed',