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

- 在多个控制器中引入 SettlementPartyEnrichment 服务，以优化代理结算和账单的处理逻辑。 - 更新 AgentSettlementBillIndexController 和 AgentSettlementBillShowController，支持根据账单 ID 和关键字进行查询。 - 在 AgentSettlementPeriodCloseController 中添加对站点管理权限的验证，确保只有具备相应权限的管理员能够关闭账期。 - 在 AgentSettlementPeriodIndexController 中更新账期数据的返回格式，提升数据的完整性和可用性。 - 引入对相对占成比例的支持，增强代理资料的管理能力，确保数据一致性。
2026-06-05 18:00:56 +08:00
parent a44679665d
commit 2d32f006c5
63 changed files with 4893 additions and 288 deletions
--- a/app/Services/AgentSettlement/AgentSettlementPeriodOpenService.php
+++ b/app/Services/AgentSettlement/AgentSettlementPeriodOpenService.php
@@ -0,0 +1,62 @@
+<?php
+
+namespace App\Services\AgentSettlement;
+
+use Illuminate\Support\Facades\DB;
+use Illuminate\Validation\ValidationException;
+
+final class AgentSettlementPeriodOpenService
+{
+    /**
+     * @param  array{admin_site_id: int, period_start: string, period_end: string}  $data
+     * @return object{id: int, admin_site_id: int, period_start: string, period_end: string, status: string}
+     */
+    public function open(array $data): object
+    {
+        $siteId = (int) $data['admin_site_id'];
+        $start = (string) $data['period_start'];
+        $end = (string) $data['period_end'];
+
+        $existingSameRange = DB::table('settlement_periods')
+            ->where('admin_site_id', $siteId)
+            ->where('status', 'open')
+            ->where('period_start', $start)
+            ->where('period_end', $end)
+            ->orderByDesc('id')
+            ->first();
+
+        if ($existingSameRange !== null) {
+            throw ValidationException::withMessages([
+                'period_start' => ['period_already_open'],
+            ]);
+        }
+
+        $otherOpen = DB::table('settlement_periods')
+            ->where('admin_site_id', $siteId)
+            ->where('status', 'open')
+            ->orderByDesc('id')
+            ->first();
+
+        if ($otherOpen !== null) {
+            throw ValidationException::withMessages([
+                'period_start' => ['period_site_has_open'],
+            ]);
+        }
+
+        $id = (int) DB::table('settlement_periods')->insertGetId([
+            'admin_site_id' => $siteId,
+            'period_start' => $start,
+            'period_end' => $end,
+            'status' => 'open',
+            'created_at' => now(),
+            'updated_at' => now(),
+        ]);
+
+        $row = DB::table('settlement_periods')->where('id', $id)->first();
+        if ($row === null) {
+            throw new \RuntimeException('period_insert_failed');
+        }
+
+        return $row;
+    }
+}