Admin Pages UI 设计规范

自动生成时间: 2026-02-04 页面路径: workbench/NextUI.Workbench/Pages/Admin/

1. 概述

Admin Pages 是 NextUI 的管理控制台页面集合，用于管理用户、角色、组、会话、客户端、配置文件和身份服务器等系统资源。

1.1 页面清单

1.2 通用布局

所有页面使用 AdminLayout 布局，包含：

• 左侧导航栏 (AdminSidebar)
• 顶部标题区 (SxSection + SxPageBox)
• 主内容区 (SxSection + SxPageBox)

2. AdminOverviewPage (管理控制台首页)

2.1 路由

• /admin
• /admin/overview

2.2 页面模式

2.3 主要组件

统计卡片 (Stats Grid)

用户菜单 (User Menu)

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

• Profile → /identity/shared-profile
• Settings → /settings
• Logout → IdentityService.LogoutAsync()

Mock Mode Warning Banner

当系统处于 Mock 模式时，显示 <SxMessageBar Intent="Info"> 警告横幅。

快速操作 (Quick Actions)

• Manage Users → /admin/users
• Manage Roles → /admin/roles
• Manage Groups → /admin/groups
• Manage Clients → /admin/clients
• User Profiles → /admin/profiles
• Active Sessions → /admin/sessions
• Manage Servers → /admin/servers

Recent Activity Section

• 使用 <SxTimeline> 组件显示最近活动
• 右上角 "View All Activity" 链接到 /admin/activity

2.4 状态变量

private bool _statsLoading = true;
private int _serverCount;
private int _totalUsers;
private int _activeUsers;
private bool _wizardOpen;
private IdentityMode _identityMode = IdentityMode.None;

2.5 事件处理

3. AdminUsersPage (用户管理)

3.1 路由

• /admin/users

3.2 页面结构

1. Server Selector - 选择身份服务器
2. Statistics Cards - 4个统计卡片
   • Total Users
   • Active Users
   • Admins
   • Disabled
3. User List - <SxAdminUserListConnected> 组件

3.3 统计数据

4. AdminUserDetailPage (用户详情)

4.1 路由

• /admin/users/{UserId}

4.2 参数

[Parameter] public string UserId { get; set; } = "";

4.3 页面结构

1. Breadcrumb - Admin > Users > [UserName]
2. Profile Card - 用户基本信息
3. Roles Card - 角色和组
4. Sessions Card - 活动会话
5. Actions Card - 操作按钮

4.4 对话框

4.5 状态变量

private bool _loading = true;
private UserDetail? _user;
private List<SessionInfo> _sessions = new();
private List<RoleSelection> _availableRoles = new();
private bool _editDialogOpen;
private bool _editRolesDialogOpen;
private bool _resetPasswordDialogOpen;
private bool _disableDialogOpen;
private bool _deleteDialogOpen;

5. AdminRolesPage (角色管理)

5.1 路由

• /admin/roles

5.2 页面结构

使用 <SxAdminRoleListConnected> 组件，显示 Realm Roles。

5.3 功能

• 查看角色列表
• 添加新角色
• 编辑角色
• 删除角色
• 支持 Composite Roles

6. AdminGroupsPage (组管理)

6.1 路由

• /admin/groups

6.2 页面结构

左右分栏布局:

• 左栏 (1/3): 组树形结构
• 右栏 (2/3): 组详情 (Tabs: Members, Roles, Settings)

6.3 对话框

6.4 数据模型

private class GroupNode
{
    public string Id { get; set; }
    public string Name { get; set; }
    public string Path { get; set; }
    public string? Description { get; set; }
    public int MemberCount { get; set; }
    public List<string> Roles { get; set; }
    public List<MemberInfo> Members { get; set; }
    public DateTime CreatedAt { get; set; }
    public List<GroupNode> Children { get; set; }
}

7. AdminSessionsPage (会话管理)

7.1 路由

• /admin/sessions

7.2 页面结构

1. Statistics Cards
   • Active Sessions
   • Unique Users
   • Desktop Sessions
   • Mobile Sessions
2. Session List - <SxDataGrid> 显示会话
3. Recent Activity - <SxTimeline> 显示活动

7.3 DataGrid 列

7.4 对话框

8. AdminActivityPage (活动日志)

8.1 路由

• /admin/activity

8.2 页面结构

1. Filter Bar - 搜索 + 类型筛选 + 刷新按钮
2. Activity List - 活动记录列表 (使用 <SxCard> 卡片显示)
3. Back Button - 返回概览

8.3 活动类型

8.4 活动项结构

┌─────────────────────────────────────────────────────────────┐
│ [Icon] Activity Message                          Time Ago    │
│        [Badge: Type]  User: username                         │
└─────────────────────────────────────────────────────────────┘

8.5 自定义 CSS 类

活动图标使用自定义 CSS 类控制颜色：

• activity-icon-* - 使用 Design Token 颜色变量

9. AdminClientsPage (客户端管理)

9.1 路由

• /admin/clients

9.2 页面结构

1. Server Selector - 选择 Keycloak 服务器
2. Statistics Cards
   • Total Clients
   • Active
   • Confidential
   • Public
3. Client List - <SxAdminClientListConnected> 组件

9.3 要求

• 仅支持 Keycloak 服务器类型

10. AdminProfilesPage (配置文件管理)

10.1 路由

• /admin/profiles

10.2 页面结构

1. Server Status Card - 显示 API 连接状态
2. Profiles List - <SxDataGrid> 显示配置文件
3. Statistics Cards
   • Total Profiles
   • Light Theme
   • Dark Theme
   • Languages

10.3 DataGrid 列

10.4 对话框

11. AdminServersPage (服务器管理)

11.1 路由

• /admin/servers

11.2 页面结构

1. Server List - <SxAdminServerList> 组件
2. Status Message - 操作反馈
3. Help Section
   • Supported Providers (Keycloak, SharedProfile API, NextUI Application)
   • Quick Start Guide (4 步骤)

11.3 事件回调

12. 通用授权模式

所有页面使用 <SxAuthGuard> 组件保护:

<SxAuthGuard Roles="@(new[] { "admin" })" RedirectToLogin="false">
    <ChildContent>
        <!-- 授权内容 -->
    </ChildContent>
    <UnauthorizedContent>
        <!-- 未授权内容 -->
    </UnauthorizedContent>
</SxAuthGuard>

12.1 未授权内容模式

13. 测试检查点

13.1 E2E 测试 (已实现)

• AdminOverviewPage - 页面加载、统计卡片、快速操作
• AdminUsersPage - 用户列表、搜索、添加用户对话框
• AdminUserDetailPage - 用户详情、Tab 切换、操作按钮
• AdminRolesPage - 角色列表、Realm/Client Tab、添加角色
• AdminGroupsPage - 组树、添加组对话框
• AdminSessionsPage - 会话列表、终止会话
• AdminActivityPage - 活动日志、筛选
• AdminClientsPage - 客户端列表、添加客户端
• AdminProfilesPage - 配置文件列表、添加配置文件
• AdminServersPage - 服务器列表、添加服务器

13.2 单元测试 (bUnit)

关联组件的测试:

• SxAdminUserEditor
• SxAdminRoleEditor
• SxAdminServerEditor
• SxAdminResetPassword

14. 规范合规检查

14.1 组件使用

• 没有直接使用原生 HTML 元素 (除了必要的 <div>, <a>)
• 所有 UI 元素使用 NextUI 组件 (SxButton, SxInput, SxCard 等)
• 布局使用 SxStack, SxGrid, SxSection, SxPageBox

14.2 样式

• 没有硬编码颜色值
• 所有样式使用 Design Token (var(--sx-*))
• AdminGroupsPage 样式已提取到 .razor.css

15. 已知问题 / TODO

1. AdminGroupsPage 内联样式应提取到单独的 CSS 文件 ✅ 已修复
2. AdminActivityPage 活动数据为硬编码 demo 数据
3. AdminUserDetailPage 用户数据来自 DemoUsers，需要连接真实 API
4. AdminSessionsPage 会话数据为模拟数据

16. 变更历史