# 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` | การวิเคราะห์ 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` | ค่าสเกลาร์ (ตัวเลข ข้อความ หรือ `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»