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,14 +190,51 @@ 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 ($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;
+                }
+            }
        }

        if (array_key_exists('email', $payload) && $primaryUser instanceof AdminUser) {
@@ -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;
+    }
+}
--- a/database/migrations/2026_06_03_190000_fix_agent_primary_admin_user_status.php
+++ b/database/migrations/2026_06_03_190000_fix_agent_primary_admin_user_status.php
@@ -0,0 +1,51 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Support\Facades\DB;
+
+/**
+ * 修正代理主账号 admin_users.status 与 agent_nodes.status 语义不一致的历史数据。
+ *
+ * admin_users: 0=可登录, 1=禁用
+ * agent_nodes: 1=启用, 0=停用
+ */
+return new class extends Migration
+{
+    public function up(): void
+    {
+        $now = now();
+
+        $enabledUserIds = DB::table('admin_user_agents as aua')
+            ->join('agent_nodes as an', 'an.id', '=', 'aua.agent_node_id')
+            ->join('admin_users as au', 'au.id', '=', 'aua.admin_user_id')
+            ->where('aua.is_primary', true)
+            ->where('an.status', 1)
+            ->where('au.status', 1)
+            ->pluck('au.id');
+
+        if ($enabledUserIds->isNotEmpty()) {
+            DB::table('admin_users')
+                ->whereIn('id', $enabledUserIds->all())
+                ->update(['status' => 0, 'updated_at' => $now]);
+        }
+
+        $disabledUserIds = DB::table('admin_user_agents as aua')
+            ->join('agent_nodes as an', 'an.id', '=', 'aua.agent_node_id')
+            ->join('admin_users as au', 'au.id', '=', 'aua.admin_user_id')
+            ->where('aua.is_primary', true)
+            ->where('an.status', 0)
+            ->where('au.status', 0)
+            ->pluck('au.id');
+
+        if ($disabledUserIds->isNotEmpty()) {
+            DB::table('admin_users')
+                ->whereIn('id', $disabledUserIds->all())
+                ->update(['status' => 1, 'updated_at' => $now]);
+        }
+    }
+
+    public function down(): void
+    {
+        // 不可逆：无法可靠还原误写前的 admin_users.status
+    }
+};
--- a/lang/en/validation_business.php
+++ b/lang/en/validation_business.php
@@ -13,4 +13,13 @@ return [
    'exceeds_delegation_ceiling' => 'These permissions exceed this node\'s delegation ceiling: :detail',
    'permission_exceeds_actor' => 'These permissions exceed what you may grant: :detail',
    'permission_catalog_incomplete' => 'Permission catalog is incomplete (missing: :detail). Run migrate and admin-auth-sync.',
+    'exceeds_parent' => 'Share rate cannot exceed the parent agent.',
+    'exceeds_available' => 'Credit limit exceeds the parent\'s available allocation.',
+    'exceeds_limit' => 'Default player rebate cannot exceed the rebate ceiling.',
+    'invalid_range' => 'Share rate must be between 0 and 100.',
+    'below_allocated' => 'Credit limit cannot be lower than credit already allocated to sub-agents.',
+    'parent_cannot_delegate' => 'The parent has not enabled this capability.',
+    'cannot_create_child_agent' => 'You are not allowed to create sub-agents.',
+    'cannot_create_player' => 'You are not allowed to create players.',
+    'primary_account_missing' => 'This agent has no bound login account; username cannot be updated.',
 ];
--- a/lang/zh/validation_business.php
+++ b/lang/zh/validation_business.php
@@ -14,4 +14,13 @@ return [
    'exceeds_delegation_ceiling' => '下列权限超出本节点下放上限：:detail',
    'permission_exceeds_actor' => '下列权限超出您可分配的范围：:detail',
    'permission_catalog_incomplete' => '权限目录不完整，缺少：:detail。请联系管理员执行 migrate 与 admin-auth-sync。',
+    'exceeds_parent' => '占成比例不能超过上级代理。',
+    'exceeds_available' => '授信额度超出上级可下发额度。',
+    'exceeds_limit' => '默认玩家回水不能超过回水上限。',
+    'invalid_range' => '占成比例必须在 0–100 之间。',
+    'below_allocated' => '授信额度不能低于已下发给下级的额度。',
+    'parent_cannot_delegate' => '上级未开放该能力，无法下放。',
+    'cannot_create_child_agent' => '当前账号无权创建下级代理。',
+    'cannot_create_player' => '当前账号无权创建玩家。',
+    'primary_account_missing' => '该代理尚未绑定登录账号，无法修改登录名。',
 ];
--- a/tests/Feature/AdminAgentLoginStatusTest.php
+++ b/tests/Feature/AdminAgentLoginStatusTest.php
@@ -0,0 +1,91 @@
+<?php
+
+use App\Models\AdminUser;
+use Illuminate\Support\Facades\Cache;
+use Illuminate\Support\Facades\Hash;
+use Illuminate\Support\Str;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+
+uses(RefreshDatabase::class);
+
+beforeEach(function (): void {
+    $this->artisan('lottery:admin-auth-sync')->assertExitCode(0);
+});
+
+test('enabled agent primary account can login after create', function (): void {
+    $siteId = (int) DB::table('admin_sites')->where('is_default', true)->value('id');
+    $rootId = (int) DB::table('agent_nodes')->where('admin_site_id', $siteId)->where('depth', 0)->value('id');
+    $service = app(\App\Services\Agent\AgentNodeService::class);
+
+    $super = AdminUser::query()->create([
+        'username' => 'login_super',
+        'name' => 'Login Super',
+        'email' => null,
+        'password' => Hash::make('secret-strong'),
+        'status' => 0,
+    ]);
+    grantSuperAdminRole($super);
+
+    $child = $service->createChild($super, agentChildPayload([
+        'parent_id' => $rootId,
+        'code' => 'login-agent',
+        'name' => 'Login Agent',
+        'username' => 'agent_login_user',
+        'status' => 1,
+    ]));
+
+    $userId = (int) DB::table('admin_user_agents')
+        ->where('agent_node_id', $child->id)
+        ->where('is_primary', true)
+        ->value('admin_user_id');
+
+    expect((int) AdminUser::query()->find($userId)?->status)->toBe(0);
+
+    $captchaKey = (string) Str::uuid();
+    Cache::put(
+        'admin_captcha:'.$captchaKey,
+        hash_hmac('sha256', 'xwz2', (string) config('app.key')),
+        now()->addSeconds(120),
+    );
+
+    $this->postJson('/api/v1/admin/auth/login', [
+        'account' => 'agent_login_user',
+        'password' => agentNodeTestPassword(),
+        'captcha_key' => $captchaKey,
+        'captcha_code' => 'xwz2',
+    ])
+        ->assertOk()
+        ->assertJsonPath('code', 0);
+});
+
+test('updating enabled agent keeps admin user login status active', function (): void {
+    $siteId = (int) DB::table('admin_sites')->where('is_default', true)->value('id');
+    $rootId = (int) DB::table('agent_nodes')->where('admin_site_id', $siteId)->where('depth', 0)->value('id');
+    $service = app(\App\Services\Agent\AgentNodeService::class);
+
+    $super = AdminUser::query()->create([
+        'username' => 'login_super2',
+        'name' => 'Login Super',
+        'email' => null,
+        'password' => Hash::make('secret-strong'),
+        'status' => 0,
+    ]);
+    grantSuperAdminRole($super);
+
+    $child = $service->createChild($super, agentChildPayload([
+        'parent_id' => $rootId,
+        'code' => 'login-agent2',
+        'name' => 'Login Agent 2',
+        'username' => 'agent_login_user2',
+        'status' => 1,
+    ]));
+
+    $service->update($child, ['name' => 'Login Agent 2 Updated', 'status' => 1]);
+
+    $userId = (int) DB::table('admin_user_agents')
+        ->where('agent_node_id', $child->id)
+        ->where('is_primary', true)
+        ->value('admin_user_id');
+
+    expect((int) AdminUser::query()->find($userId)?->status)->toBe(0);
+});
--- a/tests/Feature/AdminAgentProfileApiTest.php
+++ b/tests/Feature/AdminAgentProfileApiTest.php
@@ -0,0 +1,194 @@
+<?php
+
+use App\Models\AdminUser;
+use App\Lottery\ErrorCode;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Hash;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+
+uses(RefreshDatabase::class);
+
+beforeEach(function (): void {
+    $this->artisan('lottery:admin-auth-sync')->assertExitCode(0);
+});
+
+test('super admin can update agent profile with capability flags', function (): void {
+    $siteId = (int) DB::table('admin_sites')->where('is_default', true)->value('id');
+    $rootId = (int) DB::table('agent_nodes')->where('admin_site_id', $siteId)->where('depth', 0)->value('id');
+    $service = app(\App\Services\Agent\AgentNodeService::class);
+
+    $super = AdminUser::query()->create([
+        'username' => 'profile_super',
+        'name' => 'Profile Super',
+        'email' => null,
+        'password' => Hash::make('secret-strong'),
+        'status' => 0,
+    ]);
+    grantSuperAdminRole($super);
+
+    $child = $service->createChild($super, agentChildPayload([
+        'parent_id' => $rootId,
+        'code' => 'profile-child',
+        'name' => 'Profile Child',
+        'username' => 'profile_child',
+        'total_share_rate' => 10,
+        'credit_limit' => 1000,
+    ]));
+
+    $token = $super->createToken('test', ['*'], now()->addDay())->plainTextToken;
+
+    $this->withHeader('Authorization', 'Bearer '.$token)
+        ->putJson('/api/v1/admin/agent-nodes/'.$child->id.'/profile', [
+            'total_share_rate' => 12,
+            'credit_limit' => 1200,
+            'rebate_limit' => 0.01,
+            'default_player_rebate' => 0.005,
+            'settlement_cycle' => 'weekly',
+            'can_grant_extra_rebate' => false,
+            'can_create_child_agent' => true,
+            'can_create_player' => true,
+        ])
+        ->assertOk()
+        ->assertJsonPath('data.total_share_rate', 12)
+        ->assertJsonPath('data.can_create_child_agent', true);
+});
+
+test('super admin can update agent login username and tree reflects it', function (): void {
+    $siteId = (int) DB::table('admin_sites')->where('is_default', true)->value('id');
+    $rootId = (int) DB::table('agent_nodes')->where('admin_site_id', $siteId)->where('depth', 0)->value('id');
+    $service = app(\App\Services\Agent\AgentNodeService::class);
+
+    $super = AdminUser::query()->create([
+        'username' => 'username_super',
+        'name' => 'Username Super',
+        'email' => null,
+        'password' => Hash::make('secret-strong'),
+        'status' => 0,
+    ]);
+    grantSuperAdminRole($super);
+
+    $child = $service->createChild($super, agentChildPayload([
+        'parent_id' => $rootId,
+        'code' => 'username-child',
+        'name' => 'Username Child',
+        'username' => 'old_login',
+    ]));
+
+    $token = $super->createToken('test', ['*'], now()->addDay())->plainTextToken;
+
+    $this->withHeader('Authorization', 'Bearer '.$token)
+        ->putJson('/api/v1/admin/agent-nodes/'.$child->id, [
+            'username' => 'new_login',
+        ])
+        ->assertOk()
+        ->assertJsonPath('data.username', 'new_login');
+
+    $this->withHeader('Authorization', 'Bearer '.$token)
+        ->getJson('/api/v1/admin/agent-nodes/tree?admin_site_id='.$siteId)
+        ->assertOk()
+        ->assertJsonPath('data.tree.0.children.0.username', 'new_login');
+});
+
+test('update can provision primary login when agent node had no bound account', function (): void {
+    $siteId = (int) DB::table('admin_sites')->where('is_default', true)->value('id');
+    $rootId = (int) DB::table('agent_nodes')->where('admin_site_id', $siteId)->where('depth', 0)->value('id');
+    $service = app(\App\Services\Agent\AgentNodeService::class);
+
+    $super = AdminUser::query()->create([
+        'username' => 'provision_super',
+        'name' => 'Provision Super',
+        'email' => null,
+        'password' => Hash::make('secret-strong'),
+        'status' => 0,
+    ]);
+    grantSuperAdminRole($super);
+
+    $child = $service->createChild($super, agentChildPayload([
+        'parent_id' => $rootId,
+        'code' => 'provision-child',
+        'name' => 'Provision Child',
+        'username' => 'old_bound_login',
+    ]));
+
+    $userId = (int) DB::table('admin_user_agents')->where('agent_node_id', $child->id)->value('admin_user_id');
+    DB::table('admin_user_agent_roles')->where('agent_node_id', $child->id)->delete();
+    DB::table('admin_user_agents')->where('agent_node_id', $child->id)->delete();
+    AdminUser::query()->where('id', $userId)->delete();
+
+    $token = $super->createToken('test', ['*'], now()->addDay())->plainTextToken;
+
+    $this->withHeader('Authorization', 'Bearer '.$token)
+        ->putJson('/api/v1/admin/agent-nodes/'.$child->id, [
+            'username' => 'fresh_login',
+            'password' => agentNodeTestPassword(),
+        ])
+        ->assertOk()
+        ->assertJsonPath('data.username', 'fresh_login');
+
+    expect(
+        DB::table('admin_user_agents')->where('agent_node_id', $child->id)->where('is_primary', true)->count()
+    )->toBe(1);
+});
+
+test('agent profile update normalizes empty settlement cycle', function (): void {
+    $siteId = (int) DB::table('admin_sites')->where('is_default', true)->value('id');
+    $rootId = (int) DB::table('agent_nodes')->where('admin_site_id', $siteId)->where('depth', 0)->value('id');
+    $service = app(\App\Services\Agent\AgentNodeService::class);
+
+    $super = AdminUser::query()->create([
+        'username' => 'profile_super3',
+        'name' => 'Profile Super',
+        'email' => null,
+        'password' => Hash::make('secret-strong'),
+        'status' => 0,
+    ]);
+    grantSuperAdminRole($super);
+
+    $child = $service->createChild($super, agentChildPayload([
+        'parent_id' => $rootId,
+        'code' => 'profile-child3',
+        'name' => 'Profile Child 3',
+        'username' => 'profile_child3',
+    ]));
+
+    $token = $super->createToken('test', ['*'], now()->addDay())->plainTextToken;
+
+    $this->withHeader('Authorization', 'Bearer '.$token)
+        ->putJson('/api/v1/admin/agent-nodes/'.$child->id.'/profile', [
+            'settlement_cycle' => '',
+        ])
+        ->assertOk()
+        ->assertJsonPath('data.settlement_cycle', 'weekly');
+});
+
+test('agent profile update rejects default rebate above limit', function (): void {
+    $siteId = (int) DB::table('admin_sites')->where('is_default', true)->value('id');
+    $rootId = (int) DB::table('agent_nodes')->where('admin_site_id', $siteId)->where('depth', 0)->value('id');
+    $service = app(\App\Services\Agent\AgentNodeService::class);
+
+    $super = AdminUser::query()->create([
+        'username' => 'profile_super2',
+        'name' => 'Profile Super',
+        'email' => null,
+        'password' => Hash::make('secret-strong'),
+        'status' => 0,
+    ]);
+    grantSuperAdminRole($super);
+
+    $child = $service->createChild($super, agentChildPayload([
+        'parent_id' => $rootId,
+        'code' => 'profile-child2',
+        'name' => 'Profile Child 2',
+        'username' => 'profile_child2',
+    ]));
+
+    $token = $super->createToken('test', ['*'], now()->addDay())->plainTextToken;
+
+    $this->withHeader('Authorization', 'Bearer '.$token)
+        ->putJson('/api/v1/admin/agent-nodes/'.$child->id.'/profile', [
+            'rebate_limit' => 0.005,
+            'default_player_rebate' => 0.01,
+        ])
+        ->assertStatus(422)
+        ->assertJsonPath('code', ErrorCode::ValidationFailed->value);
+});