feat: enhance reconciliation job processing and reporting features

- Updated ReconcileItemIndexController to include admin user validation and improved transfer order handling. - Refactored ReconcileJobStoreController to ensure date range handling is more precise with start and end of day adjustments. - Enhanced various report controllers to include currency code in responses for better financial clarity. - Introduced new methods in AdminReconcileJobService for wallet transfer job creation and improved item scanning logic. - Added wallet lookup idempotent path configuration for integration services to enhance API interactions.
2026-06-16 13:50:55 +08:00
parent 606ed6817e
commit 1e7b2b31ee
21 changed files with 886 additions and 71 deletions
--- a/app/Services/Admin/AdminReconcileJobService.php
+++ b/app/Services/Admin/AdminReconcileJobService.php
@@ -10,12 +10,17 @@ use Illuminate\Http\Request;
 use App\Models\ReconcileItem;
 use App\Services\AuditLogger;
 use Illuminate\Support\Facades\DB;
+use App\Services\Wallet\WalletTransferReconcileDetector;

 /**
- * 对账任务：落库 `reconcile_jobs` / `reconcile_items`（阶段 7；差异引擎可后续替换）。
+ * 对账任务：落库 `reconcile_jobs` / `reconcile_items`。
 */
 final class AdminReconcileJobService
 {
+    public function __construct(
+        private readonly WalletTransferReconcileDetector $detector,
+    ) {}
+
    /**
     * @param  list<array{side_a_ref?: ?string, side_b_ref?: ?string, difference_amount?: int, status?: string}>|null  $items
     */
@@ -26,7 +31,12 @@ final class AdminReconcileJobService
        ?Carbon $periodStart,
        ?Carbon $periodEnd,
        ?array $items,
+        ?int $playerId = null,
    ): ReconcileJob {
+        if ($reconcileType === 'wallet_transfer' && $items === null) {
+            return $this->createWalletTransferScanJob($admin, $request, $periodStart, $periodEnd, $playerId);
+        }
+
        return DB::transaction(function () use ($admin, $request, $reconcileType, $periodStart, $periodEnd, $items): ReconcileJob {
            $jobNo = 'REC'.now()->format('YmdHis').strtoupper(Str::random(4));

@@ -81,4 +91,44 @@ final class AdminReconcileJobService
            return $job->fresh();
        });
    }
+
+    private function createWalletTransferScanJob(
+        AdminUser $admin,
+        Request $request,
+        ?Carbon $periodStart,
+        ?Carbon $periodEnd,
+        ?int $playerId,
+    ): ReconcileJob {
+        $periodEnd ??= now()->endOfDay();
+        $periodStart ??= $periodEnd->copy()->startOfDay();
+
+        [$items] = $this->detector->scanItems(
+            $periodStart,
+            $periodEnd,
+            limit: 1000,
+            staleMinutes: 15,
+            playerId: $playerId,
+            includeMainSiteCheck: true,
+        );
+
+        $job = $this->detector->persistJob($items, $periodStart, $periodEnd, (int) $admin->getKey());
+
+        AuditLogger::recordForAdmin(
+            $admin,
+            $request,
+            'reconcile_jobs',
+            'create',
+            'reconcile_job',
+            (string) $job->getKey(),
+            null,
+            [
+                'job_no' => $job->job_no,
+                'reconcile_type' => 'wallet_transfer',
+                'item_count' => count($items),
+                'player_id' => $playerId,
+            ],
+        );
+
+        return $job->fresh();
+    }
 }
--- a/app/Services/Admin/AdminReportQueryService.php
+++ b/app/Services/Admin/AdminReportQueryService.php
@@ -46,9 +46,9 @@ final class AdminReportQueryService
        $fromRaw = trim((string) ($filters['date_from'] ?? ''));
        $toRaw = trim((string) ($filters['date_to'] ?? ''));

-        // 未传日期时按历史全量范围导出/查询，避免默认“仅今天”导致空数据。
+        // 未传日期时默认近 30 个自然日（与后台报表中心默认筛选一致）。
        if ($fromRaw === '' && $toRaw === '') {
-            return $this->lifetimeBusinessDateBounds();
+            return $this->defaultReportDateRange();
        }

        $dateFrom = $fromRaw !== '' ? $fromRaw : $toRaw;
@@ -99,6 +99,19 @@ final class AdminReportQueryService
        return ['date_from' => $from, 'date_to' => $to];
    }

+    /**
+     * @return array{date_from: string, date_to: string}
+     */
+    public function defaultReportDateRange(): array
+    {
+        $today = now()->toDateString();
+
+        return [
+            'date_from' => now()->subDays(29)->toDateString(),
+            'date_to' => $today,
+        ];
+    }
+
    /**
     * @return array{date_from: string, date_to: string}
     */
@@ -298,7 +311,8 @@ final class AdminReportQueryService
        $context = $this->normalizeScope($scope);
        $currencyQuery = DB::table('ticket_orders as o')
            ->join('draws as d', 'd.id', '=', 'o.draw_id')
-            ->whereBetween('d.business_date', [$dateFrom, $dateTo]);
+            ->whereDate('d.business_date', '>=', $dateFrom)
+            ->whereDate('d.business_date', '<=', $dateTo);
        AdminDataScope::applyToTicketOrdersViaPlayer($currencyQuery, $context?->admin, 'o');
        $currencyCode = (string) ($currencyQuery->orderByDesc('o.id')->value('o.currency_code') ?? '');

@@ -335,10 +349,12 @@ final class AdminReportQueryService
        AdminDataScope::applyToTicketOrdersViaPlayer($payoutSub, $context?->admin, 'o');

        return DB::table('draws as d')
-            ->whereBetween('d.business_date', [$dateFrom, $dateTo])
+            ->whereDate('d.business_date', '>=', $dateFrom)
+            ->whereDate('d.business_date', '<=', $dateTo)
            ->leftJoinSub($betSub, 'b', 'b.draw_id', '=', 'd.id')
            ->leftJoinSub($payoutSub, 'p', 'p.draw_id', '=', 'd.id')
            ->groupBy('d.business_date')
+            ->havingRaw('COALESCE(SUM(b.total_bet_minor), 0) > 0 OR COALESCE(SUM(p.total_payout_minor), 0) > 0')
            ->orderBy('d.business_date')
            ->get([
                'd.business_date',
@@ -349,7 +365,7 @@ final class AdminReportQueryService
            ->map(static function (object $row): array {
                $businessDate = $row->business_date instanceof Carbon
                    ? $row->business_date->format('Y-m-d')
-                    : (string) $row->business_date;
+                    : substr((string) $row->business_date, 0, 10);

                return [
                    'business_date' => $businessDate,
@@ -665,6 +681,7 @@ final class AdminReportQueryService
        $context = $this->normalizeScope($scope);
        $query = DB::table('ticket_items as ti')
            ->join('ticket_orders as o', 'o.id', '=', 'ti.order_id')
+            ->join('draws as d', 'd.id', '=', 'o.draw_id')
            ->leftJoin('players as p', 'p.id', '=', 'ti.player_id')
            ->leftJoin('agent_nodes as an', 'an.id', '=', 'p.agent_node_id')
            ->selectRaw('ti.player_id')
@@ -675,8 +692,8 @@ final class AdminReportQueryService
            ->selectRaw('SUM(ti.actual_deduct_amount) as total_bet_minor')
            ->selectRaw('SUM(ti.win_amount + ti.jackpot_win_amount) as total_payout_minor')
            ->selectRaw('SUM(ti.actual_deduct_amount) - SUM(ti.win_amount + ti.jackpot_win_amount) as net_win_loss_minor')
-            ->whereDate('o.created_at', '>=', $dateFrom)
-            ->whereDate('o.created_at', '<=', $dateTo)
+            ->whereDate('d.business_date', '>=', $dateFrom)
+            ->whereDate('d.business_date', '<=', $dateTo)
            ->groupBy('ti.player_id', 'p.username', 'p.agent_node_id', 'an.code', 'an.name')
            ->orderByDesc('net_win_loss_minor');

@@ -700,13 +717,14 @@ final class AdminReportQueryService
        $context = $this->normalizeScope($scope);
        $query = DB::table('ticket_items as ti')
            ->join('ticket_orders as o', 'o.id', '=', 'ti.order_id')
+            ->join('draws as d', 'd.id', '=', 'o.draw_id')
            ->selectRaw('ti.play_code')
            ->selectRaw('ti.dimension')
            ->selectRaw('SUM(ti.actual_deduct_amount) as total_bet_minor')
            ->selectRaw('SUM(ti.win_amount + ti.jackpot_win_amount) as total_payout_minor')
            ->selectRaw('SUM(ti.actual_deduct_amount) - SUM(ti.win_amount + ti.jackpot_win_amount) as approx_house_gross_minor')
-            ->whereDate('o.created_at', '>=', $dateFrom)
-            ->whereDate('o.created_at', '<=', $dateTo)
+            ->whereDate('d.business_date', '>=', $dateFrom)
+            ->whereDate('d.business_date', '<=', $dateTo)
            ->groupBy('ti.play_code', 'ti.dimension')
            ->orderBy('ti.play_code')
            ->orderBy('ti.dimension');
@@ -726,12 +744,13 @@ final class AdminReportQueryService
        $context = $this->normalizeScope($scope);
        $query = DB::table('ticket_items as ti')
            ->join('ticket_orders as o', 'o.id', '=', 'ti.order_id')
+            ->join('draws as d', 'd.id', '=', 'o.draw_id')
            ->selectRaw('ti.play_code')
            ->selectRaw('SUM(ti.total_bet_amount - ti.actual_deduct_amount) as total_rebate_minor')
            ->selectRaw('COUNT(DISTINCT o.id) as order_count')
            ->selectRaw('COUNT(ti.id) as ticket_item_count')
-            ->whereDate('o.created_at', '>=', $dateFrom)
-            ->whereDate('o.created_at', '<=', $dateTo)
+            ->whereDate('d.business_date', '>=', $dateFrom)
+            ->whereDate('d.business_date', '<=', $dateTo)
            ->groupBy('ti.play_code')
            ->orderBy('ti.play_code');

--- a/app/Services/Integration/PartnerSiteConfig.php
+++ b/app/Services/Integration/PartnerSiteConfig.php
@@ -18,6 +18,7 @@ final readonly class PartnerSiteConfig
        public string $walletDebitPath,
        public string $walletCreditPath,
        public string $walletBalancePath,
+        public string $walletLookupIdempotentPath,
        public ?string $ssoJwtSecret,
        public ?string $walletApiKey,
        public int $walletTimeoutSeconds,
@@ -48,6 +49,7 @@ final readonly class PartnerSiteConfig
            'wallet_debit_path' => $this->walletDebitPath,
            'wallet_credit_path' => $this->walletCreditPath,
            'wallet_balance_path' => $this->walletBalancePath,
+            'wallet_lookup_idempotent_path' => $this->walletLookupIdempotentPath,
            'sso_jwt_secret' => $this->ssoJwtSecret,
            'wallet_api_key' => $this->walletApiKey,
            'wallet_timeout_seconds' => $this->walletTimeoutSeconds,
@@ -69,6 +71,7 @@ final readonly class PartnerSiteConfig
            walletDebitPath: (string) ($data['wallet_debit_path'] ?? '/wallet/debit-for-lottery'),
            walletCreditPath: (string) ($data['wallet_credit_path'] ?? '/wallet/credit-from-lottery'),
            walletBalancePath: (string) ($data['wallet_balance_path'] ?? '/wallet/balance'),
+            walletLookupIdempotentPath: (string) ($data['wallet_lookup_idempotent_path'] ?? '/wallet/lookup-idempotent'),
            ssoJwtSecret: isset($data['sso_jwt_secret']) && is_string($data['sso_jwt_secret']) && $data['sso_jwt_secret'] !== ''
                ? $data['sso_jwt_secret']
                : null,
--- a/app/Services/Integration/PartnerSiteConfigResolver.php
+++ b/app/Services/Integration/PartnerSiteConfigResolver.php
@@ -86,6 +86,7 @@ final class PartnerSiteConfigResolver
            walletDebitPath: (string) ($site->wallet_debit_path ?: '/wallet/debit-for-lottery'),
            walletCreditPath: (string) ($site->wallet_credit_path ?: '/wallet/credit-from-lottery'),
            walletBalancePath: (string) ($site->wallet_balance_path ?: '/wallet/balance'),
+            walletLookupIdempotentPath: (string) config('lottery.main_site.wallet_lookup_idempotent_path', '/wallet/lookup-idempotent'),
            ssoJwtSecret: $site->decryptedSsoJwtSecret(),
            walletApiKey: $site->decryptedWalletApiKey(),
            walletTimeoutSeconds: max(1, (int) ($site->wallet_timeout_seconds ?? 10)),
@@ -129,6 +130,7 @@ final class PartnerSiteConfigResolver
                walletDebitPath: (string) config('lottery.main_site.wallet_debit_path', '/wallet/debit-for-lottery'),
                walletCreditPath: (string) config('lottery.main_site.wallet_credit_path', '/wallet/credit-from-lottery'),
                walletBalancePath: (string) config('lottery.main_site.wallet_balance_path', '/wallet/balance'),
+                walletLookupIdempotentPath: (string) config('lottery.main_site.wallet_lookup_idempotent_path', '/wallet/lookup-idempotent'),
                ssoJwtSecret: is_string($sso) && $sso !== '' ? $sso : null,
                walletApiKey: is_string($walletKey) && $walletKey !== '' ? $walletKey : null,
                walletTimeoutSeconds: max(1, (int) config('lottery.main_site.wallet_timeout', 10)),
@@ -143,6 +145,7 @@ final class PartnerSiteConfigResolver
            walletDebitPath: '/wallet/debit-for-lottery',
            walletCreditPath: '/wallet/credit-from-lottery',
            walletBalancePath: '/wallet/balance',
+            walletLookupIdempotentPath: '/wallet/lookup-idempotent',
            ssoJwtSecret: null,
            walletApiKey: null,
            walletTimeoutSeconds: 10,
--- a/app/Services/Wallet/HttpMainSiteWalletIdempotentProbeClient.php
+++ b/app/Services/Wallet/HttpMainSiteWalletIdempotentProbeClient.php
@@ -0,0 +1,109 @@
+<?php
+
+namespace App\Services\Wallet;
+
+use App\Models\Player;
+use Illuminate\Support\Facades\Http;
+use App\Services\Integration\PartnerSiteConfigResolver;
+use App\Support\Integration\WalletApiUrlSanitizer;
+
+/** 按幂等键查询主站钱包侧是否已有对应划转记录。 */
+final class HttpMainSiteWalletIdempotentProbeClient
+{
+    public function __construct(
+        private readonly PartnerSiteConfigResolver $partnerSiteConfigResolver,
+    ) {}
+
+    public function probe(Player $player, string $idempotentKey): MainSiteWalletIdempotentProbeResult
+    {
+        $idempotentKey = trim($idempotentKey);
+        if ($idempotentKey === '') {
+            return new MainSiteWalletIdempotentProbeResult(
+                status: MainSiteWalletIdempotentProbeResult::STATUS_SKIPPED,
+                message: 'empty_idempotent_key',
+            );
+        }
+
+        $config = $this->partnerSiteConfigResolver->resolveForPlayer($player);
+        if (! $config->enabled || ! $config->hasWalletApi()) {
+            return new MainSiteWalletIdempotentProbeResult(
+                status: MainSiteWalletIdempotentProbeResult::STATUS_SKIPPED,
+                message: 'wallet_api_not_configured',
+            );
+        }
+
+        $base = WalletApiUrlSanitizer::normalizeAndValidate($config->walletApiUrl);
+        if ($base === null) {
+            return new MainSiteWalletIdempotentProbeResult(
+                status: MainSiteWalletIdempotentProbeResult::STATUS_UNAVAILABLE,
+                message: 'wallet_api_url_invalid',
+            );
+        }
+
+        $path = $config->walletLookupIdempotentPath;
+        $url = $base.'/'.ltrim($path, '/');
+        $headers = ['Accept' => 'application/json'];
+        if (is_string($config->walletApiKey) && $config->walletApiKey !== '') {
+            $headers['Authorization'] = 'Bearer '.$config->walletApiKey;
+        }
+
+        $query = [
+            'site_code' => $player->site_code,
+            'site_player_id' => $player->site_player_id,
+            'idempotent_key' => $idempotentKey,
+        ];
+
+        try {
+            $response = Http::withHeaders($headers)
+                ->timeout($config->walletTimeoutSeconds)
+                ->acceptJson()
+                ->get($url, $query);
+        } catch (\Throwable $e) {
+            return new MainSiteWalletIdempotentProbeResult(
+                status: MainSiteWalletIdempotentProbeResult::STATUS_UNAVAILABLE,
+                message: $e->getMessage(),
+            );
+        }
+
+        $payload = $response->json();
+        if (! $response->successful() || ! is_array($payload)) {
+            $message = is_array($payload) && is_string($payload['message'] ?? null)
+                ? (string) $payload['message']
+                : 'HTTP '.$response->status();
+
+            return new MainSiteWalletIdempotentProbeResult(
+                status: MainSiteWalletIdempotentProbeResult::STATUS_UNAVAILABLE,
+                message: $message,
+            );
+        }
+
+        $data = data_get($payload, 'data');
+        if (! is_array($data)) {
+            return new MainSiteWalletIdempotentProbeResult(
+                status: MainSiteWalletIdempotentProbeResult::STATUS_UNAVAILABLE,
+                message: 'invalid_response',
+            );
+        }
+
+        $found = (bool) ($data['found'] ?? false);
+        if (! $found) {
+            return new MainSiteWalletIdempotentProbeResult(
+                status: MainSiteWalletIdempotentProbeResult::STATUS_NOT_FOUND,
+                found: false,
+                success: null,
+            );
+        }
+
+        $success = (bool) ($data['success'] ?? false);
+
+        return new MainSiteWalletIdempotentProbeResult(
+            status: $success
+                ? MainSiteWalletIdempotentProbeResult::STATUS_MATCHED
+                : MainSiteWalletIdempotentProbeResult::STATUS_FAILED,
+            found: true,
+            success: $success,
+            externalRefNo: is_string($data['external_ref_no'] ?? null) ? $data['external_ref_no'] : null,
+            operation: is_string($data['operation'] ?? null) ? $data['operation'] : null,
+        );
+    }
+}
--- a/app/Services/Wallet/MainSiteWalletIdempotentProbeResult.php
+++ b/app/Services/Wallet/MainSiteWalletIdempotentProbeResult.php
@@ -0,0 +1,22 @@
+<?php
+
+namespace App\Services\Wallet;
+
+/** 主站钱包幂等键查询结果（对账勾选用）。 */
+final readonly class MainSiteWalletIdempotentProbeResult
+{
+    public const STATUS_SKIPPED = 'skipped';
+    public const STATUS_MATCHED = 'matched';
+    public const STATUS_NOT_FOUND = 'not_found';
+    public const STATUS_FAILED = 'failed_on_main';
+    public const STATUS_UNAVAILABLE = 'unavailable';
+
+    public function __construct(
+        public string $status,
+        public ?bool $found = null,
+        public ?bool $success = null,
+        public ?string $externalRefNo = null,
+        public ?string $operation = null,
+        public ?string $message = null,
+    ) {}
+}
--- a/app/Services/Wallet/WalletTransferMainSiteReconcileChecker.php
+++ b/app/Services/Wallet/WalletTransferMainSiteReconcileChecker.php
@@ -0,0 +1,90 @@
+<?php
+
+namespace App\Services\Wallet;
+
+use App\Models\Player;
+use App\Models\TransferOrder;
+use Illuminate\Support\Collection;
+
+/** 扫描结果追加主站幂等记录核对项。 */
+final class WalletTransferMainSiteReconcileChecker
+{
+    public function __construct(
+        private readonly HttpMainSiteWalletIdempotentProbeClient $probeClient,
+    ) {}
+
+    /**
+     * @param  list<array{side_a_ref: string, side_b_ref: ?string, difference_amount: int, status: string}>  $items
+     * @param  Collection<int, TransferOrder>  $orders
+     * @return list<array{side_a_ref: string, side_b_ref: ?string, difference_amount: int, status: string}>
+     */
+    public function appendIssues(array $items, Collection $orders): array
+    {
+        $existingTransferNos = collect($items)
+            ->map(fn (array $row): string => (string) ($row['side_a_ref'] ?? ''))
+            ->filter()
+            ->flip();
+
+        $players = Player::query()
+            ->whereIn('id', $orders->pluck('player_id')->unique()->all())
+            ->get()
+            ->keyBy('id');
+
+        foreach ($orders as $order) {
+            if (! $this->shouldProbeMainSite($order)) {
+                continue;
+            }
+
+            $transferNo = (string) $order->transfer_no;
+            if ($existingTransferNos->has($transferNo)) {
+                continue;
+            }
+
+            $player = $players->get((int) $order->player_id);
+            if (! $player instanceof Player) {
+                continue;
+            }
+
+            $probe = $this->probeClient->probe($player, (string) $order->idempotent_key);
+            if ($probe->status === MainSiteWalletIdempotentProbeResult::STATUS_SKIPPED) {
+                continue;
+            }
+
+            if ($probe->status === MainSiteWalletIdempotentProbeResult::STATUS_NOT_FOUND) {
+                $items[] = [
+                    'side_a_ref' => $transferNo,
+                    'side_b_ref' => null,
+                    'difference_amount' => (int) $order->amount,
+                    'status' => 'main_site_record_missing',
+                ];
+                continue;
+            }
+
+            if ($probe->status === MainSiteWalletIdempotentProbeResult::STATUS_FAILED) {
+                $items[] = [
+                    'side_a_ref' => $transferNo,
+                    'side_b_ref' => $probe->externalRefNo,
+                    'difference_amount' => (int) $order->amount,
+                    'status' => 'main_site_failed',
+                ];
+            }
+        }
+
+        return $items;
+    }
+
+    private function shouldProbeMainSite(TransferOrder $order): bool
+    {
+        if (trim((string) $order->external_ref_no) !== '') {
+            return true;
+        }
+
+        if ($order->status === 'success') {
+            return true;
+        }
+
+        return $order->direction === 'in'
+            && $order->status === 'pending_reconcile'
+            && $order->fail_reason === 'lottery_credit_failed';
+    }
+}
--- a/app/Services/Wallet/WalletTransferReconcileDetector.php
+++ b/app/Services/Wallet/WalletTransferReconcileDetector.php
@@ -28,15 +28,40 @@ final class WalletTransferReconcileDetector
        ?Carbon $periodEnd = null,
        int $limit = 500,
        int $staleMinutes = 15,
+        ?int $playerId = null,
+        bool $includeMainSiteCheck = true,
    ): ?ReconcileJob {
        $periodEnd ??= now();
        $periodStart ??= $periodEnd->copy()->subDay();
+
+        [$items, $orders] = $this->scanItems($periodStart, $periodEnd, $limit, $staleMinutes, $playerId, $includeMainSiteCheck);
+
+        if ($items === []) {
+            return null;
+        }
+
+        return $this->persistJob($items, $periodStart, $periodEnd, null);
+    }
+
+    /**
+     * @return array{
+     *   0: list<array{side_a_ref: string, side_b_ref: ?string, difference_amount: int, status: string}>,
+     *   1: \Illuminate\Support\Collection<int, TransferOrder>
+     * }
+     */
+    public function scanItems(
+        Carbon $periodStart,
+        Carbon $periodEnd,
+        int $limit = 500,
+        int $staleMinutes = 15,
+        ?int $playerId = null,
+        bool $includeMainSiteCheck = true,
+    ): array {
        $limit = max(1, $limit);
        $staleMinutes = max(1, $staleMinutes);
-
        $staleCutoff = $periodEnd->copy()->subMinutes($staleMinutes);

-        $orders = TransferOrder::query()
+        $query = TransferOrder::query()
            ->where(function ($q) use ($periodStart, $periodEnd, $staleCutoff): void {
                $q->whereBetween('created_at', [$periodStart, $periodEnd])
                    ->orWhere('status', 'pending_reconcile')
@@ -46,11 +71,16 @@ final class WalletTransferReconcileDetector
                    });
            })
            ->orderBy('id')
-            ->limit($limit)
-            ->get();
+            ->limit($limit);
+
+        if ($playerId !== null) {
+            $query->where('player_id', $playerId);
+        }
+
+        $orders = $query->get();

        if ($orders->isEmpty()) {
-            return null;
+            return [[], $orders];
        }

        $txnsByTransferNo = WalletTxn::query()
@@ -73,16 +103,28 @@ final class WalletTransferReconcileDetector
            }
        }

-        if ($items === []) {
-            return null;
+        if ($includeMainSiteCheck) {
+            $items = app(WalletTransferMainSiteReconcileChecker::class)->appendIssues($items, $orders);
        }

-        return DB::transaction(function () use ($items, $periodStart, $periodEnd): ReconcileJob {
+        return [$items, $orders];
+    }
+
+    /**
+     * @param  list<array{side_a_ref: string, side_b_ref: ?string, difference_amount: int, status: string}>  $items
+     */
+    public function persistJob(
+        array $items,
+        Carbon $periodStart,
+        Carbon $periodEnd,
+        ?int $adminUserId,
+    ): ReconcileJob {
+        return DB::transaction(function () use ($items, $periodStart, $periodEnd, $adminUserId): ReconcileJob {
            $jobNo = 'REC'.now()->format('YmdHis').strtoupper(str_replace('-', '', Str::uuid()->toString()));

            $job = ReconcileJob::query()->create([
                'job_no' => $jobNo,
-                'admin_user_id' => null,
+                'admin_user_id' => $adminUserId,
                'reconcile_type' => self::RECONCILE_TYPE,
                'status' => 'completed',
                'period_start' => $periodStart,