feat(credit): 实时同步代理已用额度，覆盖玩家下注/结算全流程

- PlayerCreditService 在下注占用、输赢结算、撤单释放等关键节点触发 AgentUsedCreditSyncService
- AgentProfileService::present 与 AgentDashboardOverviewBuilder 查询前主动同步 used_credit
- 确保代理链 used_credit（团队已用风险）实时反映下级玩家信用占用状态

app/Console/Commands/SyncAgentUsedCreditCommand.php

@@ -0,0 +1,42 @@
+<?php
+
+namespace App\Console\Commands;
+
+use App\Models\AgentNode;
+use App\Models\AgentProfile;
+use App\Services\Agent\AgentUsedCreditSyncService;
+use Illuminate\Console\Command;
+
+/** 重算代理团队已用风险（used_credit），修复历史未同步数据。 */
+final class SyncAgentUsedCreditCommand extends Command
+{
+    protected $signature = 'lottery:sync-agent-used-credit {--site= : 仅处理指定 admin_sites.code}';
+
+    protected $description = '重算代理团队已用风险（used_credit = 子树信用玩家 used_credit + frozen_credit 之和）';
+
+    public function handle(AgentUsedCreditSyncService $sync): int
+    {
+        $siteCode = $this->option('site');
+        $query = AgentNode::query()->orderBy('id');
+        if (is_string($siteCode) && $siteCode !== '') {
+            $query->whereHas('adminSite', static fn ($q) => $q->where('code', $siteCode));
+        }
+
+        $nodes = $query->get();
+        $updated = 0;
+        foreach ($nodes as $node) {
+            $profile = AgentProfile::query()->where('agent_node_id', $node->id)->first();
+            $before = $profile !== null ? (int) $profile->used_credit : null;
+            $sync->syncForAgent($node);
+            $profile?->refresh();
+            $after = $profile !== null ? (int) $profile->used_credit : null;
+            if ($before !== $after) {
+                $updated++;
+            }
+        }
+
+        $this->info('已处理 '.count($nodes).' 个代理节点，其中 '.$updated.' 个 used_credit 有变更。');
+
+        return self::SUCCESS;
+    }
+}

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\Agent\AgentUsedCreditSyncService;
 use App\Services\AgentSettlement\ShareLedgerScopedProfitAggregator;
 use App\Support\AdminAgentSettlementScope;
 use Carbon\Carbon;
@@ -20,6 +21,7 @@ final class AgentDashboardOverviewBuilder
     public function __construct(
         private readonly AdminReportQueryService $reportQuery,
         private readonly ShareLedgerScopedProfitAggregator $shareProfitAggregator,
+        private readonly AgentUsedCreditSyncService $usedCreditSync,
     ) {}
 
     /**
@@ -36,6 +38,7 @@ final class AgentDashboardOverviewBuilder
             return null;
         }
 
+        $this->usedCreditSync->syncForAgentId((int) $node->id);
         $profile = AgentProfile::query()->where('agent_node_id', $node->id)->first();
         $subtreeIds = AgentNode::query()
             ->where('path', 'like', $node->path.'%')

app/Services/Agent/AgentProfileService.php

@@ -17,6 +17,7 @@ final class AgentProfileService
         private readonly CreditAllocationValidator $creditAllocationValidator,
         private readonly RebateLimitValidator $rebateLimitValidator,
         private readonly AgentCreditAllocatedSyncService $allocatedSync,
+        private readonly AgentUsedCreditSyncService $usedCreditSync,
     ) {}
 
     /**
@@ -132,6 +133,7 @@ final class AgentProfileService
     public function present(AgentProfile $profile): array
     {
         $this->allocatedSync->syncForAgentId((int) $profile->agent_node_id);
+        $this->usedCreditSync->syncForAgentId((int) $profile->agent_node_id);
         $profile->refresh();
 
         $available = max(0, (int) $profile->credit_limit - (int) $profile->allocated_credit);

app/Services/Agent/AgentUsedCreditSyncService.php

@@ -0,0 +1,114 @@
+<?php
+
+namespace App\Services\Agent;
+
+use App\Models\AgentNode;
+use App\Models\AgentProfile;
+use App\Support\PlayerFundingMode;
+use Illuminate\Support\Facades\DB;
+
+/**
+ * 同步代理「团队当前已用风险」（agent_profiles.used_credit）：
+ * 聚合该代理子树下所有信用玩家的 player_credit_accounts.used_credit + frozen_credit。
+ *
+ * 不参与 available_credit 计算（available = credit_limit - allocated_credit），
+ * 仅作风控展示指标。
+ */
+final class AgentUsedCreditSyncService
+{
+    /**
+     * 为指定代理节点重算 used_credit。
+     */
+    public function syncForAgent(AgentNode $agent): void
+    {
+        $profile = AgentProfile::query()->where('agent_node_id', $agent->id)->first();
+        if ($profile === null) {
+            return;
+        }
+
+        $expected = $this->calculateUsedCredit($agent);
+        if ((int) $profile->used_credit === $expected) {
+            return;
+        }
+
+        $profile->used_credit = $expected;
+        $profile->save();
+    }
+
+    public function syncForAgentId(int $agentNodeId): void
+    {
+        $agent = AgentNode::query()->find($agentNodeId);
+        if ($agent === null) {
+            return;
+        }
+
+        $this->syncForAgent($agent);
+    }
+
+    /**
+     * 玩家信用变化后：同步直属代理及所有祖先代理的 used_credit。
+     */
+    public function syncForPlayerAgentChain(int $playerAgentNodeId): void
+    {
+        if ($playerAgentNodeId <= 0) {
+            return;
+        }
+
+        $agent = AgentNode::query()->find($playerAgentNodeId);
+        if ($agent === null) {
+            return;
+        }
+
+        $ancestorIds = $this->ancestorAndSelfIds($agent);
+
+        foreach ($ancestorIds as $nodeId) {
+            $this->syncForAgentId($nodeId);
+        }
+    }
+
+    /**
+     * 计算代理子树下所有信用玩家的 used_credit + frozen_credit 之和。
+     */
+    public function calculateUsedCredit(AgentNode $agent): int
+    {
+        $subtreeIds = $this->subtreeNodeIds($agent);
+        if ($subtreeIds === []) {
+            return 0;
+        }
+
+        return (int) DB::table('player_credit_accounts as pca')
+            ->join('players as p', 'p.id', '=', 'pca.player_id')
+            ->whereIn('p.agent_node_id', $subtreeIds)
+            ->where('p.funding_mode', PlayerFundingMode::CREDIT)
+            ->sum(DB::raw('pca.used_credit + pca.frozen_credit'));
+    }
+
+    /**
+     * @return list<int>
+     */
+    private function subtreeNodeIds(AgentNode $agent): array
+    {
+        return AgentNode::query()
+            ->where('path', 'like', $agent->path.'%')
+            ->pluck('id')
+            ->map(static fn ($id): int => (int) $id)
+            ->all();
+    }
+
+    /**
+     * @return list<int>
+     */
+    private function ancestorAndSelfIds(AgentNode $agent): array
+    {
+        $path = (string) $agent->path;
+        if ($path === '') {
+            return [(int) $agent->id];
+        }
+
+        $parts = explode('/', trim($path, '/'));
+        $ancestorIds = array_map('intval', $parts);
+        $ancestorIds[] = (int) $agent->id;
+
+        return $ancestorIds;
+    }
+}

app/Services/Player/PlayerCreditService.php

@@ -3,6 +3,7 @@
 namespace App\Services\Player;
 
 use App\Models\Player;
+use App\Services\Agent\AgentUsedCreditSyncService;
 use App\Support\AgentOverdueGuard;
 use App\Support\CreditAmountScale;
 use App\Support\PlayerFundingMode;
@@ -12,6 +13,9 @@ use Illuminate\Validation\ValidationException;
 
 final class PlayerCreditService
 {
+    public function __construct(
+        private readonly AgentUsedCreditSyncService $usedCreditSync,
+    ) {}
     /**
      * @param  array{credit_limit?: int}  $payload
      */
@@ -155,6 +159,8 @@ final class PlayerCreditService
             'created_at' => $now,
             'updated_at' => $now,
         ]);
+
+        $this->syncAgentUsedCredit($player);
     }
 
     public function applySettledLoss(Player $player, int $amountMinor, int $ticketItemId): void
@@ -208,6 +214,8 @@ final class PlayerCreditService
                 'used_credit' => (int) $row->used_credit + $majorDelta,
                 'updated_at' => $now,
             ]);
+
+        $this->syncAgentUsedCredit($player);
     }
 
     public function applySettledWin(Player $player, int $amountMinor, int $ticketItemId): void
@@ -243,6 +251,7 @@ final class PlayerCreditService
         }
 
         $this->decreaseUsedCredit($player, $amountMinor);
+        $this->syncAgentUsedCredit($player);
     }
 
     public function assertMayPlaceBet(Player $player, int $amountMinor): void
@@ -310,6 +319,7 @@ final class PlayerCreditService
         }
 
         $this->decreaseUsedCredit($player, $amountMinor);
+        $this->syncAgentUsedCredit($player);
     }
 
     public function reverseBetHold(Player $player, int $amountMinor, int $ticketOrderId): void
@@ -341,6 +351,7 @@ final class PlayerCreditService
         }
 
         $this->decreaseUsedCredit($player, $amountMinor);
+        $this->syncAgentUsedCredit($player);
     }
 
     public function reverseGameSettlement(Player $player, int $gameWinLossSigned, int $ticketItemId): void
@@ -395,6 +406,8 @@ final class PlayerCreditService
                 'used_credit' => (int) $row->used_credit + $majorDelta,
                 'updated_at' => $now,
             ]);
+
+        $this->syncAgentUsedCredit($player);
     }
 
     /**
@@ -414,6 +427,7 @@ final class PlayerCreditService
         );
         if ($delta > 0) {
             $this->decreaseUsedCredit($player, $delta);
+            $this->syncAgentUsedCredit($player);
         }
     }
 
@@ -508,6 +522,17 @@ final class PlayerCreditService
             ]);
     }
 
+    /** 玩家信用变动后同步直属代理及祖先链的 used_credit（团队已用风险）。 */
+    private function syncAgentUsedCredit(Player $player): void
+    {
+        $agentNodeId = (int) ($player->agent_node_id ?? 0);
+        if ($agentNodeId <= 0) {
+            return;
+        }
+
+        $this->usedCreditSync->syncForPlayerAgentChain($agentNodeId);
+    }
+
     /**
      * 识别数据库唯一约束冲突（PostgreSQL SQLSTATE 23505；SQLite SQLSTATE 23000/error code 19）。
      * 兜底扫描消息中 unique 字样，兼容驱动返回的 SQLSTATE 缺失场景。