AdminGroupsPage UI 设计规范

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

1. 组件概述

Admin Groups Page 是组管理页面，提供树形结构的组层次管理，支持添加、编辑、删除组，以及管理组成员和角色。

2. 页面结构

2.1 布局

┌────────────────────────────────────────────────────────────────┐
│ [Icon] Group Management                                        │
│        Organize users into groups...                           │
├─────────────────┬──────────────────────────────────────────────┤
│ Groups      [+] │ [Group Name] or "Select a Group"             │
├─────────────────┼──────────────────────────────────────────────┤
│ ▸ Internal (15) │ [Members] [Roles] [Settings]                 │
│   ▸ Engineering │ ─────────────────────────────                │
│     • Frontend  │ [Content based on selected tab]              │
│     • Backend   │                                              │
│   • Design      │                                              │
│ • External (10) │                                              │
└─────────────────┴──────────────────────────────────────────────┘

2.2 Grid 布局

• 左栏: grid-column: span 1 (1/3 宽度)
• 右栏: grid-column: span 2 (2/3 宽度)

3. 页面模式

4. 组树结构

4.1 树节点组件

<SxStack Orientation="Horizontal" Class="group-item [selected]">
    <SxIcon Name="folder|users" />
    <SxTypography>GroupName</SxTypography>
    <SxBadge>MemberCount</SxBadge>
</SxStack>

4.2 缩进规则

• 根级: margin-left: 0
• 每层: margin-left: depth * 16px

5. 详情面板 Tabs

5.1 Members Tab

┌────────────────────────────────────────────────────┐
│ [Search members...]                   [Add Member] │
├────────────────────────────────────────────────────┤
│ [Avatar] DisplayName                          [x]  │
│          Email                                     │
│ [Avatar] DisplayName                          [x]  │
│          Email                                     │
└────────────────────────────────────────────────────┘

5.2 Roles Tab

┌────────────────────────────────────────────────────┐
│ Roles assigned to this group will be inherited...  │
├────────────────────────────────────────────────────┤
│ [Shield] role-name                            [x]  │
│ [Shield] role-name                            [x]  │
├────────────────────────────────────────────────────┤
│ [+ Add Role]                                       │
└────────────────────────────────────────────────────┘

5.3 Settings Tab

┌────────────────────────────────────────────────────┐
│ Group Path                                         │
│ /internal/engineering                              │
│                                                    │
│ Description                                        │
│ Engineering team                                   │
│                                                    │
│ Created                                            │
│ 1/1/2026 12:00 PM                                  │
└────────────────────────────────────────────────────┘

6. 状态变量

7. 对话框规范

7.1 Add Group Dialog

按钮: Cancel, Create Group

7.2 Edit Group Dialog

按钮: Cancel, Save Changes

7.3 Delete Group Dialog

按钮: Cancel, Delete Group (红色)

7.4 Add Member Dialog

按钮: Cancel, Add Selected

7.5 Add Role Dialog

按钮: Cancel, Add Selected

8. 数据模型

8.1 GroupNode

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; }
}

8.2 MemberInfo

private class MemberInfo
{
    public string UserId { get; set; }
    public string DisplayName { get; set; }
    public string Email { get; set; }
    public string? AvatarUrl { get; set; }
}

9. 操作流程

9.1 添加组

Click [+] → Open Dialog → Fill Form → Create Group → Update Tree

9.2 编辑组

Select Group → Click [Edit] → Open Dialog → Modify → Save → Update

9.3 删除组

Select Group → Click [Delete] → Confirm Dialog → Delete → Update Tree → Clear Selection

9.4 添加成员

Select Group → Members Tab → Click [Add Member] → Select Users → Add → Update List

9.5 移除成员

Click Member [x] → Remove from List → Update Count

9.6 添加角色

Select Group → Roles Tab → Click [Add Role] → Select Roles → Add → Update List

9.7 移除角色

Click Role [x] → Remove from List

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

10.1 UC-1: 创建新组

1. Admin 点击 Groups 卡片的 [+] 按钮
2. 填写组名称 "Marketing"
3. 选择父组 "Internal Users"
4. 点击 "Create Group"
5. 组树更新，显示新组

10.2 UC-2: 管理组成员

1. Admin 选择 "Engineering" 组
2. 切换到 Members tab
3. 点击 "Add Member"
4. 选择用户
5. 点击 "Add Selected"
6. 成员列表更新

10.3 UC-3: 为组分配角色

1. Admin 选择组
2. 切换到 Roles tab
3. 点击 "Add Role"
4. 选择 "developer" 角色
5. 点击 "Add Selected"
6. 角色继承给所有成员

10.4 UC-4: 删除组

1. Admin 选择要删除的组
2. 点击 "Delete" 按钮
3. 查看警告信息
4. 确认删除
5. 组及子组被删除

11. 测试检查点

11.1 必须测试 (单元测试)

• 组树渲染正确
• 选择组更新详情面板
• Tab 切换正常
• 所有对话框打开/关闭
• 成员搜索过滤
• CRUD 操作更新状态

11.2 状态不变性测试

• 添加成员不影响角色列表
• 删除组不影响其他组
• 取消对话框不保存更改

11.3 E2E 测试

• 页面加载组管理
• 组树显示
• 添加组对话框
• 统计数据显示
• 刷新功能

12. CSS 样式

.group-item {
    padding: var(--sx-spacing-xs) var(--sx-spacing-s);
    border-radius: var(--sx-borderRadiusMedium);
    cursor: pointer;
    transition: background 0.2s;
}

.group-item:hover {
    background: var(--sx-colorNeutralBackground3);
}

.group-item.selected {
    background: var(--sx-colorBrandBackground1);
    color: white;
}

.member-item, .role-item {
    padding: var(--sx-spacing-s);
    border-radius: var(--sx-borderRadiusMedium);
    background: var(--sx-colorNeutralBackground2);
}

13. 规范合规检查

13.1 组件使用

• SxGrid 布局
• SxCard 卡片
• SxTabs/SxTabPanel 标签页
• SxDialog 对话框
• SxInput/SxTextArea 表单
• SxSelect 下拉选择
• SxSearch 搜索框
• SxAvatar 头像
• SxCheckbox 复选框
• SxBadge 徽章

13.2 样式

• 颜色使用 Design Token
• 样式已提取到 AdminGroupsPage.razor.css

14. 已知问题 / TODO

1. 内联 CSS 应提取到单独的样式文件 ✅ 已修复
2. 组数据为硬编码 Demo 数据，需要连接 API
3. 拖拽排序功能未实现

15. 变更历史