feat: 增强玩家 API，新增 locale 和时间字段，更新钱包 API 以支持可用余额计算，添加错误码与多语言支持

tests/Feature/AdminWalletApiTest.php

@@ -0,0 +1,205 @@
+<?php
+
+use App\Lottery\ErrorCode;
+use App\Models\AdminUser;
+use App\Models\Player;
+use App\Models\PlayerWallet;
+use App\Models\TransferOrder;
+use App\Models\WalletTxn;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Illuminate\Support\Facades\Hash;
+
+uses(RefreshDatabase::class);
+
+function makeAdminToken(): string
+{
+    $admin = AdminUser::query()->create([
+        'username' => 'wallet_admin',
+        'name' => 'Wallet',
+        'email' => null,
+        'password' => Hash::make('secret-strong'),
+        'status' => 0,
+    ]);
+
+    return $admin->createToken('test', ['*'], now()->addDay())->plainTextToken;
+}
+
+test('admin wallet transfer orders list requires authentication', function (): void {
+    $this->getJson('/api/v1/admin/wallet/transfer-orders')
+        ->assertUnauthorized()
+        ->assertJsonPath('code', ErrorCode::AdminUnauthenticated->value);
+});
+
+test('admin lists transfer orders with player info', function (): void {
+    $token = makeAdminToken();
+
+    $player = Player::query()->create([
+        'site_code' => 'main',
+        'site_player_id' => 'p99',
+        'username' => 'u99',
+        'nickname' => null,
+        'default_currency' => 'NPR',
+        'status' => 0,
+    ]);
+
+    TransferOrder::query()->create([
+        'transfer_no' => 'TI_test_order_1',
+        'player_id' => $player->id,
+        'direction' => 'in',
+        'currency_code' => 'NPR',
+        'amount' => 1000,
+        'idempotent_key' => 'adm-test-1',
+        'status' => 'success',
+        'external_request_payload' => null,
+        'external_response_payload' => null,
+        'external_ref_no' => 'ref1',
+        'fail_reason' => null,
+        'finished_at' => now(),
+    ]);
+
+    $this->withHeader('Authorization', 'Bearer '.$token)
+        ->getJson('/api/v1/admin/wallet/transfer-orders?per_page=10')
+        ->assertOk()
+        ->assertJsonPath('code', ErrorCode::Success->value)
+        ->assertJsonPath('data.total', 1)
+        ->assertJsonPath('data.items.0.transfer_no', 'TI_test_order_1')
+        ->assertJsonPath('data.items.0.site_player_id', 'p99')
+        ->assertJsonPath('data.items.0.status', 'success');
+});
+
+test('admin filters abnormal transfer orders', function (): void {
+    $token = makeAdminToken();
+
+    $player = Player::query()->create([
+        'site_code' => 'main',
+        'site_player_id' => 'pa',
+        'username' => null,
+        'nickname' => null,
+        'default_currency' => 'NPR',
+        'status' => 0,
+    ]);
+
+    foreach (
+        [
+            ['TI_ok', 'success'],
+            ['TI_bad', 'failed'],
+            ['TI_wait', 'pending_reconcile'],
+        ] as [$no, $st]
+    ) {
+        TransferOrder::query()->create([
+            'transfer_no' => $no,
+            'player_id' => $player->id,
+            'direction' => 'in',
+            'currency_code' => 'NPR',
+            'amount' => 100,
+            'idempotent_key' => 'k-'.$no,
+            'status' => $st,
+            'external_request_payload' => null,
+            'external_response_payload' => null,
+            'external_ref_no' => null,
+            'fail_reason' => null,
+            'finished_at' => $st === 'success' ? now() : null,
+        ]);
+    }
+
+    $resp = $this->withHeader('Authorization', 'Bearer '.$token)
+        ->getJson('/api/v1/admin/wallet/transfer-orders?abnormal=1');
+
+    $resp->assertOk()->assertJsonPath('data.total', 2);
+});
+
+test('admin lists wallet transactions and filters abnormal', function (): void {
+    $token = makeAdminToken();
+
+    $player = Player::query()->create([
+        'site_code' => 'main',
+        'site_player_id' => 'pb',
+        'username' => null,
+        'nickname' => null,
+        'default_currency' => 'NPR',
+        'status' => 0,
+    ]);
+
+    $wallet = PlayerWallet::query()->create([
+        'player_id' => $player->id,
+        'wallet_type' => 'lottery',
+        'currency_code' => 'NPR',
+        'balance' => 5000,
+        'frozen_balance' => 0,
+        'status' => 0,
+        'version' => 1,
+    ]);
+
+    WalletTxn::query()->create([
+        'txn_no' => 'WX_posted_1',
+        'player_id' => $player->id,
+        'wallet_id' => $wallet->id,
+        'biz_type' => 'transfer_in',
+        'biz_no' => 'TI_x',
+        'direction' => 1,
+        'amount' => 100,
+        'balance_before' => 0,
+        'balance_after' => 100,
+        'status' => 'posted',
+        'external_ref_no' => null,
+        'idempotent_key' => 'ik1',
+        'remark' => null,
+    ]);
+
+    WalletTxn::query()->create([
+        'txn_no' => 'WX_pending_1',
+        'player_id' => $player->id,
+        'wallet_id' => $wallet->id,
+        'biz_type' => 'transfer_out',
+        'biz_no' => 'TO_x',
+        'direction' => 2,
+        'amount' => 50,
+        'balance_before' => 100,
+        'balance_after' => 50,
+        'status' => 'pending_reconcile',
+        'external_ref_no' => null,
+        'idempotent_key' => 'ik2',
+        'remark' => null,
+    ]);
+
+    $this->withHeader('Authorization', 'Bearer '.$token)
+        ->getJson('/api/v1/admin/wallet/transactions')
+        ->assertOk()
+        ->assertJsonPath('data.total', 2);
+
+    $this->withHeader('Authorization', 'Bearer '.$token)
+        ->getJson('/api/v1/admin/wallet/transactions?abnormal=1')
+        ->assertOk()
+        ->assertJsonPath('data.total', 1)
+        ->assertJsonPath('data.items.0.status', 'pending_reconcile');
+});
+
+test('admin shows player wallets', function (): void {
+    $token = makeAdminToken();
+
+    $player = Player::query()->create([
+        'site_code' => 'main',
+        'site_player_id' => 'pc',
+        'username' => null,
+        'nickname' => null,
+        'default_currency' => 'NPR',
+        'status' => 0,
+    ]);
+
+    PlayerWallet::query()->create([
+        'player_id' => $player->id,
+        'wallet_type' => 'lottery',
+        'currency_code' => 'NPR',
+        'balance' => 77700,
+        'frozen_balance' => 0,
+        'status' => 0,
+        'version' => 0,
+    ]);
+
+    $this->withHeader('Authorization', 'Bearer '.$token)
+        ->getJson('/api/v1/admin/players/'.$player->id.'/wallets')
+        ->assertOk()
+        ->assertJsonPath('data.player.site_player_id', 'pc')
+        ->assertJsonPath('data.wallets.0.balance', 77700)
+        ->assertJsonPath('data.wallets.0.available_balance', 77700);
+});

tests/Feature/PlayerFoundationTest.php

@@ -18,13 +18,26 @@ test('player me returns profile with dev bearer', function () {
         'status' => 0,
     ]);
 
-    $this->withHeader('Authorization', 'Bearer dev:'.$player->id)
+    $this->withHeaders([
+        'Authorization' => 'Bearer dev:'.$player->id,
+        'X-Locale' => 'zh',
+    ])
         ->getJson('/api/v1/player/me')
         ->assertOk()
         ->assertJsonPath('code', ErrorCode::Success->value)
         ->assertJsonPath('data.id', $player->id)
         ->assertJsonPath('data.site_player_id', 'uid-42')
-        ->assertJsonPath('data.username', 'alice');
+        ->assertJsonPath('data.username', 'alice')
+        ->assertJsonPath('data.locale', 'zh')
+        ->assertJsonStructure([
+            'data' => [
+                'last_login_at',
+                'created_at',
+            ],
+        ]);
+
+    $player->refresh();
+    expect($player->last_login_at)->not->toBeNull();
 });
 
 test('player auth missing bearer returns localized sso 8001', function () {
@@ -68,3 +81,45 @@ test('player me works with main site jwt when dev bypass is off', function () {
         ->assertOk()
         ->assertJsonPath('data.site_player_id', 'jwt-user-1');
 });
+
+test('jwt first successful login auto-registers player mapping', function () {
+    config(['lottery.player_auth.dev_bypass' => false]);
+    config(['lottery.main_site.sso_jwt_secret' => 'jwt-test-secret']);
+
+    expect(Player::query()->count())->toBe(0);
+
+    $jwt = JWT::encode([
+        'site_code' => 'main',
+        'site_player_id' => 'brand-new-sso-1',
+        'exp' => time() + 3600,
+    ], 'jwt-test-secret', 'HS256');
+
+    $this->withHeader('Authorization', 'Bearer '.$jwt)
+        ->getJson('/api/v1/player/me')
+        ->assertOk()
+        ->assertJsonPath('data.site_player_id', 'brand-new-sso-1')
+        ->assertJsonPath('data.default_currency', 'NPR');
+
+    expect(Player::query()->where('site_player_id', 'brand-new-sso-1')->count())->toBe(1);
+});
+
+test('player me rejects non-active status with 8005', function () {
+    $code = ErrorCode::PlayerAccountSuspended->value;
+    $player = Player::query()->create([
+        'site_code' => 'main',
+        'site_player_id' => 'frozen-1',
+        'username' => null,
+        'nickname' => null,
+        'default_currency' => 'NPR',
+        'status' => 1,
+    ]);
+
+    $this->withHeaders([
+        'Authorization' => 'Bearer dev:'.$player->id,
+        'Accept-Language' => 'zh-CN,zh;q=0.9',
+    ])
+        ->getJson('/api/v1/player/me')
+        ->assertStatus(403)
+        ->assertJsonPath('code', $code)
+        ->assertJsonPath('msg', __("sso.$code", [], 'zh'));
+});

tests/Feature/WalletBalanceTest.php

@@ -25,6 +25,7 @@ test('wallet balance creates lottery wallet row and returns zeros', function ()
     $response->assertOk()
         ->assertJsonPath('code', ErrorCode::Success->value)
         ->assertJsonPath('data.balance', 0)
+        ->assertJsonPath('data.available_balance', 0)
         ->assertJsonPath('data.frozen_balance', 0)
         ->assertJsonPath('data.currency_code', 'NPR')
         ->assertJsonPath('data.wallet_type', 'lottery')

tests/Feature/WalletLogsTest.php

@@ -0,0 +1,82 @@
+<?php
+
+use App\Lottery\ErrorCode;
+use App\Models\Player;
+use App\Models\PlayerWallet;
+use App\Models\WalletTxn;
+use Database\Seeders\CurrencySeeder;
+use Database\Seeders\LotterySettingsSeeder;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Illuminate\Support\Facades\Http;
+
+uses(RefreshDatabase::class);
+
+beforeEach(function (): void {
+    config(['lottery.main_site.wallet_api_url' => null]);
+    $this->seed(CurrencySeeder::class);
+    $this->seed(LotterySettingsSeeder::class);
+});
+
+test('wallet logs returns transfer rows and pagination', function () {
+    $player = Player::query()->create([
+        'site_code' => 'main',
+        'site_player_id' => 'wl1',
+        'username' => null,
+        'nickname' => null,
+        'default_currency' => 'NPR',
+        'status' => 0,
+    ]);
+
+    $this->withHeader('Authorization', 'Bearer dev:'.$player->id)
+        ->postJson('/api/v1/wallet/transfer-in', [
+            'amount' => 300,
+            'idempotent_key' => 'log-test-1',
+        ])
+        ->assertOk();
+
+    $this->withHeader('Authorization', 'Bearer dev:'.$player->id)
+        ->getJson('/api/v1/wallet/logs?page=1&size=10')
+        ->assertOk()
+        ->assertJsonPath('code', ErrorCode::Success->value)
+        ->assertJsonPath('data.total', 1)
+        ->assertJsonPath('data.items.0.type', 'transfer_in');
+
+    expect(WalletTxn::query()->where('player_id', $player->id)->count())->toBe(1);
+});
+
+test('wallet logs filters by type refund', function () {
+    $player = Player::query()->create([
+        'site_code' => 'main',
+        'site_player_id' => 'wl2',
+        'default_currency' => 'NPR',
+        'status' => 0,
+    ]);
+
+    PlayerWallet::query()->create([
+        'player_id' => $player->id,
+        'wallet_type' => 'lottery',
+        'currency_code' => 'NPR',
+        'balance' => 500,
+        'frozen_balance' => 0,
+        'status' => 0,
+        'version' => 0,
+    ]);
+
+    config(['lottery.main_site.wallet_api_url' => 'http://failure.test']);
+    Http::fake([
+        'failure.test/*' => Http::response(['success' => false, 'message' => 'no'], 200),
+    ]);
+
+    $this->withHeader('Authorization', 'Bearer dev:'.$player->id)
+        ->postJson('/api/v1/wallet/transfer-out', [
+            'amount' => 200,
+            'idempotent_key' => 'out-fail',
+        ])
+        ->assertStatus(400);
+
+    $this->withHeader('Authorization', 'Bearer dev:'.$player->id)
+        ->getJson('/api/v1/wallet/logs?type=refund')
+        ->assertOk()
+        ->assertJsonPath('data.total', 1)
+        ->assertJsonPath('data.items.0.type', 'refund');
+});

tests/Feature/WalletTransferTest.php

@@ -0,0 +1,245 @@
+<?php
+
+use App\Lottery\ErrorCode;
+use App\Models\Player;
+use App\Models\PlayerWallet;
+use App\Models\TransferOrder;
+use App\Models\WalletTxn;
+use App\Services\LotterySettings;
+use Database\Seeders\CurrencySeeder;
+use Database\Seeders\LotterySettingsSeeder;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Illuminate\Support\Facades\Http;
+
+uses(RefreshDatabase::class);
+
+beforeEach(function (): void {
+    config(['lottery.main_site.wallet_api_url' => null]);
+    $this->seed(CurrencySeeder::class);
+    $this->seed(LotterySettingsSeeder::class);
+});
+
+test('transfer in credits lottery wallet via stub main site', function () {
+    $player = Player::query()->create([
+        'site_code' => 'main',
+        'site_player_id' => 'u1',
+        'username' => 'a',
+        'nickname' => null,
+        'default_currency' => 'NPR',
+        'status' => 0,
+    ]);
+
+    $key = 'idem-'.uniqid('', true);
+
+    $response = $this->withHeader('Authorization', 'Bearer dev:'.$player->id)
+        ->postJson('/api/v1/wallet/transfer-in', [
+            'amount' => 500,
+            'currency' => 'NPR',
+            'idempotent_key' => $key,
+        ]);
+    $response->assertOk()
+        ->assertJsonPath('code', ErrorCode::Success->value)
+        ->assertJsonPath('data.amount', 500)
+        ->assertJsonPath('data.currency_code', 'NPR')
+        ->assertJsonPath('data.balance', 500)
+        ->assertJsonPath('data.lottery_balance_after', 500);
+
+    expect((string) $response->json('data.log_id'))->toStartWith('WX_');
+
+    $wallet = PlayerWallet::query()->where('player_id', $player->id)->first();
+    expect($wallet)->not->toBeNull()
+        ->and((int) $wallet->balance)->toBe(500);
+
+    $order = TransferOrder::query()->where('idempotent_key', $key)->first();
+    expect($order?->status)->toBe('success')
+        ->and($order->external_request_payload)->not->toBeNull()
+        ->and($order->external_request_payload['amount_minor'])->toBe(500)
+        ->and($order->external_request_payload['_meta']['stub'] ?? null)->toBeTrue();
+    expect(WalletTxn::query()->where('biz_type', 'transfer_in')->count())->toBe(1);
+});
+
+test('transfer in idempotent replay returns same success shape', function () {
+    $player = Player::query()->create([
+        'site_code' => 'main',
+        'site_player_id' => 'u2',
+        'username' => null,
+        'nickname' => null,
+        'default_currency' => 'NPR',
+        'status' => 0,
+    ]);
+
+    $key = 'idem-replay-1';
+
+    $first = $this->withHeader('Authorization', 'Bearer dev:'.$player->id)
+        ->postJson('/api/v1/wallet/transfer-in', [
+            'amount' => 100,
+            'idempotent_key' => $key,
+        ]);
+
+    $second = $this->withHeader('Authorization', 'Bearer dev:'.$player->id)
+        ->postJson('/api/v1/wallet/transfer-in', [
+            'amount' => 100,
+            'idempotent_key' => $key,
+        ]);
+
+    $first->assertOk();
+    $second->assertOk();
+
+    expect((string) $first->json('data.transfer_no'))->toBe((string) $second->json('data.transfer_no'))
+        ->and(PlayerWallet::query()->where('player_id', $player->id)->first()?->balance)->toBe(100);
+});
+
+test('transfer out debits lottery and matches stub credit', function () {
+    $player = Player::query()->create([
+        'site_code' => 'main',
+        'site_player_id' => 'u3',
+        'username' => null,
+        'nickname' => null,
+        'default_currency' => 'NPR',
+        'status' => 0,
+    ]);
+
+    PlayerWallet::query()->create([
+        'player_id' => $player->id,
+        'wallet_type' => 'lottery',
+        'currency_code' => 'NPR',
+        'balance' => 1000,
+        'frozen_balance' => 0,
+        'status' => 0,
+        'version' => 0,
+    ]);
+
+    $key = 'idem-out-1';
+
+    $this->withHeader('Authorization', 'Bearer dev:'.$player->id)
+        ->postJson('/api/v1/wallet/transfer-out', [
+            'amount' => 400,
+            'idempotent_key' => $key,
+        ])
+        ->assertOk()
+        ->assertJsonPath('data.lottery_balance_after', 600);
+
+    expect((int) PlayerWallet::query()->where('player_id', $player->id)->first()?->balance)->toBe(600);
+});
+
+test('transfer out insufficient balance fails with 1001', function () {
+    $player = Player::query()->create([
+        'site_code' => 'main',
+        'site_player_id' => 'u4',
+        'username' => null,
+        'nickname' => null,
+        'default_currency' => 'NPR',
+        'status' => 0,
+    ]);
+
+    $key = 'idem-out-broke';
+
+    $code = ErrorCode::WalletInsufficientBalance->value;
+
+    $this->withHeaders([
+        'Authorization' => 'Bearer dev:'.$player->id,
+        'X-Locale' => 'zh',
+    ])
+        ->postJson('/api/v1/wallet/transfer-out', [
+            'amount' => 100,
+            'idempotent_key' => $key,
+        ])
+        ->assertStatus(400)
+        ->assertJsonPath('code', $code)
+        ->assertJsonPath('msg', __("wallet.$code", [], 'zh'));
+
+    $this->withHeaders([
+        'Authorization' => 'Bearer dev:'.$player->id,
+        'X-Locale' => 'zh',
+    ])
+        ->postJson('/api/v1/wallet/transfer-out', [
+            'amount' => 100,
+            'idempotent_key' => $key,
+        ])
+        ->assertStatus(400)
+        ->assertJsonPath('code', $code);
+});
+
+test('transfer in disabled returns 1004', function () {
+    LotterySettings::put('wallet.transfer_in_enabled', false, 'wallet');
+
+    $player = Player::query()->create([
+        'site_code' => 'main',
+        'site_player_id' => 'u5',
+        'username' => null,
+        'nickname' => null,
+        'default_currency' => 'NPR',
+        'status' => 0,
+    ]);
+
+    $code = ErrorCode::WalletTransferInDisabled->value;
+
+    $this->withHeaders([
+        'Authorization' => 'Bearer dev:'.$player->id,
+        'Accept-Language' => 'en',
+    ])
+        ->postJson('/api/v1/wallet/transfer-in', [
+            'amount' => 10,
+            'idempotent_key' => 'disabled-test',
+        ])
+        ->assertStatus(400)
+        ->assertJsonPath('code', $code);
+});
+
+test('transfer in below min amount returns 1003', function () {
+    $player = Player::query()->create([
+        'site_code' => 'main',
+        'site_player_id' => 'u-min',
+        'username' => null,
+        'nickname' => null,
+        'default_currency' => 'NPR',
+        'status' => 0,
+    ]);
+
+    $code = ErrorCode::WalletAmountExceedsLimit->value;
+
+    $this->withHeaders([
+        'Authorization' => 'Bearer dev:'.$player->id,
+        'X-Locale' => 'zh',
+    ])
+        ->postJson('/api/v1/wallet/transfer-in', [
+            'amount' => 50,
+            'idempotent_key' => 'below-min',
+        ])
+        ->assertStatus(400)
+        ->assertJsonPath('code', $code);
+});
+
+test('transfer in http 504 marks order pending reconcile', function () {
+    Http::fake([
+        'fake-main.test/*' => Http::response([], 504),
+    ]);
+    config(['lottery.main_site.wallet_api_url' => 'http://fake-main.test']);
+    config(['lottery.main_site.wallet_debit_path' => 'debit']);
+
+    $player = Player::query()->create([
+        'site_code' => 'main',
+        'site_player_id' => 'u504',
+        'username' => null,
+        'nickname' => null,
+        'default_currency' => 'NPR',
+        'status' => 0,
+    ]);
+
+    $key = 'idem-504-'.uniqid('', true);
+
+    $this->withHeader('Authorization', 'Bearer dev:'.$player->id)
+        ->postJson('/api/v1/wallet/transfer-in', [
+            'amount' => 500,
+            'currency' => 'NPR',
+            'idempotent_key' => $key,
+        ])
+        ->assertStatus(409)
+        ->assertJsonPath('code', ErrorCode::WalletTransferPending->value);
+
+    $order = TransferOrder::query()->where('idempotent_key', $key)->first();
+    expect($order?->status)->toBe('pending_reconcile')
+        ->and($order->external_request_payload['currency_code'])->toBe('NPR')
+        ->and($order->external_request_payload['_meta']['path'] ?? null)->toBe('/debit');
+    expect(WalletTxn::query()->where('player_id', $player->id)->count())->toBe(0);
+});