From 48349e330273f50713d264452f829c1a7c30de6c Mon Sep 17 00:00:00 2001 From: kang Date: Tue, 26 May 2026 14:10:16 +0800 Subject: [PATCH] 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. --- .../Draw/DrawSettlementRunController.php | 15 +- app/Services/Draw/DrawPublishService.php | 30 ++++ .../SettlementBatchWorkflowService.php | 66 ++++++++- .../Wallet/LotteryTransferService.php | 101 +++++++++----- lang/en/admin.php | 1 + lang/ne/admin.php | 1 + lang/zh/admin.php | 1 + tests/Feature/AdminWalletApiTest.php | 48 +++++++ tests/Feature/DrawPipelineTest.php | 2 + tests/Feature/SettlementOrchestratorTest.php | 132 ++++++++++++++++++ 10 files changed, 354 insertions(+), 43 deletions(-) diff --git a/app/Http/Controllers/Api/V1/Admin/Draw/DrawSettlementRunController.php b/app/Http/Controllers/Api/V1/Admin/Draw/DrawSettlementRunController.php index 12fe943..0707a40 100644 --- 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, diff --git a/app/Services/Draw/DrawPublishService.php b/app/Services/Draw/DrawPublishService.php index dcc9d28..5e56f10 100644 --- 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'); + } + } } diff --git a/app/Services/Settlement/SettlementBatchWorkflowService.php b/app/Services/Settlement/SettlementBatchWorkflowService.php index a7812b5..a448114 100644 --- 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(); + } } diff --git a/app/Services/Wallet/LotteryTransferService.php b/app/Services/Wallet/LotteryTransferService.php index 1e6e880..3b18cad 100644 --- 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(), diff --git a/lang/en/admin.php b/lang/en/admin.php index b79d445..8f04f6d 100644 --- 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).', ]; diff --git a/lang/ne/admin.php b/lang/ne/admin.php index 2b94639..7c69dae 100644 --- a/lang/ne/admin.php +++ b/lang/ne/admin.php @@ -6,4 +6,5 @@ return [ 'invalid_credentials' => 'खाता वा पासवर्ड गलत।', 'account_disabled' => 'यो खाता निष्क्रिय गरिएको छ।', 'permission_denied' => 'यो कार्य गर्न अनुमति छैन।', + 'settlement_run_skipped' => 'यस ड्रका लागि बन्दोबस्त चलाइएन (ड्र स्थिति र प्रकाशित नतिजा जाँच गर्नुहोस्)।', ]; diff --git a/lang/zh/admin.php b/lang/zh/admin.php index e12cead..4eba6e6 100644 --- a/lang/zh/admin.php +++ b/lang/zh/admin.php @@ -6,4 +6,5 @@ return [ 'invalid_credentials' => '账号或密码错误。', 'account_disabled' => '该账号已被禁用。', 'permission_denied' => '当前账号无此操作权限。', + 'settlement_run_skipped' => '本期未执行结算（请检查期号状态与已发布开奖批次）。', ]; diff --git a/tests/Feature/AdminWalletApiTest.php b/tests/Feature/AdminWalletApiTest.php index c449ac2..beece5c 100644 --- 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(); diff --git a/tests/Feature/DrawPipelineTest.php b/tests/Feature/DrawPipelineTest.php index 73d8389..f6e0faa 100644 --- 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(); diff --git a/tests/Feature/SettlementOrchestratorTest.php b/tests/Feature/SettlementOrchestratorTest.php index ab7c643..382fba2 100644 --- 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); +});