# Lilian Labs Integration - Dokumentation

## Übersicht

Die Lilian Labs Integration ermöglicht das automatische Abrufen und Speichern von Wassermessungsdaten aus der Lilian Labs API.

## Features

✅ **Token-Verwaltung** - Access Token im Admin-Bereich hinterlegen  
✅ **Automatische Synchronisation** - Messungen automatisch abrufen  
✅ **Token-Überwachung** - Warnung bei baldiger Token-Ablauf  
✅ **Daten-Visualisierung** - Übersichtliche Darstellung der Messwerte  
✅ **Multi-Location** - Unterstützung mehrerer Standorte  
✅ **Duplikat-Schutz** - Verhindert doppelte Messungen (konfigurierbar)  
✅ **Konfigurierbarer Zeitbereich** - Wählbar: 7-365 Tage  
✅ **Intelligente Synchronisation** - Nutzt konfigurierte Einstellungen  

---

## Installation & Einrichtung

### 1. Datenbank wurde bereits migriert ✅

Die Migration wurde erfolgreich ausgeführt. Folgende Tabellen wurden erstellt:
- `lilian_labs_config` - Speichert API-Konfiguration und Token
- `water_measurement` - Speichert alle Wassermessungen

### 2. Access Token hinterlegen

#### Token von Lilian Labs holen:

1. Auf [app.lilianlabs.com](https://app.lilianlabs.com) einloggen (mit 2FA)
2. Browser-Konsole öffnen (F12 → Console)
3. Folgenden Code ausführen:
   ```javascript
   localStorage.getItem('accessToken')
   ```
4. Token kopieren

#### Token in Symfony hinterlegen:

1. Im Admin-Bereich zu **"Lilian Labs"** navigieren
2. Auf **"Konfiguration"** klicken
3. Token einfügen
4. **Speichern** - Token-Ablaufdatum wird automatisch ermittelt

### 3. Point-IDs und Zeitbereich konfigurieren

Die Standard-Point-IDs sind bereits vorkonfiguriert:

```json
{
  "Messgerät 1 Beckenrand": "68ecd1bfbfea6700191d6ac3",
  "Messgerät 1 Messeinheit": "68ecda61bfea6700191dd240",
  "Messgerät 2 Beckenrand": "68ecd233bfea6700191d710b",
  "Messgerät 2 Messeinheit": "68ecd9e5bfea6700191dccd4",
  "Messgerät 3 Beckenrand": "68ecd1cfbfea6700191d6b64",
  "Messgerät 3 Messeinheit": "68ecd9febfea6700191dce38"
}
```

**Zeitbereich einstellen:**
- Standard: Letzte 30 Tage
- Wählbar: 7, 14, 30, 60, 90, 180 oder 365 Tage
- Bestimmt, wie weit zurück Messungen abgerufen werden

**Duplikat-Schutz:**
- ✅ **Aktiviert (empfohlen):** Verhindert doppelte Messungen
- ❌ **Deaktiviert:** Alle Messungen werden importiert (kann zu Duplikaten führen)

---

## Verwendung

### Admin-Oberfläche

**Zugriff:** `/admin/lilian-labs`

#### Dashboard
- **Übersicht** über alle Statistiken
- **Token-Status** mit Warnung bei baldiger Ablauf
- **Schnellaktionen:**
  - Daten synchronisieren
  - Token prüfen
  - Konfiguration bearbeiten
  - Messungen anzeigen

#### Konfiguration (`/admin/lilian-labs/config`)
- Access Token verwalten
- Point-IDs bearbeiten
- Integration aktivieren/deaktivieren
- Token-Status einsehen

#### Messungen (`/admin/lilian-labs/measurements`)
- Alle Messungen tabellarisch
- Filterung nach Standort
- Farbliche Hervorhebung kritischer Werte
- Paginierung für große Datenmengen

---

## Console Commands

### Daten manuell abrufen

```bash
php bin/console lilian-labs:fetch-data
```

**Optionen:**
- `--days=30` - Anzahl Tage rückwirkend (Standard: 30)

**Beispiele:**
```bash
# Letzte 30 Tage (Standard)
php bin/console lilian-labs:fetch-data

# Letzte 7 Tage
php bin/console lilian-labs:fetch-data --days=7

# Letzte 90 Tage
php bin/console lilian-labs:fetch-data --days=90
```

### Automatisierung mit Cron

Füge folgende Zeile zu deinen Cron-Jobs hinzu:

```bash
# Täglich um 6:00 Uhr Messungen abrufen
0 6 * * * cd /pfad/zu/projekt && php bin/console lilian-labs:fetch-data >> /var/log/lilian-labs-sync.log 2>&1
```

**Empfohlene Intervalle:**
- **Täglich:** Für normale Überwachung ausreichend
- **Mehrmals täglich:** Bei kritischer Überwachung
- **Wöchentlich:** Für historische Datenanalyse

---

## API-Service

Der `LilianLabsApiService` bietet folgende Methoden:

### `checkTokenValidity(string $token): array`
Prüft Token-Gültigkeit und holt Ablaufdatum.

```php
$result = $this->apiService->checkTokenValidity($token);
// ['valid' => true, 'sessionExpiresAt' => DateTime, 'user' => [...]]
```

### `fetchPointData(string $pointId, string $token, DateTime $dateStart, DateTime $dateEnd): array`
Holt Messdaten für einen spezifischen Point.

### `syncAllPoints(?int $daysBack = 30): array`
Synchronisiert alle konfigurierten Points.

```php
$stats = $this->apiService->syncAllPoints(30);
// ['success' => 5, 'errors' => 0, 'new_measurements' => 150, ...]
```

### `updateTokenExpiry(LilianLabsConfig $config): bool`
Aktualisiert das Token-Ablaufdatum.

---

## Datenbank-Struktur

### Tabelle: `lilian_labs_config`

| Feld | Typ | Beschreibung |
|------|-----|-------------|
| id | INT | Primary Key |
| access_token | VARCHAR(500) | Lilian Labs Access Token |
| token_expiry | DATETIME | Token-Ablaufdatum |
| last_sync | DATETIME | Letzte Synchronisation |
| point_ids | JSON | Konfigurierte Point-IDs |
| active | BOOLEAN | Integration aktiv? |
| last_error | TEXT | Letzter Fehler (falls vorhanden) |
| sync_days_back | INT | Zeitbereich in Tagen (Standard: 30) |
| prevent_duplicates | BOOLEAN | Duplikat-Schutz aktiv? (Standard: true) |
| created_at | DATETIME | Erstellungsdatum |
| updated_at | DATETIME | Letzte Änderung |

### Tabelle: `water_measurement`

| Feld | Typ | Beschreibung |
|------|-----|-------------|
| id | INT | Primary Key |
| location | VARCHAR(255) | Standort |
| point_name | VARCHAR(255) | Messpunkt-Name |
| measured_by | VARCHAR(255) | Messender Mitarbeiter |
| measured_at | DATETIME | Messzeitpunkt |
| ph | DECIMAL(5,2) | pH-Wert |
| chlorine_free | DECIMAL(5,2) | Freies Chlor |
| chlorine_total | DECIMAL(5,2) | Gesamtchlor |
| chlorine_combined | DECIMAL(5,2) | Gebundenes Chlor |
| ks43 | DECIMAL(5,2) | KS4.3-Wert |
| point_id | VARCHAR(100) | Lilian Labs Point-ID |
| imported_at | DATETIME | Import-Zeitpunkt |

**Index:** `idx_water_measurement_location_point_measured` auf (location, point_name, measured_at)

---

## Token-Verwaltung

### Token-Lebensdauer
- **Typisch:** 18-30 Tage
- **Automatische Prüfung** beim Speichern
- **Warnung** 7 Tage vor Ablauf

### Token erneuern

**WICHTIG:** Wegen aktiviertem 2FA ist keine automatische Token-Erneuerung möglich!

**Manuelle Erneuerung:**
1. Token-Warnung im Dashboard beachten
2. Auf Lilian Labs einloggen (mit 2FA)
3. Neues Token aus Browser-Console kopieren
4. In Admin-Konfiguration einfügen und speichern

**Token-Prüfung:**
- Im Dashboard auf "Token prüfen" klicken
- Zeigt Gültigkeit und verbleibende Tage an

---

## Fehlerbehandlung

### Häufige Fehler und Lösungen

#### "Token abgelaufen"
**Lösung:** Neues Token hinterlegen (siehe Token-Verwaltung)

#### "Keine aktive Konfiguration gefunden"
**Lösung:** Integration in Konfiguration aktivieren

#### "API returned status 404"
**Lösung:** Point-ID überprüfen - möglicherweise falsch oder gelöscht

#### "Measurement exists" (keine Fehler, nur Info)
**Lösung:** Messung bereits vorhanden - wird automatisch übersprungen

### Logs

Alle Fehler werden geloggt und sind einsehbar:
- **Symfony Logs:** `var/log/prod.log` oder `var/log/dev.log`
- **Console Output:** Bei manueller Command-Ausführung
- **Last Error:** Im Dashboard/Konfiguration sichtbar

---

## Messwert-Bewertung

Die Tabelle zeigt Messwerte farblich codiert:

### pH-Wert
- 🟢 **Gut:** 7.0 - 7.6
- 🟡 **Warnung:** < 7.0 oder > 7.6

### Freies Chlor
- 🟢 **Gut:** 0.3 - 0.6 mg/l
- 🟡 **Warnung:** < 0.3 oder > 0.6 mg/l

### Gebundenes Chlor
- 🟢 **Gut:** ≤ 0.2 mg/l
- 🟡 **Warnung:** > 0.2 mg/l

---

## Performance

### Optimierungen
- **Duplikat-Check:** Verhindert doppelte Einträge (konfigurierbar)
- **Batch-Processing:** Mehrere Points in einem Durchlauf
- **Index:** Schnelle Suche nach Location/Point/Datum
- **Paginierung:** Effiziente Darstellung großer Datenmengen
- **Intelligente Zeitbereichs-Steuerung:** Nutzt konfigurierte Einstellungen

### Empfohlene Einstellungen
- **Sync-Intervall:** Täglich ausreichend
- **Zeitbereich (Days-Back):** 
  - 7-14 Tage: Für regelmäßige tägliche Synchronisation
  - 30 Tage: Für wöchentliche Synchronisation (Standard)
  - 60-90 Tage: Für monatliche Synchronisation oder Ersteinrichtung
- **Duplikat-Schutz:** Aktiviert (empfohlen)
- **Batch-Size:** Alle Points in einem Durchlauf

---

## Sicherheit

✅ **ROLE_ADMIN erforderlich** - Nur Admins haben Zugriff  
✅ **Token verschlüsselt** - Sollte zusätzlich über Secrets verwaltet werden  
✅ **2FA unterstützt** - Token muss manuell erneuert werden  
✅ **Input-Validierung** - JSON-Format wird geprüft  
✅ **CSRF-Schutz** - Symfony-Standard  

**Empfehlung:** Token als Umgebungsvariable statt in Datenbank speichern:
```yaml
# config/services.yaml
parameters:
    lilian_labs.token: '%env(LILIAN_LABS_TOKEN)%'
```

---

## Troubleshooting

### Dashboard zeigt keine Daten
1. Konfiguration vorhanden? → `/admin/lilian-labs/config`
2. Integration aktiv? → Konfiguration prüfen
3. Token gültig? → "Token prüfen" klicken
4. Synchronisation durchgeführt? → "Daten synchronisieren" klicken

### Synchronisation schlägt fehl
1. **Logs prüfen:** `var/log/prod.log`
2. **Token prüfen:** Möglicherweise abgelaufen
3. **Point-IDs prüfen:** Korrekte IDs konfiguriert?
4. **Netzwerk:** Verbindung zu api.lilianlabs.com möglich?

### Token läuft zu oft ab
- **Normal:** 18-30 Tage Gültigkeit
- **Lösung:** Reminder-Service einrichten
- **Alternative:** Support nach API-Keys fragen

---

## Erweiterungsmöglichkeiten

### Geplante Features
- 📊 Grafische Auswertung (Charts)
- 📧 E-Mail-Benachrichtigung bei kritischen Werten
- 📱 Push-Benachrichtigungen
- 📈 Trend-Analysen
- 🔄 Automatische Reports
- 💾 Export-Funktionen (CSV, Excel)

### Anpassungen
- **Messwert-Schwellwerte:** In `measurements.html.twig` anpassbar
- **Point-IDs:** Über Admin-Interface verwaltbar
- **Sync-Intervall:** Via Cron-Job konfigurierbar
- **Standorte:** Automatisch aus API erkannt

---

## Support & Kontakt

**Lilian Labs API:**
- Website: [lilianlabs.com](https://lilianlabs.com)
- Support: [lilianlabs.com/service](https://lilianlabs.com/service)

**Fragen zur Integration:**
- Bei Token-Problemen → Lilian Labs Support kontaktieren
- Bei technischen Problemen → Logs prüfen

---

## Changelog

### Version 1.1.0 (26.11.2025)
- ✅ **Konfigurierbarer Zeitbereich** - Wählbar zwischen 7-365 Tagen
- ✅ **Duplikat-Schutz konfigurierbar** - Kann aktiviert/deaktiviert werden
- ✅ **Intelligente Synchronisation** - Nutzt konfigurierte Werte automatisch
- ✅ **Verbessertes Logging** - Detaillierte Ausgabe bei Duplikaten
- ✅ **UI-Verbesserungen** - Zeitbereich im Dashboard sichtbar

### Version 1.0.0 (26.11.2025)
- ✅ Initiales Release
- ✅ Token-Verwaltung
- ✅ Automatische Synchronisation
- ✅ Admin-Dashboard
- ✅ Messungen-Übersicht
- ✅ Console Command
- ✅ Duplikat-Schutz (fest aktiviert)