feat: 增强代理结算和账单管理功能

- 在多个控制器中引入 SettlementPartyEnrichment 服务，以优化代理结算和账单的处理逻辑。
- 更新 AgentSettlementBillIndexController 和 AgentSettlementBillShowController，支持根据账单 ID 和关键字进行查询。
- 在 AgentSettlementPeriodCloseController 中添加对站点管理权限的验证，确保只有具备相应权限的管理员能够关闭账期。
- 在 AgentSettlementPeriodIndexController 中更新账期数据的返回格式，提升数据的完整性和可用性。
- 引入对相对占成比例的支持，增强代理资料的管理能力，确保数据一致性。

tests/Feature/AgentSettlementPeriodOpenTest.php

@@ -0,0 +1,74 @@
+<?php
+
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Illuminate\Support\Facades\DB;
+
+uses(RefreshDatabase::class);
+
+beforeEach(function (): void {
+    $this->artisan('lottery:admin-auth-sync')->assertExitCode(0);
+});
+
+test('cannot open duplicate settlement period for same range', function (): void {
+    $siteId = (int) DB::table('admin_sites')->where('is_default', true)->value('id');
+    $super = \App\Models\AdminUser::query()->create([
+        'username' => 'period_dup_super',
+        'name' => 'Super',
+        'email' => null,
+        'password' => \Illuminate\Support\Facades\Hash::make('secret-strong'),
+        'status' => 0,
+    ]);
+    grantSuperAdminRole($super);
+    $token = $super->createToken('test', ['*'], now()->addDay())->plainTextToken;
+
+    $body = [
+        'admin_site_id' => $siteId,
+        'period_start' => '2026-06-01 00:00:00',
+        'period_end' => '2026-06-30 23:59:59',
+    ];
+
+    $this->withHeader('Authorization', 'Bearer '.$token)
+        ->postJson('/api/v1/admin/settlement-periods', $body)
+        ->assertCreated();
+
+    $this->withHeader('Authorization', 'Bearer '.$token)
+        ->postJson('/api/v1/admin/settlement-periods', $body)
+        ->assertStatus(422)
+        ->assertJsonPath(
+            'data.errors.period_start.0',
+            trans('validation.business.period_already_open'),
+        );
+});
+
+test('cannot open second settlement period while another is open on same site', function (): void {
+    $siteId = (int) DB::table('admin_sites')->where('is_default', true)->value('id');
+    $super = \App\Models\AdminUser::query()->create([
+        'username' => 'period_one_open_super',
+        'name' => 'Super',
+        'email' => null,
+        'password' => \Illuminate\Support\Facades\Hash::make('secret-strong'),
+        'status' => 0,
+    ]);
+    grantSuperAdminRole($super);
+    $token = $super->createToken('test', ['*'], now()->addDay())->plainTextToken;
+
+    $this->withHeader('Authorization', 'Bearer '.$token)
+        ->postJson('/api/v1/admin/settlement-periods', [
+            'admin_site_id' => $siteId,
+            'period_start' => '2026-06-01 00:00:00',
+            'period_end' => '2026-06-07 23:59:59',
+        ])
+        ->assertCreated();
+
+    $this->withHeader('Authorization', 'Bearer '.$token)
+        ->postJson('/api/v1/admin/settlement-periods', [
+            'admin_site_id' => $siteId,
+            'period_start' => '2026-06-08 00:00:00',
+            'period_end' => '2026-06-14 23:59:59',
+        ])
+        ->assertStatus(422)
+        ->assertJsonPath(
+            'data.errors.period_start.0',
+            trans('validation.business.period_site_has_open'),
+        );
+});