feat: 更新开发环境配置，支持在 local 和 testing 环境下的玩家身份绕过，新增钱包余额 API 路由

2026-05-08 16:02:46 +08:00
parent fc0999664a
commit 8954325194
8 changed files with 178 additions and 11 deletions
--- a/app/Http/Controllers/Api/V1/Wallet/WalletBalanceController.php
+++ b/app/Http/Controllers/Api/V1/Wallet/WalletBalanceController.php
@@ -0,0 +1,86 @@
+<?php
+
+namespace App\Http\Controllers\Api\V1\Wallet;
+
+use App\Http\Controllers\Controller;
+use App\Models\Player;
+use App\Models\PlayerWallet;
+use App\Support\ApiResponse;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+
+/**
+ * 【玩家】查询彩票侧钱包余额。
+ *
+ * 路由：`GET /api/v1/wallet/balance`，需 middleware `lottery.player`。
+ * PRD：`01-产品文档.md` §10.1.1；金额单位为最小货币 bigint（参见 `docs/04` §8）。
+ *
+ * 【行为要点】
+ * - 币种：优先 Query `currency`，否则使用玩家 `default_currency`，再回退 `config('lottery.default_currency')`
+ * - 若尚无 `player_wallets` 记录：按 `wallet_type=lottery` + 币种 **首次开立**一行（余额 0），便于新玩家直接进入查询
+ * - `main_balance`：主站钱包余额占位，接入主站 API 后再返回实数；当前固定 `null`
+ */
+class WalletBalanceController extends Controller
+{
+    private const WALLET_TYPE_LOTTERY = 'lottery';
+
+    public function __invoke(Request $request): JsonResponse
+    {
+        $player = $request->lotteryPlayer();
+        abort_if($player === null, 500, 'lottery_player missing');
+
+        $currencyCode = $this->resolveCurrencyCode($request, $player);
+        if ($currencyCode instanceof JsonResponse) {
+            return $currencyCode;
+        }
+
+        $wallet = PlayerWallet::query()->firstOrCreate(
+            [
+                'player_id' => $player->id,
+                'wallet_type' => self::WALLET_TYPE_LOTTERY,
+                'currency_code' => $currencyCode,
+            ],
+            [
+                'balance' => 0,
+                'frozen_balance' => 0,
+                'status' => 0,
+                'version' => 0,
+            ],
+        );
+
+        return ApiResponse::success([
+            'balance' => $wallet->balance,
+            'main_balance' => null,
+            'currency_code' => $wallet->currency_code,
+            'wallet_type' => $wallet->wallet_type,
+            'frozen_balance' => $wallet->frozen_balance,
+        ]);
+    }
+
+    /**
+     * @return string|JsonResponse 合法币种码或错误响应（code 1003：参数非法）
+     */
+    private function resolveCurrencyCode(Request $request, Player $player): string|JsonResponse
+    {
+        $raw = $request->query('currency');
+        if (is_string($raw) && $raw !== '') {
+            $code = strtoupper(substr(trim($raw), 0, 16));
+        } else {
+            $fallback = $player->default_currency ?? config('lottery.default_currency', 'NPR');
+            $code = strtoupper(substr(trim((string) $fallback), 0, 16));
+        }
+
+        // 币种码：字母数字，长度 1–16，与 migrations 字段一致
+        if (! preg_match('/^[A-Z0-9]{1,16}$/', $code)) {
+            // 业务码占用 1000–1999 钱包段；1003 已在 PRD 保留为「金额超出限制」，币种非法单用 1005
+            return ApiResponse::error(
+                __('wallet.invalid_currency'),
+                1005,
+                null,
+                400,
+            );
+        }
+
+        return $code;
+    }
+}