API 耗时统计

配图占位：本节用于在后续视觉评审中插入「API 耗时统计」整体视觉截图（玻璃面板、时序图 SVG、Top10 列表、5xx 错误分组）。

用途

本页面介绍 /admin/api-timing-stats 路由——管理员对全平台 API 耗时进行时段聚合的视图。设计稿见 .design/dramagon-redesign/pages/admin-api-timing-stats.html。

页面包含 4 段能力：

• 趋势图：P50 / P95 / P99 在选定时间窗内的 30 个桶的时序图（SVG）
• Top10 慢路由：按 P95 倒序的 Top10 慢路由 + 命中数
• 5xx 错误聚合：按 (status, route) 分组计数 Top5
• 时间窗切换：1h（6 桶）/ 24h（30 桶）/ 7d（42 桶），自动 60s 刷新

使用前准备

• 仅管理员账号可见；登录态与会话由 AdminGuard 守护。
• 后端依赖：/api/admin/api-timing/stats?range=1h|24h|7d
• 数据源：ApiTimingSample 模型（observer 写入）+ Prisma $queryRaw percentile_cont 聚合

操作步骤

趋势图

1. 进入页面，默认 24h 时间窗：30 个等宽桶（每桶约 48 分钟）。
2. 三条折线 P50（蓝）/ P95（紫）/ P99（红），缺数据桶填 0。
3. 切换 1h → 6 桶（约 10 分钟 / 桶）；切换 7d → 42 桶（每桶约 4 小时）。
4. 鼠标 hover 节点：tooltip 显示该桶的 P50 / P95 / P99 数值（待后续 polish 落地）。

Top10

1. 按 P95 耗时倒序展示 Top10 慢路由，每条带命中数。
2. 数字格式：P95 单位 ms（>1000 自动转 s），命中数 ≥ 1k 自动转 k。
3. 空数据时显示 EmptyState（apiTimingStats.empty i18n）。

5xx 错误聚合

1. 仅展示 status >= 400 的错误样本，按 (status, route) 分组计数 Top5。
2. 列表上方展示聚合摘要：当前窗口错误总数 + 错误率（= 错误数 / 总请求数）。
3. yesterdayDelta 展示当前窗口错误数与上一窗口的差值 + tone（up / down / flat）。

时间窗

1. 顶部 chip 切换时间窗：触发新的 percentile_cont 聚合查询。
2. 页面每 60s 自动重新拉取，切换时间窗时立即重置 interval。
3. 非法 range（如 99h）走默认 24h。

数据契约

• 响应：/api/admin/api-timing/stats 返回

  {
    range: '1h' | '24h' | '7d',
    ts: ISO 字符串,
    kpi: { p50Ms, p95Ms, p99Ms, p50Trend, p95Trend, p99Trend, totalRequests, uniqueRoutes, routeCoveragePct },
    trend: Array<{ bucketStart, p50, p95, p99 }>,
    top: Array<{ route, p95Ms, hits }>,
    errors: Array<{ status, route, count }>,
    totalErrors: number,
    errorRate: number,
    yesterdayDelta: { totalErrors, tone: 'up'|'down'|'flat' }
  }

• Trend 数组长度：1h→6 / 24h→30 / 7d→42。
• KPI 各百分位单位 ms（整数，四舍五入）。