feat: 增强玩家端 API 鉴权中间件，支持多语言错误消息返回

app/Http/Middleware/EnsurePlayerApi.php

@@ -5,15 +5,19 @@ namespace App\Http\Middleware;
 use App\Exceptions\PlayerAuthenticationException;
 use App\Services\PlayerTokenResolver;
 use App\Support\ApiResponse;
+use App\Support\LotteryMessage;
 use Closure;
 use Illuminate\Http\Request;
 use Symfony\Component\HttpFoundation\Response;
 
 /**
- * 玩家端受保护路由前置：解析 Authorization，失败时直接返回 { code, msg, data }，不进入控制器。
+ * 【玩家端 API 鉴权中间件】
  *
- * 成功后在 request 上挂 `lottery_player`，控制器内使用 `$request->lotteryPlayer()`
- *（由 AppServiceProvider 注册的宏，返回 ?Player）。
+ * - 成功：解析 Bearer → Player，写入 request attribute `lottery_player`。
+ * - 失败：直接 JSON 返回，不进入控制器；其中 msg 经由 LotteryMessage::sso() 按请求语言翻译
+ *         （依赖前置的 NegotiateLotteryLocale），code 仍为文档约定业务码（如 8001）。
+ *
+ * PlayerAuthenticationException 的 getMessage() 仅作开发与日志用语，可与 API msg 语种不一致。
  */
 class EnsurePlayerApi
 {
@@ -22,7 +26,13 @@ class EnsurePlayerApi
         try {
             $player = app(PlayerTokenResolver::class)->resolve($request);
         } catch (PlayerAuthenticationException $e) {
-            return ApiResponse::error($e->getMessage(), $e->lotteryCode, null, $e->httpStatus);
+            // msg：多语言用户提示；code / httpStatus：仍来自异常内业务定义
+            return ApiResponse::error(
+                LotteryMessage::sso($request, $e->lotteryCode),
+                $e->lotteryCode,
+                null,
+                $e->httpStatus,
+            );
         }
 
         // 使用 attributes，避免与 Laravel 内置 input 混淆

app/Http/Middleware/NegotiateLotteryLocale.php

@@ -0,0 +1,77 @@
+<?php
+
+namespace App\Http\Middleware;
+
+use Closure;
+use Illuminate\Http\Request;
+use Symfony\Component\HttpFoundation\Response;
+
+/**
+ * 【API 语言协商中间件】
+ *
+ * - 挂载位置：bootstrap/app.php 中对 api 分组 prepend，所有 /api/* 请求都会先执行本中间件。
+ * - 职责：解析客户端语言 → 写入 $request->attributes['lottery_locale'] → 调用 app()->setLocale()，
+ *         便于 trans()、LotteryMessage 及后续按 zh/en/ne 选库表文案列时使用。
+ *
+ * 【协商顺序】① 请求头 X-Locale（必须为 config 支持的 zh/en/ne 之一）；② Accept-Language 首选项；③ fallback。
+ *
+ * 【与前端】浏览器或 App 可直接带 X-Locale，或仅靠 Accept-Language；无需前端维护文案 JSON。
+ */
+class NegotiateLotteryLocale
+{
+    public function handle(Request $request, Closure $next): Response
+    {
+        $locale = $this->resolveLocale($request);
+        // attribute 名称固定为 lottery_locale，与 Request::lotteryLocale() 宏一致
+        $request->attributes->set('lottery_locale', $locale);
+        app()->setLocale($locale);
+
+        return $next($request);
+    }
+
+    /** 综合 X-Locale 与 Accept-Language，得到最终语言代码 */
+    private function resolveLocale(Request $request): string
+    {
+        /** @var list<string> $supported */
+        $supported = array_values(array_unique(config('lottery.locales.supported', ['en', 'zh', 'ne'])));
+        $fallback = (string) config('lottery.locales.fallback', 'en');
+
+        $header = strtolower(trim((string) $request->header('X-Locale', '')));
+        if ($header !== '' && in_array($header, $supported, true)) {
+            return $header;
+        }
+
+        return $this->fromAcceptLanguage((string) $request->header('Accept-Language', ''), $supported, $fallback);
+    }
+
+    /**
+     * 解析标准 Accept-Language（可带权重 q=），只认主语言段 zh / en / ne。
+     *
+     * @param  list<string>  $supported  config('lottery.locales.supported')
+     */
+    private function fromAcceptLanguage(string $header, array $supported, string $fallback): string
+    {
+        if ($header === '') {
+            return $fallback;
+        }
+
+        foreach (explode(',', $header) as $part) {
+            $code = strtolower(trim(explode(';', trim($part), 2)[0] ?? ''));
+            if ($code === '') {
+                continue;
+            }
+            $primary = explode('-', $code, 2)[0] ?? $code;
+            if ($primary === 'zh' && in_array('zh', $supported, true)) {
+                return 'zh';
+            }
+            if ($primary === 'ne' && in_array('ne', $supported, true)) {
+                return 'ne';
+            }
+            if ($primary === 'en' && in_array('en', $supported, true)) {
+                return 'en';
+            }
+        }
+
+        return $fallback;
+    }
+}

app/Providers/AppServiceProvider.php

@@ -26,5 +26,15 @@ class AppServiceProvider extends ServiceProvider
             /** @var Request $this */
             return $this->attributes->get('lottery_player');
         });
+
+        /**
+         * 【当前请求语言】zh / en / ne，与 lottery.locales.supported 对齐。
+         * 由 NegotiateLotteryLocale 写入 attribute；控制台等非 HTTP 或无该中间件时回落到 fallback。
+         */
+        Request::macro('lotteryLocale', function (): string {
+            /** @var Request $this */
+            return (string) ($this->attributes->get('lottery_locale')
+                ?? config('lottery.locales.fallback', 'en'));
+        });
     }
 }

app/Support/LotteryMessage.php

@@ -0,0 +1,36 @@
+<?php
+
+namespace App\Support;
+
+use Illuminate\Http\Request;
+
+/**
+ * 【业务文案翻译辅助类】
+ *
+ * 从 lang/{locale}/sso.php 等语言包取字符串，供 JSON 里「msg」字段使用。
+ * 当前实现：玩家 SSO / Bearer 鉴权相关错误码（8001–8004），见 docs/04 错误码段。
+ *
+ * 依赖 NegotiateLotteryLocale 已写入 lottery_locale；若未写则使用 fallback 语言包。
+ */
+final class LotteryMessage
+{
+    /**
+     * 取 SSO 鉴权类错误的用户可见文案（与 ApiResponse 的 msg 对应）。
+     *
+     * @param  int  $code  业务错误码，如 8001
+     */
+    public static function sso(Request $request, int $code): string
+    {
+        $fallback = (string) config('lottery.locales.fallback', 'en');
+        $locale = (string) ($request->attributes->get('lottery_locale') ?? $fallback);
+        $key = 'sso.'.$code; // 对应 lang/{locale}/sso.php 内键名，如 '8001'
+
+        $msg = trans($key, [], $locale);
+        // Laravel 无键时返回整条 key 字符串，此时改用 fallback 语言再试一次
+        if ($msg !== $key) {
+            return $msg;
+        }
+
+        return trans($key, [], $fallback);
+    }
+}