long-agent/user-system
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
bbeeb63dfa43e9497eb98712a009d833587991b9
user-system/docs/design/ADMIN_FRONTEND_PAGE_DESIGN.md

404 lines
13 KiB
Markdown
Raw Normal View History

docs: project docs, scripts, deployment configs, and evidence
2026-04-02 11:22:17 +08:00
# 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。
Reference in New Issue Copy Permalink