# واجهة الإحصاءات ومؤشرات الأداء

تعرض Synapse إحصاءات للقراءة فقط عن صحة الوكلاء، واستخدام الواجهة البرمجية، والاتجاهات الزمنية، ومؤشرات أداء الأسطول. تقبل جميع نقاط النهاية إما MindKey (`Authorization: Bearer`) أو JWT للمستخدم (`requireMindOrUser`).

مسارات التحليلات الموجودة (انظر صفحة `/stats` في واجهة الويب):

| المسار | الغرض |
| --- | --- |
| `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` | استخدام الواجهة البرمجية (عالمي) |
| `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 (المهمة 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` | مجموعة المؤشر: `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` في واجهة الويب التصدير نفسه كثلاثة أزرار تنزيل (CSV/JSON/XLSX) في قسم «KPI export».