AdminUsersPage UI 设计规范

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

1. 组件概述

用户管理页面，提供用户列表查看、用户统计、服务器切换等功能。页面包含权限保护，仅管理员可访问。

路由: /admin/users 布局: AdminLayout

2. 页面结构

┌─────────────────────────────────────────────────────────────┐
│ Header Section (Background: colorNeutralBackground2)        │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ [Icon: users]  User Management                          │ │
│ │                Manage system users, roles, permissions  │ │
│ └─────────────────────────────────────────────────────────┘ │
├─────────────────────────────────────────────────────────────┤
│ Content Section                                             │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Server Selector Card (Flat)                             │ │
│ │ [Icon: server] Identity Server: [SxAdminServerSelector] │ │
│ └─────────────────────────────────────────────────────────┘ │
│                                                             │
│ ┌─────────┬─────────┬─────────┬─────────┐                  │
│ │ Total   │ Active  │ Admins  │ Disabled│  Statistics      │
│ │ Users   │ Users   │         │         │  (4 columns)     │
│ │   N     │   N     │    N    │    N    │                  │
│ └─────────┴─────────┴─────────┴─────────┘                  │
│                                                             │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ SxAdminUserListConnected                                │ │
│ │ (PageSize="20")                                         │ │
│ └─────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘

3. 组件依赖

4. 状态管理

4.1 状态变量

4.2 依赖注入

5. 生命周期

5.1 OnInitializedAsync

1. 订阅 CurrentUser.Changed 事件
2. 订阅 ContextService.ContextChanged 事件
3. 初始化 ContextService（如未初始化）
4. 设置 _selectedServer 为当前服务器
5. 如果用户已认证且是管理员，加载统计数据

5.2 Dispose

1. 取消订阅 CurrentUser.Changed 事件
2. 取消订阅 ContextService.ContextChanged 事件

6. 事件处理

6.1 OnUserChanged

当用户状态变化时：

• 如果已认证且是管理员：重新加载统计
• 否则：清零统计数据

6.2 OnContextChanged

当上下文（服务器）变化时：

• 更新 _selectedServer
• 重新加载统计数据

6.3 LoadStatsAsync

加载用户统计数据：

1. 检查当前服务器是否存在
2. 设置加载状态
3. 通过 Provider 获取用户列表（PageSize=1000）
4. 计算各项统计
5. 处理异常情况

7. 权限控制

7.1 授权内容

• 要求角色: admin
• 未授权时不重定向到登录页 (RedirectToLogin="false")

7.2 未授权内容

显示访问拒绝界面：

• 图标: users (4rem, colorNeutralForeground3)
• 标题: "Access Denied"
• 说明文字
• 未登录时显示 SxLoginButton
• 已登录时显示当前用户信息和角色

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

8.1 UC-1: 管理员查看用户列表

前置条件: 用户已登录且具有 admin 角色

步骤:

1. 导航到 /admin/users
2. 页面加载，显示统计卡片（加载中）
3. 统计数据加载完成，显示数字
4. 用户列表显示在下方

预期结果: 显示完整的用户管理界面

8.2 UC-2: 切换服务器

前置条件: 用户已登录且具有 admin 角色

步骤:

1. 点击服务器选择器
2. 选择另一个服务器
3. 页面刷新统计数据
4. 用户列表更新为新服务器的数据

预期结果: 统计和列表反映新服务器的数据

8.3 UC-3: 未授权访问

前置条件: 用户未登录或不是管理员

步骤:

1. 导航到 /admin/users
2. 显示访问拒绝界面

预期结果:

• 未登录: 显示登录按钮
• 已登录非管理员: 显示当前用户和角色信息

8.4 UC-4: 加载失败处理

前置条件: 服务器不可用或网络错误

步骤:

1. 导航到 /admin/users
2. 统计数据加载失败

预期结果: 统计数字显示为 0，不显示错误信息

9. 状态不变性测试 (State Invariants)

9.1 服务器切换时的状态

9.2 加载状态

• 加载中时显示 SxProgressRing
• 加载完成后显示数字
• 加载失败时显示 0

10. 测试检查点

10.1 必须测试 (单元测试)

• 页面初始渲染正确
• 管理员可以看到完整界面
• 非管理员看到访问拒绝界面
• 统计数据加载状态显示正确
• 服务器切换触发数据重载

10.2 边界情况

• 没有服务器配置时的处理
• 服务器返回空用户列表
• 网络错误时的处理

10.3 E2E 测试

• 完整的用户管理流程
• 服务器切换流程
• 权限控制流程

11. 规范合规检查

11.1 组件使用 ✅

• 使用 SxTypography 而非裸文本
• 使用 SxStack 进行布局
• 使用 SxCard 作为容器
• 使用 SxIcon 显示图标
• 使用 SxButton / SxLoginButton 作为按钮

11.2 样式检查

• 使用 Design Token 颜色 (--sx-colorBrandForeground1 等)
• 使用 Design Token 间距 (--sx-spacing-xxl)
• 部分内联样式可优化为 CSS 类

12. 已知问题 / TODO

• 统计数据加载 PageSize=1000 可能在大量用户时性能不佳
• 缺少错误提示 UI
• 缺少刷新按钮

13. 变更历史