feat: 为玩家和管理员模块新增 API 路由与中间件别名

app/Http/Controllers/Api/V1/Admin/PingController.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace App\Http\Controllers\Api\V1\Admin;
+
+use App\Http\Controllers\Controller;
+use App\Support\ApiResponse;
+use Illuminate\Http\JsonResponse;
+
+/** 探路由用，上线前可删除或改为需登录 */
+class PingController extends Controller
+{
+    public function __invoke(): JsonResponse
+    {
+        return ApiResponse::success(['scope' => 'admin']);
+    }
+}

app/Http/Controllers/Api/V1/HealthController.php

@@ -0,0 +1,27 @@
+<?php
+
+namespace App\Http\Controllers\Api\V1;
+
+use App\Http\Controllers\Controller;
+use App\Support\ApiResponse;
+use Illuminate\Http\JsonResponse;
+
+class HealthController extends Controller
+{
+    /**
+     * 健康检查（Next / 网关探活）。路径：GET /api/v1/health
+     */
+    public function __invoke(): JsonResponse
+    {
+        $payload = [
+            'app' => config('app.name'),
+            'default_currency' => config('lottery.default_currency'),
+        ];
+
+        if (config('app.debug')) {
+            $payload['laravel'] = app()->version();
+        }
+
+        return ApiResponse::success($payload);
+    }
+}

app/Http/Controllers/Api/V1/Player/PingController.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace App\Http\Controllers\Api\V1\Player;
+
+use App\Http\Controllers\Controller;
+use App\Support\ApiResponse;
+use Illuminate\Http\JsonResponse;
+
+/** 探路由用，上线前可删除或改为需登录 */
+class PingController extends Controller
+{
+    public function __invoke(): JsonResponse
+    {
+        return ApiResponse::success(['scope' => 'player']);
+    }
+}

app/Http/Middleware/EnsureAdminApi.php

@@ -0,0 +1,18 @@
+<?php
+
+namespace App\Http\Middleware;
+
+use Closure;
+use Illuminate\Http\Request;
+use Symfony\Component\HttpFoundation\Response;
+
+/**
+ * 后台 API：后续在此校验管理员登录（如 Sanctum）与 RBAC。
+ */
+class EnsureAdminApi
+{
+    public function handle(Request $request, Closure $next): Response
+    {
+        return $next($request);
+    }
+}

app/Http/Middleware/EnsurePlayerApi.php

@@ -0,0 +1,18 @@
+<?php
+
+namespace App\Http\Middleware;
+
+use Closure;
+use Illuminate\Http\Request;
+use Symfony\Component\HttpFoundation\Response;
+
+/**
+ * 玩家端 API：后续在此校验 SSO / Bearer Token，并解析当前 players.id。
+ */
+class EnsurePlayerApi
+{
+    public function handle(Request $request, Closure $next): Response
+    {
+        return $next($request);
+    }
+}

app/Support/ApiResponse.php

@@ -0,0 +1,29 @@
+<?php
+
+namespace App\Support;
+
+use Illuminate\Http\JsonResponse;
+
+/**
+ * 与 PRD / docs/04-领域字典与编码规范.md 对齐：{ code, msg, data }。
+ */
+final class ApiResponse
+{
+    public static function success(mixed $data = null, string $msg = 'ok', int $code = 0): JsonResponse
+    {
+        return response()->json([
+            'code' => $code,
+            'msg' => $msg,
+            'data' => $data,
+        ]);
+    }
+
+    public static function error(string $msg, int $code, mixed $data = null, int $httpStatus = 400): JsonResponse
+    {
+        return response()->json([
+            'code' => $code,
+            'msg' => $msg,
+            'data' => $data,
+        ], $httpStatus);
+    }
+}

bootstrap/app.php

@@ -7,11 +7,15 @@ use Illuminate\Foundation\Configuration\Middleware;
 return Application::configure(basePath: dirname(__DIR__))
     ->withRouting(
         web: __DIR__.'/../routes/web.php',
+        api: __DIR__.'/../routes/api.php',
         commands: __DIR__.'/../routes/console.php',
         health: '/up',
     )
     ->withMiddleware(function (Middleware $middleware): void {
-        //
+        $middleware->alias([
+            'lottery.player' => \App\Http\Middleware\EnsurePlayerApi::class,
+            'lottery.admin' => \App\Http\Middleware\EnsureAdminApi::class,
+        ]);
     })
     ->withExceptions(function (Exceptions $exceptions): void {
         //

config/lottery.php

@@ -0,0 +1,15 @@
+<?php
+
+return [
+
+    'default_currency' => env('LOTTERY_DEFAULT_CURRENCY', 'NPR'),
+
+    'main_site' => [
+        'base_url' => env('MAIN_SITE_BASE_URL'),
+        'sso_jwt_secret' => env('MAIN_SITE_SSO_JWT_SECRET'),
+        'wallet_api_url' => env('MAIN_SITE_WALLET_API_URL'),
+        'wallet_api_key' => env('MAIN_SITE_WALLET_API_KEY'),
+        'wallet_timeout' => (int) env('MAIN_SITE_WALLET_TIMEOUT', 10),
+    ],
+
+];

routes/api.php

@@ -0,0 +1,30 @@
+<?php
+
+use App\Http\Controllers\Api\V1\Admin\PingController as AdminPingController;
+use App\Http\Controllers\Api\V1\HealthController;
+use App\Http\Controllers\Api\V1\Player\PingController as PlayerPingController;
+use Illuminate\Support\Facades\Route;
+
+/*
+| 全局前缀已由 bootstrap 注册为 /api，本文件内为相对路径。
+| 玩家端：/api/v1/player/...
+| 后台：  /api/v1/admin/...
+*/
+
+Route::prefix('v1')->group(function (): void {
+    Route::get('health', HealthController::class)->name('api.v1.health');
+
+    Route::middleware('lottery.player')
+        ->prefix('player')
+        ->name('api.v1.player.')
+        ->group(function (): void {
+            Route::get('ping', PlayerPingController::class)->name('ping');
+        });
+
+    Route::middleware('lottery.admin')
+        ->prefix('admin')
+        ->name('api.v1.admin.')
+        ->group(function (): void {
+            Route::get('ping', AdminPingController::class)->name('ping');
+        });
+});