fix: 部分收付累计释额并扩展结算 E2E 与 CI

账期收付改为按累计已付同步 credit_ledger，修复多笔 partial_paid 与坏账核销重复释额；新增 API E2E（占成、权限、部分收付/坏账）与 GitHub Actions e2e-api job。

Co-authored-by: Cursor <cursoragent@cursor.com>

app/Http/Controllers/Api/V1/E2E/E2EProvisionController.php

@@ -3,13 +3,16 @@
 namespace App\Http\Controllers\Api\V1\E2E;
 
 use App\Models\AdminSite;
+use App\Models\AdminUser;
 use App\Models\AgentNode;
 use App\Models\Player;
 use App\Models\PlayerWallet;
 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;
@@ -139,6 +142,87 @@ final class E2EProvisionController extends \App\Http\Controllers\Controller
         ]);
     }
 
+    public function setupSiteOperator(Request $request): JsonResponse
+    {
+        PlatformSystemRoles::ensureAll();
+
+        $roleSlug = (string) ($request->input('role_slug') ?: SiteOperatorRoles::SLUG_SITE_FINANCE);
+        $username = (string) ($request->input('username') ?: 'e2e_site_finance');
+        $password = (string) ($request->input('password') ?: env('E2E_PLAYER_PASSWORD', '12345678'));
+        $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);
+        }
+
+        $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);
+        }
+
+        /** @var AdminUser $user */
+        $user = AdminUser::query()->updateOrCreate(
+            ['username' => $username],
+            [
+                'name' => 'E2E Site Operator',
+                'email' => null,
+                'password' => $password,
+                'status' => 0,
+            ],
+        );
+
+        DB::table('admin_user_site_roles')->updateOrInsert(
+            ['admin_user_id' => $user->id, 'site_id' => $site->id],
+            ['role_id' => $roleId, 'granted_at' => now()],
+        );
+
+        return ApiResponse::success([
+            'admin_user_id' => (int) $user->id,
+            'username' => $username,
+            'password' => $password,
+            'role_slug' => $roleSlug,
+            'admin_site_id' => (int) $site->id,
+            'site_code' => $siteCode,
+        ]);
+    }
+
+    public function resetSiteSettlement(Request $request): JsonResponse
+    {
+        $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);
+        }
+
+        $siteId = (int) $site->id;
+        $periodIds = DB::table('settlement_periods')
+            ->where('admin_site_id', $siteId)
+            ->pluck('id')
+            ->all();
+
+        if ($periodIds !== []) {
+            $billIds = DB::table('settlement_bills')
+                ->whereIn('settlement_period_id', $periodIds)
+                ->pluck('id')
+                ->all();
+
+            if ($billIds !== []) {
+                DB::table('payment_records')->whereIn('settlement_bill_id', $billIds)->delete();
+            }
+
+            DB::table('settlement_adjustments')->whereIn('settlement_period_id', $periodIds)->delete();
+            DB::table('settlement_bills')->whereIn('settlement_period_id', $periodIds)->delete();
+            DB::table('settlement_periods')->where('admin_site_id', $siteId)->delete();
+        }
+
+        return ApiResponse::success([
+            'site_code' => $siteCode,
+            'admin_site_id' => $siteId,
+            'cleared_periods' => count($periodIds),
+        ]);
+    }
+
     public function mintSsoJwt(Request $request): JsonResponse
     {
         $siteCode = (string) ($request->input('site_code') ?: env('E2E_PLAYER_SITE_CODE', 'demo'));

app/Services/AgentSettlement/AgentSettlementBadDebtService.php

@@ -105,7 +105,8 @@ final class AgentSettlementBadDebtService
             if ((string) $original->owner_type === 'player' && (int) $original->owner_id > 0 && (int) $original->net_amount > 0) {
                 $player = Player::query()->find((int) $original->owner_id);
                 if ($player !== null) {
-                    $this->playerCreditService->releaseFromSettlement($player, $unpaid, $originalBillId);
+                    $cumulativePaid = (int) $original->paid_amount + $unpaid;
+                    $this->playerCreditService->releaseFromSettlement($player, $cumulativePaid, $originalBillId);
                 }
             }
 

app/Services/AgentSettlement/SettlementPaymentService.php

@@ -86,9 +86,9 @@ final class SettlementPaymentService
                 $player = Player::query()->find((int) $bill->owner_id);
                 if ($player !== null) {
                     if ((int) $bill->net_amount > 0) {
-                        $this->playerCreditService->releaseFromSettlement($player, $payAmount, $billId);
+                        $this->playerCreditService->releaseFromSettlement($player, $newPaid, $billId);
                     } elseif ((int) $bill->net_amount < 0) {
-                        $this->playerCreditService->applySettlementPayout($player, $payAmount, $billId);
+                        $this->playerCreditService->applySettlementPayout($player, $newPaid, $billId);
                     }
 
                     if ($status === 'settled') {

app/Services/Player/PlayerCreditService.php

@@ -359,62 +359,89 @@ final class PlayerCreditService
         ]);
     }
 
-    public function releaseFromSettlement(Player $player, int $amountMinor, int $billId): void
+    /**
+     * @param  int  $cumulativePaidMinor  账单累计已登记收付（minor），支持部分收付多笔递增。
+     */
+    public function releaseFromSettlement(Player $player, int $cumulativePaidMinor, int $billId): void
     {
-        if ($amountMinor <= 0 || ! PlayerFundingMode::usesCredit($player)) {
+        if ($cumulativePaidMinor <= 0 || ! PlayerFundingMode::usesCredit($player)) {
             return;
         }
 
-        // 幂等闸门：credit_ledger (settlement_bill, settlement_confirm) 唯一；重复调用直接返回。
-        try {
-            DB::table('credit_ledger')->insert([
-                'owner_type' => 'player',
-                'owner_id' => $player->id,
-                'amount' => $amountMinor,
-                'reason' => 'settlement_confirm',
-                'ref_type' => 'settlement_bill',
-                'ref_id' => $billId,
-                'created_at' => now(),
-                'updated_at' => now(),
-            ]);
-        } catch (QueryException $e) {
-            if ($this->isUniqueViolation($e)) {
-                return;
-            }
-            throw $e;
+        $delta = $this->syncSettlementBillLedger(
+            $player,
+            $billId,
+            'settlement_confirm',
+            $cumulativePaidMinor,
+        );
+        if ($delta > 0) {
+            $this->decreaseUsedCredit($player, $delta);
         }
-
-        $this->decreaseUsedCredit($player, $amountMinor);
     }
 
-    public function applySettlementPayout(Player $player, int $amountMinor, int $billId): void
+    /**
+     * @param  int  $cumulativePaidMinor  账单累计已登记收付（minor），支持部分收付多笔递增。
+     */
+    public function applySettlementPayout(Player $player, int $cumulativePaidMinor, int $billId): void
     {
-        if ($amountMinor <= 0) {
+        if ($cumulativePaidMinor <= 0 || ! PlayerFundingMode::usesCredit($player)) {
             return;
         }
 
-        if (! PlayerFundingMode::usesCredit($player)) {
-            return;
+        $this->syncSettlementBillLedger(
+            $player,
+            $billId,
+            'settlement_payout',
+            $cumulativePaidMinor,
+        );
+    }
+
+    /**
+     * 同步账期收付台账：每账单每种 reason 仅一行，amount 为累计已付；返回本次应追加的 minor 增量。
+     */
+    private function syncSettlementBillLedger(
+        Player $player,
+        int $billId,
+        string $reason,
+        int $cumulativeMinor,
+    ): int {
+        $existing = DB::table('credit_ledger')
+            ->where('owner_type', 'player')
+            ->where('owner_id', $player->id)
+            ->where('reason', $reason)
+            ->where('ref_type', 'settlement_bill')
+            ->where('ref_id', $billId)
+            ->lockForUpdate()
+            ->first();
+
+        $recorded = $existing !== null ? (int) $existing->amount : 0;
+        $delta = $cumulativeMinor - $recorded;
+        if ($delta <= 0) {
+            return 0;
         }
 
-        // 幂等闸门：credit_ledger (settlement_bill, settlement_payout) 唯一；重复入账直接返回。
-        try {
+        $now = now();
+        if ($existing === null) {
             DB::table('credit_ledger')->insert([
                 'owner_type' => 'player',
                 'owner_id' => $player->id,
-                'amount' => $amountMinor,
-                'reason' => 'settlement_payout',
+                'amount' => $cumulativeMinor,
+                'reason' => $reason,
                 'ref_type' => 'settlement_bill',
                 'ref_id' => $billId,
-                'created_at' => now(),
-                'updated_at' => now(),
+                'created_at' => $now,
+                'updated_at' => $now,
             ]);
-        } catch (QueryException $e) {
-            if ($this->isUniqueViolation($e)) {
-                return;
-            }
-            throw $e;
+        } else {
+            DB::table('credit_ledger')
+                ->where('id', (int) $existing->id)
+                ->update([
+                    'amount' => $cumulativeMinor,
+                    'updated_at' => $now,
+                ]);
         }
+
+        return $delta;
     }
 
     private function decreaseUsedCredit(Player $player, int $amountMinor): void