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

Files

zenfun 0ba94026d4 docs(admin): update dashboard alert severity color mapping

Update the UI specification to distinguish warning severity with orange
color instead of grouping it with critical (red). Also remove redundant
project overview table.

2026-01-02 21:53:50 +08:00

7.6 KiB

Raw Blame History

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 Keys	`GET /admin/dashboard/summary`	`keys.active`	整数
Total Keys	`GET /admin/dashboard/summary`	`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`	整数

请求参数:

参数	类型	说明
`period`	string	预设周期: `today`, `week`, `month`
`since`	int	自定义起始时间 (Unix 秒)
`until`	int	自定义结束时间 (Unix 秒)

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 模块后端尚未实现。

7.6 KiB Raw Blame History Unescape Escape