feat: Enhance settlement and draw management functionality

- Implement error handling for skipped settlement runs in DrawSettlementRunController, returning appropriate error messages based on draw status. - Add validation in DrawPublishService to ensure draws are ready for publication, rejecting outdated result batches. - Update SettlementBatchWorkflowService to revert ticket statuses upon settlement rejection and restore jackpot pool amounts. - Refactor LotteryTransferService to improve transaction handling for transfer order reconciliation, ensuring idempotency during reversals. - Add multi-language support for new error messages related to settlement processes.
2026-05-26 14:10:16 +08:00
parent e4118d7b1d
commit 48349e3302
10 changed files with 354 additions and 43 deletions
--- a/app/Http/Controllers/Api/V1/Admin/Draw/DrawSettlementRunController.php
+++ b/app/Http/Controllers/Api/V1/Admin/Draw/DrawSettlementRunController.php
@@ -36,8 +36,21 @@ final class DrawSettlementRunController extends Controller

        $draw->refresh();

+        if (! $ran) {
+            return ApiResponse::error(
+                trans('admin.settlement_run_skipped', [], $request->lotteryLocale()),
+                ErrorCode::ClientHttpError->value,
+                [
+                    'draw_no' => $draw->draw_no,
+                    'status' => $draw->status,
+                    'settle_version' => (int) $draw->settle_version,
+                ],
+                409,
+            );
+        }
+
        return ApiResponse::success([
-            'ran' => $ran,
+            'ran' => true,
            'draw_no' => $draw->draw_no,
            'status' => $draw->status,
            'settle_version' => (int) $draw->settle_version,
--- a/app/Services/Draw/DrawPublishService.php
+++ b/app/Services/Draw/DrawPublishService.php
@@ -31,6 +31,15 @@ final class DrawPublishService

            /** @var Draw $draw */
            $draw = Draw::query()->whereKey($lockedBatch->draw_id)->lockForUpdate()->firstOrFail();
+
+            $this->assertDrawReadyToPublish($draw, $lockedBatch);
+
+            DrawResultBatch::query()
+                ->where('draw_id', $draw->id)
+                ->where('id', '!=', $lockedBatch->id)
+                ->where('status', DrawResultBatchStatus::Published->value)
+                ->update(['status' => DrawResultBatchStatus::Rejected->value]);
+
            $lockedBatch->forceFill([
                'status' => DrawResultBatchStatus::Published->value,
                'confirmed_by' => $admin->id,
@@ -90,4 +99,25 @@ final class DrawPublishService

        return $draw->refresh();
    }
+
+    private function assertDrawReadyToPublish(Draw $draw, DrawResultBatch $batch): void
+    {
+        if ($draw->status === DrawStatus::Cancelled->value || $draw->status === DrawStatus::Settled->value) {
+            throw new \RuntimeException('draw_not_ready_to_publish');
+        }
+
+        if ((int) $batch->result_version < (int) $draw->current_result_version) {
+            throw new \RuntimeException('batch_result_version_stale');
+        }
+
+        $allowed = [
+            DrawStatus::Closed->value,
+            DrawStatus::Review->value,
+            DrawStatus::Cooldown->value,
+            DrawStatus::Settling->value,
+        ];
+        if (! in_array($draw->status, $allowed, true)) {
+            throw new \RuntimeException('draw_not_ready_to_publish');
+        }
+    }
 }
--- a/app/Services/Settlement/SettlementBatchWorkflowService.php
+++ b/app/Services/Settlement/SettlementBatchWorkflowService.php
@@ -7,6 +7,7 @@ use App\Models\Player;
 use App\Models\AdminUser;
 use App\Models\TicketItem;
 use App\Lottery\DrawStatus;
+use App\Models\JackpotPool;
 use App\Models\TicketOrder;
 use App\Models\SettlementBatch;
 use Illuminate\Support\Facades\DB;
@@ -59,10 +60,19 @@ final class SettlementBatchWorkflowService
                throw new \RuntimeException('settlement_not_pending_review');
            }

-            TicketItem::query()
-                ->whereIn('id', $locked->details()->pluck('ticket_item_id'))
-                ->where('status', 'pending_payout')
-                ->update(['status' => 'success', 'win_amount' => 0, 'jackpot_win_amount' => 0]);
+            $itemIds = $locked->details()->pluck('ticket_item_id')->map(fn ($id) => (int) $id)->all();
+            if ($itemIds !== []) {
+                TicketItem::query()
+                    ->whereIn('id', $itemIds)
+                    ->update([
+                        'status' => 'pending_draw',
+                        'win_amount' => 0,
+                        'jackpot_win_amount' => 0,
+                        'settled_at' => null,
+                    ]);
+            }
+
+            $this->restoreJackpotPoolAfterReject($locked);

            $locked->forceFill([
                'status' => SettlementBatchStatus::Rejected->value,
@@ -85,6 +95,27 @@ final class SettlementBatchWorkflowService
                throw new \RuntimeException('settlement_not_approved');
            }

+            $batchItemIds = $locked->details()->pluck('ticket_item_id')->map(fn ($id) => (int) $id)->all();
+
+            $hasPendingDraw = TicketItem::query()
+                ->where('draw_id', $locked->draw_id)
+                ->where('status', 'pending_draw')
+                ->exists();
+            if ($hasPendingDraw) {
+                throw new \RuntimeException('draw_has_unsettled_tickets');
+            }
+
+            if ($batchItemIds !== []) {
+                $orphanPendingPayout = TicketItem::query()
+                    ->where('draw_id', $locked->draw_id)
+                    ->where('status', 'pending_payout')
+                    ->whereNotIn('id', $batchItemIds)
+                    ->exists();
+                if ($orphanPendingPayout) {
+                    throw new \RuntimeException('draw_has_unsettled_tickets');
+                }
+            }
+
            $details = $locked->details()->with(['ticketItem.order'])->get();
            $playerTotals = [];
            $currencyByPlayer = [];
@@ -141,4 +172,31 @@ final class SettlementBatchWorkflowService
            return $locked->refresh();
        });
    }
+
+    private function restoreJackpotPoolAfterReject(SettlementBatch $batch): void
+    {
+        $restoreAmount = (int) $batch->total_jackpot_payout_amount;
+        if ($restoreAmount <= 0) {
+            return;
+        }
+
+        $orderId = TicketItem::query()->where('draw_id', $batch->draw_id)->value('order_id');
+        $currencyCode = strtoupper((string) (TicketOrder::query()
+            ->whereKey($orderId)
+            ->value('currency_code') ?? 'NPR'));
+
+        $pool = JackpotPool::query()
+            ->where('currency_code', $currencyCode)
+            ->where('status', 1)
+            ->lockForUpdate()
+            ->first();
+
+        if ($pool === null) {
+            return;
+        }
+
+        $pool->forceFill([
+            'current_amount' => (int) $pool->current_amount + $restoreAmount,
+        ])->save();
+    }
 }
--- a/app/Services/Wallet/LotteryTransferService.php
+++ b/app/Services/Wallet/LotteryTransferService.php
@@ -322,11 +322,35 @@ final class LotteryTransferService
        string $action,
        string $remark = '',
    ): void {
-        $allowedStatuses = $action === 'manually_process'
-            ? [self::ST_PROCESSING, self::ST_FAILED, self::ST_PENDING_RECONCILE]
-            : [self::ST_PENDING_RECONCILE];
+        if ($action === 'reverse') {
+            DB::transaction(fn (): mixed => $this->doReverse($order, $remark));

-        if (! in_array($order->status, $allowedStatuses, true)) {
+            return;
+        }
+
+        if ($action === 'manually_process') {
+            DB::transaction(fn (): mixed => $this->doManuallyProcess($order, $remark));
+
+            return;
+        }
+
+        throw new WalletOperationException(
+            'invalid_reconcile_action',
+            ErrorCode::WalletExternalRejected->value,
+            422,
+        );
+    }
+
+    private function doReverse(TransferOrder $order, string $remark): void
+    {
+        /** @var TransferOrder $locked */
+        $locked = TransferOrder::query()->whereKey($order->id)->lockForUpdate()->firstOrFail();
+
+        if ($locked->status === self::ST_REVERSED) {
+            return;
+        }
+
+        if ($locked->status !== self::ST_PENDING_RECONCILE) {
            throw new WalletOperationException(
                'order_not_pending_reconcile',
                ErrorCode::WalletExternalRejected->value,
@@ -334,54 +358,55 @@ final class LotteryTransferService
            );
        }

-        if ($action === 'reverse') {
-            $this->doReverse($order, $remark);
-        } elseif ($action === 'manually_process') {
-            $this->doManuallyProcess($order, $remark);
-        } else {
-            throw new WalletOperationException(
-                'invalid_reconcile_action',
-                ErrorCode::WalletExternalRejected->value,
-                422,
-            );
-        }
-    }
+        if ($locked->direction === self::DIR_OUT) {
+            $idempotentKey = 'reversal:'.$locked->transfer_no;
+            $alreadyCredited = WalletTxn::query()
+                ->where('idempotent_key', $idempotentKey)
+                ->where('biz_type', self::BIZ_REVERSAL)
+                ->exists();

-    private function doReverse(TransferOrder $order, string $remark): void
-    {
-        if ($order->direction === self::DIR_OUT) {
-            DB::transaction(function () use ($order, $remark): void {
-                $wallet = $this->lockLotteryWalletById($order->player_id, $order->currency_code);
+            if (! $alreadyCredited) {
+                $wallet = $this->lockLotteryWalletById($locked->player_id, $locked->currency_code);
                $this->postLotteryWalletMovement(
                    wallet: $wallet,
                    bizType: self::BIZ_REVERSAL,
                    direction: self::TXN_DIR_IN,
-                    amountMinor: (int) $order->amount,
-                    bizNo: $order->transfer_no,
+                    amountMinor: (int) $locked->amount,
+                    bizNo: $locked->transfer_no,
                    externalRefNo: null,
-                    idempotentKey: null,
+                    idempotentKey: $idempotentKey,
                    remark: $remark ?: 'reversal_pending_reconcile',
                    deltaSign: 1,
                );
-
-                $order->forceFill([
-                    'status' => self::ST_REVERSED,
-                    'fail_reason' => 'reversed: '.($remark ?: 'admin_reversal'),
-                    'finished_at' => now(),
-                ])->save();
-            });
-        } else {
-            $order->forceFill([
-                'status' => self::ST_REVERSED,
-                'fail_reason' => 'reversed: '.($remark ?: 'admin_reversal'),
-                'finished_at' => now(),
-            ])->save();
+            }
        }
+
+        $locked->forceFill([
+            'status' => self::ST_REVERSED,
+            'fail_reason' => 'reversed: '.($remark ?: 'admin_reversal'),
+            'finished_at' => now(),
+        ])->save();
    }

    private function doManuallyProcess(TransferOrder $order, string $remark): void
    {
-        $order->forceFill([
+        /** @var TransferOrder $locked */
+        $locked = TransferOrder::query()->whereKey($order->id)->lockForUpdate()->firstOrFail();
+
+        $allowedStatuses = [self::ST_PROCESSING, self::ST_FAILED, self::ST_PENDING_RECONCILE];
+        if (! in_array($locked->status, $allowedStatuses, true)) {
+            throw new WalletOperationException(
+                'order_not_pending_reconcile',
+                ErrorCode::WalletExternalRejected->value,
+                422,
+            );
+        }
+
+        if ($locked->status === self::ST_MANUALLY_PROCESSED) {
+            return;
+        }
+
+        $locked->forceFill([
            'status' => self::ST_MANUALLY_PROCESSED,
            'fail_reason' => 'manually_processed: '.($remark ?: 'admin_manual'),
            'finished_at' => now(),
--- a/lang/en/admin.php
+++ b/lang/en/admin.php
@@ -6,4 +6,5 @@ return [
    'invalid_credentials' => 'Invalid account or password.',
    'account_disabled' => 'This account has been disabled.',
    'permission_denied' => 'You do not have permission to perform this action.',
+    'settlement_run_skipped' => 'Settlement was not run for this draw (check draw status and published result batch).',
 ];
--- a/lang/ne/admin.php
+++ b/lang/ne/admin.php
@@ -6,4 +6,5 @@ return [
    'invalid_credentials' => 'खाता वा पासवर्ड गलत।',
    'account_disabled' => 'यो खाता निष्क्रिय गरिएको छ।',
    'permission_denied' => 'यो कार्य गर्न अनुमति छैन।',
+    'settlement_run_skipped' => 'यस ड्रका लागि बन्दोबस्त चलाइएन (ड्र स्थिति र प्रकाशित नतिजा जाँच गर्नुहोस्)।',
 ];
--- a/lang/zh/admin.php
+++ b/lang/zh/admin.php
@@ -6,4 +6,5 @@ return [
    'invalid_credentials' => '账号或密码错误。',
    'account_disabled' => '该账号已被禁用。',
    'permission_denied' => '当前账号无此操作权限。',
+    'settlement_run_skipped' => '本期未执行结算（请检查期号状态与已发布开奖批次）。',
 ];
--- a/tests/Feature/AdminWalletApiTest.php
+++ b/tests/Feature/AdminWalletApiTest.php
@@ -6,6 +6,7 @@ use App\Models\WalletTxn;
 use App\Lottery\ErrorCode;
 use App\Models\PlayerWallet;
 use App\Models\TransferOrder;
+use App\Services\Wallet\LotteryTransferService;
 use Illuminate\Support\Facades\Hash;
 use Illuminate\Foundation\Testing\RefreshDatabase;

@@ -278,6 +279,53 @@ test('admin lists wallet transactions and filters abnormal', function (): void {
        ->assertJsonPath('data.items.0.status', 'pending_reconcile');
 });

+test('admin transfer reverse is idempotent under concurrent reconcile', function (): void {
+    $player = Player::query()->create([
+        'site_code' => 'main',
+        'site_player_id' => 'reverse-idem',
+        'username' => null,
+        'nickname' => null,
+        'default_currency' => 'NPR',
+        'status' => 0,
+    ]);
+
+    $wallet = PlayerWallet::query()->create([
+        'player_id' => $player->id,
+        'wallet_type' => 'lottery',
+        'currency_code' => 'NPR',
+        'balance' => 1_000,
+        'frozen_balance' => 0,
+        'status' => 0,
+        'version' => 0,
+    ]);
+
+    $order = TransferOrder::query()->create([
+        'transfer_no' => 'TI_reverse_idem',
+        'player_id' => $player->id,
+        'direction' => 'out',
+        'currency_code' => 'NPR',
+        'amount' => 400,
+        'idempotent_key' => 'reverse-idem-key',
+        'status' => 'pending_reconcile',
+        'external_request_payload' => null,
+        'external_response_payload' => null,
+        'external_ref_no' => null,
+        'fail_reason' => 'main_site_timeout',
+        'finished_at' => null,
+    ]);
+
+    $service = app(LotteryTransferService::class);
+    $service->reconcileTransferOrder($order, 'reverse', 'first');
+    $service->reconcileTransferOrder($order->fresh(), 'reverse', 'second');
+
+    $wallet->refresh();
+    $order->refresh();
+
+    expect((int) $wallet->balance)->toBe(1_400)
+        ->and($order->status)->toBe('reversed')
+        ->and(WalletTxn::query()->where('biz_type', 'reversal')->count())->toBe(1);
+});
+
 test('admin shows player wallets', function (): void {
    $token = makeAdminToken();

--- a/tests/Feature/DrawPipelineTest.php
+++ b/tests/Feature/DrawPipelineTest.php
@@ -654,6 +654,8 @@ test('cooldown expiry tick moves draw to settling', function (): void {
    ]);
    LotterySettings::put('draw.require_manual_review', false, 'draw', 'RNG 开奖后是否必须进入人工审核');
    LotterySettings::put('draw.cooldown_minutes', 15, 'draw', '开奖结果发布后的冷静期分钟数');
+    LotterySettings::put('settlement.auto_approve_on_tick', false, 'settlement', '本用例仅验证进入结算态，不自动审核派彩');
+    LotterySettings::put('settlement.auto_payout_on_tick', false, 'settlement', '本用例仅验证进入结算态，不自动派彩');
    Carbon::setTestNow(Carbon::parse('2026-05-09 14:07:00', 'UTC'));

    $drawTime = now()->copy()->subMinute();
--- a/tests/Feature/SettlementOrchestratorTest.php
+++ b/tests/Feature/SettlementOrchestratorTest.php
@@ -279,3 +279,135 @@ test('admin settlement requires review before payout and can export report', fun
        ->assertOk()
        ->assertHeader('content-type', 'text/csv; charset=UTF-8');
 });
+
+test('settlement reject reverts tickets to pending_draw and allows re-settlement', function (): void {
+    $uniq = bin2hex(random_bytes(4));
+    $player = Player::query()->create([
+        'site_code' => 'test',
+        'site_player_id' => 'settle-reject-p-'.$uniq,
+        'username' => 'srp_'.$uniq,
+        'nickname' => null,
+        'default_currency' => 'NPR',
+        'status' => 0,
+    ]);
+    PlayerWallet::query()->create([
+        'player_id' => $player->id,
+        'wallet_type' => 'lottery',
+        'currency_code' => 'NPR',
+        'balance' => 5_000_000,
+        'frozen_balance' => 0,
+        'status' => 0,
+        'version' => 0,
+    ]);
+
+    $draw = Draw::query()->create([
+        'draw_no' => '20260511-902',
+        'business_date' => '2026-05-11',
+        'sequence_no' => 902,
+        'status' => DrawStatus::Open->value,
+        'start_time' => now()->subMinutes(2),
+        'close_time' => now()->addMinutes(5),
+        'draw_time' => now()->addMinutes(6),
+        'cooling_end_time' => null,
+        'result_source' => null,
+        'current_result_version' => 0,
+        'settle_version' => 0,
+        'is_reopened' => false,
+    ]);
+
+    $this->withHeader('Authorization', 'Bearer dev:'.$player->id)
+        ->postJson('/api/v1/ticket/place', [
+            'draw_id' => '20260511-902',
+            'currency_code' => 'NPR',
+            'client_trace_id' => 'settle-reject-trace-1',
+            'lines' => [
+                ['number' => '1234', 'play_code' => 'big', 'amount' => 10_000],
+            ],
+        ])
+        ->assertOk();
+
+    $batch = DrawResultBatch::query()->create([
+        'draw_id' => $draw->id,
+        'result_version' => 1,
+        'source_type' => 'rng',
+        'rng_seed_hash' => 'reject-test',
+        'raw_seed_encrypted' => null,
+        'status' => DrawResultBatchStatus::Published->value,
+        'created_by' => null,
+        'confirmed_by' => null,
+        'confirmed_at' => now(),
+    ]);
+
+    foreach (DrawPrizeLayout::slots() as $slot) {
+        $num = $slot['prize_type'] === 'first' ? '1234' : '5678';
+        DrawResultItem::query()->create([
+            'draw_id' => $draw->id,
+            'result_batch_id' => $batch->id,
+            'prize_type' => $slot['prize_type'],
+            'prize_index' => $slot['prize_index'],
+            'number_4d' => $num,
+            'suffix_3d' => substr($num, -3),
+            'suffix_2d' => substr($num, -2),
+            'head_digit' => (int) substr($num, 0, 1),
+            'tail_digit' => (int) substr($num, 3, 1),
+        ]);
+    }
+
+    $draw->forceFill([
+        'status' => DrawStatus::Settling->value,
+        'current_result_version' => 1,
+    ])->save();
+
+    $admin = AdminUser::query()->create([
+        'username' => 'settlement_reject_reviewer',
+        'name' => 'Settlement Reject Reviewer',
+        'email' => null,
+        'password' => Hash::make('secret-strong'),
+        'status' => 0,
+    ]);
+    grantSuperAdminRole($admin);
+    $token = $admin->createToken('test', ['*'], now()->addDay())->plainTextToken;
+
+    $this->withHeader('Authorization', 'Bearer '.$token)
+        ->postJson("/api/v1/admin/draws/{$draw->id}/settlement/run")
+        ->assertOk();
+
+    $settlement = SettlementBatch::query()->where('draw_id', $draw->id)->firstOrFail();
+    $item = TicketItem::query()->where('draw_id', $draw->id)->firstOrFail();
+    expect($item->status)->toBe('pending_payout');
+
+    $this->withHeader('Authorization', 'Bearer '.$token)
+        ->postJson("/api/v1/admin/settlement-batches/{$settlement->id}/reject", ['remark' => 'wrong result'])
+        ->assertOk()
+        ->assertJsonPath('data.review_status', 'rejected');
+
+    $item->refresh();
+    expect($item->status)->toBe('pending_draw')
+        ->and((int) $item->win_amount)->toBe(0);
+
+    $this->withHeader('Authorization', 'Bearer '.$token)
+        ->postJson("/api/v1/admin/draws/{$draw->id}/settlement/run")
+        ->assertOk()
+        ->assertJsonPath('data.ran', true);
+
+    $second = SettlementBatch::query()
+        ->where('draw_id', $draw->id)
+        ->where('status', 'pending_review')
+        ->orderByDesc('id')
+        ->firstOrFail();
+
+    expect((int) $second->id)->toBeGreaterThan((int) $settlement->id);
+
+    $this->withHeader('Authorization', 'Bearer '.$token)
+        ->postJson("/api/v1/admin/settlement-batches/{$second->id}/approve")
+        ->assertOk();
+
+    $this->withHeader('Authorization', 'Bearer '.$token)
+        ->postJson("/api/v1/admin/settlement-batches/{$second->id}/payout")
+        ->assertOk();
+
+    $item->refresh();
+    $draw->refresh();
+    expect($item->status)->toBe('settled_win')
+        ->and($draw->status)->toBe(DrawStatus::Settled->value);
+});