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/README.md
+++ b/docs/framework/analytics/README.md
@@ -0,0 +1,158 @@
+# Analytics-Modul Dokumentation
+
+## Übersicht
+
+Das Analytics-Modul ist ein internes Tracking- und Analysesystem, das ohne externe Abhängigkeiten Benutzeraktivitäten, Systemereignisse und Leistungsdaten erfasst und analysiert.
+
+## Kernkomponenten
+
+### Analytics (Analytics.php)
+
+Die Hauptklasse, die als zentraler Einstiegspunkt für das Tracking von Events dient.
+
+**Hauptfunktionen:**
+- `track()`: Zeichnet ein generisches Event auf
+- `page()`: Spezifisch für Seitenaufrufe
+- `user()`: Verfolgt Benutzeridentifikation
+- `performance()`: Erfasst Leistungsmetriken
+- `error()`: Protokolliert Fehler und Ausnahmen
+
+### AnalyticsManager (AnalyticsManager.php)
+
+Verwaltet die Verarbeitung und Speicherung von Events.
+
+**Hauptfunktionen:**
+- `track()`: Verarbeitet Events und wendet Middleware an
+- `addMiddleware()`: Fügt Verarbeitungsfunktionen hinzu
+- `flush()`: Schreibt gepufferte Events in den Speicher
+
+### StorageInterface und FileStorage
+
+Das Interface definiert die Speichermethoden, FileStorage implementiert die Speicherung in Dateien.
+
+**Hauptoperationen:**
+- `store()`: Speichert Events
+- `retrieve()`: Ruft Events mit Filtern ab
+- `clear()`: Löscht alle gespeicherten Daten
+
+### AnalyticsInitializer (AnalyticsInitializer.php)
+
+Konfiguriert und initialisiert den Analytics-Service beim Anwendungsstart.
+
+**Konfigurationsoptionen:**
+- Aktivierung/Deaktivierung
+- Auto-Flush und Batch-Größe
+- Storage-Typ und Pfad
+
+### AnalyticsMiddleware (AnalyticsMiddleware.php)
+
+HTTP-Middleware zum automatischen Tracking von Requests und Responses.
+
+### AnalyticsDashboard (AnalyticsDashboard.php)
+
+Stellt Methoden für Datenanalyse und -aggregation bereit:
+- `getEventStats()`: Ereignisstatistiken
+- `getTopPages()`: Meistbesuchte Seiten
+- `getUserStats()`: Benutzerstatistiken
+- `getErrorStats()`: Fehlerstatistiken
+- `getPerformanceStats()`: Leistungsmetriken
+
+### Events
+
+Vordefinierte Event-Typen:
+- `AnalyticsEvent`: Basis-Event-Klasse
+- `PageViewEvent`: Speziell für Seitenaufrufe
+
+### Controllers
+
+`AdminAnalyticsController`: Stellt das Admin-Dashboard bereit mit:
+- Übersichtsseite
+- Seitenstatistiken
+- Fehlerstatistiken
+- Leistungsstatistiken
+
+### Console
+
+`AnalyticsClearCommand`: Konsolenbefehl zum Löschen von Analytics-Daten.
+
+## Konfiguration
+
+Die Konfiguration erfolgt in `src/Config/analytics.php` mit folgenden Optionen:
+
+```php
+return [
+    'enabled' => true,           // Aktiviert/deaktiviert das Tracking
+    'auto_flush' => true,         // Automatisches Speichern nach Batch-Größe
+    'batch_size' => 50,           // Anzahl Events pro Batch
+    'storage' => 'file',          // Storage-Backend
+    'storage_path' => '...',      // Speicherpfad
+    'anonymize_ip' => true,       // IP-Anonymisierung
+    'track_events' => [...]       // Zu trackende Events
+];
+```
+
+## Verwendung
+
+### Basis-Tracking
+
+```php
+// Event tracken
+$analytics->track('button_click', ['button' => 'signup']);
+
+// Seitenaufruf tracken
+$analytics->page('/dashboard', ['section' => 'analytics']);
+
+// Benutzer identifizieren
+$analytics->user('user123', ['plan' => 'premium']);
+```
+
+### Middleware einrichten
+
+```php
+$this->addMiddleware(App\Framework\Analytics\AnalyticsMiddleware::class);
+```
+
+### Eigene Middleware hinzufügen
+
+```php
+$analyticsManager->addMiddleware(function(array $event) {
+    // Daten verarbeiten oder filtern
+    return $event;
+});
+```
+
+## Datenschutz
+
+Das System bietet integrierte Funktionen zur Anonymisierung personenbezogener Daten:
+- IP-Adressen-Anonymisierung (letztes Oktett wird entfernt)
+- Konfigurierbare Filterung sensibler Daten durch Middleware
+
+## Erweiterbarkeit
+
+### Eigene Storage-Provider
+
+Implementieren Sie das `StorageInterface` für benutzerdefinierte Speicherlösungen:
+
+```php
+class CustomStorage implements StorageInterface
+{
+    public function store(array $events): void { /* ... */ }
+    public function retrieve(array $filters = []): array { /* ... */ }
+    public function clear(): void { /* ... */ }
+}
+```
+
+### Event-Typen erweitern
+
+Erstellen Sie benutzerdefinierte Event-Klassen, die von `AnalyticsEvent` erben:
+
+```php
+class CustomEvent extends AnalyticsEvent
+{
+    public function __construct(string $customData, array $additionalProps = [])
+    {
+        parent::__construct('custom_event', 
+            array_merge(['custom_data' => $customData], $additionalProps));
+    }
+}
+```