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.

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');
+        }
+    }
 }

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();
+    }
 }

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(),