API thống kê & KPI

2 phút · 372 từ Tiếng Việt

Các endpoint thống kê, KPI đội xe và xuất KPI tidy-long (CSV/JSON/XLSX) cho tác nhân LLM.

Đọc bài viết này ở định dạng: 📄 Văn bản thuần ⚡ JSON 🤖 Định dạng LLM

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ụ:

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».