1. 页面概览
评测管理是 AIP 管理后台面向管理员的 NLQ 离线评测页，路由为 /admin/eval。它用「测试用例 → 评测运行 → 历史与回归」三个 Tab 覆盖完整闭环：先维护黄金测试集（自然语言问题 + 期望 SQL），再触发 NLQ→SQL 生成与执行校验，最后查看指标与回归趋势。
核心指标包括执行准确率（EA）、精确匹配率（EM）、语法有效率（SV）与通过用例数；回归报告按历次运行对比执行准确率，下降时标红告警，便于定位 Prompt/RAG/SQL 逻辑劣化。
一句话总结：评测管理把「用例集维护、评测执行、回归监控」串成一条流水线，让 NLQ 质量可度量、可回归。
2. 访问入口
2.1 路由与菜单
| 项目 | 值 |
|---|---|
| 路由 path | /admin/eval |
| 路由 name | AdminEval |
| 路由 title | 评测管理 |
| requiresAuth | true（父级 /admin 另有 requiresAdmin） |
| 菜单位置 | AdminLayout 侧边栏菜单项「评测管理」 |
| 前端源码 | action/web/src/views/EvalPage.vue |
| 路由注册 | action/web/src/router/index.js |
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：[新建测试用例][导出评测集]
| 表格：ID|类别|难度|问题|期望SQL|数据源|操作
| 评测运行 Tab：[运行评测]（spinner）
| 指标卡：执行准确率|精确匹配率|语法有效率|
| 通过用例|平均延迟|平均Tokens
| 通过率进度条 + 用例结果表（展开 SQL）
| 历史与回归 Tab：评测历史+运行详情+
| 回归报告（横幅+趋势折线+指标表）
+------------------------------+各板块职责：测试用例 Tab 维护黄金集；评测运行 Tab 同步执行展示结果；历史与回归 Tab 提供详情与回归检测。
4. 交互元素
| 控件 | 位置 | 含义与作用 |
|---|---|---|
| 新建测试用例 / 编辑、删除 | 测试用例表 | 弹窗：类别下拉（简单查询/多表连接/聚合统计/子查询/窗口函数，值 simple_select/join/aggregation/subquery/window）、难度（简单/中等/困难，easy/medium/hard）、问题*、期望 SQL*、数据源可选；删除有 confirm |
| 导出评测集 | 测试用例表工具栏 | GET /evaluation/test-cases/export，下载 eval_test_cases_<日期>.json |
| 运行评测 | 评测运行 Tab | POST /evaluation/runs（timeout 放宽 120s），执行中按钮显示「评测运行中...」并禁用，同步返回结果 |
| 查看 SQL / 收起 SQL | 用例结果表 | 展开/收起该用例生成的 SQL（pre 代码块） |
| 查看详情 | 评测历史表 | 打开该次运行详情（指标卡 + 用例结果表） |
5. 后端关联
API 端点（/evaluation 前缀，全部 admin 组）：
| 方法 | 路径 | 用途 |
|---|---|---|
| GET / POST | /evaluation/test-cases | 用例列表（分页 data.items）/ 创建 |
| GET | /evaluation/test-cases/export | 导出完整评测集 DTO（供制品分发/同源复用） |
| PUT / DELETE | /evaluation/test-cases/:id | 编辑 / 删除用例 |
| POST | /evaluation/runs | 触发评测运行（同步返回结果，已任务化） |
| GET | /evaluation/runs | 历史运行列表（分页 data.items） |
| GET | /evaluation/runs/:id | 运行详情（data 含 run 与 results） |
| GET | /evaluation/reports | 历次指标趋势 + regression_alerts |
5.1 关键机制
- 运行结果结构：
run_id/status/execution_accuracy/exact_match_rate/syntax_validity_rate/passed_cases/total_cases/avg_latency_ms/avg_tokens/results[]（含generated_sql/execution_status/result_match/exact_match/syntax_valid/error）。 POST /evaluation/runs已任务化（V5 Stage 0）：submitAndWaitTask15s 窗口内完成返回完整结果 + task_id，超时返 202{task_id}；前端按同步等待（timeout 120s）。- 回归检测：后端
reports返回regression_alerts（EA/EM/SV 较上次下降 >2% 告警）；前端按时间序比较执行准确率标记「下降」并显示红色横幅。 - 状态/百分比映射：PASSED/SUCCESS/COMPLETED→成功，FAILED/ERROR→失败，PENDING/RUNNING→运行中，SKIPPED→跳过；百分比兼容 0-1 与 0-100。
后端实现：action/products/aip/evaluation/handler.go、service.go（RunEval/SeedTestCases）、server/handlers.go（任务化）。
6. 权限与安全
- 认证与角色：
aip_token+ 管理员；/evaluation/*全部 admin 组，普通用户 403、无 token 401。 - 数据安全：测试用例含期望 SQL 与数据源信息，仅管理员可见。
- 写操作防护：删除用例有 confirm；「运行评测」真实执行 NLQ→SQL 生成与校验，无二次确认。
7. 常见问题与排错
问题 1：点「运行评测」很久后提示「评测运行失败」
原因：评测同步执行超过前端 timeout 120s（用例多/LLM 慢），或后端报错。
处理：减少用例数量；看后端日志定位 RunEval 报错；确认 LLM 网关可用。
问题 2：保存测试用例报「category 必须为 simple_select/join/aggregation/subquery/window 之一」
原因：类别下拉值被清空或传了非法值。
处理：从下拉重新选择类别（默认 simple_select）再保存。
问题 3：导出评测集失败或下载文件无内容
原因：/evaluation/test-cases/export 未返回 items 数组，或浏览器拦截自动下载。
处理：检查 Network 返回结构；放行自动下载；确认管理员权限。
问题 4：回归报告显示「暂无回归数据」
原因：GetReports 只统计 status=completed 的运行记录，历史为空。
处理：先运行一次评测产生 completed 记录；确认 /evaluation/reports 返回非空 items。
8. 已知缺陷与边界
| 项 | 说明 |
|---|---|
| 运行同步等待 | 前端按同步执行处理（timeout 120s），超长评测会失败；任务化 202 分支未轮询 GET /tasks/:id |
| 无用例筛选控件 | 用例接口支持 category/difficulty 过滤参数，页面未暴露筛选 UI |
| 平均延迟 / Tokens | 无耗时数据时显示 '-' |
| 种子用例默认集 | bootstrap 会写入默认评测集，删除后需手动维护 |
注：回归检测读错字段（横幅依赖 payload.regression_detected，后端实际返回 regression_alerts，横幅不显示）已于 2026-09-06 修复（改读 regression_alerts，兼容旧字段）。