feat: 增强管理员功能与数据处理

- 在多个控制器中引入 agent_node_id，以支持基于代理节点的权限和数据过滤。
- 更新 AdminRole 和 AdminUser 模型，新增角色范围和代理节点相关功能，提升角色管理的灵活性。
- 在请求验证中添加 agent_node_id 字段，确保 API 接口支持代理节点的相关操作。
- 优化 LotterySettings 服务，支持批量写入设置，提升配置管理的效率。
- 更新仪表板和报告服务，增强数据统计功能，确保管理员能够获取更全面的统计信息。

app/Http/Controllers/Api/V1/Admin/Player/AdminPlayerIndexController.php

@@ -23,15 +23,20 @@ final class AdminPlayerIndexController extends Controller
         $keyword = trim((string) $request->query('keyword', ''));
         $status = $request->query('status');
         $siteCode = $request->query('site_code');
+        $agentNodeId = $request->integer('agent_node_id') ?: null;
 
         $q = Player::query()
-            ->with(['wallets' => static fn ($wq) => $wq->orderBy('wallet_type')->orderBy('currency_code')])
+            ->with([
+                'wallets' => static fn ($wq) => $wq->orderBy('wallet_type')->orderBy('currency_code'),
+                'agentNode:id,code,name',
+            ])
             ->orderByDesc('id');
 
         AdminSiteScope::applyPlayerFilters(
             $q,
             $admin,
             is_string($siteCode) ? $siteCode : null,
+            $agentNodeId,
         );
 
         if ($keyword !== '') {

app/Http/Controllers/Api/V1/Admin/Player/AdminPlayerStoreController.php

@@ -7,6 +7,7 @@ use App\Lottery\ErrorCode;
 use App\Support\ApiMessage;
 use App\Support\ApiResponse;
 use Illuminate\Http\JsonResponse;
+use App\Support\AdminAgentScope;
 use App\Support\AdminSiteScope;
 use App\Support\PlayerApiPresenter;
 use App\Http\Controllers\Controller;
@@ -34,8 +35,30 @@ final class AdminPlayerStoreController extends Controller
             return ApiMessage::errorResponse($request, 'admin.player_already_registered', ErrorCode::ValidationFailed->value, null, 422);
         }
 
+        $agentNodeId = $admin->isSuperAdmin()
+            ? $this->resolveAgentNodeIdForSuperAdmin($request->validated('agent_node_id'), $siteCode)
+            : $admin->primaryAgentNodeId();
+
+        if ($agentNodeId === null) {
+            return ApiMessage::errorResponse(
+                $request,
+                'admin.player_create_agent_required',
+                ErrorCode::ValidationFailed->value,
+                null,
+                422,
+            );
+        }
+
+        if (! $admin->isSuperAdmin()) {
+            $agent = AdminAgentScope::primaryAgentNode($admin);
+            if ($agent === null || (int) $agentNodeId !== (int) $agent->id) {
+                return ApiMessage::errorResponse($request, 'admin.player_create_agent_forbidden', ErrorCode::AdminForbidden->value, null, 403);
+            }
+        }
+
         $player = Player::query()->create([
             'site_code' => $request->validated('site_code'),
+            'agent_node_id' => $agentNodeId,
             'site_player_id' => $request->validated('site_player_id'),
             'username' => $request->validated('username'),
             'nickname' => $request->validated('nickname'),
@@ -45,4 +68,23 @@ final class AdminPlayerStoreController extends Controller
 
         return ApiResponse::success(PlayerApiPresenter::listItem($player))->setStatusCode(201);
     }
+
+    private function resolveAgentNodeIdForSuperAdmin(mixed $requested, string $siteCode): ?int
+    {
+        if ($requested !== null && (int) $requested > 0) {
+            return (int) $requested;
+        }
+
+        $siteId = \App\Models\AdminSite::query()->where('code', $siteCode)->value('id');
+        if ($siteId === null) {
+            return null;
+        }
+
+        $rootId = \App\Models\AgentNode::query()
+            ->where('admin_site_id', (int) $siteId)
+            ->where('depth', 0)
+            ->value('id');
+
+        return $rootId !== null ? (int) $rootId : null;
+    }
 }