chore: complete update

2025-07-17 16:24:20 +02:00
parent 899227b0a4
commit 64a7051137
1300 changed files with 85570 additions and 2756 deletions
--- a/docs/framework/analytics/architecture.md
+++ b/docs/framework/analytics/architecture.md
@@ -0,0 +1,102 @@
+# Analytics-Framework: Architektur
+
+## Überblick
+
+Das Analytics-Framework verwendet eine Schichtenarchitektur mit klaren Verantwortlichkeiten:
+
+```
+┌─────────────────────────────────────────────────────┐
+│                 Öffentliche API                      │
+│                  (Analytics)                         │
+└───────────────────────┬─────────────────────────────┘
+                        │
+┌───────────────────────▼─────────────────────────────┐
+│              Event-Verarbeitung                      │
+│             (AnalyticsManager)                       │
+└───────────────────────┬─────────────────────────────┘
+                        │
+         ┌──────────────┴──────────────┐
+         │                             │
+┌────────▼─────────┐         ┌─────────▼────────┐
+│   Middleware     │         │  Storage-Layer   │
+│   (Pipeline)     │         │ (StorageInterface)│
+└──────────────────┘         └──────────────────┘
+```
+
+## Komponenten im Detail
+
+### Analytics (Frontend)
+
+Bietet eine benutzerfreundliche API für Tracking-Operationen. Diese Klasse ist der primäre Einstiegspunkt für Anwendungscode und abstrahiert die Komplexität der Eventverarbeitung.
+
+Verantwortlichkeiten:
+- Bereitstellung der öffentlichen API (`track`, `page`, `user`, `error`)
+- Integration mit dem Event-Dispatcher des Frameworks
+- Typ-Konvertierung zwischen benutzerdefinierten Ereignissen und dem internen Datenformat
+
+### AnalyticsManager (Verarbeitung)
+
+Der Manager ist das Herzstück des Systems und verantwortlich für:
+- Anwendung von Middleware-Transformationen auf Events
+- Eventpufferung für effiziente Speicherung
+- Verwaltung der Konfiguration
+- Steuerung des Storage-Layers
+
+Der Manager implementiert einen Event-Buffer, der Daten sammelt und bei Erreichen einer konfigurierbaren Größe automatisch speichert.
+
+### Middleware-System
+
+Eine Kette von Verarbeitungsfunktionen, die auf jedes Event angewendet werden:
+- Datenfilterung und -transformation
+- Anonymisierung persönlicher Daten
+- Validierung und Anreicherung von Events
+
+Jede Middleware kann Events modifizieren oder komplett verwerfen.
+
+### Storage-Layer
+
+Abstraktion für verschiedene Speichermethoden durch das `StorageInterface`:
+
+```php
+interface StorageInterface
+{
+    public function store(array $events): void;
+    public function retrieve(array $filters = []): array;
+    public function clear(): void;
+}
+```
+
+Implementierungen:
+- `FileStorage`: Speichert Events in JSON-Dateien mit täglicher Rotation
+- Erweiterbar für andere Backends (Datenbank, Redis, etc.)
+
+### HTTP-Integration
+
+`AnalyticsMiddleware` integriert Analytics in den HTTP-Request-Lifecycle:
+- Tracking von eingehenden Requests
+- Erfassung von Antwortzeiten und Statuscodes
+- Fehlererfassung bei Exceptions
+
+### Admin-Dashboard
+
+`AnalyticsDashboard` und `AdminAnalyticsController` bieten:
+- Datenaggregation und -analyse
+- Visualisierung von Metriken
+- Filterung nach Zeiträumen
+- Verschiedene spezialisierte Ansichten (Seiten, Fehler, Performance)
+
+## Datenfluss
+
+1. Event wird durch `Analytics::track()` oder ähnliche Methoden erstellt
+2. `AnalyticsManager` wendet Middleware-Pipeline an
+3. Event wird zum Buffer hinzugefügt
+4. Bei Buffer-Füllung oder explizitem `flush()` werden Events an Storage übergeben
+5. Storage speichert Events im konfigurierten Backend
+6. `AnalyticsDashboard` ruft Daten bei Bedarf vom Storage ab und aggregiert sie
+
+## Erweiterungspunkte
+
+- **Storage-Provider**: Neue Implementierungen von `StorageInterface`
+- **Middleware**: Funktionen für Filterung/Transformation
+- **Event-Typen**: Spezialisierte Event-Klassen für typsicheres Tracking
+- **Dashboard-Views**: Zusätzliche Visualisierungen und Berichte