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`, `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` (无基准数据) |

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

**响应结构**:

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

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