refactor: 更新权限管理与请求验证逻辑

- 在多个控制器中将权限检查从 hasAdminPermission 更新为 hasPermissionCode，以增强权限管理的灵活性。
- 引入 AdminScopePolicy，优化基于代理节点的权限和数据过滤逻辑，确保管理员能够更精确地控制访问权限。
- 在请求验证中添加 agent_node_id 字段，确保 API 接口支持代理节点的相关操作。
- 更新 AdminUser 模型，新增 hasPermissionCode 方法，以支持更细粒度的权限检查。
- 优化审计日志记录逻辑，确保在处理请求时能够准确记录管理员的操作。

app/Http/Controllers/Api/V1/Admin/Settlement/AdminSettlementBatchAdjustmentController.php

@@ -0,0 +1,56 @@
+<?php
+
+namespace App\Http\Controllers\Api\V1\Admin\Settlement;
+
+use App\Models\AdminUser;
+use App\Support\ApiMessage;
+use App\Support\ApiResponse;
+use Illuminate\Http\JsonResponse;
+use App\Models\SettlementBatch;
+use App\Http\Controllers\Controller;
+use App\Support\LotteryMessage;
+use App\Exceptions\TicketOperationException;
+use App\Services\Settlement\SettlementPayoutCorrectionService;
+use App\Http\Requests\Admin\SettlementPayoutAdjustmentRequest;
+
+final class AdminSettlementBatchAdjustmentController extends Controller
+{
+    public function __construct(
+        private readonly SettlementPayoutCorrectionService $service,
+    ) {}
+
+    public function __invoke(SettlementPayoutAdjustmentRequest $request, SettlementBatch $batch): JsonResponse
+    {
+        $admin = $request->user();
+        if (! $admin instanceof AdminUser) {
+            return ApiResponse::error(
+                trans('admin.unauthenticated', [], $request->lotteryLocale()),
+                \App\Lottery\ErrorCode::AdminUnauthenticated->value,
+                null,
+                401,
+            );
+        }
+
+        try {
+            $result = $this->service->apply(
+                $batch,
+                $admin,
+                (int) $request->validated('player_id'),
+                (int) $request->validated('amount_delta'),
+                (string) $request->validated('reason'),
+                $request,
+            );
+        } catch (TicketOperationException $e) {
+            return ApiResponse::error(
+                LotteryMessage::wallet($request, $e->lotteryCode),
+                $e->lotteryCode,
+                $e->payload,
+                $e->httpStatus,
+            );
+        } catch (\RuntimeException $e) {
+            return ApiMessage::runtimeErrorResponse($request, $e, 0, 422);
+        }
+
+        return ApiResponse::success($result);
+    }
+}

app/Http/Controllers/Api/V1/Admin/Settlement/AdminSettlementBatchDetailsController.php

@@ -4,7 +4,7 @@ namespace App\Http\Controllers\Api\V1\Admin\Settlement;
 
 use Illuminate\Http\Request;
 use App\Support\AdminApiList;
-use App\Support\AdminSiteScope;
+use App\Support\AdminScopePolicy;
 use App\Support\AgentNodeApiPresenter;
 use App\Models\SettlementBatch;
 use Illuminate\Http\JsonResponse;
@@ -22,7 +22,7 @@ final class AdminSettlementBatchDetailsController extends Controller
         abort_if($admin === null, 401);
 
         $p = AdminApiList::readPaging($request);
-        $agentNodeId = $request->integer('agent_node_id') ?: null;
+        $scope = AdminScopePolicy::resolveContext($request, $admin);
 
         $detailQuery = TicketSettlementDetail::query()
             ->where('settlement_batch_id', $batch->id)
@@ -33,14 +33,9 @@ final class AdminSettlementBatchDetailsController extends Controller
                 'ticketItem.order:id,currency_code',
             ]);
 
-        if (! $admin->isSuperAdmin() || ($agentNodeId !== null && $agentNodeId > 0)) {
-            $detailQuery->whereHas('ticketItem.player', static function ($playerQuery) use ($admin, $agentNodeId): void {
-                AdminSiteScope::applyPlayerFilters(
-                    $playerQuery,
-                    $admin,
-                    null,
-                    $agentNodeId !== null && $agentNodeId > 0 ? $agentNodeId : null,
-                );
+        if (! $scope->isSuperAdmin() || $scope->effectiveRequestedAgentNodeId() !== null) {
+            $detailQuery->whereHas('ticketItem.player', function ($playerQuery) use ($scope): void {
+                AdminScopePolicy::applyPlayerFilters($playerQuery, $scope);
             });
         }
 

app/Http/Controllers/Api/V1/Admin/Settlement/AdminSettlementBatchIndexController.php

@@ -4,7 +4,7 @@ namespace App\Http\Controllers\Api\V1\Admin\Settlement;
 
 use Illuminate\Http\Request;
 use App\Support\AdminApiList;
-use App\Support\AdminSiteScope;
+use App\Support\AdminScopePolicy;
 use App\Models\SettlementBatch;
 use Illuminate\Http\JsonResponse;
 use App\Http\Controllers\Controller;
@@ -23,20 +23,15 @@ final class AdminSettlementBatchIndexController extends Controller
         $p = AdminApiList::readPaging($request);
         $drawNo = trim((string) $request->query('draw_no', ''));
         $status = trim((string) $request->query('status', ''));
-        $agentNodeId = $request->integer('agent_node_id') ?: null;
+        $scope = AdminScopePolicy::resolveContext($request, $admin);
 
         $q = SettlementBatch::query()
             ->with(['draw:id,draw_no'])
             ->orderByDesc('id');
 
-        if (! $admin->isSuperAdmin() || ($agentNodeId !== null && $agentNodeId > 0)) {
-            $q->whereHas('details.ticketItem.player', static function ($playerQuery) use ($admin, $agentNodeId): void {
-                AdminSiteScope::applyPlayerFilters(
-                    $playerQuery,
-                    $admin,
-                    null,
-                    $agentNodeId !== null && $agentNodeId > 0 ? $agentNodeId : null,
-                );
+        if (! $scope->isSuperAdmin() || $scope->effectiveRequestedAgentNodeId() !== null) {
+            $q->whereHas('details.ticketItem.player', function ($playerQuery) use ($scope): void {
+                AdminScopePolicy::applyPlayerFilters($playerQuery, $scope);
             });
         }