docs(admin): update dashboard integration specs

Restructure documentation into tables for improved readability and include detailed specifications for the new traffic chart endpoint. Define explicit data refresh strategies, error handling guidelines, and response structures for admin panel components.
2026-01-13 17:47:51 +00:00 · 2026-01-02 21:45:46 +08:00
parent b1fe1ecb97
commit e5624c62f1
1 changed files with 224 additions and 97 deletions
--- a/docs/feat/admin-panel-dashboard-feat.md
+++ b/docs/feat/admin-panel-dashboard-feat.md
@@ -1,103 +1,230 @@
-
 # EZ-API 控制平面仪表盘 (Dashboard) 前后端对接功能文档

 ## 1. 文档概述
-*   **目的**: 定义前端页面 (`stitch_admin_dashboard`) 与后端 API 的交互细节，确保数据准确落地。
-*   **原则**: 后端专注于输出业务数据 API，前端专注于 UI/UX 呈现[1]。

-## 2. 功能模块对接详情
-
-### 2.1 全局导航与用户信息 (Global Navigation)
-
-*   **功能描述**: 侧边栏菜单渲染及当前登录用户信息的展示。
-*   **前端逻辑**: 页面加载时请求用户信息，菜单项当前为静态配置，但需根据路由高亮。
-
-| 页面元素 | 数据来源/逻辑 | 对应字段/参数 | 备注 |
-| :--- | :--- | :--- | :--- |
-| **用户头像/名称** | `GET /auth/whoami` | `response.user.name`<br>`response.user.avatar`<br>`response.user.email` | 需确认后端返回的角色字段以控制权限 |
-| **Logout** | 前端动作 | N/A | 点击清除本地 Token 并重定向至登录页 |
-| **菜单高亮** | 前端路由匹配 | N/A | Dashboard 对应路由 `/admin/dashboard` |
-
-### 2.2 顶部栏状态与工具 (Header Tools)
-
-*   **功能描述**: 系统健康状态监控及通知红点提示。
-*   **交互频率**: 建议前端通过轮询 (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`<br>`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. 非功能性要求与最佳实践
-
-1.  **数据刷新机制**:
-    *   `realtime` 接口建议每 5-10 秒轮询一次。
-    *   图表类数据在“时间范围”改变时触发重新请求。
-2.  **错误处理**:
-    *   所有接口需统一处理 HTTP 401 (Token 过期)，触发自动登出。
-    *   图表接口若返回空数据，需展示 "No Data" 占位符。
-3.  **开发与测试**:
-    *   由于后端接口已明确，后端只需负责输出标准 JSON，前端可利用 Mock 数据先行开发 UI，便于自动化测试介入[5]。
-    *   对于 `GET /admin/logs/stats` 的复杂聚合，建议先在 Swagger/Postman 中验证数据格式。
+| 项目 | 说明 |
+|------|------|
+| **目的** | 定义前端页面与后端 API 的交互细节，确保数据准确落地 |
+| **原则** | 后端专注于输出业务数据 API，前端专注于 UI/UX 呈现 |
+| **更新日期** | 2026-01-02 |

 ---
-*注：本对接文档基于现有端点整理，未包含计费 (Billing) 模块的后端实现。*
+
+## 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 小时高精度视图 |
+
+**响应结构**:
+
+```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 模块后端尚未实现。*