# API thống kê & KPI

Synapse cung cấp số liệu thống kê chỉ đọc về sức khỏe tác nhân, mức sử dụng API, xu hướng và KPI đội xe. Tất cả endpoint chấp nhận MindKey (`Authorization: Bearer`) hoặc JWT người dùng (`requireMindOrUser`).

Các tuyến phân tích hiện có (xem trang `/stats` trong WebUI):

| Tuyến | Mục đích |
| --- | --- |
| `GET /stats/agent` | Tổng quan tất cả tác nhân (khoảng: `days`) |
| `GET /stats/agent/comparison` | So sánh giữa các tác nhân |
| `GET /stats/agent/:mindName` | Thống kê chi tiết của một tác nhân |
| `GET /stats/agent/:mindName/health` | Điểm sức khỏe |
| `GET /stats/agent/:mindName/heatmap` | Bản đồ nhiệt hoạt động |
| `GET /stats/agent/:mindName/sessions` | Trình theo dõi phiên |
| `GET /stats/api` | Mức sử dụng API (toàn cục) |
| `GET /stats/trends` | Chuỗi thời gian |
| `GET /stats/chat/response-times` | Thời gian phản hồi chat |
| `GET /stats/a2a/flow` | Dòng tin nhắn A2A |
| `GET /stats/cron` | Phân tích cron |
| `GET /stats/team` · `/stats/backlog` · `/stats/activity` · `/stats/summary` · `/stats/fleet` · `/stats/monitoring` | Tập hợp bảng điều khiển |

## GET /export/kpis

Xuất KPI vận hành dạng tidy-long (task 7418541b). Nguồn chân lý dữ liệu là `src/db/stats.ts` — lớp xuất chỉ làm phẳng, tự nó không đo đếm gì.

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

| Tham số | Giá trị | Mặc định |
| --- | --- | --- |
| `format` | `csv` · `json` · `xlsx` | `json` |
| `days` | `1`–`365` (cửa sổ cho tổng quan tác nhân) | `7` |

Phản hồi:

- `format=json` → `{ generated_at, period_days, format: "long", columns, row_count, rows[] }`
- `format=csv` → `text/csv; charset=utf-8` (RFC 4180, BOM, CRLF) dạng tệp đính kèm
- `format=xlsx` → Sổ làm việc Excel (một trang tính `KPIs`) dạng tệp đính kèm

Các cột tidy-long (giống nhau trong mọi định dạng):

| Cột | Ý nghĩa |
| --- | --- |
| `kategorie` | Nhóm KPI: `fleet`, `summary`, `backlog`, `activity`, `team`, `monitoring`, `agent_overview` |
| `metrik` | Đường dẫn chỉ số đã làm phẳng (vd. `throughput.done_24h_total`) |
| `wert` | Giá trị vô hướng (số, văn bản hoặc `NULL` khi chỉ `detail` mang dữ liệu) |
| `einheit` | `value` · `count` · `text` · `json` |
| `zeitstempel` | Dấu thời gian tạo bản xuất ISO-8601 |
| `quelle` | Hàm nguồn trong `src/db/stats.ts` |
| `detail` | Tải JSON cho mảng/đối tượng sâu, ngược lại rỗng |

Ví dụ:

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

Trang `/stats` của WebUI hiển thị cùng bản xuất dưới dạng ba nút tải về (CSV/JSON/XLSX) trong mục «KPI export».