user-system/docs/design/ADMIN_FRONTEND_PAGE_DESIGN.md

Admin 前端页面设计

更新时间：2026-03-19

1. 文档目的

本文将 ADMIN_FRONTEND_EXECUTION_PLAN.md 中的路由范围，转换为可实施的页面设计方案。它不改变页面边界，只定义每个页面应该长什么样、怎么组织信息、允许哪些交互。

2. 导航架构

2.1 管理员导航

导航组	页面
总览	/dashboard
访问控制	/users /roles /permissions
审计日志	/logs/login /logs/operation
集成能力	/webhooks /import-export
我的账户	/profile /profile/security

2.2 非管理员导航

导航组	页面
集成能力	/webhooks
我的账户	/profile /profile/security

非管理员不展示任何 Admin 管理菜单入口，也不保留“灰掉但可见”的菜单。

3. 壳层设计

3.1 Admin Shell

+----------------------------------------------------------------------------------+
| Sidebar                | Topbar: Breadcrumb / Page Title / User / Logout       |
| - Dashboard            +--------------------------------------------------------+
| - Users                | Page Header                                            |
| - Roles                | - title                                                |
| - Permissions          | - summary                                              |
| - Logs                 | - primary action                                       |
| - Webhooks             +--------------------------------------------------------+
| - Import / Export      | Filter Bar / Toolbar                                   |
| - Profile              +--------------------------------------------------------+
| - Security             | Main Content                                           |
|                        | - cards / table / drawer / modal                       |
+----------------------------------------------------------------------------------+

3.2 登录后非管理员壳层

仍使用相同顶栏和侧栏结构，但导航项缩减为 Webhooks / Profile / Security，防止出现“可见但不可进”的无效体验。

4. 页面设计

4.1 /login

目标：

• 清晰承接三种登录方式。
• 提供足够信任感和系统说明。
• 不出现当前 MVP 不支持的社交登录入口。

布局：

+----------------------------------+-----------------------------------------------+
| Brand / Trust Panel              | Login Card                                    |
| - 系统名称                        | [密码登录] [邮箱验证码] [短信验证码]             |
| - 核心说明                        | --------------------------------------------- |
| - 后端核心能力简述                 | 表单区域                                       |
| - 安全能力标签                     | 忘记密码入口                                   |
+----------------------------------+-----------------------------------------------+

设计要点：

• 左栏使用浅石油蓝渐变与安全说明，不放营销文案。
• 登录卡宽度控制在 420px - 460px。
• 三种登录方式使用顶部 Tabs，切换不跳页。
• 底部只放“忘记密码”，不放“注册”“第三方登录”。

4.2 /forgot-password

• 单卡片页，突出邮箱输入与提交按钮。
• 成功后显示“请查收邮件”的结果态，不直接跳回登录。

4.3 /reset-password

• 先做 token 校验态，再展示重置表单。
• 校验失败进入结果页，不展示可提交表单。

4.4 /dashboard

目标：

• 用最少组件展示真实统计，不制造假趋势。

推荐布局：

+--------------------+--------------------+--------------------+--------------------+
| 总用户数            | 已激活用户          | 已锁定用户          | 已禁用用户          |
+--------------------+--------------------+--------------------+--------------------+
| 未激活用户          | 今日新增            | 本周新增            | 本月新增            |
+--------------------+--------------------+--------------------+--------------------+
| 今日成功登录        | 今日失败登录         | 本周成功登录         | 说明 / 注意事项卡片   |
+--------------------+--------------------+--------------------+--------------------+

设计要点：

• 每个指标卡只承载一个主数字。
• 右下角说明卡可展示“当前不提供趋势图与地域分布”的说明或刷新时间。
• 若展示占比，只允许基于现有字段计算，如 active / total。

4.5 /users

目标：

• 作为 Admin 核心工作台，支持高频筛选与低中频编辑。

布局：

+----------------------------------------------------------------------------------+
| Page Header: 用户管理                                              [刷新]         |
+----------------------------------------------------------------------------------+
| 关键字 | 状态 | 角色 | 创建时间范围 | 排序字段 | 排序方向 | [查询] [重置]        |
+----------------------------------------------------------------------------------+
| Table: username / nickname / email / phone / status / last_login / created_at   |
|                                                        [详情] [编辑] [状态] ...  |
+----------------------------------------------------------------------------------+
| Pagination                                                                       |
+----------------------------------------------------------------------------------+

交互动作：

• 详情：右侧抽屉，展示完整资料和角色概览。
• 编辑：右侧抽屉，保留列表上下文。
• 状态切换：确认弹窗。
• 删除：危险确认弹窗。
• 分配角色：大号弹窗。

必须遵守：

• 页面不提供“新建用户”按钮。
• 页面不提供“批量操作”。
• 页面不提供“上传他人头像”。
• 页面不提供“管理员重置密码”。

4.6 /roles

目标：

• 在简单 CRUD 下完成角色启停与权限分配。

布局结构：

• 头部：标题、说明、创建角色
• 单维筛选条：关键词搜索 或 状态切换
• 主体：角色表格
• 弹层：创建/编辑角色、分配权限

筛选约束：

• 与当前后端一致，角色页不做“关键词 + 状态”的组合查询。
• UI 上使用“筛选模式”或显式互斥交互，避免用户误以为支持复合过滤。

推荐列：

• 角色名
• 角色代码
• 描述
• 是否系统角色
• 是否默认角色
• 状态
• 更新时间
• 操作

4.7 /permissions

目标：

• 同时兼顾权限树浏览和列表操作。

布局结构：

• 头部：标题、说明、创建权限
• 工具条：视图切换（列表 / 树） + 单维筛选
• 主体：
  • 列表模式：表格
  • 树模式：左树右详情

筛选约束：

• 当前后端只支持 keyword、type、status 单维过滤，不做组合查询。
• 类型 与 状态 不应同时作为可激活筛选条件出现。

推荐列：

• 名称
• 代码
• 类型
• 路径
• 方法
• 排序
• 状态
• 操作

4.8 /logs/login

目标：

• 让管理员快速确认登录成败、失败原因和时间范围。

布局结构：

• 页头：标题、说明、刷新
• 单维查询方式切换：
  • 按用户 ID
  • 按状态
  • 按时间范围
• 主体：日志表格

推荐列：

• 用户 ID
• 登录方式
• IP
• 地点
• 结果
• 失败原因
• 时间

设计要点：

• 结果 使用显式成功/失败标签。
• 失败原因 超长时省略显示，hover 或抽屉展开。

4.9 /logs/operation

目标：

• 以检索和追溯为主，不追求复杂统计。

布局结构：

• 单维查询方式切换：
  • 关键词
  • 用户 ID
  • HTTP Method
  • 时间范围
• 主体表格
• 行展开或抽屉查看 request_params

推荐列：

• 用户 ID
• 操作名称
• 方法
• 路径
• 响应状态
• IP
• 时间

4.10 /webhooks

目标：

• 对已登录用户提供清晰可控的 Webhook 管理视图。

布局结构：

• 页头：标题、说明、创建 Webhook
• 工具条：刷新、创建
• 主体：表格或卡片列表，首版推荐表格
• 附加交互：投递记录 抽屉

推荐列：

• 名称
• URL
• 订阅事件
• 状态
• 最大重试次数
• 超时秒数
• 更新时间
• 操作

设计要点：

• 订阅事件优先显示前 2 个，剩余以 +N Tag 收纳。
• 投递记录抽屉中，status_code、event_type、attempt 使用等宽字体。

4.11 /import-export

目标：

• 把导入、导出、模板下载整合为一个操作台，而不是分散按钮。

推荐布局：

+--------------------------------------+-------------------------------------------+
| Export Panel                         | Import Panel                              |
| - format                             | - file picker                             |
| - fields                             | - format hint                             |
| - keyword / status                   | - import result summary                   |
| - download                           | - error detail list                       |
+--------------------------------------+-------------------------------------------+
| Template Download                                                         |
+----------------------------------------------------------------------------+

设计要点：

• 导出筛选只使用后端当前支持的 keyword / status / format / fields。
• 导入结果必须保留成功数、失败数、错误清单。
• 模板下载放单独卡片，不与导入按钮混在一起。

4.12 /profile

目标：

• 面向本人资料维护，不掺杂安全动作。

布局结构：

• 左侧：头像展示卡、基础信息摘要
• 右侧：资料编辑表单

字段建议：

• 用户名只读
• 可编辑：邮箱、手机号、昵称、性别、生日、地区、简介
• 头像区域只展示，不在本页上传，上传动作跳转到 /profile/security

4.13 /profile/security

目标：

• 将本人安全能力收敛到一页，但仍然保持可扫描。

推荐结构：

+----------------------------------------------------------------------------------+
| Section Nav: 密码 / 2FA / 头像 / 设备 / 登录日志 / 操作日志                      |
+----------------------------------------------------------------------------------+
| Password Card                                                                    |
+----------------------------------------------------------------------------------+
| TOTP Card                                                                        |
+----------------------------------------------------------------------------------+
| Avatar Upload Card                                                               |
+----------------------------------------------------------------------------------+
| My Devices Table                                                                 |
+----------------------------------------------------------------------------------+
| My Login Logs Table                                                              |
+----------------------------------------------------------------------------------+
| My Operation Logs Table                                                          |
+----------------------------------------------------------------------------------+

设计要点：

• 上方增加页内锚点导航，避免超长滚动失去方向。
• 修改密码 与 TOTP 放最上方，因为安全优先级最高。
• 设备与日志都只显示“本人”数据，不伪装成全局设备中心。

5. 页面共享设计规则

5.1 标题与说明

• 所有页面都要有一句边界说明。
• 文案重点说明“当前页能做什么”，而不是大段背景描述。

5.2 空态

• 空列表时给出原因和下一步动作。
• 例如 Webhook 空态可出现“创建第一个 Webhook”按钮。

5.3 错误态

• 页面级错误用整块错误卡。
• 表格局部失败只替换表格区域，不吞掉整个页面头部与筛选条。

5.4 查询方式

• /users 使用组合筛选。
• /roles、/permissions、/logs/* 使用单维查询模式。
• 单维模式必须在视觉上明显表现为“当前只激活一个筛选维度”。

6. 与后端约束对齐清单

• 不出现 创建用户 页面或按钮。
• 不出现批量启用、批量禁用、批量删除。
• 不出现管理员重置他人密码。
• 不出现全局设备管理。
• 不出现社交登录回调页或社交账号绑定页。
• Dashboard 不出现趋势图、在线人数、地域分布、最近注册用户。
• 按钮与筛选项必须只映射当前真实 API。