long-agent/user-system
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: project docs, scripts, deployment configs, and evidence

Browse Source
This commit is contained in:
long-agent
2026-04-02 11:22:17 +08:00
parent 4718980ab5
commit bbeeb63dfa
396 changed files with 165018 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

403
docs/design/ADMIN_FRONTEND_PAGE_DESIGN.md Normal file
View File

@@ -0,0 +1,403 @@
# 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。

280
docs/design/ADMIN_UI_DESIGN_SPEC.md Normal file
View File

@@ -0,0 +1,280 @@
# Admin UI 设计规范
更新时间：2026-03-19
## 1. 文档定位
本文基于 [ADMIN_FRONTEND_EXECUTION_PLAN.md](../plans/ADMIN_FRONTEND_EXECUTION_PLAN.md) 继续向下收敛，负责定义 Admin 前端的视觉语言、布局规则、组件行为和交互基线。
生效边界：
- 不扩张页面范围，不新增任何执行方案未纳入的页面。
- 不引入假数据、假图表、假按钮。
- 与真实 API 或执行方案冲突时，以 [API.md](../API.md) 和 [ADMIN_FRONTEND_EXECUTION_PLAN.md](../plans/ADMIN_FRONTEND_EXECUTION_PLAN.md) 为准。
## 2. 设计目标
1. 高密度但不压迫。后台场景需要高信息密度，但必须保证 3 秒内可定位主要操作区。
2. 可扫读。标题、指标、状态、风险项必须一眼分层，避免所有信息同权重堆叠。
3. 可追溯。删除、状态切换、权限分配、导入导出等高风险操作必须有明确确认与反馈。
4. 可落地。所有规范都要能直接映射到 `React 18 + Ant Design 5 + CSS Variables`，不依赖额外设计系统。
## 3. 视觉方向
### 3.1 主题定义
本项目采用 `Mineral Console` 视觉方向：
- 背景使用温暖矿物色，而不是纯白大平板。
- 主色使用稳重的石油蓝，强调“可信、可控、可维护”。
- 点缀色使用铜橙，只用于重点 CTA、提醒或人工介入点。
- 整体气质偏企业运维中控，而不是消费化营销页面。
### 3.2 关键词
- 稳定
- 清晰
- 审计感
- 有层次但不过度装饰
### 3.3 禁止项
- 霓虹、赛博、发光描边。
- 大面积纯黑或纯白极端对比。
- 无数据支撑的趋势图、热力图、地域图。
- 超轻字重、小字号堆叠、低对比浅灰文本。
## 4. 设计 Token
基础 token 草案已同步落在 [admin-ui-tokens.css](./admin-ui-tokens.css)，后续实现时可直接迁移到 `frontend/admin/src/styles/tokens.css`。
### 4.1 色彩系统
| Token | 值 | 用途 |
|------|----|------|
| `--color-canvas` | `#F4F1EA` | 应用整体背景 |
| `--color-layout` | `#E9E3D5` | Sidebar 与大区块分层底色 |
| `--color-surface` | `#FFFFFF` | 卡片、抽屉、表单面板 |
| `--color-surface-muted` | `#F8F5EF` | 表格工具栏、弱容器 |
| `--color-surface-strong` | `#DDD5C6` | 分组标题底、边界强调 |
| `--color-text-strong` | `#17212B` | 主文本 |
| `--color-text-base` | `#314150` | 正文 |
| `--color-text-muted` | `#677380` | 次级说明 |
| `--color-text-inverse` | `#F8FAFC` | 深色背景上的文本 |
| `--color-border-soft` | `#D6D0C3` | 默认边框 |
| `--color-border-strong` | `#BFB6A6` | 高对比边框 |
| `--color-primary` | `#0E5A6A` | 主操作色 |
| `--color-primary-hover` | `#0A4B59` | 主操作 hover |
| `--color-accent` | `#C26D3A` | 重点提示、次主按钮 |
| `--color-success` | `#217A5B` | 成功、已启用、已激活 |
| `--color-warning` | `#B7791F` | 风险、锁定、待确认 |
| `--color-danger` | `#B33A3A` | 删除、禁用、失败 |
| `--color-info` | `#2D6A9F` | 信息提示 |
### 4.2 状态映射
| 领域状态 | 颜色 | 呈现方式 |
|----------|------|----------|
| 用户 `已激活` | `success` | 实心状态点 + 浅底 Tag |
| 用户 `未激活` | `info` | 浅蓝灰 Tag |
| 用户 `已锁定` | `warning` | 琥珀色 Tag |
| 用户 `已禁用` | `danger` | 红色 Tag |
| 角色/权限 `启用` | `success` | 绿色开关或 Tag |
| 角色/权限 `禁用` | `danger` | 红色 Tag |
| Webhook `active` | `success` | 绿色 Tag |
| Webhook `inactive` | `warning` | 琥珀色 Tag |
| 登录失败 | `danger` | 红色点标记 |
| 登录成功 | `success` | 绿色点标记 |
### 4.3 字体系统
| 层级 | 字体 | 说明 |
|------|------|------|
| 主字体 | `IBM Plex Sans`, `PingFang SC`, `Microsoft YaHei`, sans-serif | 页面主体、标题、表格 |
| 等宽字体 | `JetBrains Mono`, `Consolas`, monospace | ID、状态码、时间戳、Webhook 事件名 |
字号与字重：
- `32 / 600`: 仪表盘总览数字、登录页主标题
- `24 / 600`: 页面标题
- `20 / 600`: 分区标题
- `16 / 600`: 卡片标题、表单大标签
- `14 / 500`: 正文、表格内容、按钮
- `12 / 500`: 辅助说明、标签、注释
## 5. 栅格与布局
### 5.1 页面壳层
- 左侧导航宽度：`248px`
- 折叠导航宽度：`84px`
- 顶栏高度：`64px`
- 页面内容最大宽度：`1440px`
- 页面容器左右留白：桌面 `32px`，平板 `24px`，移动 `16px`
### 5.2 栅格
| 断点 | 栅格 | 列间距 | 场景 |
|------|------|--------|------|
| `>= 1280px` | 12 列 | 24px | Desktop 主后台 |
| `768px - 1279px` | 8 列 | 20px | Tablet / 小屏笔记本 |
| `< 768px` | 4 列 | 16px | Mobile |
### 5.3 间距与圆角
- 间距刻度：`4 / 8 / 12 / 16 / 24 / 32 / 40 / 48`
- 小型控件圆角：`10px`
- 卡片和抽屉圆角：`16px`
- 大型容器圆角：`20px`
### 5.4 阴影
- 卡片阴影：轻量，强调层次，不强调浮夸漂浮感。
- 抽屉/弹窗阴影：明显高于卡片，但透明度控制在 `12%` 以内。
## 6. 组件规范
### 6.1 App Shell
- Sidebar 采用深一点的矿物底色，与内容区形成结构分层。
- 顶栏左侧放页面标题和面包屑，右侧固定为全局搜索预留位、当前用户信息、退出入口。
- 非管理员登录后，导航仅显示 `Webhooks / Profile / Security` 三组可访问页面。
### 6.2 Page Header
每个页面头部保持四段式结构：
1. 标题
2. 一句范围说明
3. 右侧主操作区
4. 次级状态信息，如“最后刷新时间”
禁止在页面头部堆叠超过两个主按钮。
### 6.3 Filter Bar
根据后端能力分三类：
- `组合筛选条`：只用于 `/users` 和 `/import-export`，可同时提交多个条件。
- `单维筛选条`：用于 `/roles`、`/permissions`、`/logs/*`，一次只激活一个查询维度，避免 UI 表达超出后端查询能力。
- `动作工具条`：用于 `/webhooks`、`/profile`，只保留刷新、创建、编辑等轻操作。
### 6.4 Metric Card
仪表盘指标卡统一规则：
- 左上是指标标题
- 中间是大号数字
- 右上是状态图标或补充标签
- 底部是一行说明文字
禁止使用折线图、面积图冒充趋势。
如需占比，只能用现有字段在前端做简单比率计算。
### 6.5 数据表格
- 头部固定高度，列标题字重 `600`
- 行 hover 使用极浅主色背景
- 表格默认不做斑马纹
- 操作列固定在右侧
- 分页统一放右下角
- 列表为空时必须给出下一步建议，不允许空白页
推荐表格密度：
- 默认使用 AntD `middle`
- 日志表、权限表允许切到 `small`
### 6.6 抽屉与弹窗
- `详情`、`编辑` 优先使用右侧抽屉，便于保留列表上下文
- `删除确认`、`状态切换确认` 使用居中弹窗
- `分配角色`、`分配权限` 使用大号弹窗，内部可包含树或双栏选择器
### 6.7 表单
- 表单标签左对齐
- 必填标识保持统一红点或星号
- 单列表单最大宽度 `560px`
- 双列表单仅用于用户资料类页面，不用于权限配置
- 长文本输入区默认展示字符限制提示
### 6.8 反馈组件
- 加载：优先骨架屏，局部操作可用按钮 loading
- 成功：轻量 toast，不阻断流程
- 失败：错误提示 + 可恢复动作
- 危险动作：必须二次确认
## 7. 交互规范
### 7.1 删除与危险操作
- 删除用户、角色、权限、Webhook 时必须展示资源名称。
- 二次确认按钮使用危险色，不使用“主要按钮”配色。
- 删除成功后停留在当前页面，刷新当前列表，不跳转空白页。
### 7.2 状态切换
- 启用/禁用、锁定/解锁类操作使用显式文本，不只依赖颜色。
- 切换成功后局部刷新当前行，不整页闪烁。
### 7.3 上传与下载
- 导入、头像上传显示明确的文件限制和格式。
- 导出使用显式格式选择，下载开始后按钮进入短时 loading。
- 上传失败必须保留错误明细区，尤其是批量导入。
### 7.4 日志与审计
- 时间统一使用 `YYYY-MM-DD HH:mm:ss`
- `IP`、`Request Path`、`Event Type`、`ID` 使用等宽字体
- 长 JSON 或请求参数通过抽屉展开，不在表格中完整摊开
## 8. 响应式规则
- `< 1280px` 时，Dashboard 卡片从四列降为两列。
- `< 1024px` 时，Sidebar 默认折叠。
- `< 768px` 时，列表页顶部操作条改为纵向堆叠。
- `< 768px` 时，抽屉改全屏。
- Mobile 只保留最高优先级列，其余字段进入“展开详情”。
## 9. 无障碍与可用性
- 文本与背景对比度不低于 `4.5:1`
- 所有图标按钮必须提供文字 tooltip
- 表单错误必须靠近字段显示
- 键盘焦点可见，焦点边框使用主色高亮
- 状态不能只靠颜色区分，必须同时有文字
## 10. Ant Design 落地映射
| 需求 | 落地建议 |
|------|----------|
| 全局主题 | 通过 `ConfigProvider` 覆盖 `colorPrimary`、`borderRadius`、`fontFamily` |
| 页面容器 | 使用 `Layout` + 自定义 CSS Modules |
| 指标卡 | `Card` + 自定义头尾结构 |
| 列表页 | `Table` + `Form` + `Space` |
| 状态标签 | `Tag` + 统一状态映射函数 |
| 抽屉编辑 | `Drawer` + `Form` |
| 二次确认 | `Modal.confirm` 或包装组件 |
| 空态/错误态 | 基于 `Result`、`Empty` 二次封装 |
## 11. 页面级设计基线
- `/login` 使用双栏欢迎布局，但不展示社交登录按钮。
- `/dashboard` 只展示真实统计卡片和简表区块。
- `/users` 只做列表、筛选、详情、编辑、状态切换、删除、角色分配。
- `/roles`、`/permissions` 保持“列表 + 编辑弹窗 + 分配弹窗”结构。
- `/logs/*` 优先突出筛选与详情展开，不做复杂可视化。
- `/profile/security` 使用分段卡片，而不是堆满一个超长大表单。
## 12. 不可突破的限制
- 不做 `/settings`
- 不做用户创建页
- 不做批量用户操作
- 不做全局设备管理页
- 不做社交登录回调页
- 不做细粒度按钮权限前端系统
- 不引入图表库实现“看起来更像后台”的伪需求

56
docs/design/admin-ui-tokens.css Normal file
View File

@@ -0,0 +1,56 @@
:root {
--font-family-sans: "IBM Plex Sans", "PingFang SC", "Microsoft YaHei", sans-serif;
--font-family-mono: "JetBrains Mono", "Consolas", monospace;
--color-canvas: #f4f1ea;
--color-layout: #e9e3d5;
--color-surface: #ffffff;
--color-surface-muted: #f8f5ef;
--color-surface-strong: #ddd5c6;
--color-text-strong: #17212b;
--color-text-base: #314150;
--color-text-muted: #677380;
--color-text-inverse: #f8fafc;
--color-border-soft: #d6d0c3;
--color-border-strong: #bfb6a6;
--color-primary: #0e5a6a;
--color-primary-hover: #0a4b59;
--color-accent: #c26d3a;
--color-success: #217a5b;
--color-warning: #b7791f;
--color-danger: #b33a3a;
--color-info: #2d6a9f;
--gradient-shell:
linear-gradient(180deg, rgba(14, 90, 106, 0.08) 0%, rgba(14, 90, 106, 0) 28%),
linear-gradient(135deg, #f7f4ee 0%, #ebe5d7 100%);
--sidebar-width: 248px;
--sidebar-width-collapsed: 84px;
--topbar-height: 64px;
--page-max-width: 1440px;
--space-1: 4px;
--space-2: 8px;
--space-3: 12px;
--space-4: 16px;
--space-5: 24px;
--space-6: 32px;
--space-7: 40px;
--space-8: 48px;
--radius-sm: 10px;
--radius-md: 16px;
--radius-lg: 20px;
--shadow-card: 0 10px 30px rgba(23, 33, 43, 0.06);
--shadow-float: 0 20px 60px rgba(23, 33, 43, 0.12);
--motion-fast: 140ms;
--motion-base: 220ms;
--motion-slow: 320ms;
--motion-ease: cubic-bezier(0.2, 0, 0, 1);
}