feat(tests): 添加结算相关功能的测试用例，增强代码覆盖率

app/Http/Controllers/Api/V1/Admin/AgentSettlement/AgentSettlementReportShowController.php

@@ -5,6 +5,7 @@ namespace App\Http\Controllers\Api\V1\Admin\AgentSettlement;
 use App\Http\Controllers\Controller;
 use App\Services\AgentSettlement\AgentSettlementReportQueryService;
 use App\Support\AdminAgentScope;
+use App\Support\AdminAgentSettlementScope;
 use App\Support\AgentSettlementPeriodWindow;
 use App\Support\ApiResponse;
 use Illuminate\Http\JsonResponse;
@@ -37,6 +38,9 @@ final class AgentSettlementReportShowController extends Controller
         }
 
         $periodId = (int) $request->query('settlement_period_id', 0);
+        if ($periodId > 0) {
+            abort_if(! AdminAgentSettlementScope::periodAccessible($admin, $periodId), 403);
+        }
         $period = $this->resolvePeriod($periodId, $request);
 
         $data = match ($type) {

app/Services/AgentSettlement/AgentGameSettlementRecorder.php

@@ -36,6 +36,10 @@ final class AgentGameSettlementRecorder
             return;
         }
 
+        if ($this->hasActiveShareLedger($item->id)) {
+            return;
+        }
+
         $player = $item->player;
         if ($player === null) {
             return;
@@ -168,6 +172,20 @@ final class AgentGameSettlementRecorder
         return 0.0;
     }
 
+    /** 原分账行存在且尚未被冲正时视为活跃，禁止重复入账。 */
+    private function hasActiveShareLedger(int $ticketItemId): bool
+    {
+        return DB::table('share_ledger as sl')
+            ->where('sl.ticket_item_id', $ticketItemId)
+            ->whereNull('sl.reversal_of_id')
+            ->whereNotExists(function ($query): void {
+                $query->selectRaw('1')
+                    ->from('share_ledger as rev')
+                    ->whereColumn('rev.reversal_of_id', 'sl.id');
+            })
+            ->exists();
+    }
+
     private function normalizeRate(float $rate): float
     {
         return max(0.0, min(1.0, $rate));

app/Services/AgentSettlement/AgentSettlementPeriodCloseService.php

@@ -27,26 +27,25 @@ final class AgentSettlementPeriodCloseService
     {
         AgentSettlementProductionGuard::assertProductionCloseAllowed();
 
-        $period = DB::table('settlement_periods')->where('id', $periodId)->first();
-        if ($period === null) {
-            throw ValidationException::withMessages([
-                'period' => ['period_not_found'],
-            ]);
-        }
+        return DB::transaction(function () use ($periodId): array {
+            $period = DB::table('settlement_periods')->where('id', $periodId)->lockForUpdate()->first();
+            if ($period === null) {
+                throw ValidationException::withMessages([
+                    'period' => ['period_not_found'],
+                ]);
+            }
 
-        if ((string) $period->status === 'closed' || (string) $period->status === 'completed') {
-            throw ValidationException::withMessages([
-                'period' => ['period_already_closed'],
-            ]);
-        }
+            if ((string) $period->status === 'closed' || (string) $period->status === 'completed') {
+                throw ValidationException::withMessages([
+                    'period' => ['period_already_closed'],
+                ]);
+            }
 
-        $adminSiteId = (int) $period->admin_site_id;
-        [$periodStart, $periodEnd] = AgentSettlementPeriodWindow::boundStrings(
-            (string) $period->period_start,
-            (string) $period->period_end,
-        );
-
-        return DB::transaction(function () use ($periodId, $period, $adminSiteId, $periodStart, $periodEnd): array {
+            $adminSiteId = (int) $period->admin_site_id;
+            [$periodStart, $periodEnd] = AgentSettlementPeriodWindow::boundStrings(
+                (string) $period->period_start,
+                (string) $period->period_end,
+            );
             try {
                 $aggregate = $this->aggregator->aggregate($adminSiteId, $periodStart, $periodEnd);
             } catch (\InvalidArgumentException $e) {

app/Services/Draw/DrawCancelBetRefundService.php

@@ -3,11 +3,14 @@
 namespace App\Services\Draw;
 
 use App\Models\Draw;
+use App\Models\Player;
 use App\Models\TicketItem;
 use App\Models\TicketOrder;
 use App\Models\WalletTxn;
+use App\Services\Player\PlayerCreditService;
 use App\Services\Ticket\RiskPoolService;
 use App\Services\Ticket\TicketWalletService;
+use App\Support\PlayerFundingMode;
 
 /**
  * 取消期号前：退本、释池，避免已扣款注单悬空。
@@ -17,6 +20,7 @@ final class DrawCancelBetRefundService
     public function __construct(
         private readonly RiskPoolService $riskPool,
         private readonly TicketWalletService $ticketWallet,
+        private readonly PlayerCreditService $playerCreditService,
     ) {}
 
     public function refundOpenBetsForDraw(Draw $draw): void
@@ -76,18 +80,27 @@ final class DrawCancelBetRefundService
             ])->save();
         }
 
-        $hasPostedDeduct = WalletTxn::query()
-            ->where('biz_type', 'bet_deduct')
-            ->where('biz_no', $lockedOrder->order_no)
-            ->where('status', 'posted')
-            ->exists();
+        $player = Player::query()->whereKey($lockedOrder->player_id)->first();
 
-        if ($hasPostedDeduct) {
-            $this->ticketWallet->reverseBetDeduct($lockedOrder);
+        if ($player !== null && PlayerFundingMode::usesCredit($player)) {
+            $holdAmount = (int) $lockedOrder->total_actual_deduct;
+            if ($holdAmount > 0) {
+                $this->playerCreditService->reverseBetHold($player, $holdAmount, (int) $lockedOrder->id);
+            }
+        } else {
+            $hasPostedDeduct = WalletTxn::query()
+                ->where('biz_type', 'bet_deduct')
+                ->where('biz_no', $lockedOrder->order_no)
+                ->where('status', 'posted')
+                ->exists();
+
+            if ($hasPostedDeduct) {
+                $this->ticketWallet->reverseBetDeduct($lockedOrder);
+            }
+
+            $this->ticketWallet->releaseReservedBetDeduct($lockedOrder, 'draw_cancelled_release');
         }
 
-        $this->ticketWallet->releaseReservedBetDeduct($lockedOrder, 'draw_cancelled_release');
-
         $lockedOrder->forceFill(['status' => 'refunded'])->save();
     }
 }

app/Services/Settlement/SettlementBatchWorkflowService.php

@@ -12,12 +12,15 @@ use App\Models\TicketOrder;
 use App\Models\SettlementBatch;
 use Illuminate\Support\Facades\DB;
 use App\Lottery\SettlementBatchStatus;
+use App\Services\AgentSettlement\GameSettlementReversalService;
 use App\Services\Ticket\TicketWalletService;
+use App\Support\PlayerFundingMode;
 
 final class SettlementBatchWorkflowService
 {
     public function __construct(
         private readonly TicketWalletService $wallet,
+        private readonly GameSettlementReversalService $gameSettlementReversal,
     ) {}
 
     public function approve(SettlementBatch $batch, AdminUser $admin, ?string $remark = null): SettlementBatch
@@ -62,6 +65,11 @@ final class SettlementBatchWorkflowService
 
             $itemIds = $locked->details()->pluck('ticket_item_id')->map(fn ($id) => (int) $id)->all();
             if ($itemIds !== []) {
+                $items = TicketItem::query()->whereIn('id', $itemIds)->get();
+                foreach ($items as $item) {
+                    $this->gameSettlementReversal->reverseTicketItem($item);
+                }
+
                 TicketItem::query()
                     ->whereIn('id', $itemIds)
                     ->update([
@@ -69,6 +77,7 @@ final class SettlementBatchWorkflowService
                         'win_amount' => 0,
                         'jackpot_win_amount' => 0,
                         'settled_at' => null,
+                        'agent_settled_at' => null,
                     ]);
             }
 
@@ -153,6 +162,9 @@ final class SettlementBatchWorkflowService
                     continue;
                 }
                 $player = Player::query()->whereKey((int) $entry['player_id'])->firstOrFail();
+                if (PlayerFundingMode::usesCredit($player)) {
+                    continue;
+                }
                 $this->wallet->creditSettlementPayout(
                     $player,
                     (string) $entry['currency_code'],

app/Services/Settlement/SettlementTickFinalizer.php

@@ -6,6 +6,7 @@ use App\Models\SettlementBatch;
 use App\Lottery\SettlementBatchStatus;
 use App\Services\AuditLogger;
 use App\Services\LotterySettings;
+use Illuminate\Support\Facades\DB;
 
 /**
  * draw tick 在自动结算后，按系统设置自动审核并派彩入账。
@@ -16,14 +17,15 @@ final class SettlementTickFinalizer
         private readonly SettlementBatchWorkflowService $workflow,
     ) {}
 
-    /** @return array{approved: int, paid: int} */
+    /** @return array{approved: int, paid: int, payout_failed: int} */
     public function finalizePendingBatches(): array
     {
         $approved = 0;
         $paid = 0;
+        $payoutFailed = 0;
 
         if (! (bool) LotterySettings::get('settlement.auto_approve_on_tick', true)) {
-            return ['approved' => 0, 'paid' => 0];
+            return ['approved' => 0, 'paid' => 0, 'payout_failed' => 0];
         }
 
         $pending = SettlementBatch::query()
@@ -58,9 +60,39 @@ final class SettlementTickFinalizer
                 );
             } catch (\Throwable $e) {
                 report($e);
+                $this->markAutoPayoutFailed($batch, $e);
+                $payoutFailed++;
             }
         }
 
-        return ['approved' => $approved, 'paid' => $paid];
+        return ['approved' => $approved, 'paid' => $paid, 'payout_failed' => $payoutFailed];
     }
-}
+
+    private function markAutoPayoutFailed(SettlementBatch $batch, \Throwable $e): void
+    {
+        $message = mb_substr($e->getMessage(), 0, 200);
+
+        DB::transaction(function () use ($batch, $message): void {
+            $locked = SettlementBatch::query()->whereKey($batch->id)->lockForUpdate()->first();
+            if ($locked === null || $locked->status !== SettlementBatchStatus::Approved->value) {
+                return;
+            }
+
+            $locked->forceFill([
+                'status' => SettlementBatchStatus::Failed->value,
+                'review_remark' => 'auto_payout_failed: '.$message,
+            ])->save();
+
+            AuditLogger::recordForSystem(
+                moduleCode: 'settlement',
+                actionCode: 'auto_payout_failed',
+                targetType: 'settlement_batch',
+                targetId: (string) $locked->id,
+                afterJson: [
+                    'draw_id' => (int) $locked->draw_id,
+                    'error' => $message,
+                ],
+            );
+        });
+    }
+}