feat: 增强奖池与钱包管理功能

更新 AdminJackpotPoolUpdateController 校验规则，禁止传入 current_amount。优化 AdminRiskPoolManualStatusController：更新奖池状态后同步 Redis 状态。在 TransferOrderReconcileController 中新增 completeCredit 方法，用于处理卡住的转账订单对账。调整 TransferOrderListController：优化转账订单处理条件。在 TicketItemsIndexController 中实现支持时区的日期筛选，提升日期处理准确性。扩展 JackpotPool 模型，新增 adjustments 关联关系。改进票据与钱包相关服务中的错误处理和事务管理。
2026-05-26 14:58:41 +08:00
parent 48349e3302
commit c8c90e3e94
45 changed files with 1877 additions and 104 deletions
--- a/app/Http/Controllers/Api/V1/Admin/Jackpot/AdminJackpotPoolAdjustController.php
+++ b/app/Http/Controllers/Api/V1/Admin/Jackpot/AdminJackpotPoolAdjustController.php
@@ -0,0 +1,69 @@
+<?php
+
+namespace App\Http\Controllers\Api\V1\Admin\Jackpot;
+
+use App\Models\JackpotPool;
+use App\Models\AdminUser;
+use App\Lottery\ErrorCode;
+use App\Support\ApiResponse;
+use Illuminate\Http\JsonResponse;
+use App\Http\Controllers\Controller;
+use App\Services\Jackpot\JackpotPoolAdjustmentService;
+use App\Http\Requests\Admin\Jackpot\AdminJackpotPoolAdjustRequest;
+use App\Http\Controllers\Api\V1\Admin\Jackpot\Concerns\PresentsJackpotPoolAdjustment;
+
+/**
+ * POST /api/v1/admin/jackpot/pools/{pool}/adjustments — 奖池余额调整（须备注，写流水）。
+ */
+final class AdminJackpotPoolAdjustController extends Controller
+{
+    use PresentsJackpotPoolAdjustment;
+
+    public function __construct(
+        private readonly JackpotPoolAdjustmentService $adjustments,
+    ) {}
+
+    public function __invoke(AdminJackpotPoolAdjustRequest $request, JackpotPool $pool): JsonResponse
+    {
+        $admin = $request->user();
+        if (! $admin instanceof AdminUser) {
+            return ApiResponse::error(
+                trans('admin.unauthenticated', [], $request->lotteryLocale()),
+                ErrorCode::AdminUnauthenticated->value,
+                null,
+                401,
+            );
+        }
+
+        try {
+            $row = $this->adjustments->apply(
+                $pool,
+                $admin,
+                (int) $request->validated('amount_delta'),
+                (string) $request->validated('reason'),
+                $request,
+            );
+        } catch (\RuntimeException $e) {
+            $msg = match ($e->getMessage()) {
+                'adjustment_delta_zero' => trans('jackpot.adjustment_delta_zero', [], $request->lotteryLocale()),
+                'adjustment_reason_required' => trans('jackpot.adjustment_reason_required', [], $request->lotteryLocale()),
+                'adjustment_would_make_balance_negative' => trans('jackpot.adjustment_negative_balance', [], $request->lotteryLocale()),
+                default => trans('api.client_error', [], $request->lotteryLocale()),
+            };
+
+            return ApiResponse::error($msg, ErrorCode::ClientHttpError->value, ['reason' => $e->getMessage()], 422);
+        }
+
+        $pool->refresh();
+
+        return ApiResponse::success([
+            'adjustment' => $this->adjustmentRow($row),
+            'pool' => [
+                'id' => (int) $pool->id,
+                'currency_code' => $pool->currency_code,
+                'current_amount' => (int) $pool->current_amount,
+                'updated_at' => $pool->updated_at?->toIso8601String(),
+            ],
+        ]);
+    }
+}
--- a/app/Http/Controllers/Api/V1/Admin/Jackpot/AdminJackpotPoolAdjustmentIndexController.php
+++ b/app/Http/Controllers/Api/V1/Admin/Jackpot/AdminJackpotPoolAdjustmentIndexController.php
@@ -0,0 +1,43 @@
+<?php
+
+namespace App\Http\Controllers\Api\V1\Admin\Jackpot;
+
+use App\Models\JackpotPool;
+use App\Support\ApiResponse;
+use App\Models\JackpotPoolAdjustment;
+use Illuminate\Http\JsonResponse;
+use App\Http\Controllers\Controller;
+use App\Support\PaginationTrait;
+use Illuminate\Http\Request;
+use App\Http\Controllers\Api\V1\Admin\Jackpot\Concerns\PresentsJackpotPoolAdjustment;
+
+/**
+ * GET /api/v1/admin/jackpot/pools/{pool}/adjustments — 奖池余额调整流水。
+ */
+final class AdminJackpotPoolAdjustmentIndexController extends Controller
+{
+    use PaginationTrait;
+    use PresentsJackpotPoolAdjustment;
+
+    public function __invoke(Request $request, JackpotPool $pool): JsonResponse
+    {
+        $perPage = $this->perPage($request, 'per_page', 10, 100);
+        $page = $this->page($request);
+
+        $paginator = JackpotPoolAdjustment::query()
+            ->where('jackpot_pool_id', $pool->id)
+            ->with('adminUser:id,username,name')
+            ->orderByDesc('id')
+            ->paginate($perPage, ['*'], 'page', $page);
+
+        return ApiResponse::success([
+            'items' => $paginator->getCollection()
+                ->map(fn (JackpotPoolAdjustment $row) => $this->adjustmentRow($row))
+                ->values()
+                ->all(),
+            'total' => $paginator->total(),
+            'page' => $paginator->currentPage(),
+            'per_page' => $paginator->perPage(),
+        ]);
+    }
+}
--- a/app/Http/Controllers/Api/V1/Admin/Jackpot/AdminJackpotPoolUpdateController.php
+++ b/app/Http/Controllers/Api/V1/Admin/Jackpot/AdminJackpotPoolUpdateController.php
@@ -16,7 +16,7 @@ final class AdminJackpotPoolUpdateController extends Controller
    public function __invoke(Request $request, JackpotPool $pool): JsonResponse
    {
        $data = $request->validate([
-            'current_amount' => 'sometimes|integer|min:0',
+            'current_amount' => 'prohibited',
            'contribution_rate' => 'sometimes|numeric|min:0|max:1',
            'trigger_threshold' => 'sometimes|integer|min:0',
            'payout_rate' => 'sometimes|numeric|min:0|max:1',
--- a/app/Http/Controllers/Api/V1/Admin/Jackpot/Concerns/PresentsJackpotPoolAdjustment.php
+++ b/app/Http/Controllers/Api/V1/Admin/Jackpot/Concerns/PresentsJackpotPoolAdjustment.php
@@ -0,0 +1,25 @@
+<?php
+
+namespace App\Http\Controllers\Api\V1\Admin\Jackpot\Concerns;
+
+use App\Models\JackpotPoolAdjustment;
+
+trait PresentsJackpotPoolAdjustment
+{
+    /** @return array<string, mixed> */
+    private function adjustmentRow(JackpotPoolAdjustment $row): array
+    {
+        return [
+            'id' => (int) $row->id,
+            'adjustment_no' => $row->adjustment_no,
+            'jackpot_pool_id' => (int) $row->jackpot_pool_id,
+            'admin_user_id' => (int) $row->admin_user_id,
+            'admin_username' => $row->adminUser?->username,
+            'amount_delta' => (int) $row->amount_delta,
+            'balance_before' => (int) $row->balance_before,
+            'balance_after' => (int) $row->balance_after,
+            'reason' => $row->reason,
+            'created_at' => $row->created_at?->toIso8601String(),
+        ];
+    }
+}
--- a/app/Http/Controllers/Api/V1/Admin/Risk/AdminRiskPoolManualStatusController.php
+++ b/app/Http/Controllers/Api/V1/Admin/Risk/AdminRiskPoolManualStatusController.php
@@ -10,9 +10,13 @@ use App\Models\RiskPoolLockLog;
 use Illuminate\Http\JsonResponse;
 use Illuminate\Support\Facades\DB;
 use App\Http\Controllers\Controller;
+use App\Services\Ticket\RiskPoolService;

 final class AdminRiskPoolManualStatusController extends Controller
 {
+    public function __construct(
+        private readonly RiskPoolService $riskPoolService,
+    ) {}
    public function close(Draw $draw, string $number_4d): JsonResponse
    {
        $pool = $this->updateStatus($draw, $number_4d, true, 'close', 'admin_manual_close');
@@ -79,7 +83,12 @@ final class AdminRiskPoolManualStatusController extends Controller
                ]);
            }

-            return $pool->fresh();
+            $fresh = $pool->fresh();
+            if ($fresh !== null) {
+                $this->riskPoolService->syncRedisStateFromPool($fresh);
+            }
+
+            return $fresh;
        });
    }

--- a/app/Http/Controllers/Api/V1/Admin/Wallet/TransferOrderListController.php
+++ b/app/Http/Controllers/Api/V1/Admin/Wallet/TransferOrderListController.php
@@ -122,7 +122,14 @@ final class TransferOrderListController extends Controller
            'idempotent_key' => $o->idempotent_key,
            'status' => $o->status,
            'can_reverse' => $canWriteWallet && $o->status === 'pending_reconcile',
-            'can_manually_process' => $canWriteWallet && in_array($o->status, ['processing', 'failed', 'pending_reconcile'], true),
+            'can_complete_credit' => $canWriteWallet
+                && $o->direction === 'in'
+                && $o->status === 'pending_reconcile'
+                && $o->fail_reason === 'lottery_credit_failed'
+                && trim((string) $o->external_ref_no) !== '',
+            'can_manually_process' => $canWriteWallet
+                && in_array($o->status, ['processing', 'failed', 'pending_reconcile'], true)
+                && ! ($o->direction === 'out' && $o->status === 'pending_reconcile'),
            'external_ref_no' => $o->external_ref_no,
            'external_request_payload' => $o->external_request_payload,
            'external_response_payload' => $o->external_response_payload,
--- a/app/Http/Controllers/Api/V1/Admin/Wallet/TransferOrderReconcileController.php
+++ b/app/Http/Controllers/Api/V1/Admin/Wallet/TransferOrderReconcileController.php
@@ -10,6 +10,7 @@ use App\Services\Wallet\LotteryTransferService;
 use App\Http\Controllers\Controller;
 use App\Http\Requests\Admin\Wallet\TransferOrderReverseRequest;
 use App\Http\Requests\Admin\Wallet\TransferOrderManuallyProcessRequest;
+use App\Http\Requests\Admin\Wallet\TransferOrderCompleteCreditRequest;
 use Illuminate\Http\JsonResponse;

 /**
@@ -71,4 +72,29 @@ final class TransferOrderReconcileController extends Controller

        return ApiResponse::success(['transfer_no' => $transferNo, 'status' => 'manually_processed']);
    }
+
+    public function completeCredit(TransferOrderCompleteCreditRequest $request, string $transferNo): JsonResponse
+    {
+        $order = TransferOrder::query()->where('transfer_no', $transferNo)->first();
+        if ($order === null) {
+            return ApiResponse::error(__('wallet.order_not_found'), 404);
+        }
+
+        try {
+            $this->transferService->reconcileTransferOrder(
+                $order,
+                'complete_credit',
+                (string) $request->validated('remark', ''),
+            );
+        } catch (WalletOperationException $e) {
+            return ApiResponse::error(
+                LotteryMessage::wallet($request, $e->lotteryCode),
+                $e->lotteryCode,
+                null,
+                $e->httpStatus,
+            );
+        }
+
+        return ApiResponse::success(['transfer_no' => $transferNo, 'status' => 'success']);
+    }
 }
--- a/app/Http/Controllers/Api/V1/Ticket/TicketDrawMyMatchController.php
+++ b/app/Http/Controllers/Api/V1/Ticket/TicketDrawMyMatchController.php
@@ -61,14 +61,14 @@ final class TicketDrawMyMatchController extends Controller
        $itemIds = TicketItem::query()
            ->where('draw_id', $draw->id)
            ->where('player_id', $player->id)
-            ->whereIn('status', ['pending_draw', 'settled_win', 'settled_lose'])
+            ->whereIn('status', ['pending_draw', 'pending_payout', 'settled_win', 'settled_lose'])
            ->pluck('id');

        $hasBets = $itemIds->isNotEmpty();
        $winningItemIds = TicketItem::query()
            ->where('draw_id', $draw->id)
            ->where('player_id', $player->id)
-            ->where('status', 'settled_win')
+            ->whereIn('status', ['settled_win', 'pending_payout'])
            ->where(function ($q): void {
                $q->where('win_amount', '>', 0)
                    ->orWhere('jackpot_win_amount', '>', 0);
@@ -90,7 +90,7 @@ final class TicketDrawMyMatchController extends Controller
        $sums = TicketItem::query()
            ->where('draw_id', $draw->id)
            ->where('player_id', $player->id)
-            ->whereIn('status', ['settled_win', 'settled_lose'])
+            ->whereIn('status', ['settled_win', 'settled_lose', 'pending_payout'])
            ->selectRaw('coalesce(sum(win_amount),0) as sum_win, coalesce(sum(jackpot_win_amount),0) as sum_jackpot')
            ->first();

--- a/app/Http/Controllers/Api/V1/Ticket/TicketItemShowController.php
+++ b/app/Http/Controllers/Api/V1/Ticket/TicketItemShowController.php
@@ -62,12 +62,13 @@ final class TicketItemShowController extends Controller
            ->where('biz_no', $order?->order_no)
            ->orderByDesc('id')
            ->first();
-        $payoutTxn = WalletTxn::query()
-            ->where('player_id', $player->id)
-            ->where('biz_type', 'settle_payout')
-            ->where('biz_no', 'like', 'SB%')
-            ->orderByDesc('id')
-            ->first();
+        $payoutTxn = $settlementBatch !== null
+            ? WalletTxn::query()
+                ->where('player_id', $player->id)
+                ->where('biz_type', 'settle_payout')
+                ->where('biz_no', 'SB'.$settlementBatch->id)
+                ->first()
+            : null;

        $timeline = [];
        if ($order?->created_at !== null) {
--- a/app/Http/Controllers/Api/V1/Ticket/TicketItemsIndexController.php
+++ b/app/Http/Controllers/Api/V1/Ticket/TicketItemsIndexController.php
@@ -2,9 +2,9 @@

 namespace App\Http\Controllers\Api\V1\Ticket;

+use Carbon\Carbon;
 use App\Models\Player;
 use App\Models\TicketItem;
-use App\Models\WalletTxn;
 use App\Support\ApiResponse;
 use Illuminate\Http\Request;
 use App\Support\PaginationTrait;
@@ -65,11 +65,13 @@ final class TicketItemsIndexController extends Controller
        }

        if ($startDate !== null) {
-            $query->whereHas('order', fn ($q) => $q->whereDate('created_at', '>=', $startDate));
+            $fromUtc = $this->scheduleDateStartUtc($startDate);
+            $query->whereHas('order', fn ($q) => $q->where('created_at', '>=', $fromUtc));
        }

        if ($endDate !== null) {
-            $query->whereHas('order', fn ($q) => $q->whereDate('created_at', '<=', $endDate));
+            $toUtc = $this->scheduleDateEndUtc($endDate);
+            $query->whereHas('order', fn ($q) => $q->where('created_at', '<=', $toUtc));
        }

        $paginator = $query->paginate(perPage: $perPage, page: $page);
@@ -119,4 +121,23 @@ final class TicketItemsIndexController extends Controller

        return $value;
    }
+
+    private function scheduleTimezone(): string
+    {
+        return (string) config('lottery.draw.timezone', 'UTC');
+    }
+
+    private function scheduleDateStartUtc(string $ymd): Carbon
+    {
+        return Carbon::createFromFormat('Y-m-d', $ymd, $this->scheduleTimezone())
+            ->startOfDay()
+            ->utc();
+    }
+
+    private function scheduleDateEndUtc(string $ymd): Carbon
+    {
+        return Carbon::createFromFormat('Y-m-d', $ymd, $this->scheduleTimezone())
+            ->endOfDay()
+            ->utc();
+    }
 }
--- a/app/Http/Controllers/Api/V1/Wallet/WalletLogsController.php
+++ b/app/Http/Controllers/Api/V1/Wallet/WalletLogsController.php
@@ -27,8 +27,8 @@ final class WalletLogsController extends Controller
        'transfer_out' => ['transfer_out'],
        'refund' => ['transfer_out_refund'],
        'reversal' => ['reversal'],
-        'bet' => ['bet_deduct', 'bet'],
-        'prize' => ['settle_payout', 'prize'],
+        'bet' => ['bet_deduct', 'bet', 'bet_reverse'],
+        'prize' => ['settle_payout', 'prize', 'jackpot_manual_payout'],
    ];

    public function __invoke(Request $request): JsonResponse
@@ -153,8 +153,9 @@ final class WalletLogsController extends Controller
    {
        return match ($biz) {
            'transfer_out_refund' => 'refund',
-            'bet_deduct' => 'bet',
-            'settle_payout' => 'prize',
+            'bet_deduct', 'bet' => 'bet',
+            'bet_reverse' => 'reversal',
+            'settle_payout', 'prize', 'jackpot_manual_payout' => 'prize',
            'reversal' => 'reversal',
            default => $biz,
        };
--- a/app/Http/Requests/Admin/Jackpot/AdminJackpotPoolAdjustRequest.php
+++ b/app/Http/Requests/Admin/Jackpot/AdminJackpotPoolAdjustRequest.php
@@ -0,0 +1,22 @@
+<?php
+
+namespace App\Http\Requests\Admin\Jackpot;
+
+use Illuminate\Foundation\Http\FormRequest;
+
+final class AdminJackpotPoolAdjustRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    /** @return array<string, mixed> */
+    public function rules(): array
+    {
+        return [
+            'amount_delta' => ['required', 'integer', 'not_in:0'],
+            'reason' => ['required', 'string', 'min:3', 'max:500'],
+        ];
+    }
+}
--- a/app/Http/Requests/Admin/Wallet/TransferOrderCompleteCreditRequest.php
+++ b/app/Http/Requests/Admin/Wallet/TransferOrderCompleteCreditRequest.php
@@ -0,0 +1,20 @@
+<?php
+
+namespace App\Http\Requests\Admin\Wallet;
+
+use Illuminate\Foundation\Http\FormRequest;
+
+final class TransferOrderCompleteCreditRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    public function rules(): array
+    {
+        return [
+            'remark' => ['sometimes', 'nullable', 'string', 'max:255'],
+        ];
+    }
+}