feat: 增强管理员权限与角色管理功能

- 在 SyncAdminAuthorizationCommand 中新增对代理和抽奖菜单操作的同步功能，确保缺失的菜单操作行能够被创建。
- 更新多个控制器中的权限检查逻辑，使用 hasPermissionCode 替代原有的权限验证方式，提升权限管理的灵活性。
- 引入 ApiMessage 统一错误响应格式，确保在权限不足时返回一致的错误信息。
- 更新 AdminRole 和 AdminUser 模型，增强角色与用户的权限管理功能，支持更细粒度的权限控制。

tests/Feature/AdminAgentAccountRoleDestroyTest.php

@@ -0,0 +1,126 @@
+<?php
+
+use App\Models\AdminRole;
+use App\Models\AdminUser;
+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('agent role can be deleted when no users assigned', 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');
+
+    $super = AdminUser::query()->create([
+        'username' => 'destroy_role_super',
+        'name' => 'Super',
+        'email' => null,
+        'password' => Hash::make('secret-strong'),
+        'status' => 0,
+    ]);
+    grantSuperAdminRole($super);
+    $token = $super->createToken('test', ['*'], now()->addDay())->plainTextToken;
+
+    $branch = app(\App\Services\Agent\AgentNodeService::class)->createChild($super, [
+        'parent_id' => $rootId,
+        'code' => 'destroy-role-branch',
+        'name' => 'Destroy Role Branch',
+    ]);
+
+    $role = AdminRole::query()->create([
+        'slug' => 'deletable_role',
+        'name' => 'Deletable',
+        'scope_type' => AdminRole::SCOPE_AGENT,
+        'owner_agent_id' => $branch->id,
+    ]);
+    $role->syncLegacyPermissionSlugs(['prd.agent.role.view']);
+
+    $this->withHeader('Authorization', 'Bearer '.$token)
+        ->deleteJson('/api/v1/admin/agent-roles/'.$role->id)
+        ->assertOk();
+
+    expect(AdminRole::query()->find($role->id))->toBeNull();
+});
+
+test('agent role cannot be deleted while assigned to a user', 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');
+
+    $super = AdminUser::query()->create([
+        'username' => 'destroy_role_blocked_super',
+        'name' => 'Super',
+        'email' => null,
+        'password' => Hash::make('secret-strong'),
+        'status' => 0,
+    ]);
+    grantSuperAdminRole($super);
+    $token = $super->createToken('test', ['*'], now()->addDay())->plainTextToken;
+
+    $branch = app(\App\Services\Agent\AgentNodeService::class)->createChild($super, [
+        'parent_id' => $rootId,
+        'code' => 'destroy-role-blocked',
+        'name' => 'Blocked Branch',
+    ]);
+
+    $role = AdminRole::query()->create([
+        'slug' => 'blocked_role',
+        'name' => 'Blocked',
+        'scope_type' => AdminRole::SCOPE_AGENT,
+        'owner_agent_id' => $branch->id,
+    ]);
+    $role->syncLegacyPermissionSlugs(['prd.agent.role.view']);
+
+    $user = app(\App\Services\Agent\AgentAdminUserService::class)->createUnderAgent($branch, [
+        'username' => 'blocked_user',
+        'nickname' => 'Blocked User',
+        'password' => 'secret-strong-2',
+        'role_ids' => [(int) $role->id],
+    ]);
+
+    expect($user->id)->toBeGreaterThan(0);
+
+    $this->withHeader('Authorization', 'Bearer '.$token)
+        ->deleteJson('/api/v1/admin/agent-roles/'.$role->id)
+        ->assertStatus(422);
+});
+
+test('agent admin user can be deleted under agent node', 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');
+
+    $super = AdminUser::query()->create([
+        'username' => 'destroy_user_super',
+        'name' => 'Super',
+        'email' => null,
+        'password' => Hash::make('secret-strong'),
+        'status' => 0,
+    ]);
+    grantSuperAdminRole($super);
+    $token = $super->createToken('test', ['*'], now()->addDay())->plainTextToken;
+
+    $branch = app(\App\Services\Agent\AgentNodeService::class)->createChild($super, [
+        'parent_id' => $rootId,
+        'code' => 'destroy-user-branch',
+        'name' => 'Destroy User Branch',
+    ]);
+
+    $user = app(\App\Services\Agent\AgentAdminUserService::class)->createUnderAgent($branch, [
+        'username' => 'agent_delete_me',
+        'nickname' => 'Delete Me',
+        'password' => 'secret-strong-3',
+        'role_ids' => [],
+    ]);
+
+    $this->withHeader('Authorization', 'Bearer '.$token)
+        ->deleteJson('/api/v1/admin/agent-admin-users/'.$user->id)
+        ->assertOk()
+        ->assertJsonPath('data.deleted', true);
+
+    expect(AdminUser::query()->find($user->id))->toBeNull();
+    expect(DB::table('admin_user_agents')->where('admin_user_id', $user->id)->exists())->toBeFalse();
+});

tests/Feature/AdminAgentDelegationApiTest.php

@@ -28,7 +28,14 @@ function grantDelegationAgentOperator(AdminUser $admin, AgentNode $agent, bool $
     ]);
 
     $codes = $manage
-        ? ['agent.node.view', 'agent.node.manage']
+        ? [
+            'agent.node.view',
+            'agent.node.manage',
+            'agent.role.view',
+            'agent.role.manage',
+            'agent.user.view',
+            'agent.user.manage',
+        ]
         : ['agent.node.view'];
 
     $actionIds = DB::table('admin_menu_actions')
@@ -55,6 +62,13 @@ function grantDelegationAgentOperator(AdminUser $admin, AgentNode $agent, bool $
         'is_primary' => true,
         'granted_at' => $now,
     ]);
+
+    DB::table('admin_user_agent_roles')->insert([
+        'admin_user_id' => $admin->id,
+        'agent_node_id' => (int) $agent->id,
+        'role_id' => $roleId,
+        'granted_at' => $now,
+    ]);
 }
 
 test('parent agent can sync delegation grants for direct child', function (): void {

tests/Feature/AdminAgentNodeApiTest.php

@@ -36,7 +36,14 @@ function grantAgentOperatorRole(AdminUser $admin, AgentNode $agent, bool $manage
     ]);
 
     $codes = $manage
-        ? ['agent.node.view', 'agent.node.manage']
+        ? [
+            'agent.node.view',
+            'agent.node.manage',
+            'agent.role.view',
+            'agent.role.manage',
+            'agent.user.view',
+            'agent.user.manage',
+        ]
         : ['agent.node.view'];
 
     $actionIds = DB::table('admin_menu_actions')
@@ -63,6 +70,13 @@ function grantAgentOperatorRole(AdminUser $admin, AgentNode $agent, bool $manage
         'is_primary' => true,
         'granted_at' => $now,
     ]);
+
+    DB::table('admin_user_agent_roles')->insert([
+        'admin_user_id' => $admin->id,
+        'agent_node_id' => (int) $agent->id,
+        'role_id' => $roleId,
+        'granted_at' => $now,
+    ]);
 }
 
 test('each admin site has exactly one root agent node after migration', function (): void {

tests/Feature/AdminAgentPermissionGranularityTest.php

@@ -0,0 +1,244 @@
+<?php
+
+use App\Models\AdminRole;
+use App\Models\AdminUser;
+use Illuminate\Support\Facades\Hash;
+use App\Support\AdminAuthProfile;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+
+uses(RefreshDatabase::class);
+
+beforeEach(function (): void {
+    $this->artisan('lottery:admin-auth-sync')->assertExitCode(0);
+});
+
+test('role with only agent role view slug does not receive manage slugs in profile', function (): void {
+    $admin = AdminUser::query()->create([
+        'username' => 'agent_role_view_only',
+        'name' => 'View Only',
+        'email' => null,
+        'password' => Hash::make('secret-strong'),
+        'status' => 0,
+    ]);
+
+    $role = AdminRole::query()->create([
+        'slug' => 'agent_role_view_only',
+        'name' => 'Agent role view only',
+    ]);
+    $role->syncLegacyPermissionSlugs(['prd.agent.role.view']);
+
+    $siteId = AdminUser::defaultAdminSiteId();
+    $admin->roles()->sync([
+        (int) $role->id => ['site_id' => $siteId, 'granted_at' => now()],
+    ]);
+
+    $profile = AdminAuthProfile::fromAdmin($admin->fresh());
+
+    expect($profile['permissions'])->toContain('prd.agent.role.view')
+        ->and($profile['permissions'])->toContain('prd.agent.view')
+        ->not->toContain('prd.agent.role.manage')
+        ->not->toContain('prd.agent.user.manage')
+        ->not->toContain('prd.agent.manage');
+});
+
+test('role with only agent role manage can create roles but not agent nodes', 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');
+
+    $super = AdminUser::query()->create([
+        'username' => 'granularity_super',
+        'name' => 'Super',
+        'email' => null,
+        'password' => Hash::make('secret-strong'),
+        'status' => 0,
+    ]);
+    grantSuperAdminRole($super);
+
+    $service = app(\App\Services\Agent\AgentNodeService::class);
+    $branch = $service->createChild($super, [
+        'parent_id' => $rootId,
+        'code' => 'granularity-branch',
+        'name' => 'Granularity Branch',
+    ]);
+
+    $admin = AdminUser::query()->create([
+        'username' => 'agent_role_manage_only',
+        'name' => 'Role Manage',
+        'email' => null,
+        'password' => Hash::make('secret-strong'),
+        'status' => 0,
+    ]);
+
+    $role = AdminRole::query()->create([
+        'slug' => 'agent_role_manage_only',
+        'name' => 'Agent role manage only',
+    ]);
+    $role->syncLegacyPermissionSlugs(['prd.agent.role.manage']);
+
+    $siteId = (int) $branch->admin_site_id;
+    DB::table('admin_user_site_roles')->insert([
+        'admin_user_id' => $admin->id,
+        'site_id' => $siteId,
+        'role_id' => $role->id,
+        'granted_at' => now(),
+    ]);
+    DB::table('admin_user_agents')->insert([
+        'admin_user_id' => $admin->id,
+        'agent_node_id' => $branch->id,
+        'is_primary' => true,
+        'granted_at' => now(),
+    ]);
+    DB::table('admin_user_agent_roles')->insert([
+        'admin_user_id' => $admin->id,
+        'agent_node_id' => $branch->id,
+        'role_id' => $role->id,
+        'granted_at' => now(),
+    ]);
+
+    $token = $admin->createToken('test', ['*'], now()->addDay())->plainTextToken;
+
+    $this->withHeader('Authorization', 'Bearer '.$token)
+        ->postJson('/api/v1/admin/agent-nodes/'.$branch->id.'/roles', [
+            'slug' => 'ops_role_only',
+            'name' => 'Ops Role',
+            'permission_slugs' => ['prd.agent.role.view'],
+        ])
+        ->assertOk();
+
+    $this->withHeader('Authorization', 'Bearer '.$token)
+        ->postJson('/api/v1/admin/agent-nodes', [
+            'parent_id' => $branch->id,
+            'code' => 'should-fail',
+            'name' => 'Should Fail',
+        ])
+        ->assertForbidden();
+});
+
+test('role with only agent node manage cannot create roles or admin users', 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');
+
+    $super = AdminUser::query()->create([
+        'username' => 'granularity_super_node',
+        'name' => 'Super',
+        'email' => null,
+        'password' => Hash::make('secret-strong'),
+        'status' => 0,
+    ]);
+    grantSuperAdminRole($super);
+
+    $service = app(\App\Services\Agent\AgentNodeService::class);
+    $branch = $service->createChild($super, [
+        'parent_id' => $rootId,
+        'code' => 'granularity-node-only',
+        'name' => 'Node Only Branch',
+    ]);
+
+    $admin = AdminUser::query()->create([
+        'username' => 'agent_node_manage_only',
+        'name' => 'Node Manage',
+        'email' => null,
+        'password' => Hash::make('secret-strong'),
+        'status' => 0,
+    ]);
+
+    $role = AdminRole::query()->create([
+        'slug' => 'agent_node_manage_only',
+        'name' => 'Agent node manage only',
+    ]);
+    $role->syncLegacyPermissionSlugs(['prd.agent.manage']);
+
+    $siteId = (int) $branch->admin_site_id;
+    DB::table('admin_user_site_roles')->insert([
+        'admin_user_id' => $admin->id,
+        'site_id' => $siteId,
+        'role_id' => $role->id,
+        'granted_at' => now(),
+    ]);
+    DB::table('admin_user_agents')->insert([
+        'admin_user_id' => $admin->id,
+        'agent_node_id' => $branch->id,
+        'is_primary' => true,
+        'granted_at' => now(),
+    ]);
+    DB::table('admin_user_agent_roles')->insert([
+        'admin_user_id' => $admin->id,
+        'agent_node_id' => $branch->id,
+        'role_id' => $role->id,
+        'granted_at' => now(),
+    ]);
+
+    $token = $admin->createToken('test', ['*'], now()->addDay())->plainTextToken;
+
+    $this->withHeader('Authorization', 'Bearer '.$token)
+        ->postJson('/api/v1/admin/agent-nodes/'.$branch->id.'/roles', [
+            'slug' => 'should_fail_role',
+            'name' => 'Should Fail Role',
+            'permission_slugs' => ['prd.agent.role.view'],
+        ])
+        ->assertForbidden();
+
+    $this->withHeader('Authorization', 'Bearer '.$token)
+        ->postJson('/api/v1/admin/agent-nodes/'.$branch->id.'/admin-users', [
+            'username' => 'should_fail_user',
+            'name' => 'Should Fail User',
+            'password' => 'secret-strong-2',
+            'role_ids' => [],
+        ])
+        ->assertForbidden();
+});
+
+test('agent-bound admin with only site role bindings still receives manage slugs in profile', 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');
+
+    $super = AdminUser::query()->create([
+        'username' => 'granularity_super_site_fallback',
+        'name' => 'Super',
+        'email' => null,
+        'password' => Hash::make('secret-strong'),
+        'status' => 0,
+    ]);
+    grantSuperAdminRole($super);
+
+    $service = app(\App\Services\Agent\AgentNodeService::class);
+    $branch = $service->createChild($super, [
+        'parent_id' => $rootId,
+        'code' => 'site-fallback-branch',
+        'name' => 'Site Fallback Branch',
+    ]);
+
+    $role = AdminRole::query()->create([
+        'slug' => 'agent_role_manage_site_only',
+        'name' => 'Agent role manage site bind',
+        'scope_type' => \App\Models\AdminRole::SCOPE_AGENT,
+        'owner_agent_id' => $branch->id,
+    ]);
+    $role->syncLegacyPermissionSlugs(['prd.agent.role.manage']);
+
+    $admin = AdminUser::query()->create([
+        'username' => 'agent_site_roles_only',
+        'name' => 'Site Roles Only',
+        'email' => null,
+        'password' => Hash::make('secret-strong'),
+        'status' => 0,
+    ]);
+
+    DB::table('admin_user_agents')->insert([
+        'admin_user_id' => $admin->id,
+        'agent_node_id' => $branch->id,
+        'is_primary' => true,
+        'granted_at' => now(),
+    ]);
+    DB::table('admin_user_site_roles')->insert([
+        'admin_user_id' => $admin->id,
+        'site_id' => $siteId,
+        'role_id' => $role->id,
+        'granted_at' => now(),
+    ]);
+
+    $profile = AdminAuthProfile::fromAdmin($admin->fresh());
+
+    expect($profile['permissions'])->toContain('prd.agent.role.manage');
+    expect(DB::table('admin_user_agent_roles')->where('admin_user_id', $admin->id)->count())->toBe(0);
+});

tests/Feature/AdminAgentRoleApiTest.php

@@ -28,7 +28,15 @@ function grantAgentRoleManager(AdminUser $admin, AgentNode $agent): void
         'updated_at' => $now,
     ]);
 
-    $codes = ['agent.node.view', 'agent.node.manage', 'service.players.view'];
+    $codes = [
+        'agent.node.view',
+        'agent.node.manage',
+        'agent.role.view',
+        'agent.role.manage',
+        'agent.user.view',
+        'agent.user.manage',
+        'service.players.view',
+    ];
     $actionIds = DB::table('admin_menu_actions')->whereIn('permission_code', $codes)->pluck('id');
     foreach ($actionIds as $actionId) {
         DB::table('admin_role_menu_actions')->insert([

tests/Feature/AdminAgentRolePermissionPersistTest.php

@@ -0,0 +1,62 @@
+<?php
+
+use App\Models\AdminRole;
+use App\Models\AdminUser;
+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('platform role sync persists agent role and user manage slugs', function (): void {
+    $super = AdminUser::query()->create([
+        'username' => 'persist_super',
+        'name' => 'Super',
+        'email' => null,
+        'password' => Hash::make('secret-strong'),
+        'status' => 0,
+    ]);
+    grantSuperAdminRole($super);
+    $token = $super->createToken('test', ['*'], now()->addDay())->plainTextToken;
+
+    $role = AdminRole::query()->create([
+        'slug' => 'agent_persist_test',
+        'name' => 'Agent Persist Test',
+    ]);
+
+    $this->withHeader('Authorization', 'Bearer '.$token)
+        ->putJson('/api/v1/admin/admin-roles/'.$role->id.'/permissions', [
+            'permission_slugs' => [
+                'prd.agent.view',
+                'prd.agent.manage',
+                'prd.agent.role.view',
+                'prd.agent.role.manage',
+                'prd.agent.user.view',
+                'prd.agent.user.manage',
+            ],
+        ])
+        ->assertOk()
+        ->assertJsonPath('data.permission_slugs', function ($slugs): bool {
+            $list = is_array($slugs) ? $slugs : [];
+
+            return in_array('prd.agent.role.manage', $list, true)
+                && in_array('prd.agent.user.manage', $list, true);
+        });
+});
+
+test('sync fails with clear error when agent manage menu actions are missing', function (): void {
+    DB::table('admin_menu_actions')
+        ->whereIn('permission_code', ['agent.role.manage', 'agent.user.manage'])
+        ->delete();
+
+    $role = AdminRole::query()->create([
+        'slug' => 'agent_missing_catalog',
+        'name' => 'Missing Catalog',
+    ]);
+
+    expect(fn () => $role->syncLegacyPermissionSlugs(['prd.agent.role.manage']))
+        ->toThrow(\Illuminate\Validation\ValidationException::class);
+});

tests/Feature/AdminDrawRolePermissionRoundTripTest.php

@@ -0,0 +1,60 @@
+<?php
+
+use App\Models\AdminRole;
+use App\Models\AdminUser;
+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('role with only draw view slug does not round-trip as manage', function (): void {
+    $role = AdminRole::query()->create([
+        'slug' => 'draw_view_only',
+        'name' => 'Draw view only',
+    ]);
+    $role->syncLegacyPermissionSlugs(['prd.draw_result.view']);
+
+    expect($role->legacyPermissionSlugs())
+        ->toContain('prd.draw_result.view')
+        ->not->toContain('prd.draw_result.manage');
+});
+
+test('platform role sync can drop draw manage while keeping view', function (): void {
+    $super = AdminUser::query()->create([
+        'username' => 'draw_perm_super',
+        'name' => 'Super',
+        'email' => null,
+        'password' => Hash::make('secret-strong'),
+        'status' => 0,
+    ]);
+    grantSuperAdminRole($super);
+    $token = $super->createToken('test', ['*'], now()->addDay())->plainTextToken;
+
+    $role = AdminRole::query()->create([
+        'slug' => 'draw_toggle_test',
+        'name' => 'Draw toggle test',
+    ]);
+
+    $this->withHeader('Authorization', 'Bearer '.$token)
+        ->putJson('/api/v1/admin/admin-roles/'.$role->id.'/permissions', [
+            'permission_slugs' => ['prd.draw_result.view', 'prd.draw_result.manage'],
+        ])
+        ->assertOk()
+        ->assertJsonPath('data.permission_slugs', fn ($slugs): bool => in_array('prd.draw_result.manage', $slugs, true));
+
+    $this->withHeader('Authorization', 'Bearer '.$token)
+        ->putJson('/api/v1/admin/admin-roles/'.$role->id.'/permissions', [
+            'permission_slugs' => ['prd.draw_result.view'],
+        ])
+        ->assertOk()
+        ->assertJsonPath('data.permission_slugs', function ($slugs): bool {
+            $list = is_array($slugs) ? $slugs : [];
+
+            return in_array('prd.draw_result.view', $list, true)
+                && ! in_array('prd.draw_result.manage', $list, true);
+        });
+});

tests/Pest.php

@@ -20,6 +20,8 @@ pest()->extend(TestCase::class)
  // ->use(RefreshDatabase::class)
     ->in('Feature');
 
+pest()->extend(TestCase::class)->in('Unit');
+
 /*
 |--------------------------------------------------------------------------
 | Expectations

tests/Unit/ApiValidationErrorsTest.php

@@ -0,0 +1,52 @@
+<?php
+
+use App\Support\ApiValidationErrors;
+
+test('normalizes english regex error for code field in zh', function (): void {
+    $errors = ApiValidationErrors::normalize(
+        ['code' => ['The code field format is invalid.']],
+        'zh',
+    );
+
+    expect($errors['code'][0])->toContain('编码只能使用字母、数字');
+});
+
+test('normalizes business shorthand unique in zh', function (): void {
+    $errors = ApiValidationErrors::normalize(['code' => ['unique']], 'zh');
+
+    expect($errors['code'][0])->toBe('该内容已存在，请更换后重试。');
+});
+
+test('summary joins multiple field errors', function (): void {
+    $normalized = [
+        'code' => ['编码格式不正确。'],
+        'name' => ['名称不能为空。'],
+    ];
+
+    expect(ApiValidationErrors::summary($normalized))->toBe('编码格式不正确。；名称不能为空。');
+});
+
+test('keeps already localized chinese messages', function (): void {
+    $message = '最小下注额不能小于 0';
+    $errors = ApiValidationErrors::normalize(['items.0.min_bet_amount' => [$message]], 'zh');
+
+    expect($errors['items.0.min_bet_amount'][0])->toBe($message);
+});
+
+test('normalizes english min length for password in zh', function (): void {
+    $errors = ApiValidationErrors::normalize(
+        ['password' => ['The password field must be at least 8 characters.']],
+        'zh',
+    );
+
+    expect($errors['password'][0])->toBe('密码至少需要 8 个字符。');
+});
+
+test('normalizes exact draw items message in zh', function (): void {
+    $errors = ApiValidationErrors::normalize(
+        ['items' => ['items must contain the complete 23 draw prize slots.']],
+        'zh',
+    );
+
+    expect($errors['items'][0])->toContain('23');
+});