# 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。