监控看板

1. 页面概览

监控看板是 AIP 管理后台面向管理员的运行监控页，路由为 /admin/monitoring。概览 Tab 用指标卡片展示查询总数、成功率、平均/P95 延迟、总 Tokens 与 LLM 失败率；历史趋势 Tab 用 echarts 折线/柱状图展示按时间窗口的查询量与延迟；反馈统计 Tab 汇总用户评分与反馈类型分布。

指标数据来自 NLQ 查询日志（nlq_query_logs）与 LLM 调用日志聚合，反馈来自用户对查询结果的评价（POST /feedback）。管理员据此掌握平台健康度、性能瓶颈与用户满意度。

一句话总结：监控看板把「运行指标、历史趋势、用户反馈」三个维度集中展示，是 AIP 平台的健康仪表盘。

2. 访问入口

2.1 路由与菜单

2.2 认证与权限

守卫校验 aip_is_admin='1'，否则跳 /chat；请求走 action/web/src/api/aipClient.js（aip_token Bearer JWT），401 清 token 跳登录。

2.3 端口与 API 前缀

AIP 后端 18080，前缀 /aip-api（实际 /aip-api/v1/...，Vite 代理重写为 /api/v1）。

3. 界面布局

+------------------------------+
| 监控看板  [刷新]  [alert 提示] |
| Tab：概览 | 历史趋势 | 反馈统计
+------------------------------+
| 概览 Tab：核心指标（card）    |
|   查询总数|成功率|平均延迟|P95 延迟|总Tokens|LLM 失败率
|   （成功率/失败率按阈值着色） |
| 历史趋势 Tab（card）：        |
|   时间窗口下拉[近 1 天▾]      |
|   echarts：柱=查询量、        |
|   线=平均延迟（左轴）、       |
|   线=成功率（右轴 %）         |
| 反馈统计 Tab：                |
|   反馈概览卡（平均评分+N条）  |
|   评分分布+反馈类型分布（CSS柱条）
|   最近反馈列表（星级/类型/时间/问题/评论）
+------------------------------+

各板块职责：概览卡片对成功率（≥90% 绿）与 LLM 失败率（≥10% 红）着色提示；历史趋势支持时间窗口切换并渲染图表；反馈统计用 CSS 柱条展示评分/类型分布。

4. 交互元素

5. 后端关联

API 端点（monitoring 挂 protected 登录组；feedback/stats 挂 admin 组）：

5.1 关键机制

• 指标聚合：从 nlq_query_logs 统计查询总数/成功率/延迟（含 P95），从 LLM 调用日志统计失败率与 Tokens；空库时 LLM 字段为 nil，前端 fmtTokens 显示 -。
• 百分比兼容：success_rate 等 0-1 与 0-100 两种数值统一转百分比；图表内数据统一转 0-100（null 跳过该点）。
• 反馈分布：rating_distribution（1~5 星）与 type_distribution（sql_correct/sql_syntax_error/wrong_result/misunderstood）渲染为相对最大值的 CSS 柱条。
• 图表懒渲染：切到历史趋势 Tab 才 init echarts（容器此时才挂载）；watch(activeTab) 补渲染，页面卸载时 dispose。

后端实现位于 action/products/aip/monitoring/handler.go、service.go（GetMetrics/GetHistory），feedback/handler.go、service.go（Stats）。

6. 权限与安全

• 认证与角色：aip_token + 管理员；/feedback/stats 为 admin 组，/monitoring/* 指标挂 protected 登录组。
• 数据安全：监控聚合数据不区分用户维度，仅管理员可见页面入口。
• 只读页面：监控看板无任何写操作，仅查询与图表展示。

7. 常见问题与排错

问题 1：概览指标全为 0

原因：GET /monitoring/metrics 失败（后端未就绪/401）num() 兜底 0；或确无查询日志。
处理：确认请求返回；先产生一次 NLQ 查询再「刷新」。

问题 2：历史趋势图空白

原因：historyData 为空（后端未就绪）或容器未挂载即渲染。
处理：确认 /monitoring/history 返回非空 items；切到历史趋势 Tab 后会自动补渲染。

问题 3：切换时间窗口后图表未更新

原因：fetchHistory 在 finally 调 renderChart，若 chartRef 容器未就绪会跳过。
处理：确认当前在历史趋势 Tab；重新切换窗口或点「刷新」。

问题 4：反馈统计平均评分显示 '-'

原因：avg_rating 缺失或为空（无已评分反馈）。
处理：属正常兜底；产生评分反馈后重新加载。

8. 已知缺陷与边界