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'],

app/Services/Admin/AgentDashboardOverviewBuilder.php

@@ -8,6 +8,7 @@ use App\Models\AgentProfile;
 use App\Models\Player;
 use App\Support\AdminScopeContext;
 use App\Support\AdminScopeContextResolver;
+use App\Services\AgentSettlement\ShareLedgerScopedProfitAggregator;
 use App\Support\AdminAgentSettlementScope;
 use Carbon\Carbon;
 use Illuminate\Support\Facades\DB;
@@ -18,6 +19,7 @@ final class AgentDashboardOverviewBuilder
 {
     public function __construct(
         private readonly AdminReportQueryService $reportQuery,
+        private readonly ShareLedgerScopedProfitAggregator $shareProfitAggregator,
     ) {}
 
     /**
@@ -58,6 +60,8 @@ final class AgentDashboardOverviewBuilder
         $sevenDayFrom = now()->subDays(6)->toDateString();
         $todayTotals = $this->reportQuery->periodFinanceTotals($today, $today, $scope);
         $sevenDayTotals = $this->reportQuery->periodFinanceTotals($sevenDayFrom, $today, $scope);
+        $todayShareProfit = $this->shareProfitAggregator->sumShareProfitForAdmin($admin, $today, $today);
+        $sevenDayShareProfit = $this->shareProfitAggregator->sumShareProfitForAdmin($admin, $sevenDayFrom, $today);
         $currencyCode = $this->reportQuery->resolvePeriodCurrencyCode($today, $today, $scope)
             ?? $this->reportQuery->resolvePeriodCurrencyCode($sevenDayFrom, $today, $scope);
         $teamPlayerStats = $this->teamPlayerStats($subtreeIds);
@@ -87,10 +91,11 @@ final class AgentDashboardOverviewBuilder
             'bet_order_count_today' => $todayActivityStats['order_count'],
             'today_bet_minor' => $todayTotals['total_bet_minor'],
             'today_payout_minor' => $todayTotals['total_payout_minor'],
-            'today_profit_minor' => $todayTotals['approx_house_gross_minor'],
+            'today_profit_minor' => $todayShareProfit,
             'seven_day_bet_minor' => $sevenDayTotals['total_bet_minor'],
             'seven_day_payout_minor' => $sevenDayTotals['total_payout_minor'],
-            'seven_day_profit_minor' => $sevenDayTotals['approx_house_gross_minor'],
+            'seven_day_profit_minor' => $sevenDayShareProfit,
+            'profit_scope' => 'share_profit',
             'currency_code' => $currencyCode,
             'pending_bill_count' => $pendingBillStats['count'],
             'pending_unpaid_minor' => $pendingBillStats['unpaid_minor'],