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

- 添加ensureSuperAdmin方法，限制管理员设置操作权限
- 在AdminSettingController接口中新增权限检查，防止非超级管理员操作
- AdminPlayerIndexController新增direct agent筛选支持
- AdminPlayerUpdateController新增对信用玩家默认币别变更的拒绝逻辑
- 新增WalletSettlementBillsController，实现玩家信用盘账期账单摘要接口
- AgentProfileService调整，新增返点限额和分享比例自动下调机制，保持子代理及玩家配置不超父级
- AgentProfileService增加can_grant_extra_rebate权限继承限制，阻止无权限代理开启
- AgentSettlementPeriodCloseService增加玩家账单回水信用释放逻辑，确保信用额度同步
- PlayerCreditService新增释放账单回水对应信用逻辑，维护账期信用一致性
- TicketPlacementService和TicketPreviewService新增信用玩家投注币别匹配校验，防止币别不符
- PlayerLedgerLogsService优化信用额度计算，增加可用额度上下限限制，防止负值和超限
- 调整后台管理导航，仅超管可见设置入口，强化权限隔离
- 路由新增玩家信用账单查询接口
- 补充多项AgentProfile相关单元测试覆盖额度限制、返点继承、返点下调场景及权限限制
- 增加站点管理员登录测试，验证系统设置菜单不可见，提升用户权限体验

tests/Feature/AdminAgentProfileApiTest.php

@@ -297,6 +297,61 @@ test('child agent profile update rejects credit above parent available', functio
         ->assertJsonPath('code', ErrorCode::ValidationFailed->value);
 });
 
+test('agent profile update rejects credit below already allocated amount', function (): void {
+    $siteId = (int) DB::table('admin_sites')->where('is_default', true)->value('id');
+    $rootId = (int) DB::table('agent_nodes')->where('admin_site_id', $siteId)->where('depth', 0)->value('id');
+    $service = app(\App\Services\Agent\AgentNodeService::class);
+
+    \App\Models\AgentProfile::query()->updateOrCreate(
+        ['agent_node_id' => $rootId],
+        [
+            'total_share_rate' => 100,
+            'credit_limit' => 10000,
+            'allocated_credit' => 0,
+            'used_credit' => 0,
+            'rebate_limit' => 1,
+            'default_player_rebate' => 0,
+        ],
+    );
+
+    $super = AdminUser::query()->create([
+        'username' => 'below_allocated_super',
+        'name' => 'Below Allocated Super',
+        'email' => null,
+        'password' => Hash::make('secret-strong'),
+        'status' => 0,
+    ]);
+    grantSuperAdminRole($super);
+
+    $agent = $service->createChild($super, agentChildPayload([
+        'parent_id' => $rootId,
+        'code' => 'below-allocated-agent',
+        'name' => 'Below Allocated Agent',
+        'username' => 'below_allocated_agent',
+        'credit_limit' => 5000,
+    ]));
+    $service->createChild($super, agentChildPayload([
+        'parent_id' => $agent->id,
+        'code' => 'below-allocated-child',
+        'name' => 'Below Allocated Child',
+        'username' => 'below_allocated_child',
+        'credit_limit' => 3000,
+    ]));
+
+    $token = $super->createToken('test', ['*'], now()->addDay())->plainTextToken;
+
+    $this->withHeader('Authorization', 'Bearer '.$token)
+        ->putJson('/api/v1/admin/agent-nodes/'.$agent->id.'/profile', [
+            'credit_limit' => 2000,
+        ])
+        ->assertStatus(422)
+        ->assertJsonPath('code', ErrorCode::ValidationFailed->value);
+
+    $profile = DB::table('agent_profiles')->where('agent_node_id', $agent->id)->first();
+    expect((int) $profile->credit_limit)->toBe(5000)
+        ->and((int) $profile->allocated_credit)->toBe(3000);
+});
+
 test('child agent profile update rejects rebate above parent', function (): void {
     $siteId = (int) DB::table('admin_sites')->where('is_default', true)->value('id');
     $rootId = (int) DB::table('agent_nodes')->where('admin_site_id', $siteId)->where('depth', 0)->value('id');
@@ -385,6 +440,266 @@ test('agent profile update rejects default rebate above limit', function (): voi
         ->assertJsonPath('code', ErrorCode::ValidationFailed->value);
 });
 
+test('lowering agent rebate limit clamps descendant agent and player rebate profiles', function (): void {
+    $siteId = (int) DB::table('admin_sites')->where('is_default', true)->value('id');
+    $siteCode = (string) DB::table('admin_sites')->where('id', $siteId)->value('code');
+    $rootId = (int) DB::table('agent_nodes')->where('admin_site_id', $siteId)->where('depth', 0)->value('id');
+    $service = app(\App\Services\Agent\AgentNodeService::class);
+
+    \App\Models\AgentProfile::query()->updateOrCreate(
+        ['agent_node_id' => $rootId],
+        [
+            'total_share_rate' => 100,
+            'credit_limit' => 10000,
+            'allocated_credit' => 0,
+            'used_credit' => 0,
+            'rebate_limit' => 1,
+            'default_player_rebate' => 0,
+            'can_grant_extra_rebate' => true,
+        ],
+    );
+
+    $super = AdminUser::query()->create([
+        'username' => 'clamp_rebate_super',
+        'name' => 'Clamp Rebate Super',
+        'email' => null,
+        'password' => Hash::make('secret-strong'),
+        'status' => 0,
+    ]);
+    grantSuperAdminRole($super);
+
+    $agent = $service->createChild($super, agentChildPayload([
+        'parent_id' => $rootId,
+        'code' => 'clamp-rebate-agent',
+        'name' => 'Clamp Rebate Agent',
+        'username' => 'clamp_rebate_agent',
+        'rebate_limit' => 10,
+        'default_player_rebate' => 6,
+        'can_grant_extra_rebate' => true,
+    ]));
+    $childAgent = $service->createChild($super, agentChildPayload([
+        'parent_id' => $agent->id,
+        'code' => 'clamp-rebate-child',
+        'name' => 'Clamp Rebate Child',
+        'username' => 'clamp_rebate_child',
+        'rebate_limit' => 8,
+        'default_player_rebate' => 6,
+        'can_grant_extra_rebate' => true,
+    ]));
+    $grandchildAgent = $service->createChild($super, agentChildPayload([
+        'parent_id' => $childAgent->id,
+        'code' => 'clamp-rebate-grandchild',
+        'name' => 'Clamp Rebate Grandchild',
+        'username' => 'clamp_rebate_grandchild',
+        'rebate_limit' => 7,
+        'default_player_rebate' => 5,
+        'can_grant_extra_rebate' => true,
+    ]));
+
+    $directPlayer = \App\Models\Player::query()->create([
+        'site_code' => $siteCode,
+        'agent_node_id' => $agent->id,
+        'site_player_id' => 'clamp-direct-player',
+        'username' => 'clamp_direct_player',
+        'default_currency' => 'NPR',
+        'status' => 0,
+    ]);
+    $downlinePlayer = \App\Models\Player::query()->create([
+        'site_code' => $siteCode,
+        'agent_node_id' => $childAgent->id,
+        'site_player_id' => 'clamp-downline-player',
+        'username' => 'clamp_downline_player',
+        'default_currency' => 'NPR',
+        'status' => 0,
+    ]);
+    $grandchildPlayer = \App\Models\Player::query()->create([
+        'site_code' => $siteCode,
+        'agent_node_id' => $grandchildAgent->id,
+        'site_player_id' => 'clamp-grandchild-player',
+        'username' => 'clamp_grandchild_player',
+        'default_currency' => 'NPR',
+        'status' => 0,
+    ]);
+
+    DB::table('player_rebate_profiles')->insert([
+        [
+            'player_id' => $directPlayer->id,
+            'game_type' => '*',
+            'inherit_from_agent' => false,
+            'rebate_rate' => 0.10,
+            'extra_rebate_rate' => 0.03,
+            'created_at' => now(),
+            'updated_at' => now(),
+        ],
+        [
+            'player_id' => $downlinePlayer->id,
+            'game_type' => '*',
+            'inherit_from_agent' => false,
+            'rebate_rate' => 0.10,
+            'extra_rebate_rate' => 0.03,
+            'created_at' => now(),
+            'updated_at' => now(),
+        ],
+        [
+            'player_id' => $grandchildPlayer->id,
+            'game_type' => '*',
+            'inherit_from_agent' => false,
+            'rebate_rate' => 0.07,
+            'extra_rebate_rate' => 0.01,
+            'created_at' => now(),
+            'updated_at' => now(),
+        ],
+    ]);
+
+    $token = $super->createToken('test', ['*'], now()->addDay())->plainTextToken;
+
+    $this->withHeader('Authorization', 'Bearer '.$token)
+        ->putJson('/api/v1/admin/agent-nodes/'.$agent->id.'/profile', [
+            'rebate_limit' => 2,
+            'default_player_rebate' => 0,
+            'can_grant_extra_rebate' => false,
+        ])
+        ->assertOk()
+        ->assertJsonPath('data.rebate_limit', 2);
+
+    $directProfile = DB::table('player_rebate_profiles')->where('player_id', $directPlayer->id)->first();
+    expect(round((float) $directProfile->rebate_rate, 4))->toBe(0.02)
+        ->and(round((float) $directProfile->extra_rebate_rate, 4))->toBe(0.0);
+
+    $childProfile = DB::table('agent_profiles')->where('agent_node_id', $childAgent->id)->first();
+    expect(round((float) $childProfile->rebate_limit, 4))->toBe(0.02)
+        ->and(round((float) $childProfile->default_player_rebate, 4))->toBe(0.02)
+        ->and((bool) $childProfile->can_grant_extra_rebate)->toBeFalse();
+
+    $downlineProfile = DB::table('player_rebate_profiles')->where('player_id', $downlinePlayer->id)->first();
+    expect(round((float) $downlineProfile->rebate_rate, 4))->toBe(0.02)
+        ->and(round((float) $downlineProfile->extra_rebate_rate, 4))->toBe(0.0);
+
+    $grandchildProfile = DB::table('agent_profiles')->where('agent_node_id', $grandchildAgent->id)->first();
+    expect(round((float) $grandchildProfile->rebate_limit, 4))->toBe(0.02)
+        ->and(round((float) $grandchildProfile->default_player_rebate, 4))->toBe(0.02)
+        ->and((bool) $grandchildProfile->can_grant_extra_rebate)->toBeFalse();
+
+    $grandchildPlayerProfile = DB::table('player_rebate_profiles')->where('player_id', $grandchildPlayer->id)->first();
+    expect(round((float) $grandchildPlayerProfile->rebate_rate, 4))->toBe(0.02)
+        ->and(round((float) $grandchildPlayerProfile->extra_rebate_rate, 4))->toBe(0.0);
+});
+
+test('agent profile update rejects enabling extra rebate when parent disallows it', function (): void {
+    $siteId = (int) DB::table('admin_sites')->where('is_default', true)->value('id');
+    $rootId = (int) DB::table('agent_nodes')->where('admin_site_id', $siteId)->where('depth', 0)->value('id');
+    $service = app(\App\Services\Agent\AgentNodeService::class);
+
+    \App\Models\AgentProfile::query()->updateOrCreate(
+        ['agent_node_id' => $rootId],
+        [
+            'total_share_rate' => 100,
+            'credit_limit' => 10000,
+            'allocated_credit' => 0,
+            'used_credit' => 0,
+            'rebate_limit' => 1,
+            'default_player_rebate' => 0,
+            'can_grant_extra_rebate' => true,
+        ],
+    );
+
+    $super = AdminUser::query()->create([
+        'username' => 'extra_rebate_super',
+        'name' => 'Extra Rebate Super',
+        'email' => null,
+        'password' => Hash::make('secret-strong'),
+        'status' => 0,
+    ]);
+    grantSuperAdminRole($super);
+
+    $parent = $service->createChild($super, agentChildPayload([
+        'parent_id' => $rootId,
+        'code' => 'extra-rebate-parent',
+        'name' => 'Extra Rebate Parent',
+        'username' => 'extra_rebate_parent',
+        'rebate_limit' => 10,
+        'can_grant_extra_rebate' => false,
+    ]));
+    $child = $service->createChild($super, agentChildPayload([
+        'parent_id' => $parent->id,
+        'code' => 'extra-rebate-child',
+        'name' => 'Extra Rebate Child',
+        'username' => 'extra_rebate_child',
+        'rebate_limit' => 2,
+    ]));
+
+    $token = $super->createToken('test', ['*'], now()->addDay())->plainTextToken;
+
+    $this->withHeader('Authorization', 'Bearer '.$token)
+        ->putJson('/api/v1/admin/agent-nodes/'.$child->id.'/profile', [
+            'can_grant_extra_rebate' => true,
+        ])
+        ->assertStatus(422)
+        ->assertJsonPath('code', ErrorCode::ValidationFailed->value);
+});
+
+test('lowering agent share rate clamps descendant agent share rates', function (): void {
+    $siteId = (int) DB::table('admin_sites')->where('is_default', true)->value('id');
+    $rootId = (int) DB::table('agent_nodes')->where('admin_site_id', $siteId)->where('depth', 0)->value('id');
+    $service = app(\App\Services\Agent\AgentNodeService::class);
+
+    $super = AdminUser::query()->create([
+        'username' => 'clamp_share_super',
+        'name' => 'Clamp Share Super',
+        'email' => null,
+        'password' => Hash::make('secret-strong'),
+        'status' => 0,
+    ]);
+    grantSuperAdminRole($super);
+
+    $agent = $service->createChild($super, agentChildPayload([
+        'parent_id' => $rootId,
+        'code' => 'clamp-share-agent',
+        'name' => 'Clamp Share Agent',
+        'username' => 'clamp_share_agent',
+        'total_share_rate' => 60,
+    ]));
+    $childAgent = $service->createChild($super, agentChildPayload([
+        'parent_id' => $agent->id,
+        'code' => 'clamp-share-child',
+        'name' => 'Clamp Share Child',
+        'username' => 'clamp_share_child',
+        'total_share_rate' => 40,
+    ]));
+    $grandchildAgent = $service->createChild($super, agentChildPayload([
+        'parent_id' => $childAgent->id,
+        'code' => 'clamp-share-grandchild',
+        'name' => 'Clamp Share Grandchild',
+        'username' => 'clamp_share_grandchild',
+        'total_share_rate' => 25,
+    ]));
+    $lowShareGrandchild = $service->createChild($super, agentChildPayload([
+        'parent_id' => $childAgent->id,
+        'code' => 'clamp-share-low',
+        'name' => 'Clamp Share Low',
+        'username' => 'clamp_share_low',
+        'total_share_rate' => 15,
+    ]));
+
+    $token = $super->createToken('test', ['*'], now()->addDay())->plainTextToken;
+
+    $this->withHeader('Authorization', 'Bearer '.$token)
+        ->putJson('/api/v1/admin/agent-nodes/'.$agent->id.'/profile', [
+            'total_share_rate' => 20,
+        ])
+        ->assertOk()
+        ->assertJsonPath('data.total_share_rate', 20);
+
+    $childProfile = DB::table('agent_profiles')->where('agent_node_id', $childAgent->id)->first();
+    expect(round((float) $childProfile->total_share_rate, 4))->toBe(20.0);
+
+    $grandchildProfile = DB::table('agent_profiles')->where('agent_node_id', $grandchildAgent->id)->first();
+    expect(round((float) $grandchildProfile->total_share_rate, 4))->toBe(20.0);
+
+    $lowShareGrandchildProfile = DB::table('agent_profiles')->where('agent_node_id', $lowShareGrandchild->id)->first();
+    expect(round((float) $lowShareGrandchildProfile->total_share_rate, 4))->toBe(15.0);
+});
+
 test('partial agent profile update preserves unchanged share rate', function (): void {
     $siteId = (int) DB::table('admin_sites')->where('is_default', true)->value('id');
     $rootId = (int) DB::table('agent_nodes')->where('admin_site_id', $siteId)->where('depth', 0)->value('id');