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

- 新增 settlement-operations 合并列表 API，收付/调账接口改为标准分页 - actionable_only 流水在内存过滤后正确分页 - 已结账单流水不再展示补差/冲正快捷动作 - 坏账核销支持 idempotency_key 并写入 result_bill_id - 补充操作记录、流水与坏账幂等相关测试
2026-06-26 16:40:46 +08:00
parent 7ec8f4c5a2
commit c83343e989
20 changed files with 1045 additions and 212 deletions
--- a/app/Http/Controllers/Api/V1/Admin/AgentSettlement/AgentSettlementAdjustmentIndexController.php
+++ b/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(),
        ]);
    }
 }
--- a/app/Http/Controllers/Api/V1/Admin/AgentSettlement/AgentSettlementBillBadDebtWriteOffController.php
+++ b/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();
--- a/app/Http/Controllers/Api/V1/Admin/AgentSettlement/AgentSettlementOperationsIndexController.php
+++ b/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,
+        ]);
+    }
+}
--- a/app/Http/Controllers/Api/V1/Admin/AgentSettlement/AgentSettlementPaymentIndexController.php
+++ b/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(),
        ]);
    }
 }
--- a/app/Http/Controllers/Api/V1/E2E/E2ECaptchaPeekController.php
+++ b/app/Http/Controllers/Api/V1/E2E/E2ECaptchaPeekController.php
@@ -2,10 +2,12 @@

 namespace App\Http\Controllers\Api\V1\E2E;

-use App\Services\AdminCaptchaService;
+use App\Lottery\ErrorCode;
 use App\Support\ApiResponse;
-use Illuminate\Http\JsonResponse;
 use Illuminate\Http\Request;
+use Illuminate\Http\JsonResponse;
+use App\Http\Controllers\Controller;
+use App\Services\AdminCaptchaService;

 /**
 * E2E 辅助：peek captcha bypass 码。
@@ -14,14 +16,15 @@ use Illuminate\Http\Request;
 * 改用 e2e 约定：captcha_code == "LOTTERY_E2E_BYPASS" 在 LOTTERY_E2E=true 时视为通过。
 * 本端点不返回任何"答案"，仅返回约定码提示。
 */
-final class E2ECaptchaPeekController extends \App\Http\Controllers\Controller
+final class E2ECaptchaPeekController extends Controller
 {
    public function player(Request $request): JsonResponse
    {
        $key = (string) $request->input('captcha_key', '');
        if ($key === '') {
-            return ApiResponse::error('captcha_key required', 'e2e_invalid_input', null, 422);
+            return ApiResponse::error('captcha_key required', ErrorCode::ValidationFailed->value, null, 422);
        }
+
        return $this->peek($key, AdminCaptchaService::SCOPE_PLAYER);
    }

@@ -29,8 +32,9 @@ final class E2ECaptchaPeekController extends \App\Http\Controllers\Controller
    {
        $key = (string) $request->input('captcha_key', '');
        if ($key === '') {
-            return ApiResponse::error('captcha_key required', 'e2e_invalid_input', null, 422);
+            return ApiResponse::error('captcha_key required', ErrorCode::ValidationFailed->value, null, 422);
        }
+
        return $this->peek($key, AdminCaptchaService::SCOPE_ADMIN);
    }

--- a/app/Http/Controllers/Api/V1/E2E/E2EDrawController.php
+++ b/app/Http/Controllers/Api/V1/E2E/E2EDrawController.php
@@ -2,11 +2,14 @@

 namespace App\Http\Controllers\Api\V1\E2E;

+use App\Lottery\ErrorCode;
 use App\Lottery\DrawStatus;
 use App\Support\ApiResponse;
-use Illuminate\Http\JsonResponse;
 use Illuminate\Http\Request;
+use Illuminate\Http\JsonResponse;
 use Illuminate\Support\Facades\DB;
+use App\Http\Controllers\Controller;
+use Illuminate\Support\Facades\Artisan;

 /**
 * E2E 辅助：期号时间/状态快进。
@@ -19,13 +22,13 @@ use Illuminate\Support\Facades\DB;
 *
 * 严格仅在 LOTTERY_E2E=true 时由 E2EServiceProvider 注册。
 */
-final class E2EDrawController extends \App\Http\Controllers\Controller
+final class E2EDrawController extends Controller
 {
    public function closeNow(Request $request, string $drawNo): JsonResponse
    {
        $draw = DB::table('draws')->where('draw_no', $drawNo)->first();
        if (! $draw) {
-            return ApiResponse::error('draw not found', 'e2e_draw_missing', null, 404);
+            return ApiResponse::error('draw not found', ErrorCode::NotFound->value, null, 404);
        }

        DB::table('draws')
@@ -44,7 +47,7 @@ final class E2EDrawController extends \App\Http\Controllers\Controller
    {
        $draw = DB::table('draws')->where('draw_no', $drawNo)->first();
        if (! $draw) {
-            return ApiResponse::error('draw not found', 'e2e_draw_missing', null, 404);
+            return ApiResponse::error('draw not found', ErrorCode::NotFound->value, null, 404);
        }

        DB::table('draws')
@@ -62,7 +65,7 @@ final class E2EDrawController extends \App\Http\Controllers\Controller
    {
        $draw = DB::table('draws')->where('draw_no', $drawNo)->first();
        if (! $draw) {
-            return ApiResponse::error('draw not found', 'e2e_draw_missing', null, 404);
+            return ApiResponse::error('draw not found', ErrorCode::NotFound->value, null, 404);
        }

        DB::table('draws')
@@ -82,8 +85,9 @@ final class E2EDrawController extends \App\Http\Controllers\Controller
    {
        $draw = DB::table('draws')->where('draw_no', $drawNo)->first();
        if (! $draw) {
-            return ApiResponse::error('draw not found', 'e2e_draw_missing', null, 404);
+            return ApiResponse::error('draw not found', ErrorCode::NotFound->value, null, 404);
        }
+
        return $this->inspectById((int) $draw->id);
    }

@@ -91,11 +95,11 @@ final class E2EDrawController extends \App\Http\Controllers\Controller
    public function tick(Request $request): JsonResponse
    {
        try {
-            $exit = \Illuminate\Support\Facades\Artisan::call('lottery:draw-tick');
+            $exit = Artisan::call('lottery:draw-tick');
        } catch (\Throwable $e) {
            return ApiResponse::error(
                'draw-tick failed: '.$e->getMessage(),
-                'e2e_tick_failed',
+                ErrorCode::InternalError->value,
                ['trace' => array_slice(explode("\n", $e->getTraceAsString()), 0, 5)],
                500,
            );
@@ -103,13 +107,14 @@ final class E2EDrawController extends \App\Http\Controllers\Controller

        return ApiResponse::success([
            'exit_code' => $exit,
-            'output' => \Illuminate\Support\Facades\Artisan::output(),
+            'output' => Artisan::output(),
        ]);
    }

    private function inspectById(int $id): JsonResponse
    {
        $d = DB::table('draws')->where('id', $id)->first();
+
        return ApiResponse::success([
            'id' => (int) $d->id,
            'draw_no' => $d->draw_no,
--- a/app/Http/Controllers/Api/V1/E2E/E2EPlayerStateController.php
+++ b/app/Http/Controllers/Api/V1/E2E/E2EPlayerStateController.php
@@ -2,10 +2,12 @@

 namespace App\Http\Controllers\Api\V1\E2E;

+use App\Lottery\ErrorCode;
 use App\Support\ApiResponse;
-use Illuminate\Http\JsonResponse;
 use Illuminate\Http\Request;
+use Illuminate\Http\JsonResponse;
 use Illuminate\Support\Facades\DB;
+use App\Http\Controllers\Controller;

 /**
 * E2E 辅助：重置/查询玩家状态。
@@ -17,7 +19,7 @@ use Illuminate\Support\Facades\DB;
 *
 * 严格仅在 LOTTERY_E2E=true 时由 E2EServiceProvider 注册。
 */
-final class E2EPlayerStateController extends \App\Http\Controllers\Controller
+final class E2EPlayerStateController extends Controller
 {
    public function reset(Request $request): JsonResponse
    {
@@ -32,7 +34,7 @@ final class E2EPlayerStateController extends \App\Http\Controllers\Controller
            ->value('id');

        if (! $playerId) {
-            return ApiResponse::error('e2e player not found', 'e2e_player_missing', null, 404);
+            return ApiResponse::error('e2e player not found', ErrorCode::NotFound->value, null, 404);
        }

        DB::transaction(function () use ($playerId, $balance, $currency) {
@@ -70,7 +72,7 @@ final class E2EPlayerStateController extends \App\Http\Controllers\Controller
        $balance = (int) $request->input('balance', -1);

        if ($balance < 0) {
-            return ApiResponse::error('balance must be >= 0', 'e2e_invalid_input', null, 422);
+            return ApiResponse::error('balance must be >= 0', ErrorCode::ValidationFailed->value, null, 422);
        }

        $playerId = DB::table('players')
@@ -79,7 +81,7 @@ final class E2EPlayerStateController extends \App\Http\Controllers\Controller
            ->value('id');

        if (! $playerId) {
-            return ApiResponse::error('e2e player not found', 'e2e_player_missing', null, 404);
+            return ApiResponse::error('e2e player not found', ErrorCode::NotFound->value, null, 404);
        }

        DB::table('player_wallets')
@@ -130,7 +132,7 @@ final class E2EPlayerStateController extends \App\Http\Controllers\Controller
            ->first();

        if (! $player) {
-            return ApiResponse::error('e2e player not found', 'e2e_player_missing', null, 404);
+            return ApiResponse::error('e2e player not found', ErrorCode::NotFound->value, null, 404);
        }

        $wallets = DB::table('player_wallets')
--- a/app/Http/Controllers/Api/V1/E2E/E2EProvisionController.php
+++ b/app/Http/Controllers/Api/V1/E2E/E2EProvisionController.php
@@ -2,27 +2,29 @@

 namespace App\Http\Controllers\Api\V1\E2E;

+use Firebase\JWT\JWT;
+use App\Models\Player;
 use App\Models\AdminSite;
 use App\Models\AdminUser;
 use App\Models\AgentNode;
-use App\Models\Player;
+use App\Lottery\ErrorCode;
 use App\Models\PlayerWallet;
+use App\Support\ApiResponse;
+use Illuminate\Http\Request;
+use App\Support\PlayerAuthSource;
+use Illuminate\Http\JsonResponse;
+use App\Support\SiteOperatorRoles;
+use Illuminate\Support\Facades\DB;
+use App\Http\Controllers\Controller;
+use App\Support\PlatformSystemRoles;
+use Illuminate\Support\Facades\Hash;
 use App\Services\Agent\AgentNodeService;
 use App\Services\Integration\PartnerSiteConfigResolver;
-use App\Support\ApiResponse;
-use App\Support\PlatformSystemRoles;
-use App\Support\PlayerAuthSource;
-use App\Support\SiteOperatorRoles;
-use Firebase\JWT\JWT;
-use Illuminate\Http\JsonResponse;
-use Illuminate\Http\Request;
-use Illuminate\Support\Facades\DB;
-use Illuminate\Support\Facades\Hash;

 /**
 * E2E 辅助：信用玩家 / SSO JWT / 主站钱包 mock 配置。
 */
-final class E2EProvisionController extends \App\Http\Controllers\Controller
+final class E2EProvisionController extends Controller
 {
    public function setupCreditPlayer(Request $request): JsonResponse
    {
@@ -34,7 +36,7 @@ final class E2EProvisionController extends \App\Http\Controllers\Controller

        $site = AdminSite::query()->where('code', $siteCode)->first();
        if ($site === null) {
-            return ApiResponse::error('site not found', 'e2e_site_missing', null, 404);
+            return ApiResponse::error('site not found', ErrorCode::NotFound->value, null, 404);
        }

        $extra = $site->extra_json ?? [];
@@ -54,7 +56,7 @@ final class E2EProvisionController extends \App\Http\Controllers\Controller
            ->value('id');

        if ($rootId <= 0) {
-            return ApiResponse::error('root agent missing', 'e2e_agent_missing', null, 500);
+            return ApiResponse::error('root agent missing', ErrorCode::InternalError->value, null, 500);
        }

        $leafCode = (string) $request->input('agent_code', 'e2e_leaf');
@@ -64,9 +66,9 @@ final class E2EProvisionController extends \App\Http\Controllers\Controller
            ->first();

        if ($leaf === null) {
-            $super = \App\Models\AdminUser::query()->where('username', 'admin')->first();
+            $super = AdminUser::query()->where('username', 'admin')->first();
            if ($super === null) {
-                return ApiResponse::error('admin user missing', 'e2e_admin_missing', null, 500);
+                return ApiResponse::error('admin user missing', ErrorCode::InternalError->value, null, 500);
            }
            $leaf = app(AgentNodeService::class)->createChild($super, [
                'parent_id' => $rootId,
@@ -153,12 +155,12 @@ final class E2EProvisionController extends \App\Http\Controllers\Controller

        $site = AdminSite::query()->where('code', $siteCode)->first();
        if ($site === null) {
-            return ApiResponse::error('site not found', 'e2e_site_missing', null, 404);
+            return ApiResponse::error('site not found', ErrorCode::NotFound->value, null, 404);
        }

        $roleId = (int) DB::table('admin_roles')->where('slug', $roleSlug)->value('id');
        if ($roleId <= 0) {
-            return ApiResponse::error('role not found', 'e2e_role_missing', null, 500);
+            return ApiResponse::error('role not found', ErrorCode::InternalError->value, null, 500);
        }

        /** @var AdminUser $user */
@@ -192,7 +194,7 @@ final class E2EProvisionController extends \App\Http\Controllers\Controller
        $siteCode = (string) ($request->input('site_code') ?: env('E2E_PLAYER_SITE_CODE', 'demo'));
        $site = AdminSite::query()->where('code', $siteCode)->first();
        if ($site === null) {
-            return ApiResponse::error('site not found', 'e2e_site_missing', null, 404);
+            return ApiResponse::error('site not found', ErrorCode::NotFound->value, null, 404);
        }

        $siteId = (int) $site->id;
@@ -230,12 +232,12 @@ final class E2EProvisionController extends \App\Http\Controllers\Controller

        $site = AdminSite::query()->where('code', $siteCode)->first();
        if ($site === null) {
-            return ApiResponse::error('site not found', 'e2e_site_missing', null, 404);
+            return ApiResponse::error('site not found', ErrorCode::NotFound->value, null, 404);
        }

        $secret = $site->decryptedSsoJwtSecret();
        if (! is_string($secret) || $secret === '') {
-            return ApiResponse::error('sso secret missing on site', 'e2e_sso_secret_missing', null, 500);
+            return ApiResponse::error('sso secret missing on site', ErrorCode::InternalError->value, null, 500);
        }

        $now = time();
@@ -258,12 +260,12 @@ final class E2EProvisionController extends \App\Http\Controllers\Controller
        $siteCode = (string) ($request->input('site_code') ?: env('E2E_PLAYER_SITE_CODE', 'demo'));
        $baseUrl = rtrim((string) $request->input('base_url', ''), '/');
        if ($baseUrl === '') {
-            return ApiResponse::error('base_url required', 'e2e_invalid_input', null, 422);
+            return ApiResponse::error('base_url required', ErrorCode::ValidationFailed->value, null, 422);
        }

        $site = AdminSite::query()->where('code', $siteCode)->first();
        if ($site === null) {
-            return ApiResponse::error('site not found', 'e2e_site_missing', null, 404);
+            return ApiResponse::error('site not found', ErrorCode::NotFound->value, null, 404);
        }

        $site->wallet_api_url = $baseUrl;
@@ -286,7 +288,7 @@ final class E2EProvisionController extends \App\Http\Controllers\Controller

        $site = AdminSite::query()->where('code', $siteCode)->first();
        if ($site === null) {
-            return ApiResponse::error('site not found', 'e2e_site_missing', null, 404);
+            return ApiResponse::error('site not found', ErrorCode::NotFound->value, null, 404);
        }

        $site->wallet_api_url = null;
--- a/app/Http/Requests/Admin/AdminSettlementBillBadDebtRequest.php
+++ b/app/Http/Requests/Admin/AdminSettlementBillBadDebtRequest.php
@@ -15,6 +15,7 @@ final class AdminSettlementBillBadDebtRequest extends ApiFormRequest
    {
        return [
            'reason' => ['sometimes', 'nullable', 'string', 'max:255'],
+            'idempotency_key' => ['sometimes', 'nullable', 'string', 'max:64'],
        ];
    }
 }