mirror of https://github.com/EZ-Api/ez-api.git synced 2026-01-13 17:47:51 +00:00

Files

zenfun f400ffde95 refactor(api): update traffic chart response structure

Change the traffic chart API response from bucket-based to series-based
to better support frontend visualization libraries. The new format
provides a shared X-axis and aligned data arrays for each model series.

- Replace `buckets` with `x` and `series` in response
- Implement data alignment and zero-filling for time slots
- Update Swagger documentation including pending definitions

BREAKING CHANGE: The `GET /admin/logs/stats/traffic-chart` response
schema has changed. `buckets` and `models` fields are removed.

2026-01-08 18:40:44 +08:00

13 KiB

Raw Blame History

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
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 时返回):

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

响应结构:

{
  "granularity": "hour",
  "since": 1735689600,
  "until": 1735776000,
  "x": {
    "labels": ["2025-01-01T00:00:00Z", "2025-01-01T01:00:00Z"],
    "timestamps": [1735689600, 1735693200],
    "totals": {
      "data": [2050, 1800],
      "tokens_in": [82000, 70000],
      "tokens_out": [128000, 110000]
    }
  },
  "series": [
    {
      "name": "gpt-4-turbo",
      "data": [1200, 900],
      "tokens_in": [50000, 38000],
      "tokens_out": [80000, 62000]
    },
    {
      "name": "claude-3.5-sonnet",
      "data": [800, 700],
      "tokens_in": [30000, 26000],
      "tokens_out": [45000, 40000]
    },
    {
      "name": "other",
      "data": [50, 200],
      "tokens_in": [2000, 6000],
      "tokens_out": [3000, 8000]
    }
  ]
}

前端渲染建议:

图表类型	数据映射
X 轴	`x.labels` (格式化为 00:00, 04:00 等)
Y 轴	请求数量
堆叠系列	`series` 数组，每个模型一个系列
系列数据	`series[i].data`
总量标签	`x.totals.data`

时间范围选择器映射:

选择器选项	请求参数
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`	渲染堆叠柱状图	请求失败 → 显示错误提示	`series` 为空或 `x.labels` 为空 → 显示 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 接口在大数据量下的响应时间

注：本对接文档基于现有端点整理

13 KiB Raw Blame History Unescape Escape

EZ-API admin-panel Dashboard 功能文档

1. 文档概述

2. API 端点总览

3. 功能模块对接详情

3.1 全局导航与用户信息

3.2 顶部栏状态与工具

3.3 核心指标卡片

实时指标

统计指标

3.4 告警摘要

3.5 流量分析图表 (Traffic Analysis)

推荐端点: GET /admin/logs/stats/traffic-chart

备选端点: GET /admin/logs/stats

3.6 模型使用排行 (Top Models)

4. 错误处理

5. 数据刷新策略

6. 开发与测试建议

13 KiB

Raw Blame History

推荐端点: `GET /admin/logs/stats/traffic-chart`

备选端点: `GET /admin/logs/stats`