feat: enhance admin role management and reconciliation features

- Updated AGENTS.md to clarify site admin roles and their associated permissions. - Refactored reconciliation controllers to include admin user validation and improved access control based on admin roles. - Enhanced AdminReconcileJobService to support player-specific reconciliation and site-based job creation. - Removed deprecated rebate commission report functionality from the API and related services. - Improved dashboard overview builders to accommodate new site operator roles and their specific functionalities.
2026-06-16 16:04:01 +08:00
parent 3a59cc3f42
commit 4e370a79dc
35 changed files with 1230 additions and 180 deletions
--- a/app/Support/AdminAuthProfile.php
+++ b/app/Support/AdminAuthProfile.php
@@ -40,6 +40,7 @@ final class AdminAuthProfile
     *   },
     *   site: ?array{id: int, code: string, name: string},
     *   is_super_admin: bool,
+     *   account_kind: 'super_admin'|'site_admin'|'site_finance'|'site_cs'|'agent_operator'|'platform_account',
     *   operational_permissions: list<string>,
     *   delegation_ceiling: list<string>,
     *   accessible_sites?: list<array{id: int, code: string, name: string}>
@@ -49,6 +50,7 @@ final class AdminAuthProfile
    {
        $fresh = $admin->fresh();
        $permissionSlugs = $fresh->adminPermissionSlugs();
+        $operationalCodes = $fresh->effectiveMenuActionPermissionCodes();
        $agent = self::agentContext($fresh);

        $payload = [
@@ -61,7 +63,8 @@ final class AdminAuthProfile
            'agent' => $agent,
            'site' => self::siteContext($fresh),
            'is_super_admin' => $fresh->isSuperAdmin(),
-            'operational_permissions' => $permissionSlugs,
+            'account_kind' => self::accountKind($fresh),
+            'operational_permissions' => $operationalCodes,
            'delegation_ceiling' => AgentDelegationAuthorization::delegationLegacySlugsForAdminUser($fresh),
        ];

@@ -81,7 +84,7 @@ final class AdminAuthProfile
            return null;
        }

-        if (! SitePlatformRole::userHasSiteAdminRole($admin)) {
+        if (! SiteOperatorRoles::userHasSiteOperatorRole($admin)) {
            return null;
        }

@@ -130,4 +133,22 @@ final class AdminAuthProfile
            'can_create_player' => (bool) ($profile?->can_create_player ?? false),
        ];
    }
+
+    private static function accountKind(AdminUser $admin): string
+    {
+        if ($admin->isSuperAdmin()) {
+            return 'super_admin';
+        }
+
+        if ($admin->hasPrimaryAgentBinding()) {
+            return 'agent_operator';
+        }
+
+        $siteRole = SiteOperatorRoles::primarySiteOperatorSlug($admin);
+        if ($siteRole !== null) {
+            return $siteRole;
+        }
+
+        return 'platform_account';
+    }
 }
--- a/app/Support/AdminAuthorizationRegistry.php
+++ b/app/Support/AdminAuthorizationRegistry.php
@@ -565,7 +565,6 @@ final class AdminAuthorizationRegistry
            ['code' => 'admin.reports.daily-profit', 'module_code' => 'report', 'name' => '每日盈亏汇总', 'http_method' => 'GET', 'uri_pattern' => '/api/v1/admin/reports/daily-profit', 'route_name' => 'api.v1.admin.reports.daily-profit', 'auth_mode' => 'permission_required', 'is_audit_required' => false, 'permission_codes' => ['service.report.view']],
            ['code' => 'admin.reports.player-win-loss', 'module_code' => 'report', 'name' => '玩家输赢报表', 'http_method' => 'GET', 'uri_pattern' => '/api/v1/admin/reports/player-win-loss', 'route_name' => 'api.v1.admin.reports.player-win-loss', 'auth_mode' => 'permission_required', 'is_audit_required' => false, 'permission_codes' => ['service.report.view']],
            ['code' => 'admin.reports.play-dimension', 'module_code' => 'report', 'name' => '玩法维度报表', 'http_method' => 'GET', 'uri_pattern' => '/api/v1/admin/reports/play-dimension', 'route_name' => 'api.v1.admin.reports.play-dimension', 'auth_mode' => 'permission_required', 'is_audit_required' => false, 'permission_codes' => ['service.report.view']],
-            ['code' => 'admin.reports.rebate-commission', 'module_code' => 'report', 'name' => '佣金回水报表', 'http_method' => 'GET', 'uri_pattern' => '/api/v1/admin/reports/rebate-commission', 'route_name' => 'api.v1.admin.reports.rebate-commission', 'auth_mode' => 'permission_required', 'is_audit_required' => false, 'permission_codes' => ['service.report.view']],
            ['code' => 'admin.report-jobs.index', 'module_code' => 'report', 'name' => '报表任务列表', 'http_method' => 'GET', 'uri_pattern' => '/api/v1/admin/report-jobs', 'route_name' => 'api.v1.admin.report-jobs.index', 'auth_mode' => 'permission_required', 'is_audit_required' => false, 'permission_codes' => ['service.report.view']],
            ['code' => 'admin.report-jobs.store', 'module_code' => 'report', 'name' => '创建报表任务', 'http_method' => 'POST', 'uri_pattern' => '/api/v1/admin/report-jobs', 'route_name' => 'api.v1.admin.report-jobs.store', 'auth_mode' => 'permission_required', 'is_audit_required' => true, 'permission_codes' => ['service.report.export']],
            ['code' => 'admin.report-jobs.show', 'module_code' => 'report', 'name' => '报表任务详情', 'http_method' => 'GET', 'uri_pattern' => '/api/v1/admin/report-jobs/{report_job}', 'route_name' => 'api.v1.admin.report-jobs.show', 'auth_mode' => 'permission_required', 'is_audit_required' => false, 'permission_codes' => ['service.report.view', 'service.report.export']],
--- a/app/Support/AdminReconcileScope.php
+++ b/app/Support/AdminReconcileScope.php
@@ -0,0 +1,206 @@
+<?php
+
+namespace App\Support;
+
+use App\Lottery\ErrorCode;
+use App\Models\AdminSite;
+use App\Models\AdminUser;
+use App\Models\AgentNode;
+use App\Models\Player;
+use App\Models\ReconcileJob;
+use App\Support\ApiMessage;
+use Illuminate\Database\Eloquent\Builder;
+use Illuminate\Http\JsonResponse;
+
+/** 对账任务：按接入站点（及绑定代理子树）收敛可见范围。 */
+final class AdminReconcileScope
+{
+    /**
+     * @param  Builder<ReconcileJob>  $query
+     */
+    public static function applyToJobsQuery(Builder $query, AdminUser $admin): void
+    {
+        if ($admin->isSuperAdmin()) {
+            return;
+        }
+
+        $siteIds = $admin->accessibleAdminSiteIds();
+        if ($siteIds === null) {
+            return;
+        }
+
+        if ($siteIds === []) {
+            $query->whereRaw('0 = 1');
+
+            return;
+        }
+
+        $siteCodes = AdminSite::query()
+            ->whereIn('id', $siteIds)
+            ->pluck('code')
+            ->map(static fn ($code): string => (string) $code)
+            ->all();
+
+        $agent = AdminAgentScope::primaryAgentNode($admin);
+
+        $query->where(function (Builder $outer) use ($siteIds, $siteCodes, $agent): void {
+            $outer->whereIn('admin_site_id', $siteIds);
+
+            if ($siteCodes !== []) {
+                $outer->orWhere(function (Builder $legacy) use ($siteCodes, $agent): void {
+                    $legacy->whereNull('admin_site_id')
+                        ->whereHas('items', function (Builder $items) use ($siteCodes, $agent): void {
+                            self::applyItemsTransferPlayerScope($items, $siteCodes, $agent);
+                        });
+                });
+            }
+        });
+
+        if ($agent instanceof AgentNode) {
+            $query->whereHas('items', function (Builder $items) use ($agent): void {
+                self::applyItemsAgentSubtree($items, $agent);
+            });
+        }
+    }
+
+    public static function jobAccessible(AdminUser $admin, ReconcileJob $job): bool
+    {
+        if ($admin->isSuperAdmin()) {
+            return true;
+        }
+
+        $siteIds = $admin->accessibleAdminSiteIds();
+        if ($siteIds === null) {
+            return true;
+        }
+
+        if ($siteIds === []) {
+            return false;
+        }
+
+        $jobSiteId = $job->admin_site_id !== null ? (int) $job->admin_site_id : null;
+        if ($jobSiteId !== null) {
+            if (! in_array($jobSiteId, $siteIds, true)) {
+                return false;
+            }
+        } else {
+            $siteCodes = AdminSite::query()
+                ->whereIn('id', $siteIds)
+                ->pluck('code')
+                ->map(static fn ($code): string => (string) $code)
+                ->all();
+
+            $hasScopedItem = $job->items()
+                ->where(function (Builder $items) use ($siteCodes, $admin): void {
+                    $agent = AdminAgentScope::primaryAgentNode($admin);
+                    self::applyItemsTransferPlayerScope($items, $siteCodes, $agent);
+                })
+                ->exists();
+
+            if (! $hasScopedItem) {
+                return false;
+            }
+        }
+
+        $agent = AdminAgentScope::primaryAgentNode($admin);
+        if ($agent === null) {
+            return true;
+        }
+
+        return $job->items()
+            ->where(function (Builder $items) use ($agent): void {
+                self::applyItemsAgentSubtree($items, $agent);
+            })
+            ->exists();
+    }
+
+    public static function resolveAdminSiteIdForJob(AdminUser $admin, ?Player $player = null): ?int
+    {
+        if ($player !== null) {
+            $siteId = AdminSite::query()
+                ->where('code', (string) $player->site_code)
+                ->value('id');
+
+            return $siteId !== null ? (int) $siteId : null;
+        }
+
+        if ($admin->isSuperAdmin()) {
+            return null;
+        }
+
+        $agent = AdminAgentScope::primaryAgentNode($admin);
+        if ($agent !== null) {
+            return (int) $agent->admin_site_id;
+        }
+
+        $siteIds = $admin->accessibleAdminSiteIds();
+
+        return $siteIds[0] ?? null;
+    }
+
+    public static function denyUnlessJobAccessible(AdminUser $admin, ReconcileJob $job): ?JsonResponse
+    {
+        if (! self::jobAccessible($admin, $job)) {
+            return ApiMessage::errorResponse(
+                request(),
+                'admin.reconcile_job_access_denied',
+                ErrorCode::AdminForbidden->value,
+                null,
+                403,
+            );
+        }
+
+        return null;
+    }
+
+    /**
+     * @param  Builder<\App\Models\ReconcileItem>  $query
+     * @param  list<string>  $siteCodes
+     */
+    public static function applyItemsTransferPlayerScope(
+        Builder $query,
+        array $siteCodes,
+        ?AgentNode $agent = null,
+    ): void {
+        if ($siteCodes === []) {
+            $query->whereRaw('0 = 1');
+
+            return;
+        }
+
+        $query->whereExists(function ($sub) use ($siteCodes, $agent): void {
+            $sub->selectRaw('1')
+                ->from('transfer_orders')
+                ->join('players', 'players.id', '=', 'transfer_orders.player_id')
+                ->whereColumn('transfer_orders.transfer_no', 'reconcile_items.side_a_ref');
+
+            $sub->whereIn('players.site_code', $siteCodes);
+
+            if ($agent instanceof AgentNode) {
+                $sub->whereIn('players.agent_node_id', function ($nodes) use ($agent): void {
+                    $nodes->select('id')
+                        ->from('agent_nodes')
+                        ->where('path', 'like', $agent->path.'%');
+                });
+            }
+        });
+    }
+
+    /**
+     * @param  Builder<\App\Models\ReconcileItem>  $query
+     */
+    private static function applyItemsAgentSubtree(Builder $query, AgentNode $agent): void
+    {
+        $query->whereExists(function ($sub) use ($agent): void {
+            $sub->selectRaw('1')
+                ->from('transfer_orders')
+                ->join('players', 'players.id', '=', 'transfer_orders.player_id')
+                ->whereColumn('transfer_orders.transfer_no', 'reconcile_items.side_a_ref')
+                ->whereIn('players.agent_node_id', function ($nodes) use ($agent): void {
+                    $nodes->select('id')
+                        ->from('agent_nodes')
+                        ->where('path', 'like', $agent->path.'%');
+                });
+        });
+    }
+}
--- a/app/Support/PlatformSystemRoles.php
+++ b/app/Support/PlatformSystemRoles.php
@@ -4,19 +4,29 @@ namespace App\Support;

 use App\Models\AdminRole;

-/** 平台角色管理仅维护的两个内置系统角色。 */
+/** 平台内置系统角色（超管 / 站点运营 / 代理）。 */
 final class PlatformSystemRoles
 {
    public const SLUG_SUPER_ADMIN = AdminRole::ROLE_SUPER_ADMIN;

    public const SLUG_AGENT = 'agent';

-    public const SLUG_SITE_ADMIN = SitePlatformRole::SLUG;
+    public const SLUG_SITE_ADMIN = SiteOperatorRoles::SLUG_SITE_ADMIN;
+
+    public const SLUG_SITE_FINANCE = SiteOperatorRoles::SLUG_SITE_FINANCE;
+
+    public const SLUG_SITE_CS = SiteOperatorRoles::SLUG_SITE_CS;

    /** @return list<string> */
    public static function fixedSlugs(): array
    {
-        return [self::SLUG_SUPER_ADMIN, self::SLUG_SITE_ADMIN, self::SLUG_AGENT];
+        return [
+            self::SLUG_SUPER_ADMIN,
+            self::SLUG_SITE_ADMIN,
+            self::SLUG_SITE_FINANCE,
+            self::SLUG_SITE_CS,
+            self::SLUG_AGENT,
+        ];
    }

    public static function isFixedSlug(string $slug): bool
@@ -52,6 +62,8 @@ final class PlatformSystemRoles
    {
        self::ensureSuperAdminRole();
        SiteAdminDefaultRolePermissions::ensurePlatformSiteAdminRole();
+        SiteFinanceDefaultRolePermissions::ensurePlatformSiteFinanceRole();
+        SiteCsDefaultRolePermissions::ensurePlatformSiteCsRole();
        AgentDefaultRolePermissions::ensurePlatformAgentRole();
    }
 }
--- a/app/Support/SiteAdminDefaultRolePermissions.php
+++ b/app/Support/SiteAdminDefaultRolePermissions.php
@@ -23,9 +23,11 @@ final class SiteAdminDefaultRolePermissions
        'prd.users.manage',
        'prd.tickets.view',
        'prd.report.view',
+        'prd.report.export',
+        'prd.draw_result.view',
+        'prd.wallet_reconcile.manage',
        'prd.settlement.agent.view',
        'prd.settlement.agent.manage',
-        'prd.integration.view',
    ];

    /**
@@ -46,7 +48,7 @@ final class SiteAdminDefaultRolePermissions
            [
                'code' => SitePlatformRole::SLUG,
                'name' => '站点管理员',
-                'description' => '接入站点后台默认权限（代理/玩家/结算运营 + 站点仪表盘）',
+                'description' => '接入站点后台默认权限（本站代理/玩家/信用结算 + 钱包流水与经营报表 + 期号只读）',
                'status' => 1,
                'is_system' => true,
                'sort_order' => 40,
--- a/app/Support/SiteCsDefaultRolePermissions.php
+++ b/app/Support/SiteCsDefaultRolePermissions.php
@@ -0,0 +1,49 @@
+<?php
+
+namespace App\Support;
+
+use App\Models\AdminRole;
+
+/** 平台「站点客服」内置角色：单玩家查询，不含全局经营报表与代理管理。 */
+final class SiteCsDefaultRolePermissions
+{
+    /** @var list<string> */
+    private const TEMPLATE_SLUGS = [
+        'prd.dashboard.view',
+        'prd.users.view_cs',
+        'prd.tickets.view',
+        'prd.wallet_reconcile.view_cs',
+    ];
+
+    /** @return list<string> */
+    public static function templateSlugs(): array
+    {
+        return self::TEMPLATE_SLUGS;
+    }
+
+    public static function ensurePlatformSiteCsRole(): AdminRole
+    {
+        $role = AdminRole::query()->updateOrCreate(
+            [
+                'slug' => SiteOperatorRoles::SLUG_SITE_CS,
+                'scope_type' => AdminRole::SCOPE_SYSTEM,
+            ],
+            [
+                'code' => SiteOperatorRoles::SLUG_SITE_CS,
+                'name' => '站点客服',
+                'description' => '单站客服：玩家/注单/单用户钱包查询工作台，不含全局报表与代理经营',
+                'status' => 1,
+                'is_system' => true,
+                'sort_order' => 42,
+                'owner_agent_id' => null,
+                'delegated_from_role_id' => null,
+            ],
+        );
+
+        $role->syncLegacyPermissionSlugs(
+            AdminPermissionInheritance::expand(self::TEMPLATE_SLUGS),
+        );
+
+        return $role->fresh() ?? $role;
+    }
+}
--- a/app/Support/SiteFinanceDefaultRolePermissions.php
+++ b/app/Support/SiteFinanceDefaultRolePermissions.php
@@ -0,0 +1,55 @@
+<?php
+
+namespace App\Support;
+
+use App\Models\AdminRole;
+
+/** 平台「站点财务」内置角色：对账、报表导出、结算收付，不含代理树经营。 */
+final class SiteFinanceDefaultRolePermissions
+{
+    /** @var list<string> */
+    private const TEMPLATE_SLUGS = [
+        'prd.dashboard.view',
+        'prd.draw_result.view',
+        'prd.users.view_finance',
+        'prd.tickets.view',
+        'prd.report.view',
+        'prd.report.export',
+        'prd.wallet_reconcile.manage',
+        'prd.wallet_adjust.manage',
+        'prd.settlement.agent.view',
+        'prd.settlement.agent.manage',
+    ];
+
+    /** @return list<string> */
+    public static function templateSlugs(): array
+    {
+        return self::TEMPLATE_SLUGS;
+    }
+
+    public static function ensurePlatformSiteFinanceRole(): AdminRole
+    {
+        $role = AdminRole::query()->updateOrCreate(
+            [
+                'slug' => SiteOperatorRoles::SLUG_SITE_FINANCE,
+                'scope_type' => AdminRole::SCOPE_SYSTEM,
+            ],
+            [
+                'code' => SiteOperatorRoles::SLUG_SITE_FINANCE,
+                'name' => '站点财务',
+                'description' => '单站财务/对账：钱包流水、对账、经营报表导出、信用结算收付',
+                'status' => 1,
+                'is_system' => true,
+                'sort_order' => 41,
+                'owner_agent_id' => null,
+                'delegated_from_role_id' => null,
+            ],
+        );
+
+        $role->syncLegacyPermissionSlugs(
+            AdminPermissionInheritance::expand(self::TEMPLATE_SLUGS),
+        );
+
+        return $role->fresh() ?? $role;
+    }
+}
--- a/app/Support/SiteOperatorRoles.php
+++ b/app/Support/SiteOperatorRoles.php
@@ -0,0 +1,62 @@
+<?php
+
+namespace App\Support;
+
+use App\Models\AdminUser;
+use Illuminate\Support\Facades\DB;
+
+/** 接入站点平台账号内置角色（绑定 admin_user_site_roles，无代理节点）。 */
+final class SiteOperatorRoles
+{
+    public const SLUG_SITE_ADMIN = 'site_admin';
+
+    public const SLUG_SITE_FINANCE = 'site_finance';
+
+    public const SLUG_SITE_CS = 'site_cs';
+
+    /** @return list<string> */
+    public static function slugs(): array
+    {
+        return [
+            self::SLUG_SITE_ADMIN,
+            self::SLUG_SITE_FINANCE,
+            self::SLUG_SITE_CS,
+        ];
+    }
+
+    public static function isSiteOperatorSlug(string $slug): bool
+    {
+        return in_array($slug, self::slugs(), true);
+    }
+
+    public static function userHasSiteOperatorRole(AdminUser $user): bool
+    {
+        if ($user->isSuperAdmin() || $user->hasPrimaryAgentBinding()) {
+            return false;
+        }
+
+        return self::primarySiteOperatorSlug($user) !== null;
+    }
+
+    public static function userHasSiteAdminRole(AdminUser $user): bool
+    {
+        return self::primarySiteOperatorSlug($user) === self::SLUG_SITE_ADMIN;
+    }
+
+    public static function primarySiteOperatorSlug(AdminUser $user): ?string
+    {
+        if ($user->isSuperAdmin() || $user->hasPrimaryAgentBinding()) {
+            return null;
+        }
+
+        $slug = DB::table('admin_user_site_roles as usr')
+            ->join('admin_roles as r', 'r.id', '=', 'usr.role_id')
+            ->where('usr.admin_user_id', $user->id)
+            ->whereIn('r.slug', self::slugs())
+            ->orderBy('usr.site_id')
+            ->orderBy('r.sort_order')
+            ->value('r.slug');
+
+        return is_string($slug) && $slug !== '' ? $slug : null;
+    }
+}
--- a/app/Support/SitePlatformRole.php
+++ b/app/Support/SitePlatformRole.php
@@ -7,10 +7,10 @@ use App\Models\AdminUser;
 use Illuminate\Support\Facades\DB;
 use Illuminate\Validation\ValidationException;

-/** 接入站点后台账号统一使用平台系统角色 slug=site_admin。 */
+/** 接入站点后台主运营角色 slug=site_admin。 */
 final class SitePlatformRole
 {
-    public const SLUG = 'site_admin';
+    public const SLUG = SiteOperatorRoles::SLUG_SITE_ADMIN;

    public static function resolve(): AdminRole
    {
@@ -41,14 +41,6 @@ final class SitePlatformRole

    public static function userHasSiteAdminRole(AdminUser $user): bool
    {
-        if ($user->isSuperAdmin() || $user->hasPrimaryAgentBinding()) {
-            return false;
-        }
-
-        return DB::table('admin_user_site_roles as usr')
-            ->join('admin_roles as r', 'r.id', '=', 'usr.role_id')
-            ->where('usr.admin_user_id', $user->id)
-            ->where('r.slug', self::SLUG)
-            ->exists();
+        return SiteOperatorRoles::userHasSiteAdminRole($user);
    }
 }