feat: enhance risk pool management and role validation

- Updated AGENTS.md to streamline information on risk pool operations and agent account restrictions.
- Introduced filtering options in AdminRiskPoolIndexController for active risk pools.
- Refactored AdminRiskPoolLockLogIndexController to support grouping by ticket or entry.
- Enhanced AdminRoleStoreController and AdminRoleUpdateController to prevent the use of reserved slugs for new roles.
- Improved error messaging for role creation and updates to clarify reserved role restrictions.
- Added new API routes for ticket item retrieval to improve admin functionalities.

app/Http/Controllers/Api/V1/Admin/User/AdminRoleStoreController.php

@@ -2,22 +2,71 @@
 
 namespace App\Http\Controllers\Api\V1\Admin\User;
 
+use App\Models\AdminRole;
 use App\Lottery\ErrorCode;
 use App\Support\ApiMessage;
+use App\Support\ApiResponse;
+use App\Services\AuditLogger;
 use Illuminate\Http\JsonResponse;
+use Illuminate\Support\Facades\DB;
 use App\Http\Controllers\Controller;
+use App\Support\AdminRoleApiPresenter;
+use App\Support\PlatformSystemRoles;
 use App\Http\Requests\Admin\AdminRoleStoreRequest;
 
 final class AdminRoleStoreController extends Controller
 {
     public function __invoke(AdminRoleStoreRequest $request): JsonResponse
     {
-        return ApiMessage::errorResponse(
+        $slug = strtolower(trim((string) $request->validated('slug')));
+        if (PlatformSystemRoles::isFixedSlug($slug)) {
+            return ApiMessage::errorResponse(
+                $request,
+                'admin.role_slug_reserved',
+                ErrorCode::ValidationFailed->value,
+                ['slug' => $slug],
+                422,
+            );
+        }
+
+        $role = DB::transaction(function () use ($request, $slug): AdminRole {
+            $maxSort = (int) AdminRole::query()
+                ->where('scope_type', AdminRole::SCOPE_SYSTEM)
+                ->max('sort_order');
+
+            /** @var AdminRole $role */
+            $role = AdminRole::query()->create([
+                'slug' => $slug,
+                'code' => $slug,
+                'name' => $request->validated('name'),
+                'description' => $request->validated('description'),
+                'status' => (int) ($request->validated('status') ?? 1),
+                'is_system' => false,
+                'sort_order' => max(100, $maxSort + 10),
+                'scope_type' => AdminRole::SCOPE_SYSTEM,
+                'owner_agent_id' => null,
+                'delegated_from_role_id' => null,
+            ]);
+
+            $permissionSlugs = $request->validated('permission_slugs', []);
+            if (is_array($permissionSlugs) && $permissionSlugs !== []) {
+                $role->syncLegacyPermissionSlugs(array_values($permissionSlugs));
+            }
+
+            return $role->refresh();
+        });
+
+        AuditLogger::recordForAdmin(
+            $request->lotteryAdmin(),
             $request,
-            'admin.platform_roles_fixed',
-            ErrorCode::ValidationFailed->value,
+            'system',
+            'admin_role.create',
+            'admin_role',
+            (string) $role->id,
             null,
-            422,
+            AdminRoleApiPresenter::item($role),
         );
+
+        return ApiResponse::success(AdminRoleApiPresenter::item($role))->setStatusCode(201);
     }
 }