# API statystyk i KPI

Synapse udostępnia statystyki tylko do odczytu dotyczące zdrowia agentów, użycia API, trendów i KPI floty. Wszystkie endpointy akceptują MindKey (`Authorization: Bearer`) albo JWT użytkownika (`requireMindOrUser`).

Istniejące trasy analityczne (zob. strona `/stats` w WebUI):

| Trasa | Cel |
| --- | --- |
| `GET /stats/agent` | Przegląd wszystkich agentów (okres: `days`) |
| `GET /stats/agent/comparison` | Porównanie między agentami |
| `GET /stats/agent/:mindName` | Szczegółowe statystyki jednego agenta |
| `GET /stats/agent/:mindName/health` | Wynik zdrowia |
| `GET /stats/agent/:mindName/heatmap` | Mapa cieplna aktywności |
| `GET /stats/agent/:mindName/sessions` | Tracker sesji |
| `GET /stats/api` | Użycie API (globalne) |
| `GET /stats/trends` | Szeregi czasowe |
| `GET /stats/chat/response-times` | Czasy odpowiedzi czatu |
| `GET /stats/a2a/flow` | Przepływ wiadomości A2A |
| `GET /stats/cron` | Analityka cronów |
| `GET /stats/team` · `/stats/backlog` · `/stats/activity` · `/stats/summary` · `/stats/fleet` · `/stats/monitoring` | Agregaty pulpitu |

## GET /export/kpis

Eksport tidy-long operacyjnych KPI (task 7418541b). Źródłem prawdy danych jest `src/db/stats.ts` — warstwa eksportu tylko spłaszcza, sama niczego nie mierzy.

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

| Parametr | Wartości | Domyślnie |
| --- | --- | --- |
| `format` | `csv` · `json` · `xlsx` | `json` |
| `days` | `1`–`365` (okno dla przeglądu agentów) | `7` |

Odpowiedź:

- `format=json` → `{ generated_at, period_days, format: "long", columns, row_count, rows[] }`
- `format=csv` → `text/csv; charset=utf-8` (RFC 4180, BOM, CRLF) jako załącznik
- `format=xlsx` → skoroszyt Excel (jeden arkusz `KPIs`) jako załącznik

Kolumny tidy-long (identyczne we wszystkich formatach):

| Kolumna | Znaczenie |
| --- | --- |
| `kategorie` | Grupa KPI: `fleet`, `summary`, `backlog`, `activity`, `team`, `monitoring`, `agent_overview` |
| `metrik` | Spłaszczona ścieżka metryki (np. `throughput.done_24h_total`) |
| `wert` | Wartość skalarna (liczba, tekst albo `NULL`, gdy tylko `detail` niesie dane) |
| `einheit` | `value` · `count` · `text` · `json` |
| `zeitstempel` | Znacznik czasu generowania eksportu ISO-8601 |
| `quelle` | Funkcja źródłowa w `src/db/stats.ts` |
| `detail` | Ładunek JSON dla tablic/głębokich obiektów, w przeciwnym razie pusty |

Przykład:

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

Strona `/stats` WebUI renderuje ten sam eksport jako trzy przyciski pobierania (CSV/JSON/XLSX) w sekcji „KPI export".