feat: enhance player authentication and agent management features

- Updated AGENTS.md to clarify player interface bindings and agent account restrictions.
- Improved PlayerAuthLoginController to include captcha verification for player login.
- Enhanced AdminPlayerIndexController with permission checks for admin users.
- Refactored AdminPlayerStoreController to enforce agent node restrictions for non-super admins.
- Introduced new error codes for player authentication failures and updated related services.
- Enhanced validation rules for agent profiles to include settlement cycle options.
- Improved AdminCaptchaService to support separate scopes for admin and player captcha handling.
- Updated various services to ensure proper credit management and settlement processes.

app/Services/AgentSettlement/GameSettlementReversalService.php

@@ -3,13 +3,17 @@
 namespace App\Services\AgentSettlement;
 
 use App\Models\Player;
-use App\Support\CreditAmountScale;
 use App\Models\TicketItem;
+use App\Services\Player\PlayerCreditService;
 use App\Support\PlayerFundingMode;
 use Illuminate\Support\Facades\DB;
 
 final class GameSettlementReversalService
 {
+    public function __construct(
+        private readonly PlayerCreditService $playerCreditService,
+    ) {}
+
     public function reverseTicketItem(TicketItem $item): void
     {
         $ledger = DB::table('share_ledger')->where('ticket_item_id', $item->id)->whereNull('reversal_of_id')->first();
@@ -60,21 +64,10 @@ final class GameSettlementReversalService
             }
 
             $player = Player::query()->find((int) $ledger->player_id);
-            if ($player !== null && PlayerFundingMode::usesCredit($player) && (int) $ledger->game_win_loss > 0) {
-                $playerId = (int) $ledger->player_id;
-                $row = DB::table('player_credit_accounts')->where('player_id', $playerId)->first();
-                if ($row !== null) {
-                    $deltaMinor = (int) $ledger->game_win_loss;
-                    $deltaMajor = CreditAmountScale::minorToMajor(
-                        $deltaMinor,
-                        (string) $player->default_currency,
-                    );
-                    DB::table('player_credit_accounts')
-                        ->where('player_id', $playerId)
-                        ->update([
-                            'used_credit' => max(0, (int) $row->used_credit - $deltaMajor),
-                            'updated_at' => $settledAt,
-                        ]);
+            if ($player !== null && PlayerFundingMode::usesCredit($player)) {
+                $gameWinLoss = (int) $ledger->game_win_loss;
+                if ($gameWinLoss !== 0) {
+                    $this->playerCreditService->reverseGameSettlement($player, $gameWinLoss, $item->id);
                 }
             }
         });

app/Services/AgentSettlement/SettlementCenterLedgerService.php

@@ -19,6 +19,7 @@ final class SettlementCenterLedgerService
         'bet_hold_release',
         'game_settlement_loss',
         'game_settlement_win',
+        'game_settlement_reversal',
         'settlement_confirm',
         'settlement_payout',
     ];
@@ -572,10 +573,9 @@ final class SettlementCenterLedgerService
             $id = (int) $stub->entry_id;
             if ($kind === 'credit' && isset($creditById[$id])) {
                 $row = $creditById[$id];
-                $pid = (int) $row->player_id;
                 $bill = (string) ($row->ref_type ?? '') === 'settlement_bill'
                     ? ($creditBillRefs[(int) ($row->ref_id ?? 0)] ?? null)
-                    : ($playerBills[$pid] ?? null);
+                    : null;
                 $items[] = $this->formatCreditEntry($row, $bill, $ticketRefs);
             } elseif ($kind === 'payment' && isset($paymentById[$id])) {
                 $items[] = $this->formatPaymentEntry($paymentById[$id]);