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.

app/Services/AgentSettlement/AgentSettlementPeriodOpenService.php

@@ -2,6 +2,7 @@
 
 namespace App\Services\AgentSettlement;
 
+use App\Support\AgentSettlementPeriodWindow;
 use Illuminate\Support\Facades\DB;
 use Illuminate\Validation\ValidationException;
 
@@ -14,8 +15,10 @@ final class AgentSettlementPeriodOpenService
     public function open(array $data): object
     {
         $siteId = (int) $data['admin_site_id'];
-        $start = (string) $data['period_start'];
-        $end = (string) $data['period_end'];
+        [$start, $end] = AgentSettlementPeriodWindow::normalizeInputBounds(
+            (string) $data['period_start'],
+            (string) $data['period_end'],
+        );
 
         $existingSameRange = DB::table('settlement_periods')
             ->where('admin_site_id', $siteId)
@@ -43,6 +46,12 @@ final class AgentSettlementPeriodOpenService
             ]);
         }
 
+        if ($this->overlapsExistingPeriod($siteId, $start, $end)) {
+            throw ValidationException::withMessages([
+                'period_start' => ['period_overlaps_existing'],
+            ]);
+        }
+
         $id = (int) DB::table('settlement_periods')->insertGetId([
             'admin_site_id' => $siteId,
             'period_start' => $start,
@@ -59,4 +68,13 @@ final class AgentSettlementPeriodOpenService
 
         return $row;
     }
+
+    private function overlapsExistingPeriod(int $siteId, string $start, string $end): bool
+    {
+        return DB::table('settlement_periods')
+            ->where('admin_site_id', $siteId)
+            ->where('period_start', '<=', $end)
+            ->where('period_end', '>=', $start)
+            ->exists();
+    }
 }