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

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

app/Services/Agent/AgentNodeService.php

@@ -120,7 +120,7 @@ final class AgentNodeService
             ]);
             AgentPlatformRole::assignPrimaryOperator($user, $node);
 
-            $this->agentProfileService->upsertForNode($node, [
+            $profilePayload = [
                 'total_share_rate' => (float) ($payload['total_share_rate'] ?? 0),
                 'credit_limit' => (int) ($payload['credit_limit'] ?? 0),
                 'rebate_limit' => (float) ($payload['rebate_limit'] ?? 0),
@@ -129,7 +129,11 @@ final class AgentNodeService
                 'can_grant_extra_rebate' => (bool) ($payload['can_grant_extra_rebate'] ?? false),
                 'can_create_child_agent' => (bool) ($payload['can_create_child_agent'] ?? false),
                 'can_create_player' => (bool) ($payload['can_create_player'] ?? true),
-            ], $parent);
+            ];
+            if (array_key_exists('relative_share_rate', $payload)) {
+                $profilePayload['relative_share_rate'] = (float) $payload['relative_share_rate'];
+            }
+            $this->agentProfileService->upsertForNode($node, $profilePayload, $parent);
 
             return $node->fresh(['adminSite']);
         });

app/Services/Agent/AgentProfileService.php

@@ -32,8 +32,22 @@ final class AgentProfileService
         $rebateLimit = (float) ($payload['rebate_limit'] ?? 0);
         $defaultRebate = (float) ($payload['default_player_rebate'] ?? 0);
 
+        $useRelative = $parent !== null && array_key_exists('relative_share_rate', $payload);
+
+        // 如果提供了相对占成比例，计算绝对总占成
+        if ($useRelative) {
+            $relativeShare = (float) $payload['relative_share_rate'];
+            $this->shareRateValidator->assertRelativeShareWithinBounds($relativeShare);
+            $parentRate = $this->shareRateValidator->totalShareRateForNode($parent);
+            $totalShare = round($parentRate * $relativeShare / 100, 2);
+        }
+
         if ($parent !== null) {
-            $this->shareRateValidator->assertChildWithinParent($parent, $totalShare);
+            $this->shareRateValidator->assertChildWithinParent(
+                $parent,
+                $totalShare,
+                $useRelative ? 'relative_share_rate' : 'total_share_rate',
+            );
         }
 
         return DB::transaction(function () use ($node, $payload, $parent, $totalShare, $creditLimit, $rebateLimit, $defaultRebate): AgentProfile {

app/Services/Agent/ShareRateValidator.php

@@ -8,17 +8,26 @@ use Illuminate\Validation\ValidationException;
 
 final class ShareRateValidator
 {
-    public function assertChildWithinParent(AgentNode $parent, float $childTotalShareRate): void
+    public function assertChildWithinParent(AgentNode $parent, float $childTotalShareRate, string $field = 'total_share_rate'): void
     {
         $parentRate = $this->totalShareRateForNode($parent);
         if ($childTotalShareRate > $parentRate) {
             throw ValidationException::withMessages([
-                'total_share_rate' => ['exceeds_parent'],
+                $field => ['exceeds_parent'],
             ]);
         }
         if ($childTotalShareRate < 0 || $childTotalShareRate > 100) {
             throw ValidationException::withMessages([
-                'total_share_rate' => ['invalid_range'],
+                $field => ['invalid_range'],
+            ]);
+        }
+    }
+
+    public function assertRelativeShareWithinBounds(float $relativeShareRate, string $field = 'relative_share_rate'): void
+    {
+        if ($relativeShareRate < 0 || $relativeShareRate > 100) {
+            throw ValidationException::withMessages([
+                $field => ['invalid_range'],
             ]);
         }
     }