fix(settlement): 操作记录分页、流水动作与坏账幂等加固

- 新增 settlement-operations 合并列表 API，收付/调账接口改为标准分页
- actionable_only 流水在内存过滤后正确分页
- 已结账单流水不再展示补差/冲正快捷动作
- 坏账核销支持 idempotency_key 并写入 result_bill_id
- 补充操作记录、流水与坏账幂等相关测试

tests/Feature/AdminCreditLedgerFilterTest.php

@@ -1,11 +1,13 @@
 <?php
 
-use App\Models\AdminUser;
+use App\Models\Draw;
 use App\Models\Player;
+use App\Models\AdminUser;
+use App\Lottery\DrawStatus;
 use App\Support\PlayerFundingMode;
-use Illuminate\Foundation\Testing\RefreshDatabase;
 use Illuminate\Support\Facades\DB;
 use Illuminate\Support\Facades\Hash;
+use Illuminate\Foundation\Testing\RefreshDatabase;
 
 uses(RefreshDatabase::class);
 
@@ -235,6 +237,156 @@ test('credit ledger settlement bill reference keeps the referenced bill id', fun
         ->assertJsonPath('data.items.0.ref_id', $referencedBillId);
 });
 
+test('credit ledger settled bill payment row omits adjustment actions', function (): void {
+    $site = DB::table('admin_sites')->where('is_default', true)->first();
+    $siteId = (int) $site->id;
+    $siteCode = (string) $site->code;
+
+    $periodId = (int) DB::table('settlement_periods')->insertGetId([
+        'admin_site_id' => $siteId,
+        'period_start' => now()->subDay(),
+        'period_end' => now()->addDay(),
+        'status' => 'closed',
+        'created_at' => now(),
+        'updated_at' => now(),
+    ]);
+
+    $player = Player::query()->create([
+        'site_code' => $siteCode,
+        'site_player_id' => 'native:ledger-settled-actions',
+        'funding_mode' => PlayerFundingMode::CREDIT,
+        'username' => 'ledger_settled_actions',
+        'default_currency' => 'NPR',
+        'status' => 0,
+    ]);
+
+    $billId = (int) DB::table('settlement_bills')->insertGetId([
+        'settlement_period_id' => $periodId,
+        'bill_type' => 'player',
+        'owner_type' => 'player',
+        'owner_id' => $player->id,
+        'counterparty_type' => 'agent',
+        'counterparty_id' => 1,
+        'net_amount' => 100,
+        'unpaid_amount' => 0,
+        'paid_amount' => 100,
+        'status' => 'settled',
+        'created_at' => now(),
+        'updated_at' => now(),
+    ]);
+
+    DB::table('payment_records')->insert([
+        'settlement_bill_id' => $billId,
+        'payer_type' => 'player',
+        'payer_id' => $player->id,
+        'payee_type' => 'agent',
+        'payee_id' => 1,
+        'amount' => 100,
+        'status' => 'confirmed',
+        'created_at' => now(),
+        'updated_at' => now(),
+    ]);
+
+    $admin = AdminUser::query()->create([
+        'username' => 'ledger_settled_actions_super',
+        'name' => 'Ledger Settled Actions',
+        'email' => null,
+        'password' => Hash::make('secret-strong'),
+        'status' => 0,
+    ]);
+    grantSuperAdminRole($admin);
+    $token = $admin->createToken('test', ['*'], now()->addDay())->plainTextToken;
+
+    $this->withHeader('Authorization', 'Bearer '.$token)
+        ->getJson('/api/v1/admin/credit-ledger?admin_site_id='.$siteId.'&settlement_period_id='.$periodId.'&reason=payment_record')
+        ->assertOk()
+        ->assertJsonPath('data.items.0.available_actions', ['view_player', 'view_bill']);
+});
+
+test('credit ledger actionable_only paginates after hydration filter', function (): void {
+    $site = DB::table('admin_sites')->where('is_default', true)->first();
+    $siteId = (int) $site->id;
+    $siteCode = (string) $site->code;
+    $agentId = (int) DB::table('agent_nodes')->where('admin_site_id', $siteId)->where('depth', 0)->value('id');
+
+    $periodId = (int) DB::table('settlement_periods')->insertGetId([
+        'admin_site_id' => $siteId,
+        'period_start' => now()->subDay(),
+        'period_end' => now()->addDay(),
+        'status' => 'closed',
+        'created_at' => now(),
+        'updated_at' => now(),
+    ]);
+
+    $player = Player::query()->create([
+        'site_code' => $siteCode,
+        'site_player_id' => 'native:ledger-actionable',
+        'funding_mode' => PlayerFundingMode::CREDIT,
+        'username' => 'ledger_actionable_user',
+        'default_currency' => 'NPR',
+        'status' => 0,
+    ]);
+
+    DB::table('credit_ledger')->insert([
+        'owner_type' => 'player',
+        'owner_id' => $player->id,
+        'amount' => -100,
+        'reason' => 'bet_hold',
+        'created_at' => now()->subMinute(),
+        'updated_at' => now()->subMinute(),
+    ]);
+
+    $actionableBillId = (int) DB::table('settlement_bills')->insertGetId([
+        'settlement_period_id' => $periodId,
+        'bill_type' => 'player',
+        'owner_type' => 'player',
+        'owner_id' => $player->id,
+        'counterparty_type' => 'agent',
+        'counterparty_id' => $agentId,
+        'net_amount' => 200,
+        'unpaid_amount' => 200,
+        'paid_amount' => 0,
+        'status' => 'confirmed',
+        'created_at' => now(),
+        'updated_at' => now(),
+    ]);
+
+    $actionablePaymentId = (int) DB::table('payment_records')->insertGetId([
+        'settlement_bill_id' => $actionableBillId,
+        'payer_type' => 'player',
+        'payer_id' => $player->id,
+        'payee_type' => 'agent',
+        'payee_id' => $agentId,
+        'amount' => 50,
+        'status' => 'confirmed',
+        'created_at' => now(),
+        'updated_at' => now(),
+    ]);
+
+    $admin = AdminUser::query()->create([
+        'username' => 'ledger_actionable_super',
+        'name' => 'Ledger Actionable',
+        'email' => null,
+        'password' => Hash::make('secret-strong'),
+        'status' => 0,
+    ]);
+    grantSuperAdminRole($admin);
+    $token = $admin->createToken('test', ['*'], now()->addDay())->plainTextToken;
+
+    $this->withHeader('Authorization', 'Bearer '.$token)
+        ->getJson('/api/v1/admin/credit-ledger?admin_site_id='.$siteId.'&settlement_period_id='.$periodId.'&actionable_only=1')
+        ->assertOk()
+        ->assertJsonPath('data.total', 1)
+        ->assertJsonPath('data.items.0.entry_kind', 'payment')
+        ->assertJsonPath('data.items.0.id', $actionablePaymentId);
+
+    $this->withHeader('Authorization', 'Bearer '.$token)
+        ->getJson('/api/v1/admin/credit-ledger?admin_site_id='.$siteId.'&settlement_period_id='.$periodId.'&actionable_only=1&per_page=1&page=2')
+        ->assertOk()
+        ->assertJsonPath('data.total', 1)
+        ->assertJsonPath('data.items', []);
+});
+
 test('credit ledger entry_kind share returns share ledger rows', function (): void {
     $site = DB::table('admin_sites')->where('is_default', true)->first();
     $siteId = (int) $site->id;
@@ -301,11 +453,11 @@ test('credit ledger entry_kind share returns share ledger rows', function (): vo
 
 function createShareLedgerTicketItem(Player $player): int
 {
-    $draw = \App\Models\Draw::query()->create([
+    $draw = Draw::query()->create([
         'draw_no' => 'DRAW-SHARE-LEDGER',
         'business_date' => now()->toDateString(),
         'sequence_no' => random_int(1, 9999),
-        'status' => \App\Lottery\DrawStatus::Open->value,
+        'status' => DrawStatus::Open->value,
         'current_result_version' => 0,
         'settle_version' => 0,
         'is_reopened' => false,

tests/Feature/AgentSettlementListsApiTest.php

@@ -1,9 +1,9 @@
 <?php
 
 use App\Models\AdminUser;
-use Illuminate\Foundation\Testing\RefreshDatabase;
 use Illuminate\Support\Facades\DB;
 use Illuminate\Support\Facades\Hash;
+use Illuminate\Foundation\Testing\RefreshDatabase;
 
 uses(RefreshDatabase::class);
 
@@ -87,12 +87,30 @@ test('settlement payments and adjustments index return items', function (): void
     $this->withHeader('Authorization', 'Bearer '.$token)
         ->getJson('/api/v1/admin/settlement-payments?admin_site_id='.$siteId)
         ->assertOk()
-        ->assertJsonPath('data.items.0.settlement_bill_id', $billId);
+        ->assertJsonPath('data.items.0.settlement_bill_id', $billId)
+        ->assertJsonPath('data.total', 1)
+        ->assertJsonPath('data.page', 1);
 
     $this->withHeader('Authorization', 'Bearer '.$token)
         ->getJson('/api/v1/admin/settlement-adjustments?admin_site_id='.$siteId)
         ->assertOk()
-        ->assertJsonPath('data.items.0.original_bill_id', $billId);
+        ->assertJsonPath('data.items.0.original_bill_id', $billId)
+        ->assertJsonPath('data.total', 1);
+
+    $operations = $this->withHeader('Authorization', 'Bearer '.$token)
+        ->getJson('/api/v1/admin/settlement-operations?admin_site_id='.$siteId.'&settlement_period_id='.$periodId)
+        ->assertOk()
+        ->assertJsonPath('data.total', 2)
+        ->json('data.items');
+
+    expect(collect($operations)->pluck('kind')->sort()->values()->all())
+        ->toBe(['adjustment', 'payment']);
+
+    $this->withHeader('Authorization', 'Bearer '.$token)
+        ->getJson('/api/v1/admin/settlement-operations?admin_site_id='.$siteId.'&settlement_period_id='.$periodId.'&operation_type=payment')
+        ->assertOk()
+        ->assertJsonPath('data.total', 1)
+        ->assertJsonPath('data.items.0.kind', 'payment');
 
     $this->withHeader('Authorization', 'Bearer '.$token)
         ->getJson('/api/v1/admin/settlement-bills?admin_site_id='.$siteId.'&bill_type=player')

tests/Feature/FundOperationsHardeningTest.php

@@ -1,15 +1,15 @@
 <?php
 
-use App\Models\AdminUser;
 use App\Models\Player;
+use App\Models\AdminUser;
 use App\Models\PlayerWallet;
 use App\Models\TransferOrder;
-use App\Services\AgentSettlement\AgentSettlementBadDebtService;
-use App\Services\AgentSettlement\SettlementPaymentService;
-use App\Services\Wallet\LotteryTransferService;
-use Illuminate\Foundation\Testing\RefreshDatabase;
 use Illuminate\Support\Facades\DB;
 use Illuminate\Support\Facades\Hash;
+use App\Services\Wallet\LotteryTransferService;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use App\Services\AgentSettlement\SettlementPaymentService;
+use App\Services\AgentSettlement\AgentSettlementBadDebtService;
 
 uses(RefreshDatabase::class);
 
@@ -215,6 +215,70 @@ test('bad debt write off is idempotent when retried', function (): void {
         ->and(DB::table('settlement_adjustments')->where('original_bill_id', $billId)->count())->toBe(1);
 });
 
+test('bad debt write off idempotency key prevents duplicate records', function (): void {
+    $site = DB::table('admin_sites')->where('is_default', true)->first();
+    $agentId = (int) DB::table('agent_nodes')->where('depth', 0)->value('id');
+
+    $periodId = (int) DB::table('settlement_periods')->insertGetId([
+        'admin_site_id' => (int) $site->id,
+        'period_start' => now()->subDays(7),
+        'period_end' => now(),
+        'status' => 'closed',
+        'created_at' => now(),
+        'updated_at' => now(),
+    ]);
+
+    $player = Player::query()->create([
+        'site_code' => (string) $site->code,
+        'agent_node_id' => $agentId,
+        'site_player_id' => 'bd-idem-key',
+        'auth_source' => 'lottery_native',
+        'funding_mode' => 'credit',
+        'username' => 'bdidemkey',
+        'nickname' => null,
+        'default_currency' => 'NPR',
+        'status' => 0,
+    ]);
+
+    $billId = (int) DB::table('settlement_bills')->insertGetId([
+        'settlement_period_id' => $periodId,
+        'bill_type' => 'player',
+        'owner_type' => 'player',
+        'owner_id' => $player->id,
+        'counterparty_type' => 'agent',
+        'counterparty_id' => $agentId,
+        'gross_win_loss' => 5000,
+        'rebate_amount' => 0,
+        'adjustment_amount' => 0,
+        'net_amount' => 5000,
+        'paid_amount' => 0,
+        'unpaid_amount' => 5000,
+        'status' => 'overdue',
+        'confirmed_at' => now(),
+        'locked_at' => now(),
+        'created_at' => now(),
+        'updated_at' => now(),
+    ]);
+
+    $admin = AdminUser::query()->create([
+        'username' => 'bad_debt_key_admin',
+        'name' => 'Bad Debt Key',
+        'email' => null,
+        'password' => Hash::make('secret-strong'),
+        'status' => 0,
+    ]);
+
+    $service = app(AgentSettlementBadDebtService::class);
+    $key = 'bd-idem-key-1';
+    $first = $service->writeOff($billId, 'uncollectible', (int) $admin->id, $key);
+    $second = $service->writeOff($billId, 'uncollectible', (int) $admin->id, $key);
+
+    expect($second)->toBe($first)
+        ->and(DB::table('settlement_adjustments')->where('original_bill_id', $billId)->count())->toBe(1)
+        ->and(DB::table('settlement_adjustments')->where('original_bill_id', $billId)->value('idempotency_key'))
+        ->toBe($key);
+});
+
 test('out pending reconcile reverse still credits lottery wallet once', function (): void {
     $player = Player::query()->create([
         'site_code' => 'main',
@@ -258,4 +322,4 @@ test('out pending reconcile reverse still credits lottery wallet once', function
 
     expect((int) $wallet->balance)->toBe(1_400)
         ->and($order->status)->toBe('reversed');
-});
+});