From bbf58cb07607928246b0ac98c173aa6ca4b91272 Mon Sep 17 00:00:00 2001
From: kang <kangdeng28@gmail.com>
Date: Fri, 8 May 2026 13:47:48 +0800
Subject: [PATCH] =?UTF-8?q?feat:=20=E4=B8=BA=E7=8E=A9=E5=AE=B6=E5=92=8C?=
 =?UTF-8?q?=E7=AE=A1=E7=90=86=E5=91=98=E6=A8=A1=E5=9D=97=E6=96=B0=E5=A2=9E?=
 =?UTF-8?q?=20API=20=E8=B7=AF=E7=94=B1=E4=B8=8E=E4=B8=AD=E9=97=B4=E4=BB=B6?=
 =?UTF-8?q?=E5=88=AB=E5=90=8D?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../Api/V1/Admin/PingController.php           | 16 ++++++++++
 .../Controllers/Api/V1/HealthController.php   | 27 +++++++++++++++++
 .../Api/V1/Player/PingController.php          | 16 ++++++++++
 app/Http/Middleware/EnsureAdminApi.php        | 18 +++++++++++
 app/Http/Middleware/EnsurePlayerApi.php       | 18 +++++++++++
 app/Support/ApiResponse.php                   | 29 ++++++++++++++++++
 bootstrap/app.php                             |  6 +++-
 config/lottery.php                            | 15 ++++++++++
 routes/api.php                                | 30 +++++++++++++++++++
 9 files changed, 174 insertions(+), 1 deletion(-)
 create mode 100644 app/Http/Controllers/Api/V1/Admin/PingController.php
 create mode 100644 app/Http/Controllers/Api/V1/HealthController.php
 create mode 100644 app/Http/Controllers/Api/V1/Player/PingController.php
 create mode 100644 app/Http/Middleware/EnsureAdminApi.php
 create mode 100644 app/Http/Middleware/EnsurePlayerApi.php
 create mode 100644 app/Support/ApiResponse.php
 create mode 100644 config/lottery.php
 create mode 100644 routes/api.php

diff --git a/app/Http/Controllers/Api/V1/Admin/PingController.php b/app/Http/Controllers/Api/V1/Admin/PingController.php
new file mode 100644
index 0000000..275ede1
--- /dev/null
+++ b/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']);
+    }
+}
diff --git a/app/Http/Controllers/Api/V1/HealthController.php b/app/Http/Controllers/Api/V1/HealthController.php
new file mode 100644
index 0000000..a37422b
--- /dev/null
+++ b/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);
+    }
+}
diff --git a/app/Http/Controllers/Api/V1/Player/PingController.php b/app/Http/Controllers/Api/V1/Player/PingController.php
new file mode 100644
index 0000000..8ff80e4
--- /dev/null
+++ b/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']);
+    }
+}
diff --git a/app/Http/Middleware/EnsureAdminApi.php b/app/Http/Middleware/EnsureAdminApi.php
new file mode 100644
index 0000000..db0d045
--- /dev/null
+++ b/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);
+    }
+}
diff --git a/app/Http/Middleware/EnsurePlayerApi.php b/app/Http/Middleware/EnsurePlayerApi.php
new file mode 100644
index 0000000..2ca6567
--- /dev/null
+++ b/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);
+    }
+}
diff --git a/app/Support/ApiResponse.php b/app/Support/ApiResponse.php
new file mode 100644
index 0000000..1a3041b
--- /dev/null
+++ b/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);
+    }
+}
diff --git a/bootstrap/app.php b/bootstrap/app.php
index c183276..ed46bfb 100644
--- a/bootstrap/app.php
+++ b/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 {
         //
diff --git a/config/lottery.php b/config/lottery.php
new file mode 100644
index 0000000..2c126fc
--- /dev/null
+++ b/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),
+    ],
+
+];
diff --git a/routes/api.php b/routes/api.php
new file mode 100644
index 0000000..d773e83
--- /dev/null
+++ b/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');
+        });
+});