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

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

app/Http/Controllers/Api/V1/Admin/AgentSettlement/AgentSettlementAdjustmentIndexController.php

@@ -2,16 +2,19 @@
 
 namespace App\Http\Controllers\Api\V1\Admin\AgentSettlement;
 
-use App\Http\Controllers\Controller;
-use App\Support\AdminAgentSettlementScope;
 use App\Support\ApiResponse;
-use Illuminate\Http\JsonResponse;
 use Illuminate\Http\Request;
-use Illuminate\Database\Query\Builder;
+use App\Support\PaginationTrait;
+use Illuminate\Http\JsonResponse;
 use Illuminate\Support\Facades\DB;
+use App\Http\Controllers\Controller;
+use Illuminate\Database\Query\Builder;
+use App\Support\AdminAgentSettlementScope;
 
 final class AgentSettlementAdjustmentIndexController extends Controller
 {
+    use PaginationTrait;
+
     public function __invoke(Request $request): JsonResponse
     {
         $admin = $request->lotteryAdmin();
@@ -69,8 +72,20 @@ final class AgentSettlementAdjustmentIndexController extends Controller
             });
         }
 
+        $meta = $this->paginationMeta($request, defaultPerPage: 20, maxPerPage: 200);
+        $paginator = $query->paginate(
+            $meta['per_page'],
+            ['sa.*', 'sp.period_start', 'sp.period_end', 'sp.admin_site_id', 'sb.bill_type as original_bill_type', 'sb.owner_type as original_owner_type', 'sb.owner_id as original_owner_id'],
+            'page',
+            $meta['page'],
+        );
+
         return ApiResponse::success([
-            'items' => $query->limit(200)->get(),
+            'items' => $paginator->items(),
+            'total' => $paginator->total(),
+            'page' => $paginator->currentPage(),
+            'per_page' => $paginator->perPage(),
+            'last_page' => $paginator->lastPage(),
         ]);
     }
 }

app/Http/Controllers/Api/V1/Admin/AgentSettlement/AgentSettlementBillBadDebtWriteOffController.php

@@ -2,15 +2,15 @@
 
 namespace App\Http\Controllers\Api\V1\Admin\AgentSettlement;
 
+use App\Support\ApiResponse;
+use App\Services\AuditLogger;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Support\Facades\DB;
 use App\Http\Controllers\Controller;
+use App\Support\AdminAgentSettlementScope;
 use App\Http\Middleware\RecordAdminApiAudit;
 use App\Http\Requests\Admin\AdminSettlementBillBadDebtRequest;
 use App\Services\AgentSettlement\AgentSettlementBadDebtService;
-use App\Services\AuditLogger;
-use App\Support\AdminAgentSettlementScope;
-use App\Support\ApiResponse;
-use Illuminate\Http\JsonResponse;
-use Illuminate\Support\Facades\DB;
 
 final class AgentSettlementBillBadDebtWriteOffController extends Controller
 {
@@ -31,6 +31,7 @@ final class AgentSettlementBillBadDebtWriteOffController extends Controller
             $settlement_bill,
             $request->validated('reason'),
             (int) $admin->id,
+            $request->validated('idempotency_key'),
         );
 
         $after = DB::table('settlement_bills')->where('id', $settlement_bill)->first();

app/Http/Controllers/Api/V1/Admin/AgentSettlement/AgentSettlementOperationsIndexController.php

@@ -0,0 +1,53 @@
+<?php
+
+namespace App\Http\Controllers\Api\V1\Admin\AgentSettlement;
+
+use App\Support\ApiResponse;
+use Illuminate\Http\Request;
+use App\Support\PaginationTrait;
+use Illuminate\Http\JsonResponse;
+use App\Http\Controllers\Controller;
+use App\Support\AdminAgentSettlementScope;
+use App\Services\AgentSettlement\SettlementOperationsListFilters;
+use App\Services\AgentSettlement\SettlementOperationsListService;
+
+/** GET /api/v1/admin/settlement-operations */
+final class AgentSettlementOperationsIndexController extends Controller
+{
+    use PaginationTrait;
+
+    public function __construct(
+        private readonly SettlementOperationsListService $operationsList,
+    ) {}
+
+    public function __invoke(Request $request): JsonResponse
+    {
+        $admin = $request->lotteryAdmin();
+        abort_if($admin === null, 401);
+
+        $filters = SettlementOperationsListFilters::fromQuery($request->query());
+
+        if ($filters->settlementPeriodId !== null) {
+            abort_if(! AdminAgentSettlementScope::periodAccessible($admin, $filters->settlementPeriodId), 403);
+        }
+
+        if ($filters->adminSiteId !== null) {
+            abort_if(! AdminAgentSettlementScope::siteAccessible($admin, $filters->adminSiteId), 403);
+        }
+
+        $page = $this->page($request);
+        $perPage = $this->perPage($request, 'per_page', 20, 100);
+
+        $result = $this->operationsList->list($admin, $page, $perPage, $filters);
+        $total = (int) $result['total'];
+        $lastPage = max(1, (int) ceil($total / max(1, $perPage)));
+
+        return ApiResponse::success([
+            'items' => $result['items'],
+            'total' => $total,
+            'page' => $page,
+            'per_page' => $perPage,
+            'last_page' => $lastPage,
+        ]);
+    }
+}

app/Http/Controllers/Api/V1/Admin/AgentSettlement/AgentSettlementPaymentIndexController.php

@@ -2,15 +2,18 @@
 
 namespace App\Http\Controllers\Api\V1\Admin\AgentSettlement;
 
+use App\Support\ApiResponse;
+use Illuminate\Http\Request;
+use App\Support\PaginationTrait;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Support\Facades\DB;
 use App\Http\Controllers\Controller;
 use App\Support\AdminAgentSettlementScope;
-use App\Support\ApiResponse;
-use Illuminate\Http\JsonResponse;
-use Illuminate\Http\Request;
-use Illuminate\Support\Facades\DB;
 
 final class AgentSettlementPaymentIndexController extends Controller
 {
+    use PaginationTrait;
+
     public function __invoke(Request $request): JsonResponse
     {
         $admin = $request->lotteryAdmin();
@@ -54,8 +57,15 @@ final class AgentSettlementPaymentIndexController extends Controller
 
         AdminAgentSettlementScope::applyDirectEdgeScopeToBillsQuery($query, $admin, 'sb');
 
+        $meta = $this->paginationMeta($request, defaultPerPage: 20, maxPerPage: 200);
+        $paginator = $query->paginate($meta['per_page'], ['pr.*', 'sb.bill_type', 'sb.owner_type', 'sb.owner_id', 'sb.counterparty_type', 'sb.counterparty_id', 'sp.period_start', 'sp.period_end', 'sp.admin_site_id'], 'page', $meta['page']);
+
         return ApiResponse::success([
-            'items' => $query->limit(200)->get(),
+            'items' => $paginator->items(),
+            'total' => $paginator->total(),
+            'page' => $paginator->currentPage(),
+            'per_page' => $paginator->perPage(),
+            'last_page' => $paginator->lastPage(),
         ]);
     }
 }