# 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));
    }
}
```