feat: 增强代理和玩家管理功能

- 在多个控制器中更新权限检查逻辑，确保管理员能够更灵活地管理代理和玩家。
- 在 AdminPlayerStoreController 中引入对玩家创建能力的验证，确保只有具备相应权限的管理员能够创建玩家。
- 更新请求验证逻辑，新增 credit_limit、rebate_rate 和 extra_rebate_rate 字段，以支持更细粒度的玩家管理。
- 在 AgentNodeProfileController 中添加对父代理能力授予的验证，确保子代理的权限在父代理范围内。
- 引入 AgentProfileFieldRules 以简化代理资料更新请求的规则定义，提升代码复用性。

app/Services/AgentSettlement/AgentSettlementPeriodCloseService.php

@@ -2,13 +2,20 @@
 
 namespace App\Services\AgentSettlement;
 
-use App\Support\Settlement\DesignDocExample12;
+use App\Models\AgentNode;
+use App\Services\Agent\AgentCreditAllocatedSyncService;
+use App\Support\AgentSettlementProductionGuard;
 use Illuminate\Support\Facades\DB;
 
 final class AgentSettlementPeriodCloseService
 {
     public function __construct(
-        private readonly ShareSettlementCalculator $calculator,
+        private readonly AgentPeriodAggregator $aggregator,
+        private readonly SettlementBillGenerator $billGenerator,
+        private readonly PeriodCloseRebateService $periodCloseRebate,
+        private readonly UnsettledTicketPeriodWarning $unsettledWarning,
+        private readonly PlatformRoundingAdjuster $platformRounding,
+        private readonly AgentCreditAllocatedSyncService $allocatedSync,
     ) {}
 
     /**
@@ -16,51 +23,74 @@ final class AgentSettlementPeriodCloseService
      */
     public function closePeriod(int $periodId): array
     {
+        AgentSettlementProductionGuard::assertProductionCloseAllowed();
+
         $period = DB::table('settlement_periods')->where('id', $periodId)->first();
         if ($period === null) {
             throw new \InvalidArgumentException('period_not_found');
         }
 
-        $result = $this->calculator->calculate(
-            sharedNetWinLoss: DesignDocExample12::SHARED_NET_WIN_LOSS,
-            totalSharesByCode: [
-                'A' => DesignDocExample12::TOTAL_SHARE_A,
-                'B' => DesignDocExample12::TOTAL_SHARE_B,
-                'C' => DesignDocExample12::TOTAL_SHARE_C,
-            ],
-            extraRebateByCode: ['C' => DesignDocExample12::EXTRA_REBATE_BY_C],
-            gameWinLoss: DesignDocExample12::GAME_WIN_LOSS,
-            basicRebate: DesignDocExample12::BASIC_REBATE,
-            chainFromPlayer: ['C', 'B', 'A'],
+        if ((string) $period->status === 'closed') {
+            throw new \InvalidArgumentException('period_already_closed');
+        }
+
+        $adminSiteId = (int) $period->admin_site_id;
+        $aggregate = $this->aggregator->aggregate(
+            $adminSiteId,
+            (string) $period->period_start,
+            (string) $period->period_end,
         );
 
-        $playerBillId = DB::table('settlement_bills')->insertGetId([
-            'settlement_period_id' => $periodId,
-            'bill_type' => 'player',
-            'owner_type' => 'player',
-            'owner_id' => 0,
-            'counterparty_type' => 'agent',
-            'counterparty_id' => 0,
-            'gross_win_loss' => DesignDocExample12::GAME_WIN_LOSS,
-            'rebate_amount' => DesignDocExample12::BASIC_REBATE + DesignDocExample12::EXTRA_REBATE_BY_C,
-            'adjustment_amount' => 0,
-            'net_amount' => (int) DesignDocExample12::PLAYER_NET_SETTLEMENT,
-            'paid_amount' => 0,
-            'unpaid_amount' => (int) DesignDocExample12::PLAYER_NET_SETTLEMENT,
-            'status' => 'pending',
-            'created_at' => now(),
-            'updated_at' => now(),
-        ]);
+        if ($aggregate['players'] === []) {
+            throw new \InvalidArgumentException('period_no_ledger_rows');
+        }
+
+        $billIds = $this->billGenerator->generate($periodId, $adminSiteId, $aggregate);
+
+        $roundingDiff = $this->platformRounding->apply($periodId, $aggregate);
+
+        $rebateStats = $this->periodCloseRebate->dispatchAndAllocate(
+            $periodId,
+            (string) $period->period_start,
+            (string) $period->period_end,
+        );
+
+        $unsettled = $this->unsettledWarning->countForSite(
+            $adminSiteId,
+            (string) $period->period_start,
+            (string) $period->period_end,
+        );
 
         DB::table('settlement_periods')->where('id', $periodId)->update([
             'status' => 'closed',
             'updated_at' => now(),
         ]);
 
+        DB::table('share_ledger')
+            ->whereBetween('settled_at', [$period->period_start, $period->period_end])
+            ->update(['settlement_period_id' => $periodId]);
+
+        $this->reconcileAllocatedCreditForSite($adminSiteId);
+
         return [
             'period_id' => $periodId,
-            'settlement' => $result,
-            'player_bill_id' => $playerBillId,
+            'bill_ids' => $billIds,
+            'player_count' => count($aggregate['players']),
+            'agent_edges' => $aggregate['agent_edges'],
+            'rebate_dispatched' => $rebateStats['dispatched'],
+            'rebate_allocations' => $rebateStats['allocations'],
+            'unsettled_ticket_count' => $unsettled['count'],
+            'unsettled_ticket_sample' => $unsettled['ticket_item_ids'],
+            'platform_rounding_adjustment' => $roundingDiff,
         ];
     }
+
+    /** 关账后按真理源重算各代理「已下发额度」，避免与直属玩家/下级代理授信脱节。 */
+    private function reconcileAllocatedCreditForSite(int $adminSiteId): void
+    {
+        $nodes = AgentNode::query()->where('admin_site_id', $adminSiteId)->get();
+        foreach ($nodes as $node) {
+            $this->allocatedSync->syncForAgent($node);
+        }
+    }
 }