feat(agent-profile): 限制代理及玩家返点和分成范围，增强权限校验

- 添加ensureSuperAdmin方法，限制管理员设置操作权限 - 在AdminSettingController接口中新增权限检查，防止非超级管理员操作 - AdminPlayerIndexController新增direct agent筛选支持 - AdminPlayerUpdateController新增对信用玩家默认币别变更的拒绝逻辑 - 新增WalletSettlementBillsController，实现玩家信用盘账期账单摘要接口 - AgentProfileService调整，新增返点限额和分享比例自动下调机制，保持子代理及玩家配置不超父级 - AgentProfileService增加can_grant_extra_rebate权限继承限制，阻止无权限代理开启 - AgentSettlementPeriodCloseService增加玩家账单回水信用释放逻辑，确保信用额度同步 - PlayerCreditService新增释放账单回水对应信用逻辑，维护账期信用一致性 - TicketPlacementService和TicketPreviewService新增信用玩家投注币别匹配校验，防止币别不符 - PlayerLedgerLogsService优化信用额度计算，增加可用额度上下限限制，防止负值和超限 - 调整后台管理导航，仅超管可见设置入口，强化权限隔离 - 路由新增玩家信用账单查询接口 - 补充多项AgentProfile相关单元测试覆盖额度限制、返点继承、返点下调场景及权限限制 - 增加站点管理员登录测试，验证系统设置菜单不可见，提升用户权限体验
2026-07-01 15:35:46 +08:00
parent ed5a983003
commit 992195b00c
21 changed files with 1218 additions and 35 deletions
--- a/app/Services/Agent/AgentProfileService.php
+++ b/app/Services/Agent/AgentProfileService.php
@@ -118,6 +118,17 @@ final class AgentProfileService
                $profile->used_credit = 0;
            }
            $profile->save();
+            $this->clampDescendantAgentShareRates($node, (float) $profile->total_share_rate);
+            $this->clampDirectPlayerRebates(
+                $node,
+                (float) $profile->rebate_limit,
+                (bool) $profile->can_grant_extra_rebate,
+            );
+            $this->clampDescendantAgentRebates(
+                $node,
+                (float) $profile->rebate_limit,
+                (bool) $profile->can_grant_extra_rebate,
+            );

            if ($parent !== null) {
                $this->allocatedSync->syncForAgent($parent);
@@ -290,11 +301,18 @@ final class AgentProfileService
     */
    public function assertChildCapabilityGrantsWithinParent(AgentNode $parent, array $childPayload, AdminUser $actor): void
    {
+        $parentProfile = $this->profileForNode((int) $parent->id);
+        if ((bool) ($childPayload['can_grant_extra_rebate'] ?? false)
+            && ! ($parentProfile?->can_grant_extra_rebate ?? false)) {
+            throw ValidationException::withMessages([
+                'can_grant_extra_rebate' => ['parent_cannot_delegate'],
+            ]);
+        }
+
        if ($actor->isSuperAdmin() || \App\Support\AdminAgentSettlementScope::canManageSitePeriods($actor)) {
            return;
        }

-        $parentProfile = $this->profileForNode((int) $parent->id);
        if ((bool) ($childPayload['can_create_child_agent'] ?? false)
            && ! ($parentProfile?->can_create_child_agent ?? false)) {
            throw ValidationException::withMessages([
@@ -324,6 +342,113 @@ final class AgentProfileService
        return (bool) ($profile?->can_create_player ?? false);
    }

+    private function clampDescendantAgentShareRates(AgentNode $parent, float $parentTotalShareRate): void
+    {
+        $children = AgentNode::query()
+            ->where('parent_id', (int) $parent->id)
+            ->orderBy('id')
+            ->get();
+
+        foreach ($children as $child) {
+            $profile = AgentProfile::query()
+                ->where('agent_node_id', (int) $child->id)
+                ->first();
+
+            if ($profile === null) {
+                continue;
+            }
+
+            $totalShareRate = max(0.0, (float) $profile->total_share_rate);
+            $nextTotalShareRate = min($totalShareRate, $parentTotalShareRate);
+
+            if (abs($nextTotalShareRate - $totalShareRate) >= 1e-9) {
+                $profile->forceFill([
+                    'total_share_rate' => $nextTotalShareRate,
+                ])->save();
+            }
+
+            $this->clampDescendantAgentShareRates($child, $nextTotalShareRate);
+        }
+    }
+
+    private function clampDirectPlayerRebates(AgentNode $agent, float $rebateLimit, bool $canGrantExtraRebate): void
+    {
+        $rows = DB::table('player_rebate_profiles as prp')
+            ->join('players as p', 'p.id', '=', 'prp.player_id')
+            ->where('p.agent_node_id', (int) $agent->id)
+            ->where('prp.inherit_from_agent', false)
+            ->select([
+                'prp.id',
+                'prp.rebate_rate',
+                'prp.extra_rebate_rate',
+            ])
+            ->get();
+
+        $now = now();
+        foreach ($rows as $row) {
+            $rebateRate = max(0.0, (float) $row->rebate_rate);
+            $extraRate = max(0.0, (float) $row->extra_rebate_rate);
+
+            $nextRebate = min($rebateRate, $rebateLimit);
+            $remaining = max(0.0, $rebateLimit - $nextRebate);
+            $nextExtra = $canGrantExtraRebate ? min($extraRate, $remaining) : 0.0;
+
+            if (abs($nextRebate - $rebateRate) < 1e-9 && abs($nextExtra - $extraRate) < 1e-9) {
+                continue;
+            }
+
+            DB::table('player_rebate_profiles')
+                ->where('id', (int) $row->id)
+                ->update([
+                    'rebate_rate' => $nextRebate,
+                    'extra_rebate_rate' => $nextExtra,
+                    'updated_at' => $now,
+                ]);
+        }
+    }
+
+    private function clampDescendantAgentRebates(
+        AgentNode $parent,
+        float $parentRebateLimit,
+        bool $parentCanGrantExtraRebate,
+    ): void {
+        $children = AgentNode::query()
+            ->where('parent_id', (int) $parent->id)
+            ->orderBy('id')
+            ->get();
+
+        foreach ($children as $child) {
+            $profile = AgentProfile::query()
+                ->where('agent_node_id', (int) $child->id)
+                ->first();
+
+            if ($profile === null) {
+                continue;
+            }
+
+            $rebateLimit = max(0.0, (float) $profile->rebate_limit);
+            $defaultRebate = max(0.0, (float) $profile->default_player_rebate);
+            $canGrantExtraRebate = (bool) $profile->can_grant_extra_rebate;
+
+            $nextRebateLimit = min($rebateLimit, $parentRebateLimit);
+            $nextDefaultRebate = min($defaultRebate, $nextRebateLimit);
+            $nextCanGrantExtraRebate = $parentCanGrantExtraRebate && $canGrantExtraRebate;
+
+            if (abs($nextRebateLimit - $rebateLimit) >= 1e-9
+                || abs($nextDefaultRebate - $defaultRebate) >= 1e-9
+                || $nextCanGrantExtraRebate !== $canGrantExtraRebate) {
+                $profile->forceFill([
+                    'rebate_limit' => $nextRebateLimit,
+                    'default_player_rebate' => $nextDefaultRebate,
+                    'can_grant_extra_rebate' => $nextCanGrantExtraRebate,
+                ])->save();
+            }
+
+            $this->clampDirectPlayerRebates($child, $nextRebateLimit, $nextCanGrantExtraRebate);
+            $this->clampDescendantAgentRebates($child, $nextRebateLimit, $nextCanGrantExtraRebate);
+        }
+    }
+
    private function assertAgentProfileExists(AgentNode $agent): void
    {
        if (AgentProfile::query()->where('agent_node_id', $agent->id)->exists()) {
--- a/app/Services/AgentSettlement/AgentSettlementPeriodCloseService.php
+++ b/app/Services/AgentSettlement/AgentSettlementPeriodCloseService.php
@@ -3,7 +3,9 @@
 namespace App\Services\AgentSettlement;

 use App\Models\AgentNode;
+use App\Models\Player;
 use App\Services\Agent\AgentCreditAllocatedSyncService;
+use App\Services\Player\PlayerCreditService;
 use App\Support\AgentSettlementPeriodWindow;
 use App\Support\AgentSettlementProductionGuard;
 use Illuminate\Support\Facades\DB;
@@ -18,6 +20,7 @@ final class AgentSettlementPeriodCloseService
        private readonly UnsettledTicketPeriodWarning $unsettledWarning,
        private readonly PlatformRoundingAdjuster $platformRounding,
        private readonly AgentCreditAllocatedSyncService $allocatedSync,
+        private readonly PlayerCreditService $playerCreditService,
    ) {}

    /**
@@ -63,6 +66,7 @@ final class AgentSettlementPeriodCloseService
            $roundingDiff = $this->platformRounding->apply($periodId, $aggregate);

            $rebateStats = $this->periodCloseRebate->dispatchAndAllocate($periodId, $adminSiteId, $periodStart, $periodEnd);
+            $this->releasePlayerBillRebatesFromCredit($periodId);

            $unsettled = $this->unsettledWarning->countForSite($adminSiteId, $periodStart, $periodEnd);

@@ -100,6 +104,28 @@ final class AgentSettlementPeriodCloseService
        });
    }

+    /** 玩家亏损账单里的回水已抵扣应付额，应同步释放同等已用信用。 */
+    private function releasePlayerBillRebatesFromCredit(int $periodId): void
+    {
+        $bills = DB::table('settlement_bills')
+            ->where('settlement_period_id', $periodId)
+            ->where('bill_type', 'player')
+            ->where('owner_type', 'player')
+            ->where('gross_win_loss', '>', 0)
+            ->where('rebate_amount', '>', 0)
+            ->get(['id', 'owner_id', 'gross_win_loss', 'rebate_amount']);
+
+        foreach ($bills as $bill) {
+            $player = Player::query()->find((int) $bill->owner_id);
+            if ($player === null) {
+                continue;
+            }
+
+            $rebateMinor = min((int) $bill->gross_win_loss, (int) $bill->rebate_amount);
+            $this->playerCreditService->releaseRebateInBill($player, $rebateMinor, (int) $bill->id);
+        }
+    }
+
    /** 关账后按真理源重算各代理「已下发额度」，避免与直属玩家/下级代理授信脱节。 */
    private function reconcileAllocatedCreditForSite(int $adminSiteId): void
    {
--- a/app/Services/Player/PlayerCreditService.php
+++ b/app/Services/Player/PlayerCreditService.php
@@ -448,6 +448,27 @@ final class PlayerCreditService
        );
    }

+    /**
+     * 账期回水进入玩家账单后，已抵扣玩家应付亏损，需同步释放对应已用信用。
+     */
+    public function releaseRebateInBill(Player $player, int $rebateMinor, int $billId): void
+    {
+        if ($rebateMinor <= 0 || ! PlayerFundingMode::usesCredit($player)) {
+            return;
+        }
+
+        $delta = $this->syncSettlementBillLedger(
+            $player,
+            $billId,
+            'rebate_in_bill',
+            $rebateMinor,
+        );
+        if ($delta > 0) {
+            $this->decreaseUsedCredit($player, $delta);
+            $this->syncAgentUsedCredit($player);
+        }
+    }
+
    /**
     * 同步账期收付台账：每账单每种 reason 仅一行，amount 为累计已付；返回本次应追加的 minor 增量。
     */
--- a/app/Services/Ticket/TicketPlacementService.php
+++ b/app/Services/Ticket/TicketPlacementService.php
@@ -39,6 +39,8 @@ final class TicketPlacementService
    public function place(Player $player, array $payload): array
    {
        $currencyCode = strtoupper((string) $payload['currency_code']);
+        $this->assertCreditCurrencyMatchesPlayer($player, $currencyCode);
+
        $clientTraceId = isset($payload['client_trace_id']) && $payload['client_trace_id'] !== ''
            ? (string) $payload['client_trace_id']
            : null;
@@ -552,4 +554,21 @@ final class TicketPlacementService

        return str_pad($number, 4, '0', STR_PAD_LEFT);
    }
+
+    private function assertCreditCurrencyMatchesPlayer(Player $player, string $currencyCode): void
+    {
+        if (! PlayerFundingMode::usesCredit($player)) {
+            return;
+        }
+
+        $defaultCurrency = strtoupper((string) $player->default_currency);
+        if ($currencyCode === $defaultCurrency) {
+            return;
+        }
+
+        throw new TicketOperationException('credit_currency_mismatch', ErrorCode::ConfigCurrencyInvalid->value, 400, [
+            'currency_code' => $currencyCode,
+            'expected_currency' => $defaultCurrency,
+        ]);
+    }
 }
--- a/app/Services/Ticket/TicketPreviewService.php
+++ b/app/Services/Ticket/TicketPreviewService.php
@@ -37,6 +37,8 @@ final class TicketPreviewService
        }

        $currencyCode = strtoupper((string) $payload['currency_code']);
+        $this->assertCreditCurrencyMatchesPlayer($player, $currencyCode);
+
        $lines = [];
        $totalBet = 0;
        $totalRebate = 0;
@@ -136,4 +138,21 @@ final class TicketPreviewService
            'warnings' => $warningRows,
        ];
    }
+
+    private function assertCreditCurrencyMatchesPlayer(Player $player, string $currencyCode): void
+    {
+        if (! PlayerFundingMode::usesCredit($player)) {
+            return;
+        }
+
+        $defaultCurrency = strtoupper((string) $player->default_currency);
+        if ($currencyCode === $defaultCurrency) {
+            return;
+        }
+
+        throw new TicketOperationException('credit_currency_mismatch', ErrorCode::ConfigCurrencyInvalid->value, 400, [
+            'currency_code' => $currencyCode,
+            'expected_currency' => $defaultCurrency,
+        ]);
+    }
 }
--- a/app/Services/Wallet/PlayerLedgerLogsService.php
+++ b/app/Services/Wallet/PlayerLedgerLogsService.php
@@ -182,12 +182,19 @@ final class PlayerLedgerLogsService
        $offset = max(0, ($page - 1) * $perPage);
        $pageRows = array_slice($simplified, $offset, $perPage);

-        $runningMinor = $this->playerCreditService->availableCreditMinor($player, $currency);
+        $creditLimitMinor = $this->creditLimitMinor($player, $currency);
+        $runningMinor = $this->clampCreditAvailableMinor(
+            $this->playerCreditService->availableCreditMinor($player, $currency),
+            $creditLimitMinor,
+        );
        foreach (array_slice($simplified, 0, $offset) as $priorRow) {
            if (! $this->adminCreditRowAffectsAvailableBalance($priorRow)) {
                continue;
            }
-            $runningMinor -= $this->adminCreditRowSignedDelta($priorRow);
+            $runningMinor = $this->clampCreditAvailableMinor(
+                $runningMinor - $this->adminCreditRowSignedDelta($priorRow),
+                $creditLimitMinor,
+            );
        }
        $items = [];
        foreach ($pageRows as $formatted) {
@@ -208,9 +215,9 @@ final class PlayerLedgerLogsService
                'balance_after_formatted' => CurrencyFormatter::fromMinor($runningMinor),
                'balance_before' => $signed >= 0
                    ? max(0, $runningMinor - $signed)
-                    : $runningMinor + abs($signed),
+                    : $this->clampCreditAvailableMinor($runningMinor + abs($signed), $creditLimitMinor),
            ]);
-            $runningMinor -= $signed;
+            $runningMinor = $this->clampCreditAvailableMinor($runningMinor - $signed, $creditLimitMinor);
        }

        return [
@@ -449,14 +456,16 @@ final class PlayerLedgerLogsService
            ->slice(0, $offset)
            ->filter(fn (object $entry): bool => $entry->source === 'credit')
            ->count();
+        $creditLimitMinor = $this->creditLimitMinor($player, $currency);
        $runningMinor = $this->advanceCreditLedgerRunningMinor(
            (int) $player->id,
            $reasonFilter,
            $this->playerCreditService->availableCreditMinor($player, $currency),
            $priorCreditRows,
+            $creditLimitMinor,
        );
        $items = $pageRows
-            ->map(function (object $entry) use (&$runningMinor, $player, $currency): array {
+            ->map(function (object $entry) use (&$runningMinor, $player, $currency, $creditLimitMinor): array {
                if ($entry->source === 'rebate') {
                    return $this->formatPlayerRebateRow($entry->row, $player, $currency);
                }
@@ -473,7 +482,7 @@ final class PlayerLedgerLogsService
                    $affectsBalance,
                );
                if ($affectsBalance) {
-                    $runningMinor -= $amount;
+                    $runningMinor = $this->clampCreditAvailableMinor($runningMinor - $amount, $creditLimitMinor);
                }

                return $formatted;
@@ -694,7 +703,10 @@ final class PlayerLedgerLogsService
        ?array $reasonFilter,
        int $runningMinor,
        int $skipRows,
+        int $creditLimitMinor,
    ): int {
+        $runningMinor = $this->clampCreditAvailableMinor($runningMinor, $creditLimitMinor);
+
        if ($skipRows <= 0) {
            return $runningMinor;
        }
@@ -707,12 +719,27 @@ final class PlayerLedgerLogsService
            if (! $this->creditReasonAffectsAvailableBalance((string) $row->reason)) {
                continue;
            }
-            $runningMinor -= (int) $row->amount;
+            $runningMinor = $this->clampCreditAvailableMinor($runningMinor - (int) $row->amount, $creditLimitMinor);
        }

        return $runningMinor;
    }

+    private function creditLimitMinor(Player $player, string $currency): int
+    {
+        $credit = DB::table('player_credit_accounts')->where('player_id', $player->id)->first();
+        if ($credit === null) {
+            return 0;
+        }
+
+        return \App\Support\CreditAmountScale::majorToMinor((int) $credit->credit_limit, $currency);
+    }
+
+    private function clampCreditAvailableMinor(int $amountMinor, int $creditLimitMinor): int
+    {
+        return min(max(0, $amountMinor), max(0, $creditLimitMinor));
+    }
+
    /**
     * @param  array<string, mixed>  $formatted
     */