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