AdminOverviewPage UI 设计规范

自动生成时间: 2026-02-04 组件路径: workbench/NextUI.Workbench/Pages/Admin/AdminOverviewPage.razor

1. 组件概述

Admin Overview Page 是管理控制台的首页/仪表板，显示系统统计信息、快速操作入口、最近活动，并根据身份验证状态显示不同内容。

2. 页面模式

模式 条件 显示内容
Dashboard IsAuthenticated && HasAdminRole 完整控制台 (统计、快速操作、活动)
Access Denied IsAuthenticated && !HasAdminRole 访问被拒绝，显示当前用户角色
Demo Login Prompt !IsAuthenticated && MockMode Demo 模式提示，Demo Login 按钮
Setup Wizard !IsAuthenticated && NoneMode 配置向导提示，自动打开 Wizard
Login Prompt !IsAuthenticated && OIDCMode 登录提示，Login as Admin 按钮

3. 页面结构

3.1 Header Section

┌─────────────────────────────────────────────────────────────┐
│ [Icon] Admin Console                          [Avatar] Name ▼│
│         System administration...               Menu Button   │
└─────────────────────────────────────────────────────────────┘

用户菜单 (User Menu)

当点击头像/用户名时显示下拉菜单：

菜单项 图标 链接/操作
Profile user /identity/shared-profile
Settings cog /settings
Logout right-from-bracket IdentityService.LogoutAsync()

3.1.1 Mock Mode Warning Banner

当系统处于 Mock 模式时，在页面顶部显示警告横幅：

┌─────────────────────────────────────────────────────────────┐
│ ⚠️ [Info] Running in mock mode. For production, configure   │
│            a real identity provider.                        │
└─────────────────────────────────────────────────────────────┘
  • 组件: <SxMessageBar Intent="MessageIntent.Info">

3.2 Stats Section (Authorized)

┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│   [Server]   │ │   [Users]    │ │   [Check]    │ │   [Clock]    │
│      N       │ │      N       │ │    100%      │ │      N       │
│ Active       │ │ Total Users  │ │ System       │ │ Active       │
│ Servers      │ │              │ │ Health       │ │ Sessions     │
└──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘

3.3 Quick Actions

┌─────────────────────────────────────────────────────────────┐
│ Quick Actions                                               │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ...         │
│ │ Manage      │ │ Manage      │ │ Manage      │             │
│ │ Users       │ │ Roles       │ │ Groups      │             │
│ └─────────────┘ └─────────────┘ └─────────────┘             │
└─────────────────────────────────────────────────────────────┘

3.4 Recent Activity

┌─────────────────────────────────────────────────────────────┐
│ Recent Activity                          [View All Activity]│
├─────────────────────────────────────────────────────────────┤
│ [Empty State: No recent activity]                           │
│ OR                                                          │
│ ● [icon] Activity description                      Time ago │
│ ● [icon] Activity description                      Time ago │
│ ● [icon] Activity description                      Time ago │
└─────────────────────────────────────────────────────────────┘

Recent Activity Card 结构

  • 标题: "Recent Activity"
  • 右侧操作: "View All Activity" 链接到 /admin/activity
  • 内容: 使用 <SxTimeline> 组件显示活动列表
  • 空状态: 显示 "No recent activity" 提示

4. 状态变量

变量 类型 默认值 说明
_statsLoading bool true 统计数据加载状态
_serverCount int 0 服务器数量
_totalUsers int 0 用户总数
_activeUsers int 0 活跃用户数
_wizardOpen bool false Setup Wizard 打开状态
_identityMode IdentityMode None 身份验证模式

5. 依赖服务

服务 说明
ICurrentUser 当前用户信息
IIdentityService 身份验证服务 (登出)
IIdentitySetupService 身份配置检测
AdminContextService 管理上下文 (当前服务器)
IAdminProviderFactory 管理提供者工厂
IServerRegistry 服务器注册表
NavigationManager 导航管理

6. 事件处理

事件 来源 处理
CurrentUser.Changed 用户状态变化 重新加载统计或重置数据
ContextService.ContextChanged 上下文变化 重新加载统计

7. 操作按钮

按钮 条件 行为
Profile Dashboard Mode 导航到 /identity/shared-profile
Settings Dashboard Mode 导航到 /settings
Logout Dashboard Mode 调用 IdentityService.LogoutAsync()
Configure Authentication None Mode 打开 Setup Wizard
Try Demo Login None Mode 导航到 /identity
Demo Login Mock Mode 导航到 /identity
Login as Admin OIDC Mode SxLoginButton 组件

8. 状态转换图

                    ┌─────────────────┐
                    │   Page Load     │
                    └────────┬────────┘
                             │
                    ┌────────▼────────┐
                    │ Detect Identity │
                    │     Mode        │
                    └────────┬────────┘
                             │
        ┌────────────────────┼────────────────────┐
        │                    │                    │
        ▼                    ▼                    ▼
   ┌─────────┐         ┌─────────┐         ┌─────────┐
   │  None   │         │  Mock   │         │  OIDC   │
   │  Mode   │         │  Mode   │         │  Mode   │
   └────┬────┘         └────┬────┘         └────┬────┘
        │                   │                    │
        ▼                   │                    │
   Open Wizard              │                    │
   Automatically            │                    │
        │                   │                    │
        └───────────────────┼────────────────────┘
                            │
                   ┌────────▼────────┐
                   │ Is Authenticated│
                   │   & Has Admin?  │
                   └────────┬────────┘
                            │
              ┌─────────────┴─────────────┐
              │ Yes                   No  │
              ▼                           ▼
       ┌───────────┐               ┌───────────┐
       │ Dashboard │               │  Access   │
       │   Mode    │               │  Denied   │
       └───────────┘               └───────────┘

9. 典型使用场景 (Use Cases)

9.1 UC-1: 首次访问 (无配置)

  1. 用户访问 /admin
  2. 系统检测 IdentityMode.None
  3. 自动打开 Setup Wizard
  4. 用户配置身份验证
  5. 页面刷新，显示 Dashboard

9.2 UC-2: Demo 模式登录

  1. 用户访问 /admin
  2. 系统检测 IdentityMode.Mock
  3. 显示 Demo Login 提示
  4. 用户点击 "Demo Login"
  5. 导航到 /identity
  6. 选择 Admin 用户登录
  7. 返回显示 Dashboard

9.3 UC-3: Admin 查看统计

  1. Admin 用户已登录
  2. 访问 /admin
  3. 显示加载状态
  4. 加载服务器数量、用户数量
  5. 显示统计卡片

9.4 UC-4: 快速操作导航

  1. Admin 在 Dashboard
  2. 点击 "Manage Users"
  3. 导航到 /admin/users

10. 测试检查点

10.1 必须测试 (单元测试)

  • 未认证时显示正确的提示内容
  • Admin 角色用户显示 Dashboard
  • 非 Admin 用户显示 Access Denied
  • Mock 模式下显示 Demo 提示
  • 统计数据正确加载和显示

10.2 E2E 测试

  • 页面加载显示 Admin Console 标题
  • 统计卡片显示
  • 快速操作按钮可点击
  • 用户菜单可打开

10.3 边界情况

  • 服务器不可用时的错误处理
  • 统计加载超时处理
  • 用户状态变化时的 UI 更新

11. 规范合规检查

11.1 组件使用

  • 使用 SxSection, SxPageBox 布局
  • 使用 SxCard, SxStack, SxGrid 组件
  • 使用 SxTypography 文本
  • 使用 SxIcon 图标
  • 使用 SxButton, SxCommandBar 按钮
  • 使用 SxProgressRing 加载状态

11.2 样式

  • 颜色使用 Design Token
  • 间距使用 Design Token
  • 字体使用 TypographyVariant

12. 已知问题 / TODO

  1. Recent Activity 为空状态，需要实现活动日志数据源
  2. System Health 固定显示 100%，需要实际健康检查
  3. 用户菜单已实现，但菜单项图标需确认是否与设计一致

13. 变更历史

日期 变更内容
2026-02-04 初始生成
2026-02-04 UI Review: 添加用户菜单详情、Mock Mode Banner、Recent Activity Card 结构