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/Admin/AdminDashboardAnalyticsBuilder.php

@@ -3,6 +3,7 @@
 namespace App\Services\Admin;
 
 use App\Models\AdminUser;
+use App\Services\AgentSettlement\ShareLedgerScopedProfitAggregator;
 use App\Support\AdminScopeContextResolver;
 
 /**
@@ -12,6 +13,7 @@ final class AdminDashboardAnalyticsBuilder
 {
     public function __construct(
         private readonly AdminReportQueryService $reportQuery,
+        private readonly ShareLedgerScopedProfitAggregator $shareProfitAggregator,
     ) {}
 
     /**
@@ -53,6 +55,27 @@ final class AdminDashboardAnalyticsBuilder
         $dateTo = $range['date_to'];
 
         $trend = $this->reportQuery->dailyProfitSeriesFilled($dateFrom, $dateTo, scope: $scope);
+        $summary = $this->reportQuery->periodFinanceTotals($dateFrom, $dateTo, $scope);
+        $dailySeries = $trend['series'];
+        $profitScope = 'house_gross';
+
+        if ($admin->primaryAgentNode() !== null) {
+            $profitScope = 'share_profit';
+            $shareByDate = $this->shareProfitAggregator->shareProfitByBusinessDate($admin, $dateFrom, $dateTo);
+            $summary['approx_house_gross_minor'] = $this->shareProfitAggregator->sumShareProfitForAdmin(
+                $admin,
+                $dateFrom,
+                $dateTo,
+            );
+            $dailySeries = array_map(
+                static function (array $row) use ($shareByDate): array {
+                    $row['approx_house_gross_minor'] = $shareByDate[(string) $row['business_date']] ?? 0;
+
+                    return $row;
+                },
+                $dailySeries,
+            );
+        }
 
         return [
             'period' => $period,
@@ -60,9 +83,10 @@ final class AdminDashboardAnalyticsBuilder
             'play_code' => $playCode,
             'date_from' => $dateFrom,
             'date_to' => $dateTo,
+            'profit_scope' => $profitScope,
             'currency_code' => $this->reportQuery->resolvePeriodCurrencyCode($dateFrom, $dateTo, $scope),
-            'summary' => $this->reportQuery->periodFinanceTotals($dateFrom, $dateTo, $scope),
-            'daily_series' => $trend['series'],
+            'summary' => $summary,
+            'daily_series' => $dailySeries,
             'chart_meta' => [
                 'chart_date_from' => $trend['chart_date_from'],
                 'chart_date_to' => $trend['chart_date_to'],