docs(admin): add dashboard integration documentation

Add detailed specification for the EZ-API Control Plane Dashboard
frontend-backend integration. This document defines the data mapping,
API endpoints, and UI logic for global navigation, real-time metrics,
traffic analysis, and alert summaries.

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

@@ -0,0 +1,103 @@
+
+# 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 中验证数据格式。
+
+---
+*注：本对接文档基于现有端点整理，未包含计费 (Billing) 模块的后端实现。*