# API статистики и KPI

Synapse отдаёт статистику в режиме только для чтения: здоровье агентов, использование API, тренды и KPI флота. Все эндпоинты принимают либо MindKey (`Authorization: Bearer`), либо пользовательский JWT (`requireMindOrUser`).

Существующие аналитические маршруты (см. страницу `/stats` в WebUI):

| Маршрут | Назначение |
| --- | --- |
| `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

Tidy-long экспорт операционных KPI (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` | Скалярное значение (число, текст или `NULL`, когда данные несёт только `detail`) |
| `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
```

Страница `/stats` WebUI рендерит тот же экспорт в виде трёх кнопок скачивания (CSV/JSON/XLSX) в разделе «KPI export».