ez-api/docs/feat/admin-panel-dashboard-feat.md

EZ-API 控制平面仪表盘 (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	user.avatar	可选字段
用户名称	GET /auth/whoami	user.name	-
用户邮箱	GET /auth/whoami	user.email	-
用户角色	GET /auth/whoami	identity_type	admin / master
Logout	前端动作	N/A	清除本地 Token，重定向登录页

3.2 顶部栏状态与工具

UI 组件	端点	字段/逻辑
System Status 胶囊	GET /status	status == "ok" → 绿色 "NOMINAL"；否则红色
Notifications 徽章	GET /admin/alerts/stats	active_count > 0 → 显示红点

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
since	int	自定义起始时间 (Unix 秒)
until	int	自定义结束时间 (Unix 秒)

已知限制 (待 fix-dashboard-summary-api 实现后解决):

• period=week 使用自然周起点 (周一)，非滚动 7 天
• period=month 使用自然月起点 (1号)，非滚动 30 天
• 趋势数据 (delta/trend) 当前不返回，前端需隐藏趋势指示器
• 建议使用 since/until 实现精确的滚动时间窗口

3.4 告警摘要

端点: GET /admin/alerts?status=active&limit=2&offset=0

UI 元素	字段	渲染逻辑
状态文本	GET /admin/alerts/stats → active_count	"X active events require attention"
事件内容	items[i].message	告警详情文本
事件时间	items[i].created_at	转换为相对时间 "42m ago"
指示器颜色	items[i].severity	critical-> 红色 ;warning → 橙色; info → 绿色

告警严重级别:

Severity	颜色	说明
critical	红色	严重告警
warning	橙色	警告
info	绿色	信息

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 小时高精度视图

响应结构:

{
  "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	按模型聚合的分布数据

3.6 模型使用排行 (Top Models)

端点: GET /admin/dashboard/summary

字段: top_models 数组

UI 元素	字段	渲染逻辑
模型名称	top_models[i].name	显示模型 ID
请求数量	top_models[i].count	整数
占比百分比	top_models[i].percentage	百分比，如后端未返回则前端计算
进度条颜色	索引	固定色板: 蓝→靛→紫→青→蓝绿

---

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 中验证
自动化测试	利用 Mock Server 进行前端组件测试
性能监控	关注 traffic-chart 接口在大数据量下的响应时间

---

注：本对接文档基于现有端点整理，Billing 模块后端尚未实现。