# 통계 & 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 내보내기(task 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)으로 렌더링합니다.