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

- 在多个控制器中引入 agent_node_id，以支持基于代理节点的权限和数据过滤。 - 更新 AdminRole 和 AdminUser 模型，新增角色范围和代理节点相关功能，提升角色管理的灵活性。 - 在请求验证中添加 agent_node_id 字段，确保 API 接口支持代理节点的相关操作。 - 优化 LotterySettings 服务，支持批量写入设置，提升配置管理的效率。 - 更新仪表板和报告服务，增强数据统计功能，确保管理员能够获取更全面的统计信息。
2026-06-02 14:36:58 +08:00
parent d5232c756f
commit 0841fbed32
96 changed files with 5004 additions and 182 deletions
--- a/app/Http/Controllers/Api/V1/Admin/Agent/AgentAdminUserRoleSyncController.php
+++ b/app/Http/Controllers/Api/V1/Admin/Agent/AgentAdminUserRoleSyncController.php
@@ -0,0 +1,56 @@
+<?php
+
+namespace App\Http\Controllers\Api\V1\Admin\Agent;
+
+use App\Models\AdminUser;
+use App\Support\ApiResponse;
+use App\Services\AuditLogger;
+use Illuminate\Http\JsonResponse;
+use App\Http\Controllers\Controller;
+use App\Services\Agent\AgentAdminUserService;
+use App\Support\AdminAgentNodeAccess;
+use App\Support\AdminUserApiPresenter;
+use App\Http\Requests\Admin\AgentAdminUserRoleSyncRequest;
+
+final class AgentAdminUserRoleSyncController extends Controller
+{
+    public function __invoke(
+        AgentAdminUserRoleSyncRequest $request,
+        AdminUser $admin_user,
+        AgentAdminUserService $service,
+    ): JsonResponse {
+        $admin = $request->lotteryAdmin();
+        abort_if($admin === null, 401);
+
+        $agent = $admin_user->primaryAgentNode();
+        if ($agent === null) {
+            abort(404);
+        }
+
+        $denied = AdminAgentNodeAccess::denyUnlessNodeVisible($admin, $agent);
+        if ($denied !== null) {
+            return $denied;
+        }
+
+        if (! $admin->isSuperAdmin() && ! $admin->hasAdminPermission('prd.agent.user.manage')) {
+            return AdminAgentNodeAccess::denyUnlessCanManageParent($admin, $agent);
+        }
+
+        $before = AdminUserApiPresenter::listItem($admin_user);
+        $user = $service->syncRoles($agent, $admin_user, $request->validated('role_ids'));
+        $after = AdminUserApiPresenter::listItem($user);
+
+        AuditLogger::recordForAdmin(
+            $admin,
+            $request,
+            'agent',
+            'agent_admin_user.sync_roles',
+            'admin_user',
+            (string) $user->id,
+            $before,
+            $after,
+        );
+
+        return ApiResponse::success($after);
+    }
+}
--- a/app/Http/Controllers/Api/V1/Admin/Agent/AgentNodeAdminUserIndexController.php
+++ b/app/Http/Controllers/Api/V1/Admin/Agent/AgentNodeAdminUserIndexController.php
@@ -0,0 +1,41 @@
+<?php
+
+namespace App\Http\Controllers\Api\V1\Admin\Agent;
+
+use App\Models\AdminUser;
+use App\Models\AgentNode;
+use App\Support\ApiResponse;
+use Illuminate\Http\Request;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Support\Facades\DB;
+use App\Http\Controllers\Controller;
+use App\Support\AdminAgentNodeAccess;
+use App\Support\AdminUserApiPresenter;
+
+final class AgentNodeAdminUserIndexController extends Controller
+{
+    public function __invoke(Request $request, AgentNode $agent_node): JsonResponse
+    {
+        $admin = $request->lotteryAdmin();
+        abort_if($admin === null, 401);
+
+        $denied = AdminAgentNodeAccess::denyUnlessNodeVisible($admin, $agent_node);
+        if ($denied !== null) {
+            return $denied;
+        }
+
+        $userIds = DB::table('admin_user_agents')
+            ->where('agent_node_id', $agent_node->id)
+            ->pluck('admin_user_id');
+
+        $users = AdminUser::query()
+            ->whereIn('id', $userIds)
+            ->orderBy('username')
+            ->get();
+
+        return ApiResponse::success([
+            'agent_node_id' => (int) $agent_node->id,
+            'items' => $users->map(static fn (AdminUser $user): array => AdminUserApiPresenter::listItem($user))->all(),
+        ]);
+    }
+}
--- a/app/Http/Controllers/Api/V1/Admin/Agent/AgentNodeAdminUserStoreController.php
+++ b/app/Http/Controllers/Api/V1/Admin/Agent/AgentNodeAdminUserStoreController.php
@@ -0,0 +1,49 @@
+<?php
+
+namespace App\Http\Controllers\Api\V1\Admin\Agent;
+
+use App\Models\AgentNode;
+use App\Support\ApiResponse;
+use App\Services\AuditLogger;
+use Illuminate\Http\JsonResponse;
+use App\Http\Controllers\Controller;
+use App\Services\Agent\AgentAdminUserService;
+use App\Support\AdminAgentNodeAccess;
+use App\Support\AdminUserApiPresenter;
+use App\Http\Requests\Admin\AgentAdminUserStoreRequest;
+
+final class AgentNodeAdminUserStoreController extends Controller
+{
+    public function __invoke(
+        AgentAdminUserStoreRequest $request,
+        AgentNode $agent_node,
+        AgentAdminUserService $service,
+    ): JsonResponse {
+        $admin = $request->lotteryAdmin();
+        abort_if($admin === null, 401);
+
+        $denied = AdminAgentNodeAccess::denyUnlessNodeVisible($admin, $agent_node);
+        if ($denied !== null) {
+            return $denied;
+        }
+
+        if (! $admin->isSuperAdmin() && ! $admin->hasAdminPermission('prd.agent.user.manage')) {
+            return AdminAgentNodeAccess::denyUnlessCanManageParent($admin, $agent_node);
+        }
+
+        $user = $service->createUnderAgent($agent_node, $request->validated());
+
+        AuditLogger::recordForAdmin(
+            $admin,
+            $request,
+            'agent',
+            'agent_admin_user.create',
+            'admin_user',
+            (string) $user->id,
+            null,
+            AdminUserApiPresenter::listItem($user),
+        );
+
+        return ApiResponse::success(AdminUserApiPresenter::listItem($user))->setStatusCode(201);
+    }
+}
--- a/app/Http/Controllers/Api/V1/Admin/Agent/AgentNodeChildrenController.php
+++ b/app/Http/Controllers/Api/V1/Admin/Agent/AgentNodeChildrenController.php
@@ -0,0 +1,33 @@
+<?php
+
+namespace App\Http\Controllers\Api\V1\Admin\Agent;
+
+use App\Models\AgentNode;
+use App\Support\ApiResponse;
+use Illuminate\Http\Request;
+use Illuminate\Http\JsonResponse;
+use App\Http\Controllers\Controller;
+use App\Support\AdminAgentNodeAccess;
+use App\Support\AgentNodePresenter;
+
+final class AgentNodeChildrenController extends Controller
+{
+    public function __invoke(Request $request, AgentNode $agent_node): JsonResponse
+    {
+        $admin = $request->lotteryAdmin();
+        abort_if($admin === null, 401);
+
+        $denied = AdminAgentNodeAccess::denyUnlessNodeVisible($admin, $agent_node);
+        if ($denied !== null) {
+            return $denied;
+        }
+
+        $items = $agent_node->children()
+            ->orderBy('code')
+            ->get()
+            ->map(static fn (AgentNode $child): array => AgentNodePresenter::item($child))
+            ->all();
+
+        return ApiResponse::success(['items' => $items]);
+    }
+}
--- a/app/Http/Controllers/Api/V1/Admin/Agent/AgentNodeDelegationGrantIndexController.php
+++ b/app/Http/Controllers/Api/V1/Admin/Agent/AgentNodeDelegationGrantIndexController.php
@@ -0,0 +1,56 @@
+<?php
+
+namespace App\Http\Controllers\Api\V1\Admin\Agent;
+
+use App\Http\Controllers\Controller;
+use App\Models\AgentNode;
+use App\Services\Agent\AgentDelegationService;
+use App\Support\AdminAgentNodeAccess;
+use App\Support\AgentDelegationAuthorization;
+use App\Support\ApiMessage;
+use App\Support\ApiResponse;
+use App\Lottery\ErrorCode;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+
+final class AgentNodeDelegationGrantIndexController extends Controller
+{
+    public function __invoke(
+        Request $request,
+        AgentNode $agent_node,
+        AgentDelegationService $service,
+    ): JsonResponse {
+        $admin = $request->lotteryAdmin();
+        abort_if($admin === null, 401);
+
+        $denied = AdminAgentNodeAccess::denyUnlessNodeVisible($admin, $agent_node);
+        if ($denied !== null) {
+            return $denied;
+        }
+
+        if ($agent_node->isRoot()) {
+            return ApiMessage::errorResponse(
+                $request,
+                'admin.agent_delegation_root_denied',
+                ErrorCode::ValidationFailed->value,
+                null,
+                422,
+            );
+        }
+
+        if (! AgentDelegationAuthorization::childIsManageableBy($admin, $agent_node)) {
+            return ApiMessage::errorResponse(
+                $request,
+                'admin.agent_delegation_manage_denied',
+                ErrorCode::AdminForbidden->value,
+                null,
+                403,
+            );
+        }
+
+        return ApiResponse::success([
+            'child_agent_id' => (int) $agent_node->id,
+            'grants' => $service->listForChild($agent_node, $admin),
+        ]);
+    }
+}
--- a/app/Http/Controllers/Api/V1/Admin/Agent/AgentNodeDelegationGrantSyncController.php
+++ b/app/Http/Controllers/Api/V1/Admin/Agent/AgentNodeDelegationGrantSyncController.php
@@ -0,0 +1,72 @@
+<?php
+
+namespace App\Http\Controllers\Api\V1\Admin\Agent;
+
+use App\Http\Controllers\Controller;
+use App\Http\Requests\Admin\AgentDelegationGrantSyncRequest;
+use App\Models\AgentNode;
+use App\Services\Agent\AgentDelegationService;
+use App\Services\AuditLogger;
+use App\Support\AdminAgentNodeAccess;
+use App\Support\AgentDelegationAuthorization;
+use App\Support\ApiMessage;
+use App\Support\ApiResponse;
+use App\Lottery\ErrorCode;
+use Illuminate\Http\JsonResponse;
+
+final class AgentNodeDelegationGrantSyncController extends Controller
+{
+    public function __invoke(
+        AgentDelegationGrantSyncRequest $request,
+        AgentNode $agent_node,
+        AgentDelegationService $service,
+    ): JsonResponse {
+        $admin = $request->lotteryAdmin();
+        abort_if($admin === null, 401);
+
+        $denied = AdminAgentNodeAccess::denyUnlessNodeVisible($admin, $agent_node);
+        if ($denied !== null) {
+            return $denied;
+        }
+
+        if ($agent_node->isRoot()) {
+            return ApiMessage::errorResponse(
+                $request,
+                'admin.agent_delegation_root_denied',
+                ErrorCode::ValidationFailed->value,
+                null,
+                422,
+            );
+        }
+
+        if (! AgentDelegationAuthorization::childIsManageableBy($admin, $agent_node)) {
+            return ApiMessage::errorResponse(
+                $request,
+                'admin.agent_delegation_manage_denied',
+                ErrorCode::AdminForbidden->value,
+                null,
+                403,
+            );
+        }
+
+        $before = $service->listForChild($agent_node);
+        $grants = $request->validated('grants');
+        $after = $service->syncGrants($admin, $agent_node, $grants);
+
+        AuditLogger::recordForAdmin(
+            $admin,
+            $request,
+            'agent',
+            'agent.delegation.sync',
+            'agent_node',
+            (string) $agent_node->id,
+            ['grants' => $before],
+            ['grants' => $after],
+        );
+
+        return ApiResponse::success([
+            'child_agent_id' => (int) $agent_node->id,
+            'grants' => $after,
+        ]);
+    }
+}
--- a/app/Http/Controllers/Api/V1/Admin/Agent/AgentNodeDestroyController.php
+++ b/app/Http/Controllers/Api/V1/Admin/Agent/AgentNodeDestroyController.php
@@ -0,0 +1,70 @@
+<?php
+
+namespace App\Http\Controllers\Api\V1\Admin\Agent;
+
+use App\Lottery\ErrorCode;
+use App\Models\AgentNode;
+use App\Support\ApiMessage;
+use App\Support\ApiResponse;
+use App\Services\AuditLogger;
+use Illuminate\Http\JsonResponse;
+use App\Http\Controllers\Controller;
+use App\Services\Agent\AgentNodeService;
+use App\Support\AdminAgentNodeAccess;
+use App\Support\AdminAgentScope;
+use App\Support\AgentNodePresenter;
+use Illuminate\Support\Facades\DB;
+
+final class AgentNodeDestroyController extends Controller
+{
+    public function __invoke(
+        \Illuminate\Http\Request $request,
+        AgentNode $agent_node,
+        AgentNodeService $service,
+    ): JsonResponse {
+        $admin = $request->lotteryAdmin();
+        abort_if($admin === null, 401);
+
+        $denied = AdminAgentNodeAccess::denyUnlessNodeVisible($admin, $agent_node);
+        if ($denied !== null) {
+            return $denied;
+        }
+
+        if (! AdminAgentScope::nodeManageableBy($admin, $agent_node)) {
+            return AdminAgentNodeAccess::denyUnlessNodeVisible($admin, $agent_node)
+                ?? AdminAgentNodeAccess::denyUnlessCanManageParent($admin, $agent_node);
+        }
+
+        if ($agent_node->isRoot()) {
+            return ApiMessage::errorResponse($request, 'admin.agent_root_delete_denied', ErrorCode::ValidationFailed->value, null, 422);
+        }
+
+        if ($agent_node->children()->exists()) {
+            return ApiMessage::errorResponse($request, 'admin.agent_node_has_children_cannot_delete', ErrorCode::ValidationFailed->value, null, 422);
+        }
+
+        if (DB::table('admin_user_agents')->where('agent_node_id', (int) $agent_node->id)->exists()) {
+            return ApiMessage::errorResponse($request, 'admin.agent_node_has_users_cannot_delete', ErrorCode::ValidationFailed->value, null, 422);
+        }
+
+        if (DB::table('admin_roles')->where('owner_agent_id', (int) $agent_node->id)->exists()) {
+            return ApiMessage::errorResponse($request, 'admin.agent_node_has_roles_cannot_delete', ErrorCode::ValidationFailed->value, null, 422);
+        }
+
+        $before = AgentNodePresenter::item($agent_node);
+        $service->destroy($agent_node);
+
+        AuditLogger::recordForAdmin(
+            $admin,
+            $request,
+            'system',
+            'agent_node.destroy',
+            'agent_node',
+            (string) $agent_node->id,
+            $before,
+            null,
+        );
+
+        return ApiResponse::success(null);
+    }
+}
--- a/app/Http/Controllers/Api/V1/Admin/Agent/AgentNodeRoleIndexController.php
+++ b/app/Http/Controllers/Api/V1/Admin/Agent/AgentNodeRoleIndexController.php
@@ -0,0 +1,38 @@
+<?php
+
+namespace App\Http\Controllers\Api\V1\Admin\Agent;
+
+use App\Models\AdminRole;
+use App\Models\AgentNode;
+use App\Support\ApiResponse;
+use Illuminate\Http\Request;
+use Illuminate\Http\JsonResponse;
+use App\Http\Controllers\Controller;
+use App\Support\AdminAgentNodeAccess;
+use App\Support\AdminRoleApiPresenter;
+
+final class AgentNodeRoleIndexController extends Controller
+{
+    public function __invoke(Request $request, AgentNode $agent_node): JsonResponse
+    {
+        $admin = $request->lotteryAdmin();
+        abort_if($admin === null, 401);
+
+        $denied = AdminAgentNodeAccess::denyUnlessNodeVisible($admin, $agent_node);
+        if ($denied !== null) {
+            return $denied;
+        }
+
+        $roles = AdminRole::query()
+            ->where('scope_type', AdminRole::SCOPE_AGENT)
+            ->where('owner_agent_id', $agent_node->id)
+            ->orderBy('sort_order')
+            ->orderBy('id')
+            ->get();
+
+        return ApiResponse::success([
+            'agent_node_id' => (int) $agent_node->id,
+            'items' => $roles->map(static fn (AdminRole $role): array => AdminRoleApiPresenter::item($role))->all(),
+        ]);
+    }
+}
--- a/app/Http/Controllers/Api/V1/Admin/Agent/AgentNodeRoleStoreController.php
+++ b/app/Http/Controllers/Api/V1/Admin/Agent/AgentNodeRoleStoreController.php
@@ -0,0 +1,49 @@
+<?php
+
+namespace App\Http\Controllers\Api\V1\Admin\Agent;
+
+use App\Models\AgentNode;
+use App\Support\ApiResponse;
+use App\Services\AuditLogger;
+use Illuminate\Http\JsonResponse;
+use App\Http\Controllers\Controller;
+use App\Services\Agent\AgentRoleService;
+use App\Support\AdminAgentNodeAccess;
+use App\Support\AdminRoleApiPresenter;
+use App\Http\Requests\Admin\AgentRoleStoreRequest;
+
+final class AgentNodeRoleStoreController extends Controller
+{
+    public function __invoke(
+        AgentRoleStoreRequest $request,
+        AgentNode $agent_node,
+        AgentRoleService $service,
+    ): JsonResponse {
+        $admin = $request->lotteryAdmin();
+        abort_if($admin === null, 401);
+
+        $denied = AdminAgentNodeAccess::denyUnlessNodeVisible($admin, $agent_node);
+        if ($denied !== null) {
+            return $denied;
+        }
+
+        if (! $admin->isSuperAdmin() && ! $admin->hasAdminPermission('prd.agent.role.manage')) {
+            return AdminAgentNodeAccess::denyUnlessCanManageParent($admin, $agent_node);
+        }
+
+        $role = $service->createForAgent($admin, $agent_node, $request->validated());
+
+        AuditLogger::recordForAdmin(
+            $admin,
+            $request,
+            'agent',
+            'agent_role.create',
+            'admin_role',
+            (string) $role->id,
+            null,
+            AdminRoleApiPresenter::item($role),
+        );
+
+        return ApiResponse::success(AdminRoleApiPresenter::item($role));
+    }
+}
--- a/app/Http/Controllers/Api/V1/Admin/Agent/AgentNodeShowController.php
+++ b/app/Http/Controllers/Api/V1/Admin/Agent/AgentNodeShowController.php
@@ -0,0 +1,27 @@
+<?php
+
+namespace App\Http\Controllers\Api\V1\Admin\Agent;
+
+use App\Models\AgentNode;
+use App\Support\ApiResponse;
+use Illuminate\Http\Request;
+use Illuminate\Http\JsonResponse;
+use App\Http\Controllers\Controller;
+use App\Support\AdminAgentNodeAccess;
+use App\Support\AgentNodePresenter;
+
+final class AgentNodeShowController extends Controller
+{
+    public function __invoke(Request $request, AgentNode $agent_node): JsonResponse
+    {
+        $admin = $request->lotteryAdmin();
+        abort_if($admin === null, 401);
+
+        $denied = AdminAgentNodeAccess::denyUnlessNodeVisible($admin, $agent_node);
+        if ($denied !== null) {
+            return $denied;
+        }
+
+        return ApiResponse::success(AgentNodePresenter::item($agent_node));
+    }
+}
--- a/app/Http/Controllers/Api/V1/Admin/Agent/AgentNodeStoreController.php
+++ b/app/Http/Controllers/Api/V1/Admin/Agent/AgentNodeStoreController.php
@@ -0,0 +1,43 @@
+<?php
+
+namespace App\Http\Controllers\Api\V1\Admin\Agent;
+
+use App\Models\AgentNode;
+use App\Support\ApiResponse;
+use App\Services\AuditLogger;
+use Illuminate\Http\JsonResponse;
+use App\Http\Controllers\Controller;
+use App\Services\Agent\AgentNodeService;
+use App\Support\AdminAgentNodeAccess;
+use App\Support\AgentNodePresenter;
+use App\Http\Requests\Admin\AgentNodeStoreRequest;
+
+final class AgentNodeStoreController extends Controller
+{
+    public function __invoke(AgentNodeStoreRequest $request, AgentNodeService $service): JsonResponse
+    {
+        $admin = $request->lotteryAdmin();
+        abort_if($admin === null, 401);
+
+        $parent = AgentNode::query()->findOrFail((int) $request->validated('parent_id'));
+        $denied = AdminAgentNodeAccess::denyUnlessCanManageParent($admin, $parent);
+        if ($denied !== null) {
+            return $denied;
+        }
+
+        $node = $service->createChild($admin, $request->validated());
+
+        AuditLogger::recordForAdmin(
+            $admin,
+            $request,
+            'system',
+            'agent_node.create',
+            'agent_node',
+            (string) $node->id,
+            null,
+            AgentNodePresenter::item($node),
+        );
+
+        return ApiResponse::success(AgentNodePresenter::item($node));
+    }
+}
--- a/app/Http/Controllers/Api/V1/Admin/Agent/AgentNodeTreeController.php
+++ b/app/Http/Controllers/Api/V1/Admin/Agent/AgentNodeTreeController.php
@@ -0,0 +1,37 @@
+<?php
+
+namespace App\Http\Controllers\Api\V1\Admin\Agent;
+
+use App\Support\ApiResponse;
+use Illuminate\Http\Request;
+use Illuminate\Http\JsonResponse;
+use App\Http\Controllers\Controller;
+use App\Support\AdminAgentNodeAccess;
+use App\Support\AdminAgentScope;
+use App\Support\AgentNodePresenter;
+
+final class AgentNodeTreeController extends Controller
+{
+    public function __invoke(Request $request): JsonResponse
+    {
+        $admin = $request->lotteryAdmin();
+        abort_if($admin === null, 401);
+
+        $siteId = AdminAgentNodeAccess::resolveAdminSiteId(
+            $admin,
+            $request->integer('admin_site_id') ?: null,
+        );
+
+        $denied = AdminAgentNodeAccess::denyUnlessSiteResolved($admin, $siteId);
+        if ($denied !== null) {
+            return $denied;
+        }
+
+        $nodes = AdminAgentScope::visibleNodesQuery($admin, (int) $siteId)->get();
+
+        return ApiResponse::success([
+            'admin_site_id' => (int) $siteId,
+            'tree' => AgentNodePresenter::tree($nodes),
+        ]);
+    }
+}
--- a/app/Http/Controllers/Api/V1/Admin/Agent/AgentNodeUpdateController.php
+++ b/app/Http/Controllers/Api/V1/Admin/Agent/AgentNodeUpdateController.php
@@ -0,0 +1,57 @@
+<?php
+
+namespace App\Http\Controllers\Api\V1\Admin\Agent;
+
+use App\Models\AgentNode;
+use App\Support\ApiResponse;
+use App\Services\AuditLogger;
+use Illuminate\Http\JsonResponse;
+use App\Http\Controllers\Controller;
+use App\Services\Agent\AgentNodeService;
+use App\Support\AdminAgentNodeAccess;
+use App\Support\AdminAgentScope;
+use App\Support\AgentNodePresenter;
+use App\Http\Requests\Admin\AgentNodeUpdateRequest;
+
+final class AgentNodeUpdateController extends Controller
+{
+    public function __invoke(
+        AgentNodeUpdateRequest $request,
+        AgentNode $agent_node,
+        AgentNodeService $service,
+    ): JsonResponse {
+        $admin = $request->lotteryAdmin();
+        abort_if($admin === null, 401);
+
+        $denied = AdminAgentNodeAccess::denyUnlessNodeVisible($admin, $agent_node);
+        if ($denied !== null) {
+            return $denied;
+        }
+
+        if (! AdminAgentScope::nodeManageableBy($admin, $agent_node)) {
+            return AdminAgentNodeAccess::denyUnlessNodeVisible($admin, $agent_node)
+                ?? AdminAgentNodeAccess::denyUnlessCanManageParent($admin, $agent_node);
+        }
+
+        if ($agent_node->isRoot() && ! $admin->isSuperAdmin()) {
+            return AdminAgentNodeAccess::denyUnlessCanManageParent($admin, $agent_node);
+        }
+
+        $before = AgentNodePresenter::item($agent_node);
+        $node = $service->update($agent_node, $request->validated());
+        $after = AgentNodePresenter::item($node);
+
+        AuditLogger::recordForAdmin(
+            $admin,
+            $request,
+            'system',
+            'agent_node.update',
+            'agent_node',
+            (string) $node->id,
+            $before,
+            $after,
+        );
+
+        return ApiResponse::success($after);
+    }
+}
--- a/app/Http/Controllers/Api/V1/Admin/Agent/AgentRoleDestroyController.php
+++ b/app/Http/Controllers/Api/V1/Admin/Agent/AgentRoleDestroyController.php
@@ -0,0 +1,49 @@
+<?php
+
+namespace App\Http\Controllers\Api\V1\Admin\Agent;
+
+use App\Models\AdminRole;
+use App\Support\ApiResponse;
+use App\Services\AuditLogger;
+use Illuminate\Http\JsonResponse;
+use App\Http\Controllers\Controller;
+use App\Services\Agent\AgentRoleService;
+use App\Support\AgentRoleAuthorization;
+use App\Support\AdminRoleApiPresenter;
+
+final class AgentRoleDestroyController extends Controller
+{
+    public function __invoke(
+        \Illuminate\Http\Request $request,
+        AdminRole $admin_role,
+        AgentRoleService $service,
+    ): JsonResponse {
+        $admin = $request->lotteryAdmin();
+        abort_if($admin === null, 401);
+
+        if (! $admin_role->isAgentScoped()) {
+            abort(404);
+        }
+
+        $denied = AgentRoleAuthorization::denyUnlessRoleManageable($admin, $admin_role);
+        if ($denied !== null) {
+            return $denied;
+        }
+
+        $before = AdminRoleApiPresenter::item($admin_role);
+        $service->destroy($admin_role);
+
+        AuditLogger::recordForAdmin(
+            $admin,
+            $request,
+            'agent',
+            'agent_role.destroy',
+            'admin_role',
+            (string) $admin_role->id,
+            $before,
+            null,
+        );
+
+        return ApiResponse::success(null);
+    }
+}
--- a/app/Http/Controllers/Api/V1/Admin/Agent/AgentRolePermissionSyncController.php
+++ b/app/Http/Controllers/Api/V1/Admin/Agent/AgentRolePermissionSyncController.php
@@ -0,0 +1,55 @@
+<?php
+
+namespace App\Http\Controllers\Api\V1\Admin\Agent;
+
+use App\Models\AdminRole;
+use App\Support\ApiResponse;
+use App\Services\AuditLogger;
+use Illuminate\Http\JsonResponse;
+use App\Http\Controllers\Controller;
+use App\Services\Agent\AgentRoleService;
+use App\Support\AgentRoleAuthorization;
+use App\Support\AdminRoleApiPresenter;
+use App\Http\Requests\Admin\AgentRolePermissionSyncRequest;
+
+final class AgentRolePermissionSyncController extends Controller
+{
+    public function __invoke(
+        AgentRolePermissionSyncRequest $request,
+        AdminRole $admin_role,
+        AgentRoleService $service,
+    ): JsonResponse {
+        $admin = $request->lotteryAdmin();
+        abort_if($admin === null, 401);
+
+        if (! $admin_role->isAgentScoped()) {
+            abort(404);
+        }
+
+        $denied = AgentRoleAuthorization::denyUnlessRoleManageable($admin, $admin_role);
+        if ($denied !== null) {
+            return $denied;
+        }
+
+        if ($admin_role->isReadOnlyTemplate()) {
+            return AgentRoleAuthorization::denyUnlessRoleManageable($admin, $admin_role);
+        }
+
+        $slugs = array_values(array_unique($request->validated('permission_slugs')));
+        $before = AdminRoleApiPresenter::item($admin_role);
+        $role = $service->syncPermissions($admin, $admin_role, $slugs);
+
+        AuditLogger::recordForAdmin(
+            $admin,
+            $request,
+            'agent',
+            'agent_role.sync_permissions',
+            'admin_role',
+            (string) $role->id,
+            $before,
+            AdminRoleApiPresenter::item($role),
+        );
+
+        return ApiResponse::success(AdminRoleApiPresenter::item($role));
+    }
+}
--- a/app/Http/Controllers/Api/V1/Admin/Agent/AgentRoleUpdateController.php
+++ b/app/Http/Controllers/Api/V1/Admin/Agent/AgentRoleUpdateController.php
@@ -0,0 +1,54 @@
+<?php
+
+namespace App\Http\Controllers\Api\V1\Admin\Agent;
+
+use App\Models\AdminRole;
+use App\Support\ApiResponse;
+use App\Services\AuditLogger;
+use Illuminate\Http\JsonResponse;
+use App\Http\Controllers\Controller;
+use App\Services\Agent\AgentRoleService;
+use App\Support\AgentRoleAuthorization;
+use App\Support\AdminRoleApiPresenter;
+use App\Http\Requests\Admin\AgentRoleUpdateRequest;
+
+final class AgentRoleUpdateController extends Controller
+{
+    public function __invoke(
+        AgentRoleUpdateRequest $request,
+        AdminRole $admin_role,
+        AgentRoleService $service,
+    ): JsonResponse {
+        $admin = $request->lotteryAdmin();
+        abort_if($admin === null, 401);
+
+        if (! $admin_role->isAgentScoped()) {
+            abort(404);
+        }
+
+        $denied = AgentRoleAuthorization::denyUnlessRoleManageable($admin, $admin_role);
+        if ($denied !== null) {
+            return $denied;
+        }
+
+        if ($admin_role->isReadOnlyTemplate()) {
+            return AgentRoleAuthorization::denyUnlessRoleManageable($admin, $admin_role);
+        }
+
+        $before = AdminRoleApiPresenter::item($admin_role);
+        $role = $service->update($admin_role, $request->validated());
+
+        AuditLogger::recordForAdmin(
+            $admin,
+            $request,
+            'agent',
+            'agent_role.update',
+            'admin_role',
+            (string) $role->id,
+            $before,
+            AdminRoleApiPresenter::item($role),
+        );
+
+        return ApiResponse::success(AdminRoleApiPresenter::item($role));
+    }
+}