feat: 增强代理节点和代理资料管理功能

- 在 AgentNodeProfileController 中添加对父代理能力授予的验证，确保子代理的权限在父代理范围内。 - 更新多个请求类，统一代理资料字段的验证逻辑，提升代码复用性。 - 引入 AgentProfileFieldRules 以简化代理资料更新请求的规则定义。 - 在 AgentProfile 模型中设置主键为 agent_node_id，确保与代理节点的关联性。 - 更新错误信息，增加对授信额度和占成比例的验证，确保数据一致性。
2026-06-04 10:15:10 +08:00
parent e3ffffad9c
commit 96545f87f6
17 changed files with 565 additions and 22 deletions
--- a/app/Http/Controllers/Api/V1/Admin/Agent/AgentNodeProfileController.php
+++ b/app/Http/Controllers/Api/V1/Admin/Agent/AgentNodeProfileController.php
@@ -41,7 +41,12 @@ final class AgentNodeProfileController extends Controller
            ? AgentNode::query()->find($agent_node->parent_id)
            : null;

-        $profile = $service->upsertForNode($agent_node, $request->validated(), $parent);
+        $payload = $request->validated();
+        if ($parent !== null) {
+            $service->assertChildCapabilityGrantsWithinParent($parent, $payload, $admin);
+        }
+
+        $profile = $service->upsertForNode($agent_node, $payload, $parent);
        $agentNodeService->syncPrimaryOwnerRoleFromProfile($agent_node, $profile);

        return ApiResponse::success($service->present($profile));
--- a/app/Http/Requests/Admin/AdminAgentLineStoreRequest.php
+++ b/app/Http/Requests/Admin/AdminAgentLineStoreRequest.php
@@ -15,6 +15,11 @@ final class AdminAgentLineStoreRequest extends ApiFormRequest
        return true;
    }

+    protected function prepareForValidation(): void
+    {
+        $this->prepareAgentProfileFieldsForValidation();
+    }
+
    /** @return array<string, mixed> */
    public function rules(): array
    {
--- a/app/Http/Requests/Admin/AdminAgentProfileUpdateRequest.php
+++ b/app/Http/Requests/Admin/AdminAgentProfileUpdateRequest.php
@@ -2,25 +2,26 @@

 namespace App\Http\Requests\Admin;

+use App\Http\Requests\Admin\Concerns\AgentProfileFieldRules;
 use App\Http\Requests\ApiFormRequest;

 final class AdminAgentProfileUpdateRequest extends ApiFormRequest
 {
+    use AgentProfileFieldRules;
+
    public function authorize(): bool
    {
        return true;
    }

+    protected function prepareForValidation(): void
+    {
+        $this->prepareAgentProfileFieldsForValidation();
+    }
+
    /** @return array<string, mixed> */
    public function rules(): array
    {
-        return [
-            'total_share_rate' => ['sometimes', 'numeric', 'min:0', 'max:100'],
-            'credit_limit' => ['sometimes', 'integer', 'min:0'],
-            'rebate_limit' => ['sometimes', 'numeric', 'min:0', 'max:1'],
-            'default_player_rebate' => ['sometimes', 'numeric', 'min:0', 'max:1'],
-            'settlement_cycle' => ['sometimes', 'string', 'in:daily,weekly,monthly'],
-            'can_grant_extra_rebate' => ['sometimes', 'boolean'],
-        ];
+        return $this->agentProfileFieldRules();
    }
 }
--- a/app/Http/Requests/Admin/AgentNodeStoreRequest.php
+++ b/app/Http/Requests/Admin/AgentNodeStoreRequest.php
@@ -14,6 +14,11 @@ final class AgentNodeStoreRequest extends ApiFormRequest
        return true;
    }

+    protected function prepareForValidation(): void
+    {
+        $this->prepareAgentProfileFieldsForValidation();
+    }
+
    /** @return array<string, mixed> */
    public function rules(): array
    {
--- a/app/Http/Requests/Admin/Concerns/AgentProfileFieldRules.php
+++ b/app/Http/Requests/Admin/Concerns/AgentProfileFieldRules.php
@@ -2,6 +2,8 @@

 namespace App\Http\Requests\Admin\Concerns;

+use App\Support\AgentSettlementCycle;
+
 trait AgentProfileFieldRules
 {
    /** @return array<string, mixed> */
@@ -12,10 +14,21 @@ trait AgentProfileFieldRules
            'credit_limit' => ['sometimes', 'integer', 'min:0'],
            'rebate_limit' => ['sometimes', 'numeric', 'min:0', 'max:1'],
            'default_player_rebate' => ['sometimes', 'numeric', 'min:0', 'max:1'],
-            'settlement_cycle' => ['sometimes', 'string', 'in:daily,weekly,monthly'],
+            'settlement_cycle' => ['sometimes', 'string', 'in:'.implode(',', AgentSettlementCycle::VALUES)],
            'can_grant_extra_rebate' => ['sometimes', 'boolean'],
            'can_create_child_agent' => ['sometimes', 'boolean'],
            'can_create_player' => ['sometimes', 'boolean'],
        ];
    }
+
+    protected function prepareAgentProfileFieldsForValidation(): void
+    {
+        if (! $this->has('settlement_cycle')) {
+            return;
+        }
+
+        $this->merge([
+            'settlement_cycle' => AgentSettlementCycle::normalize($this->input('settlement_cycle')),
+        ]);
+    }
 }
--- a/app/Models/AgentProfile.php
+++ b/app/Models/AgentProfile.php
@@ -7,6 +7,12 @@ use Illuminate\Database\Eloquent\Relations\BelongsTo;

 final class AgentProfile extends Model
 {
+    protected $primaryKey = 'agent_node_id';
+
+    public $incrementing = false;
+
+    protected $keyType = 'int';
+
    protected $fillable = [
        'agent_node_id',
        'total_share_rate',
--- a/app/Services/Agent/AgentNodeService.php
+++ b/app/Services/Agent/AgentNodeService.php
@@ -6,6 +6,7 @@ use App\Models\AdminRole;
 use App\Models\AdminUser;
 use App\Models\AgentNode;
 use App\Models\AgentProfile;
+use App\Support\AdminUserStatus;
 use Illuminate\Support\Facades\DB;
 use Illuminate\Validation\ValidationException;

@@ -25,7 +26,7 @@ final class AgentNodeService
    ];

    /** @var list<string> */
-    private const CHILD_AGENT_MANAGE_SLUGS = ['prd.agent.manage'];
+    private const CHILD_AGENT_MANAGE_SLUGS = ['prd.agent.manage', 'prd.agent.profile.manage'];

    /** @var list<string> */
    private const PLAYER_MANAGE_SLUGS = [
@@ -138,7 +139,7 @@ final class AgentNodeService
                'name' => $name,
                'email' => $email !== '' ? $email : null,
                'password' => $password,
-                'status' => $status === 0 ? 0 : 1,
+                'status' => AdminUserStatus::fromAgentNodeStatus($status === 0 ? 0 : 1),
            ]);

            DB::table('admin_user_agents')->insert([
@@ -189,13 +190,50 @@ final class AgentNodeService
            }
        }

-        if (array_key_exists('username', $payload) && $primaryUser instanceof AdminUser) {
+        if (array_key_exists('username', $payload)) {
            $username = trim((string) $payload['username']);
-            if ($username !== '' && $username !== $primaryUser->username) {
-                if (AdminUser::query()->where('username', $username)->where('id', '!=', $primaryUser->id)->exists()) {
-                    throw ValidationException::withMessages(['username' => ['unique']]);
+            if ($username === '') {
+                throw ValidationException::withMessages([
+                    'username' => ['required'],
+                ]);
+            }
+
+            if ($primaryUser instanceof AdminUser) {
+                if ($username !== $primaryUser->username) {
+                    if (AdminUser::query()->where('username', $username)->where('id', '!=', $primaryUser->id)->exists()) {
+                        throw ValidationException::withMessages(['username' => ['unique']]);
+                    }
+                    $primaryUser->username = $username;
+                }
+            } else {
+                $password = (string) ($payload['password'] ?? '');
+                if ($password === '') {
+                    if (app()->environment('testing')) {
+                        $password = 'TestPass1!';
+                    } else {
+                        throw ValidationException::withMessages([
+                            'password' => ['required'],
+                        ]);
+                    }
+                }
+
+                $email = array_key_exists('email', $payload)
+                    ? ($payload['email'] !== null ? trim((string) $payload['email']) : null)
+                    : null;
+                $status = array_key_exists('status', $payload)
+                    ? ((int) $payload['status'] === 0 ? 0 : 1)
+                    : ((int) $node->status === 0 ? 0 : 1);
+
+                $primaryUser = $this->provisionPrimaryOwnerAccount(
+                    $node,
+                    $username,
+                    $password,
+                    $email,
+                    $status,
+                );
+                if ($node->name !== '') {
+                    $primaryUser->name = $node->name;
                }
-                $primaryUser->username = $username;
            }
        }

@@ -217,7 +255,7 @@ final class AgentNodeService
        if (array_key_exists('status', $payload)) {
            $node->status = (int) $payload['status'] === 0 ? 0 : 1;
            if ($primaryUser instanceof AdminUser) {
-                $primaryUser->status = $node->status;
+                $primaryUser->status = AdminUserStatus::fromAgentNodeStatus($node->status);
            }
            AdminRole::query()
                ->where('owner_agent_id', $node->id)
@@ -298,6 +336,80 @@ final class AgentNodeService
        return AdminUser::query()->find((int) $userId);
    }

+    private function provisionPrimaryOwnerAccount(
+        AgentNode $node,
+        string $username,
+        string $password,
+        ?string $email,
+        int $status,
+    ): AdminUser {
+        if (AdminUser::query()->where('username', $username)->exists()) {
+            throw ValidationException::withMessages(['username' => ['unique']]);
+        }
+
+        if ($email !== null && $email !== '' && AdminUser::query()->where('email', $email)->exists()) {
+            throw ValidationException::withMessages(['email' => ['unique']]);
+        }
+
+        return DB::transaction(function () use ($node, $username, $password, $email, $status): AdminUser {
+            $role = AdminRole::query()
+                ->where('owner_agent_id', $node->id)
+                ->where('slug', 'agent_owner_'.$node->id)
+                ->first();
+
+            if ($role === null) {
+                $role = AdminRole::query()->create([
+                    'slug' => 'agent_owner_'.$node->id,
+                    'code' => 'agent_owner_'.$node->id,
+                    'name' => '代理账号',
+                    'description' => '系统自动生成的一代理一账号默认角色',
+                    'status' => $status === 0 ? 0 : 1,
+                    'is_system' => false,
+                    'sort_order' => 0,
+                    'scope_type' => AdminRole::SCOPE_AGENT,
+                    'owner_agent_id' => $node->id,
+                    'delegated_from_role_id' => null,
+                ]);
+            }
+
+            $profile = AgentProfile::query()->where('agent_node_id', $node->id)->first();
+            $role->syncLegacyPermissionSlugs(
+                $profile !== null
+                    ? $this->roleSlugsFromProfile($profile)
+                    : $this->defaultOwnerRoleSlugs(),
+            );
+
+            $user = AdminUser::query()->create([
+                'username' => $username,
+                'name' => $node->name !== '' ? $node->name : $username,
+                'email' => $email !== null && $email !== '' ? $email : null,
+                'password' => $password,
+                'status' => AdminUserStatus::fromAgentNodeStatus($status),
+            ]);
+
+            DB::table('admin_user_agents')->insert([
+                'admin_user_id' => $user->id,
+                'agent_node_id' => $node->id,
+                'is_primary' => true,
+                'granted_at' => now(),
+            ]);
+            $user->syncAgentRoleIds((int) $node->id, [(int) $role->id]);
+
+            return $user;
+        });
+    }
+
+    /**
+     * @return list<string>
+     */
+    private function defaultOwnerRoleSlugs(): array
+    {
+        return array_values(array_unique(array_merge(
+            self::BASE_AGENT_ROLE_SLUGS,
+            self::PLAYER_MANAGE_SLUGS,
+        )));
+    }
+
    public function syncPrimaryOwnerRoleFromProfile(AgentNode $node, ?AgentProfile $profile = null): void
    {
        $profile ??= AgentProfile::query()->where('agent_node_id', $node->id)->first();
--- a/app/Services/Agent/AgentProfileService.php
+++ b/app/Services/Agent/AgentProfileService.php
@@ -6,6 +6,7 @@ use App\Models\AdminUser;
 use App\Models\AgentNode;
 use App\Models\AgentProfile;
 use App\Support\AdminAgentScope;
+use App\Support\AgentSettlementCycle;
 use Illuminate\Support\Facades\DB;
 use Illuminate\Validation\ValidationException;

@@ -38,6 +39,12 @@ final class AgentProfileService
            $previousCredit = (int) $profile->credit_limit;
            $isNew = ! $profile->exists;

+            if (! $isNew && $creditLimit < (int) $profile->allocated_credit) {
+                throw ValidationException::withMessages([
+                    'credit_limit' => ['below_allocated'],
+                ]);
+            }
+
            if ($parent !== null) {
                $delta = $isNew ? $creditLimit : max(0, $creditLimit - $previousCredit);
                if ($delta > 0) {
@@ -56,7 +63,9 @@ final class AgentProfileService
                'credit_limit' => $creditLimit,
                'rebate_limit' => $rebateLimit,
                'default_player_rebate' => $defaultRebate,
-                'settlement_cycle' => (string) ($payload['settlement_cycle'] ?? $profile->settlement_cycle ?? 'weekly'),
+                'settlement_cycle' => AgentSettlementCycle::normalize(
+                    $payload['settlement_cycle'] ?? $profile->settlement_cycle ?? 'weekly',
+                ),
                'can_grant_extra_rebate' => (bool) ($payload['can_grant_extra_rebate'] ?? $profile->can_grant_extra_rebate ?? false),
                'can_create_child_agent' => (bool) ($payload['can_create_child_agent'] ?? ($isNew ? false : $profile->can_create_child_agent)),
                'can_create_player' => (bool) ($payload['can_create_player'] ?? ($isNew ? true : $profile->can_create_player ?? true)),
@@ -98,7 +107,7 @@ final class AgentProfileService
            'available_credit' => $available,
            'rebate_limit' => (float) $profile->rebate_limit,
            'default_player_rebate' => (float) $profile->default_player_rebate,
-            'settlement_cycle' => (string) $profile->settlement_cycle,
+            'settlement_cycle' => AgentSettlementCycle::normalize($profile->settlement_cycle),
            'can_grant_extra_rebate' => (bool) $profile->can_grant_extra_rebate,
            'can_create_child_agent' => (bool) $profile->can_create_child_agent,
            'can_create_player' => (bool) $profile->can_create_player,
--- a/app/Services/Agent/AgentSiteProvisioningService.php
+++ b/app/Services/Agent/AgentSiteProvisioningService.php
@@ -7,6 +7,7 @@ use App\Models\AdminSite;
 use App\Models\AdminUser;
 use App\Models\AgentNode;
 use App\Services\Integration\IntegrationSiteService;
+use App\Support\AdminUserStatus;
 use Illuminate\Support\Facades\DB;
 use Illuminate\Validation\ValidationException;

@@ -115,7 +116,7 @@ final class AgentSiteProvisioningService
                'name' => $name,
                'email' => $email !== '' ? $email : null,
                'password' => $password,
-                'status' => $status === 0 ? 0 : 1,
+                'status' => AdminUserStatus::fromAgentNodeStatus($status === 0 ? 0 : 1),
            ]);

            DB::table('admin_user_agents')->insert([
--- a/app/Support/AdminAuthorizationRegistry.php
+++ b/app/Support/AdminAuthorizationRegistry.php
@@ -427,7 +427,7 @@ final class AdminAuthorizationRegistry
            ['code' => 'admin.agent-delegation-grants.index', 'module_code' => 'agent', 'name' => '代理下放上限查看', 'http_method' => 'GET', 'uri_pattern' => '/api/v1/admin/agent-nodes/{agent_node}/delegation-grants', 'route_name' => 'api.v1.admin.agent-delegation-grants.index', 'auth_mode' => 'permission_required', 'is_audit_required' => false, 'permission_codes' => ['agent.node.view', 'agent.node.manage']],
            ['code' => 'admin.agent-delegation-grants.sync', 'module_code' => 'agent', 'name' => '代理下放上限同步', 'http_method' => 'PUT', 'uri_pattern' => '/api/v1/admin/agent-nodes/{agent_node}/delegation-grants', 'route_name' => 'api.v1.admin.agent-delegation-grants.sync', 'auth_mode' => 'permission_required', 'is_audit_required' => true, 'permission_codes' => ['agent.node.manage']],
            ['code' => 'admin.agent-nodes.profile.show', 'module_code' => 'agent', 'name' => '代理占成授信查看', 'http_method' => 'GET', 'uri_pattern' => '/api/v1/admin/agent-nodes/{agent_node}/profile', 'route_name' => 'api.v1.admin.agent-nodes.profile.show', 'auth_mode' => 'permission_required', 'is_audit_required' => false, 'permission_codes' => ['agent.profile.manage', 'agent.node.manage'], 'legacy_permission_slugs' => ['prd.agent.profile.manage', 'prd.agent.manage']],
-            ['code' => 'admin.agent-nodes.profile.update', 'module_code' => 'agent', 'name' => '代理占成授信更新', 'http_method' => 'PUT', 'uri_pattern' => '/api/v1/admin/agent-nodes/{agent_node}/profile', 'route_name' => 'api.v1.admin.agent-nodes.profile.update', 'auth_mode' => 'permission_required', 'is_audit_required' => true, 'permission_codes' => ['agent.profile.manage'], 'legacy_permission_slugs' => ['prd.agent.profile.manage']],
+            ['code' => 'admin.agent-nodes.profile.update', 'module_code' => 'agent', 'name' => '代理占成授信更新', 'http_method' => 'PUT', 'uri_pattern' => '/api/v1/admin/agent-nodes/{agent_node}/profile', 'route_name' => 'api.v1.admin.agent-nodes.profile.update', 'auth_mode' => 'permission_required', 'is_audit_required' => true, 'permission_codes' => ['agent.profile.manage', 'agent.node.manage'], 'legacy_permission_slugs' => ['prd.agent.profile.manage', 'prd.agent.manage']],
            ['code' => 'admin.settlement-periods.store', 'module_code' => 'settlement', 'name' => '创建代理账期', 'http_method' => 'POST', 'uri_pattern' => '/api/v1/admin/settlement-periods', 'route_name' => 'api.v1.admin.settlement-periods.store', 'auth_mode' => 'permission_required', 'is_audit_required' => true, 'permission_codes' => ['settlement.agent.manage'], 'legacy_permission_slugs' => ['prd.settlement.agent.manage']],
            ['code' => 'admin.settlement-periods.close', 'module_code' => 'settlement', 'name' => '关闭代理账期', 'http_method' => 'POST', 'uri_pattern' => '/api/v1/admin/settlement-periods/{settlement_period}/close', 'route_name' => 'api.v1.admin.settlement-periods.close', 'auth_mode' => 'permission_required', 'is_audit_required' => true, 'permission_codes' => ['settlement.agent.manage'], 'legacy_permission_slugs' => ['prd.settlement.agent.manage']],
            ['code' => 'admin.settlement-bills.index', 'module_code' => 'settlement', 'name' => '代理账单列表', 'http_method' => 'GET', 'uri_pattern' => '/api/v1/admin/settlement-bills', 'route_name' => 'api.v1.admin.settlement-bills.index', 'auth_mode' => 'permission_required', 'is_audit_required' => false, 'permission_codes' => ['settlement.agent.view', 'settlement.agent.manage'], 'legacy_permission_slugs' => ['prd.settlement.agent.view', 'prd.settlement.agent.manage']],
--- a/app/Support/AdminUserStatus.php
+++ b/app/Support/AdminUserStatus.php
@@ -0,0 +1,16 @@
+<?php
+
+namespace App\Support;
+
+/** admin_users.status：0=可登录，1=禁用（与 agent_nodes 的 1=启用 不同）。 */
+final class AdminUserStatus
+{
+    public const ACTIVE = 0;
+
+    public const DISABLED = 1;
+
+    public static function fromAgentNodeStatus(int $agentNodeStatus): int
+    {
+        return (int) $agentNodeStatus === 1 ? self::ACTIVE : self::DISABLED;
+    }
+}
--- a/app/Support/AgentSettlementCycle.php
+++ b/app/Support/AgentSettlementCycle.php
@@ -0,0 +1,16 @@
+<?php
+
+namespace App\Support;
+
+final class AgentSettlementCycle
+{
+    /** @var list<string> */
+    public const VALUES = ['daily', 'weekly', 'monthly'];
+
+    public static function normalize(mixed $value, string $default = 'weekly'): string
+    {
+        $normalized = is_string($value) ? strtolower(trim($value)) : '';
+
+        return in_array($normalized, self::VALUES, true) ? $normalized : $default;
+    }
+}