EZ-API 控制平面仪表盘 (Dashboard) 前后端对接功能文档
1. 文档概述
- 目的: 定义前端页面 (
stitch_admin_dashboard) 与后端 API 的交互细节，确保数据准确落地。
- 原则: 后端专注于输出业务数据 API，前端专注于 UI/UX 呈现[1]。
2. 功能模块对接详情
2.1 全局导航与用户信息 (Global Navigation)
- 功能描述: 侧边栏菜单渲染及当前登录用户信息的展示。
- 前端逻辑: 页面加载时请求用户信息，菜单项当前为静态配置，但需根据路由高亮。
| 页面元素 |
数据来源/逻辑 |
对应字段/参数 |
备注 |
| 用户头像/名称 |
GET /auth/whoami |
response.user.name
response.user.avatar
response.user.email |
需确认后端返回的角色字段以控制权限 |
| Logout |
前端动作 |
N/A |
点击清除本地 Token 并重定向至登录页 |
| 菜单高亮 |
前端路由匹配 |
N/A |
Dashboard 对应路由 /admin/dashboard |
- 功能描述: 系统健康状态监控及通知红点提示。
- 交互频率: 建议前端通过轮询 (Polling) 或 WebSocket (如有) 更新状态。
| 接口端点 |
方法 |
对应 UI 组件 |
字段映射/逻辑 |
/status |
GET |
System Status |
若 status == 'ok'，显示 "NOMINAL" (绿色)；否则显示异常状态 |
/admin/alerts/stats |
GET |
Notifications |
读取 active_count；若 >0 显示红色徽章 |
2.3 仪表盘核心指标 (Key Metrics Cards)
- 功能描述: 展示 RPM、活跃 Key、Token 消耗及错误率。
- 数据聚合: 涉及实时数据与统计数据的混合展示。为降低前端处理难度，建议响应 JSON 结构与仪表盘字段高度一致[2]。
A. 实时指标 (Real-time)
- 接口:
GET /admin/realtime
- UI 组件: "Requests Per Minute" 卡片
| 前端字段 |
后端字段 (data) |
渲染逻辑 |
| Value |
rpm |
显示数值 (如 747,000) |
| Trend |
trend_percentage |
(需确认后端是否提供，否则前端仅展示当前值) |
B. 统计概览 (Summary Stats)
- 接口:
GET /admin/dashboard/summary
- UI 组件: Active Keys, Consumed Tokens, Error Rate
| 前端字段 |
后端字段 (data) |
渲染逻辑 |
| Active Keys |
keys.active |
直接展示数值 |
| Consumed Tokens |
tokens.total |
展示数值，若有 tokens.trend 则渲染涨跌幅 |
| Error Rate |
requests.error_rate |
格式化为百分比 (e.g., 0.02%) |
2.4 告警摘要 (Warnings & Alerts Summary)
- 接口:
GET /admin/alerts
- 参数:
status=active, limit=2, offset=0
| UI 区域 |
字段映射 |
逻辑说明 |
| 状态文本 |
统计接口 count |
"X active events require attention" |
| 事件内容 |
list[i].message |
显示告警详情文本 |
| 事件时间 |
list[i].created_at |
前端将 Unix 时间戳转换为 "42m ago" 格式 |
| 指示器颜色 |
list[i].severity |
critical/warning -> 红色; info -> 绿色 |
2.5 流量分析图表 (Traffic Analysis)
- 功能描述: 展示指定时间范围内的流量趋势。
- 接口:
GET /admin/logs/stats
- 关键逻辑: 根据时间选择器切换请求参数。
| 时间选择 |
请求参数 |
数据处理逻辑 |
| 24H (默认) |
group_by=hour
since={now-24h}, until={now} |
渲染 24 个柱状数据点 |
| < 6H |
group_by=minute |
渲染分钟级高精度图表 |
| 数据维度 |
限制说明: 当前后端不支持 time x model 的嵌套堆叠数据。 |
折衷方案: 前端仅渲染总量的时间曲线，或在该卡片旁单独展示模型分布饼图，不强行做堆叠柱状图。 |
2.6 模型使用排行 (Top Models)
- 接口:
GET /admin/dashboard/summary (推荐) 或 GET /admin/logs/stats?group_by=model
- UI 组件: 进度条列表
| UI 元素 |
后端字段 |
处理逻辑 |
| 模型名称 |
top_models[i].name |
显示模型 ID (如 gpt-4) |
| 占比数值 |
top_models[i].percentage |
如后端未返回百分比，前端需计算 count / total_requests |
| 进度条颜色 |
index |
前端根据索引配置固定色板 (蓝->靛->紫...) |
3. 非功能性要求与最佳实践
- 数据刷新机制:
realtime 接口建议每 5-10 秒轮询一次。- 图表类数据在“时间范围”改变时触发重新请求。
- 错误处理:
- 所有接口需统一处理 HTTP 401 (Token 过期)，触发自动登出。
- 图表接口若返回空数据，需展示 "No Data" 占位符。
- 开发与测试:
- 由于后端接口已明确，后端只需负责输出标准 JSON，前端可利用 Mock 数据先行开发 UI，便于自动化测试介入[5]。
- 对于
GET /admin/logs/stats 的复杂聚合，建议先在 Swagger/Postman 中验证数据格式。
注：本对接文档基于现有端点整理，未包含计费 (Billing) 模块的后端实现。
b1fe1ecb97