diff --git a/docs/feat/admin-panel-dashboard-feat.md b/docs/feat/admin-panel-dashboard-feat.md
index 4e874c6..dfda3d8 100644
--- 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`
`response.user.avatar`
`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`
`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) 模块的后端实现。*
\ No newline at end of file
+
+## 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 模块后端尚未实现。*