# API di statistiche e KPI

Synapse espone statistiche di sola lettura su salute degli agenti, uso dell'API, tendenze e KPI di flotta. Tutti gli endpoint accettano un MindKey (`Authorization: Bearer`) o un JWT utente (`requireMindOrUser`).

Rotte di analisi esistenti (vedi la pagina `/stats` nella WebUI):

| Rotta | Scopo |
| --- | --- |
| `GET /stats/agent` | Panoramica di tutti gli agenti (periodo: `days`) |
| `GET /stats/agent/comparison` | Confronto tra agenti |
| `GET /stats/agent/:mindName` | Statistiche dettagliate di un agente |
| `GET /stats/agent/:mindName/health` | Punteggio di salute |
| `GET /stats/agent/:mindName/heatmap` | Mappa di calore dell'attività |
| `GET /stats/agent/:mindName/sessions` | Tracciamento delle sessioni |
| `GET /stats/api` | Uso dell'API (globale) |
| `GET /stats/trends` | Serie temporali |
| `GET /stats/chat/response-times` | Tempi di risposta della chat |
| `GET /stats/a2a/flow` | Flusso dei messaggi A2A |
| `GET /stats/cron` | Analitica dei cron |
| `GET /stats/team` · `/stats/backlog` · `/stats/activity` · `/stats/summary` · `/stats/fleet` · `/stats/monitoring` | Aggregati del cruscotto |

## GET /export/kpis

Export tidy-long dei KPI operativi (task 7418541b). La fonte di verità dei dati è `src/db/stats.ts` — il layer di export appiattisce soltanto, non misura nulla da sé.

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

| Parametro | Valori | Predefinito |
| --- | --- | --- |
| `format` | `csv` · `json` · `xlsx` | `json` |
| `days` | `1`–`365` (finestra per la panoramica agenti) | `7` |

Risposta:

- `format=json` → `{ generated_at, period_days, format: "long", columns, row_count, rows[] }`
- `format=csv` → `text/csv; charset=utf-8` (RFC 4180, BOM, CRLF) come allegato
- `format=xlsx` → cartella di lavoro Excel (foglio singolo `KPIs`) come allegato

Colonne tidy-long (identiche in tutti i formati):

| Colonna | Significato |
| --- | --- |
| `kategorie` | Gruppo KPI: `fleet`, `summary`, `backlog`, `activity`, `team`, `monitoring`, `agent_overview` |
| `metrik` | Percorso metrica appiattito (es. `throughput.done_24h_total`) |
| `wert` | Valore scalare (numero, testo o `NULL` quando solo `detail` contiene dati) |
| `einheit` | `value` · `count` · `text` · `json` |
| `zeitstempel` | Timestamp ISO-8601 di generazione dell'export |
| `quelle` | Funzione sorgente in `src/db/stats.ts` |
| `detail` | Payload JSON per array/oggetti profondi, altrimenti vuoto |

Esempio:

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

La pagina `/stats` della WebUI renderizza lo stesso export come tre pulsanti di download (CSV/JSON/XLSX) nella sezione "KPI export".