docs(admin): update dashboard feature specification

- Add detailed interaction tables for system status, metrics, and charts
- Update API field mappings to match backend implementation
- Clarify error handling, loading states, and edge cases

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

@@ -27,10 +27,10 @@
 
 | 页面元素 | 数据来源 | 字段映射 | 备注 |
 |----------|----------|----------|------|
-| 用户头像 | `GET /auth/whoami` | `user.avatar` | 可选字段 |
-| 用户名称 | `GET /auth/whoami` | `user.name` | - |
-| 用户邮箱 | `GET /auth/whoami` | `user.email` | - |
-| 用户角色 | `GET /auth/whoami` | `identity_type` | `admin` / `master` |
+| 用户头像 | 前端本地配置 / 默认头像 | - | 后端暂无头像字段 |
+| 用户名称 | 前端本地配置 / 默认文案 | - | 后端暂无姓名字段 |
+| 用户邮箱 | 前端本地配置 / 隐藏 | - | 后端暂无邮箱字段 |
+| 用户角色 | `GET /auth/whoami` | `type`, `role` | `type=admin|master|key`，`role=admin` |
 | Logout | 前端动作 | N/A | 清除本地 Token，重定向登录页 |
 
 ### 3.2 顶部栏状态与工具
@@ -38,7 +38,14 @@
 | UI 组件 | 端点 | 字段/逻辑 |
 |---------|------|-----------|
 | System Status 胶囊 | `GET /status` | `status == "ok"` → 绿色 "NOMINAL"；否则红色 |
-| Notifications 徽章 | `GET /admin/alerts/stats` | `active_count > 0` → 显示红点 |
+| Notifications 徽章 | `GET /admin/alerts/stats` | `active > 0` → 显示红点 |
+
+**交互说明**:
+
+| 功能点 | 用户操作 | 前端行为 | 后端请求 | 成功反馈 | 异常处理 | 风险/边界 |
+|--------|----------|----------|----------|----------|----------|-----------|
+| 系统状态 | 页面加载 / 轮询 | 显示状态胶囊 | `GET /status` | OK → NOMINAL | 请求失败 → 显示 UNKNOWN 或灰色 | 高频失败时避免闪烁 |
+| 通知入口 | 点击铃铛 | 跳转到告警页面或展开侧栏 | 无 | 页面切换 | 无 | 当前无专用“通知已读”接口 |
 
 ### 3.3 核心指标卡片
 
@@ -106,13 +113,21 @@
 | `delta` | 与前一周期相比的百分比变化 (四舍五入到 1 位小数) |
 | `direction` | `up` (增长 >0.5%), `down` (下降 <-0.5%), `stable`, `new` (无基准数据) |
 
+**交互说明**:
+
+| 功能点 | 用户操作 | 前端行为 | 后端请求 | 成功反馈 | 异常处理 | 风险/边界 |
+|--------|----------|----------|----------|----------|----------|-----------|
+| 实时卡片刷新 | 页面加载/定时轮询 | 显示加载态或保留上次数据 | `GET /admin/realtime` | 数值更新 | 请求失败 → 保留上次数据并标记“已过期” | `updated_at` 可能为空 |
+| 时间范围切换 | 选择 24H/7D/30D | 触发汇总与图表更新 | `GET /admin/dashboard/summary` + `GET /admin/logs/stats/traffic-chart` | 刷新 KPI 与趋势 | 400/500 → 展示错误提示 | 7D/30D 为滚动窗口 |
+| 趋势展示 | 默认展示 | 若 `include_trends=true` 显示趋势 | `GET /admin/dashboard/summary` | 显示 ↑↓ 或 Stable | 无趋势字段 → 隐藏趋势区域 | `direction=new` 仅显示 “New” |
+
 ### 3.4 告警摘要
 
 **端点**: `GET /admin/alerts?status=active&limit=2&offset=0`
 
 | UI 元素 | 字段 | 渲染逻辑 |
 |---------|------|----------|
-| 状态文本 | `GET /admin/alerts/stats` → `active_count` | "X active events require attention" |
+| 状态文本 | `GET /admin/alerts/stats` → `active` | "X active events require attention" |
 | 事件内容 | `items[i].message` | 告警详情文本 |
 | 事件时间 | `items[i].created_at` | 转换为相对时间 "42m ago" |
 | 指示器颜色 | `items[i].severity` | `critical`-> 红色 ;`warning` → 橙色; `info` → 绿色 |
@@ -125,6 +140,13 @@
 | `warning` | 橙色 | 警告 |
 | `info` | 绿色 | 信息 |
 
+**交互说明**:
+
+| 功能点 | 用户操作 | 前端行为 | 后端请求 | 成功反馈 | 异常处理 | 风险/边界 |
+|--------|----------|----------|----------|----------|----------|-----------|
+| 告警摘要展示 | 页面加载/轮询 | 拉取统计与最新告警 | `GET /admin/alerts/stats` + `GET /admin/alerts` | 更新列表与计数 | 请求失败 → 显示占位文案 | 列表为空 → 显示 "All Clear" |
+| 进入告警页 | 点击卡片/箭头 | 路由跳转 | 无 | 进入详情页 | 无 | 路由未实现时隐藏入口 |
+
 ### 3.5 流量分析图表 (Traffic Analysis)
 
 #### 推荐端点: `GET /admin/logs/stats/traffic-chart`
@@ -200,6 +222,14 @@
 | `group_by=minute` | 按分钟聚合的时间序列 (需 since/until，≤6h) |
 | `group_by=model` | 按模型聚合的分布数据 |
 
+**交互说明**:
+
+| 功能点 | 用户操作 | 前端行为 | 后端请求 | 成功反馈 | 异常处理 | 风险/边界 |
+|--------|----------|----------|----------|----------|----------|-----------|
+| 图表加载 | 页面加载 | 请求默认 24H 图表 | `GET /admin/logs/stats/traffic-chart` | 渲染堆叠柱状图 | 请求失败 → 显示错误提示 | `buckets` 为空 → 显示 No Data |
+| 时间粒度切换 | 选择分钟级范围 | 自动切换 granularity=minute | `GET /admin/logs/stats/traffic-chart` | 图表更细粒度 | 400 → 回退到 hour 并提示 | minute 范围 ≤ 6h |
+| Top 模型限制 | 修改显示数量 | 约束 top_n ≤ 20 | `GET /admin/logs/stats/traffic-chart` | 图表更新 | 400 → 自动回退到 20 | 模型过多时显示 "other" |
+
 ### 3.6 模型使用排行 (Top Models)
 
 **端点**: `GET /admin/dashboard/summary`
@@ -208,11 +238,23 @@
 
 | UI 元素 | 字段 | 渲染逻辑 |
 |---------|------|----------|
-| 模型名称 | `top_models[i].name` | 显示模型 ID |
-| 请求数量 | `top_models[i].count` | 整数 |
-| 占比百分比 | `top_models[i].percentage` | 百分比，如后端未返回则前端计算 |
+| 模型名称 | `top_models[i].model` | 显示模型 ID |
+| 请求数量 | `top_models[i].requests` | 整数 |
+| Token 数量 | `top_models[i].tokens` | 整数 |
+| 占比百分比 | 前端计算 | `requests / sum(requests)` → 百分比 |
 | 进度条颜色 | 索引 | 固定色板: 蓝→靛→紫→青→蓝绿 |
 
+**展开视图端点**: `GET /admin/logs/stats?group_by=model&since={unix}&until={unix}`
+
+**展开视图字段**: `items[i].model`, `items[i].count`, `items[i].tokens_in`, `items[i].tokens_out`, `items[i].avg_latency_ms`
+
+**交互说明**:
+
+| 功能点 | 用户操作 | 前端行为 | 后端请求 | 成功反馈 | 异常处理 | 风险/边界 |
+|--------|----------|----------|----------|----------|----------|-----------|
+| 排行加载 | 页面加载/时间范围变更 | 拉取 Top Models | `GET /admin/dashboard/summary` | 渲染列表与进度条 | 请求失败 → 显示占位 | 为空 → 隐藏卡片 |
+| 展开查看更多 | 点击“查看更多/展开” | 打开弹窗/抽屉，展示完整模型列表 | `GET /admin/logs/stats?group_by=model` | 列表显示全量模型 | 请求失败 → 显示错误提示 | 模型过多时需滚动或搜索 |
+
 ---
 
 ## 4. 错误处理