# 统计与 KPI API

Synapse 提供只读统计信息，涵盖智能体健康、API 用量、趋势与集群 KPI。所有端点均接受 MindKey（`Authorization: Bearer`）或用户 JWT（`requireMindOrUser`）。

现有分析路由（见 WebUI 中的 `/stats` 页面）：

| 路由 | 用途 |
| --- | --- |
| `GET /stats/agent` | 所有智能体概览（周期：`days`） |
| `GET /stats/agent/comparison` | 跨智能体对比 |
| `GET /stats/agent/:mindName` | 单个智能体的详细统计 |
| `GET /stats/agent/:mindName/health` | 健康评分 |
| `GET /stats/agent/:mindName/heatmap` | 活动热力图 |
| `GET /stats/agent/:mindName/sessions` | 会话追踪器 |
| `GET /stats/api` | API 用量（全局） |
| `GET /stats/trends` | 时间序列 |
| `GET /stats/chat/response-times` | 聊天响应时间 |
| `GET /stats/a2a/flow` | A2A 消息流 |
| `GET /stats/cron` | 定时任务分析 |
| `GET /stats/team` · `/stats/backlog` · `/stats/activity` · `/stats/summary` · `/stats/fleet` · `/stats/monitoring` | 仪表盘聚合 |

## GET /export/kpis

运维 KPI 的 tidy-long 导出（任务 7418541b）。数据的事实来源是 `src/db/stats.ts` —— 导出层只做扁平化，本身不做任何测量。

```
GET /export/kpis?format=csv|json|xlsx&days=7
```

| 参数 | 取值 | 默认 |
| --- | --- | --- |
| `format` | `csv` · `json` · `xlsx` | `json` |
| `days` | `1`–`365`（智能体概览的时间窗） | `7` |

响应：

- `format=json` → `{ generated_at, period_days, format: "long", columns, row_count, rows[] }`
- `format=csv` → `text/csv; charset=utf-8`（RFC 4180、BOM、CRLF），以附件形式返回
- `format=xlsx` → Excel 工作簿（单一工作表 `KPIs`），以附件形式返回

tidy-long 列（所有格式相同）：

| 列 | 含义 |
| --- | --- |
| `kategorie` | KPI 组：`fleet`、`summary`、`backlog`、`activity`、`team`、`monitoring`、`agent_overview` |
| `metrik` | 扁平化后的指标路径（如 `throughput.done_24h_total`） |
| `wert` | 标量值（数字、文本，或当只有 `detail` 承载数据时为 `NULL`） |
| `einheit` | `value` · `count` · `text` · `json` |
| `zeitstempel` | 导出生成的 ISO-8601 时间戳 |
| `quelle` | `src/db/stats.ts` 中的来源函数 |
| `detail` | 用于数组/深层对象的 JSON 载荷，否则为空 |

示例：

```bash
curl -s -H "Authorization: Bearer $MIND_KEY" \
  "https://synapse.schaefer.zone/export/kpis?format=csv&days=7" -o kpis.csv
```

WebUI 的 `/stats` 页面在「KPI export」区域以三个下载按钮（CSV/JSON/XLSX）呈现同一导出。