404 lines
13 KiB
Markdown
404 lines
13 KiB
Markdown
# Admin 前端页面设计
|
||
|
||
更新时间：2026-03-19
|
||
|
||
## 1. 文档目的
|
||
|
||
本文将 [ADMIN_FRONTEND_EXECUTION_PLAN.md](../plans/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
|
||
|
||
```text
|
||
+----------------------------------------------------------------------------------+
|
||
| 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 不支持的社交登录入口。
|
||
|
||
布局：
|
||
|
||
```text
|
||
+----------------------------------+-----------------------------------------------+
|
||
| Brand / Trust Panel | Login Card |
|
||
| - 系统名称 | [密码登录] [邮箱验证码] [短信验证码] |
|
||
| - 核心说明 | --------------------------------------------- |
|
||
| - 后端核心能力简述 | 表单区域 |
|
||
| - 安全能力标签 | 忘记密码入口 |
|
||
+----------------------------------+-----------------------------------------------+
|
||
```
|
||
|
||
设计要点：
|
||
|
||
- 左栏使用浅石油蓝渐变与安全说明，不放营销文案。
|
||
- 登录卡宽度控制在 `420px - 460px`。
|
||
- 三种登录方式使用顶部 `Tabs`，切换不跳页。
|
||
- 底部只放“忘记密码”，不放“注册”“第三方登录”。
|
||
|
||
### 4.2 `/forgot-password`
|
||
|
||
- 单卡片页，突出邮箱输入与提交按钮。
|
||
- 成功后显示“请查收邮件”的结果态，不直接跳回登录。
|
||
|
||
### 4.3 `/reset-password`
|
||
|
||
- 先做 token 校验态，再展示重置表单。
|
||
- 校验失败进入结果页，不展示可提交表单。
|
||
|
||
### 4.4 `/dashboard`
|
||
|
||
目标：
|
||
|
||
- 用最少组件展示真实统计，不制造假趋势。
|
||
|
||
推荐布局：
|
||
|
||
```text
|
||
+--------------------+--------------------+--------------------+--------------------+
|
||
| 总用户数 | 已激活用户 | 已锁定用户 | 已禁用用户 |
|
||
+--------------------+--------------------+--------------------+--------------------+
|
||
| 未激活用户 | 今日新增 | 本周新增 | 本月新增 |
|
||
+--------------------+--------------------+--------------------+--------------------+
|
||
| 今日成功登录 | 今日失败登录 | 本周成功登录 | 说明 / 注意事项卡片 |
|
||
+--------------------+--------------------+--------------------+--------------------+
|
||
```
|
||
|
||
设计要点：
|
||
|
||
- 每个指标卡只承载一个主数字。
|
||
- 右下角说明卡可展示“当前不提供趋势图与地域分布”的说明或刷新时间。
|
||
- 若展示占比，只允许基于现有字段计算，如 `active / total`。
|
||
|
||
### 4.5 `/users`
|
||
|
||
目标：
|
||
|
||
- 作为 Admin 核心工作台，支持高频筛选与低中频编辑。
|
||
|
||
布局：
|
||
|
||
```text
|
||
+----------------------------------------------------------------------------------+
|
||
| 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`
|
||
|
||
目标：
|
||
|
||
- 把导入、导出、模板下载整合为一个操作台，而不是分散按钮。
|
||
|
||
推荐布局：
|
||
|
||
```text
|
||
+--------------------------------------+-------------------------------------------+
|
||
| 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`
|
||
|
||
目标：
|
||
|
||
- 将本人安全能力收敛到一页，但仍然保持可扫描。
|
||
|
||
推荐结构：
|
||
|
||
```text
|
||
+----------------------------------------------------------------------------------+
|
||
| 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。
|