docs(admin): add dashboard feature design and mockup assets

Organize admin panel feature documentation into a dedicated directory and include an interactive HTML mockup along with a reference screenshot for the EZ-API Control Plane Dashboard.
2026-01-13 17:47:51 +00:00 · 2026-01-03 17:11:02 +08:00
parent f938abbdfa
commit 8a52d58674
3 changed files with 466 additions and 0 deletions
--- a/docs/feat/admin-panel-dashboard-feat/admin-panel-dashboard-feat.md
+++ b/docs/feat/admin-panel-dashboard-feat/admin-panel-dashboard-feat.md
@@ -0,0 +1,302 @@
+# EZ-API admin-panel Dashboard 功能文档
+
+## 1. 文档概述
+
+| **更新日期** | 2026-01-02 |
+
+---
+
+## 2. API 端点总览
+
+| 端点 | 方法 | 用途 | 刷新策略 |
+|------|------|------|----------|
+| `/status` | GET | 系统健康状态 | 轮询 30s |
+| `/auth/whoami` | GET | 当前用户信息 | 页面加载 |
+| `/admin/realtime` | GET | 实时 QPS/RPM | 轮询 5-10s |
+| `/admin/dashboard/summary` | GET | 概览指标聚合 | 时间范围变更时 |
+| `/admin/alerts` | GET | 告警列表 | 轮询 60s |
+| `/admin/alerts/stats` | GET | 告警统计 | 轮询 60s |
+| `/admin/logs/stats` | GET | 日志统计 (单维度) | 时间范围变更时 |
+| `/admin/logs/stats/traffic-chart` | GET | 流量图表 (时间×模型) | 时间范围变更时 |
+
+---
+
+## 3. 功能模块对接详情
+
+### 3.1 全局导航与用户信息
+
+| 页面元素 | 数据来源 | 字段映射 | 备注 |
+|----------|----------|----------|------|
+| 用户头像 | 前端本地配置 / 默认头像 | - | 后端暂无头像字段 |
+| 用户名称 | 前端本地配置 / 默认文案 | - | 后端暂无姓名字段 |
+| 用户邮箱 | 前端本地配置 / 隐藏 | - | 后端暂无邮箱字段 |
+| 用户角色 | `GET /auth/whoami` | `type`, `role` | `type=admin|master|key`，`role=admin` |
+| Logout | 前端动作 | N/A | 清除本地 Token，重定向登录页 |
+
+### 3.2 顶部栏状态与工具
+
+| UI 组件 | 端点 | 字段/逻辑 |
+|---------|------|-----------|
+| System Status 胶囊 | `GET /status` | `status == "ok"` → 绿色 "NOMINAL"；否则红色 |
+| Notifications 徽章 | `GET /admin/alerts/stats` | `active > 0` → 显示红点 |
+
+**交互说明**:
+
+| 功能点 | 用户操作 | 前端行为 | 后端请求 | 成功反馈 | 异常处理 | 风险/边界 |
+|--------|----------|----------|----------|----------|----------|-----------|
+| 系统状态 | 页面加载 / 轮询 | 显示状态胶囊 | `GET /status` | OK → NOMINAL | 请求失败 → 显示 UNKNOWN 或灰色 | 高频失败时避免闪烁 |
+| 通知入口 | 点击铃铛 | 跳转到告警页面或展开侧栏 | 无 | 页面切换 | 无 | 当前无专用“通知已读”接口 |
+
+### 3.3 核心指标卡片
+
+#### 实时指标
+
+| 卡片名称 | 端点 | 字段 | 渲染逻辑 |
+|----------|------|------|----------|
+| Requests Per Minute | `GET /admin/realtime` | `rpm` | 格式化显示 (如 747,000) |
+| 当前 QPS | `GET /admin/realtime` | `qps` | 小数点后 1 位 |
+| 限流用户数 | `GET /admin/realtime` | `rate_limited_count` | 整数 |
+
+#### 统计指标
+
+| 卡片名称 | 端点 | 字段 | 渲染逻辑 |
+|----------|------|------|----------|
+| Active Provider Keys | `GET /admin/dashboard/summary` | `provider_keys.active` | 整数 (上游凭证) |
+| Total Provider Keys | `GET /admin/dashboard/summary` | `provider_keys.total` | 整数 |
+| Consumed Tokens | `GET /admin/dashboard/summary` | `tokens.total` | 格式化 (如 892k) |
+| Input Tokens | `GET /admin/dashboard/summary` | `tokens.input` | - |
+| Output Tokens | `GET /admin/dashboard/summary` | `tokens.output` | - |
+| Error Rate | `GET /admin/dashboard/summary` | `requests.error_rate` | 百分比 (如 0.02%) |
+| Total Requests | `GET /admin/dashboard/summary` | `requests.total` | 整数 |
+| Failed Requests | `GET /admin/dashboard/summary` | `requests.failed` | 整数 |
+
+> **字段说明**:
+> - `provider_keys`: 上游 Provider API 密钥 (model.APIKey)
+> - `keys`: Master 生成的子 Token (model.Key)，用于内部监控
+> - "Active Keys" UI 卡片应使用 `provider_keys.active`
+
+**请求参数**:
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `period` | string | 预设周期: `today`, `week`, `month`, `last7d`, `last30d`, `all` |
+| `since` | int | 自定义起始时间 (Unix 秒) |
+| `until` | int | 自定义结束时间 (Unix 秒) |
+| `include_trends` | bool | 是否包含趋势数据 (与前一周期对比) |
+
+**周期类型说明**:
+
+| 周期值 | 时间窗口 | 趋势对比周期 |
+|--------|----------|--------------|
+| `today` | 今日 00:00 UTC → 当前 | 昨日 |
+| `week` | 本周一 00:00 UTC → 当前 | 上一自然周 |
+| `month` | 本月 1 日 00:00 UTC → 当前 | 上一自然月 |
+| `last7d` | 当前 - 7 天 → 当前 | 14 天前 → 7 天前 |
+| `last30d` | 当前 - 30 天 → 当前 | 60 天前 → 30 天前 |
+| `all` | 无时间过滤 | 不支持趋势 |
+
+**趋势数据** (当 `include_trends=true` 时返回):
+
+```json
+{
+  "trends": {
+    "requests": { "delta": 12.5, "direction": "up" },
+    "tokens": { "delta": -1.1, "direction": "down" },
+    "error_rate": { "delta": 0.0, "direction": "stable" },
+    "latency": { "delta": -5.2, "direction": "down" }
+  }
+}
+```
+
+| 字段 | 说明 |
+|------|------|
+| `delta` | 与前一周期相比的百分比变化 (四舍五入到 1 位小数) |
+| `direction` | `up` (增长 >0.5%), `down` (下降 <-0.5%), `stable`, `new` (无基准数据) |
+
+**交互说明**:
+
+| 功能点 | 用户操作 | 前端行为 | 后端请求 | 成功反馈 | 异常处理 | 风险/边界 |
+|--------|----------|----------|----------|----------|----------|-----------|
+| 实时卡片刷新 | 页面加载/定时轮询 | 显示加载态或保留上次数据 | `GET /admin/realtime` | 数值更新 | 请求失败 → 保留上次数据并标记“已过期” | `updated_at` 可能为空 |
+| 时间范围切换 | 选择 24H/7D/30D | 触发汇总与图表更新 | `GET /admin/dashboard/summary` + `GET /admin/logs/stats/traffic-chart` | 刷新 KPI 与趋势 | 400/500 → 展示错误提示 | 7D/30D 为滚动窗口 |
+| 趋势展示 | 默认展示 | 若 `include_trends=true` 显示趋势 | `GET /admin/dashboard/summary` | 显示 ↑↓ 或 Stable | 无趋势字段 → 隐藏趋势区域 | `direction=new` 仅显示 “New” |
+
+### 3.4 告警摘要
+
+**端点**: `GET /admin/alerts?status=active&limit=2&offset=0`
+
+| UI 元素 | 字段 | 渲染逻辑 |
+|---------|------|----------|
+| 状态文本 | `GET /admin/alerts/stats` → `active` | "X active events require attention" |
+| 事件内容 | `items[i].message` | 告警详情文本 |
+| 事件时间 | `items[i].created_at` | 转换为相对时间 "42m ago" |
+| 指示器颜色 | `items[i].severity` | `critical`-> 红色 ;`warning` → 橙色; `info` → 绿色 |
+
+**告警严重级别**:
+
+| Severity | 颜色 | 说明 |
+|----------|------|------|
+| `critical` | 红色 | 严重告警 |
+| `warning` | 橙色 | 警告 |
+| `info` | 绿色 | 信息 |
+
+**交互说明**:
+
+| 功能点 | 用户操作 | 前端行为 | 后端请求 | 成功反馈 | 异常处理 | 风险/边界 |
+|--------|----------|----------|----------|----------|----------|-----------|
+| 告警摘要展示 | 页面加载/轮询 | 拉取统计与最新告警 | `GET /admin/alerts/stats` + `GET /admin/alerts` | 更新列表与计数 | 请求失败 → 显示占位文案 | 列表为空 → 显示 "All Clear" |
+| 进入告警页 | 点击卡片/箭头 | 路由跳转 | 无 | 进入详情页 | 无 | 路由未实现时隐藏入口 |
+
+### 3.5 流量分析图表 (Traffic Analysis)
+
+#### 推荐端点: `GET /admin/logs/stats/traffic-chart`
+
+此端点专为堆叠流量图表设计，返回"时间×模型"二维聚合数据。
+
+**请求参数**:
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `granularity` | string | `hour` | 时间粒度: `hour` 或 `minute` |
+| `since` | int | 24h 前 | 起始时间 (Unix 秒) |
+| `until` | int | 当前 | 结束时间 (Unix 秒) |
+| `top_n` | int | 5 | Top 模型数量 (1-20)，其余归入 "other" |
+
+**时间粒度约束**:
+
+| 粒度 | 约束 | 典型场景 |
+|------|------|----------|
+| `hour` | 无限制 | 24H / 7D / 30D 视图 |
+| `minute` | 必须提供 `since` + `until`，范围 ≤ 6 小时 | 近 1-6 小时高精度视图 |
+
+**响应结构**:
+
+```json
+{
+  "granularity": "hour",
+  "since": 1735689600,
+  "until": 1735776000,
+  "models": ["gpt-4-turbo", "claude-3.5-sonnet", "llama-3-70b", "other"],
+  "buckets": [
+    {
+      "time": "2025-01-01T00:00:00Z",
+      "timestamp": 1735689600,
+      "breakdown": {
+        "gpt-4-turbo": { "count": 1200, "tokens_in": 50000, "tokens_out": 80000 },
+        "claude-3.5-sonnet": { "count": 800, "tokens_in": 30000, "tokens_out": 45000 },
+        "other": { "count": 50, "tokens_in": 2000, "tokens_out": 3000 }
+      },
+      "total": { "count": 2050, "tokens_in": 82000, "tokens_out": 128000 }
+    }
+  ]
+}
+```
+
+**前端渲染建议**:
+
+| 图表类型 | 数据映射 |
+|----------|----------|
+| X 轴 | `buckets[i].time` (格式化为 00:00, 04:00 等) |
+| Y 轴 | 请求数量 |
+| 堆叠系列 | `models` 数组，每个模型一个系列 |
+| 系列数据 | `buckets[i].breakdown[model].count` |
+| 总量标签 | `buckets[i].total.count` |
+
+**时间范围选择器映射**:
+
+| 选择器选项 | 请求参数 |
+|------------|----------|
+| 24H (默认) | `granularity=hour&since={now-24h}&until={now}` |
+| 7D | `granularity=hour&since={now-7d}&until={now}` |
+| 30D | `granularity=hour&since={now-30d}&until={now}` |
+| 最近 1H | `granularity=minute&since={now-1h}&until={now}` |
+| 最近 6H | `granularity=minute&since={now-6h}&until={now}` |
+
+#### 备选端点: `GET /admin/logs/stats`
+
+单维度聚合，适用于简单场景。
+
+| 参数 | 返回数据 |
+|------|----------|
+| `group_by=hour` | 按小时聚合的时间序列 |
+| `group_by=minute` | 按分钟聚合的时间序列 (需 since/until，≤6h) |
+| `group_by=model` | 按模型聚合的分布数据 |
+
+**交互说明**:
+
+| 功能点 | 用户操作 | 前端行为 | 后端请求 | 成功反馈 | 异常处理 | 风险/边界 |
+|--------|----------|----------|----------|----------|----------|-----------|
+| 图表加载 | 页面加载 | 请求默认 24H 图表 | `GET /admin/logs/stats/traffic-chart` | 渲染堆叠柱状图 | 请求失败 → 显示错误提示 | `buckets` 为空 → 显示 No Data |
+| 时间粒度切换 | 选择分钟级范围 | 自动切换 granularity=minute | `GET /admin/logs/stats/traffic-chart` | 图表更细粒度 | 400 → 回退到 hour 并提示 | minute 范围 ≤ 6h |
+| Top 模型限制 | 修改显示数量 | 约束 top_n ≤ 20 | `GET /admin/logs/stats/traffic-chart` | 图表更新 | 400 → 自动回退到 20 | 模型过多时显示 "other" |
+
+### 3.6 模型使用排行 (Top Models)
+
+**端点**: `GET /admin/dashboard/summary`
+
+**字段**: `top_models` 数组
+
+| UI 元素 | 字段 | 渲染逻辑 |
+|---------|------|----------|
+| 模型名称 | `top_models[i].model` | 显示模型 ID |
+| 请求数量 | `top_models[i].requests` | 整数 |
+| Token 数量 | `top_models[i].tokens` | 整数 |
+| 占比百分比 | 前端计算 | `requests / sum(requests)` → 百分比 |
+| 进度条颜色 | 索引 | 固定色板: 蓝→靛→紫→青→蓝绿 |
+
+**展开视图端点**: `GET /admin/logs/stats?group_by=model&since={unix}&until={unix}`
+
+**展开视图字段**: `items[i].model`, `items[i].count`, `items[i].tokens_in`, `items[i].tokens_out`, `items[i].avg_latency_ms`
+
+**交互说明**:
+
+| 功能点 | 用户操作 | 前端行为 | 后端请求 | 成功反馈 | 异常处理 | 风险/边界 |
+|--------|----------|----------|----------|----------|----------|-----------|
+| 排行加载 | 页面加载/时间范围变更 | 拉取 Top Models | `GET /admin/dashboard/summary` | 渲染列表与进度条 | 请求失败 → 显示占位 | 为空 → 隐藏卡片 |
+| 展开查看更多 | 点击“查看更多/展开” | 打开弹窗/抽屉，展示完整模型列表 | `GET /admin/logs/stats?group_by=model` | 列表显示全量模型 | 请求失败 → 显示错误提示 | 模型过多时需滚动或搜索 |
+
+---
+
+## 4. 错误处理
+
+| HTTP 状态码 | 处理方式 |
+|-------------|----------|
+| 200 | 正常渲染数据 |
+| 400 | 显示参数错误提示 |
+| 401 | Token 过期，触发自动登出 |
+| 403 | 权限不足提示 |
+| 500 | 显示系统错误，建议重试 |
+
+**空数据处理**:
+
+| 场景 | UI 表现 |
+|------|---------|
+| 图表无数据 | 显示 "No Data" 占位符 |
+| 告警列表为空 | 显示 "All Clear" 状态 |
+| Top Models 为空 | 隐藏该卡片或显示提示 |
+
+---
+
+## 5. 数据刷新策略
+
+| 数据类型 | 刷新机制 | 频率 |
+|----------|----------|------|
+| 系统状态 | 定时轮询 | 30 秒 |
+| 实时指标 (RPM/QPS) | 定时轮询 | 5-10 秒 |
+| 告警统计 | 定时轮询 | 60 秒 |
+| 概览指标 | 时间范围变更触发 | 按需 |
+| 流量图表 | 时间范围变更触发 | 按需 |
+
+---
+
+## 6. 开发与测试建议
+
+| 建议项 | 说明 |
+|--------|------|
+| Mock 数据 | 前端可利用 Mock 数据先行开发 UI |
+| Swagger 验证 | 复杂聚合接口建议先在 Swagger 中验证 |
+| 性能监控 | 关注 traffic-chart 接口在大数据量下的响应时间 |
+
+---
+
+*注：本对接文档基于现有端点整理*