# Steckdosenschaltzeiten System

## Übersicht

Das Steckdosenschaltzeiten-System ermöglicht Administratoren eine detaillierte Kalenderübersicht aller Schaltungen der Smart Plug Steckdosen (TAPO). Das System protokolliert automatisch:

- **Verbindungsstatus**: Wann eine Steckdose vom Strom getrennt war
- **Schaltzustände**: Wann eine Steckdose ein- oder ausgeschaltet war  
- **Systemereignisse**: Automatische Checks, manuelle Änderungen, API-Zugriffe
- **Performance-Daten**: Antwortzeiten, Energieverbrauch, Firmware-Versionen

## Funktionen

### 📅 Kalenderansicht mit FullCalendar
- Moderne FullCalendar-Integration mit deutscher Lokalisierung
- Monat-, Wochen- und Tages-Ansichten
- Farbkodierte Events basierend auf Schaltungsstatus
- Interaktive Event-Details mit detaillierten Informationen

### 🔌 Automatisches Logging
- Kontinuierliche Überwachung aller registrierten Steckdosen
- Automatische Protokollierung bei Statusänderungen
- Integration in das bestehende Drucker-Monitor-System

### 📊 Administrator-Dashboard  
- Dedizierte Übersicht unter `/admin/steckdosenschaltzeiten`
- Verlinkt über Footer (nur für Administratoren sichtbar)
- Echtzeit-Statistiken mit modernen Karten-Design

### 🔍 Erweiterte Filterung
- Filter nach Drucker im Kalender
- Verschiedene Ansichtsmodi (Monat/Woche/Tag)
- Legende für bessere Übersichtlichkeit

### 🧹 Automatische Bereinigung
- Konfigurierbare Löschung alter Logs
- Performance-Optimierung durch Cache-Management
- Datenschutz-konforme Datenhaltung

## Kalender-Features

### Farbkodierung
- **🟢 Grün**: Steckdose EIN (Status: `on`)
- **🔴 Orange**: Steckdose AUS (Status: `off`)
- **🔌 Blau**: Verbunden (Status: `connected`)
- **❌ Rot**: Getrennt (Status: `disconnected`)

### Event-Details
Beim Klick auf ein Kalenderereignis werden folgende Details angezeigt:
- Zeitpunkt der Schaltung
- Drucker-Name
- Status und Quelle der Änderung
- Benutzer (bei manueller Schaltung)
- Technische Daten (Antwortzeit, Verbrauch, Spannung, Strom)
- Notizen und Fehlermeldungen

### Ansichtsmodi
- **Monatsansicht**: Übersicht aller Schaltungen im Monat
- **Wochenansicht**: Detaillierte Tageszeiten sichtbar
- **Tagesansicht**: Stündliche Aufschlüsselung

## Datenbankmodell

### PlugStatusLog
```python
- id (Primary Key)
- printer_id (Foreign Key -> Printer)
- status (String): 'connected', 'disconnected', 'on', 'off'
- timestamp (DateTime): Zeitpunkt der Statusänderung
- ip_address (String): IP der Steckdose
- power_consumption (Float): Stromverbrauch in Watt
- voltage (Float): Spannung in Volt  
- current (Float): Stromstärke in Ampere
- source (String): 'system', 'manual', 'api', 'scheduler'
- user_id (Foreign Key -> User): Bei manueller Änderung
- notes (Text): Zusätzliche Notizen
- response_time_ms (Integer): Antwortzeit in Millisekunden
- error_message (Text): Fehlermeldung bei Problemen
- firmware_version (String): Firmware-Version der Steckdose
```

## API-Endpunkte

### Kalender-Daten abrufen
```
GET /api/admin/plug-schedules/calendar
Parameter:
- start (required): Start-Datum im ISO-Format
- end (required): End-Datum im ISO-Format
- printer_id (optional): Filter nach Drucker
```

### Logs abrufen
```
GET /api/admin/plug-schedules/logs
Parameter:
- printer_id (optional): Filter nach Drucker
- status (optional): Filter nach Status
- hours (optional): Zeitraum in Stunden (Standard: 24)
- page (optional): Seite für Paginierung
- per_page (optional): Einträge pro Seite
```

### Statistiken abrufen
```
GET /api/admin/plug-schedules/statistics
Parameter:
- hours (optional): Zeitraum in Stunden (Standard: 24)
```

### Alte Logs bereinigen
```
POST /api/admin/plug-schedules/cleanup
Body:
{
  "days": 30  // Logs älter als X Tage löschen
}
```

## Integration

### Printer Monitor Integration
Das System ist vollständig in das bestehende `printer_monitor.py` integriert:

- `_check_outlet_status()`: Loggt jeden Status-Check
- `_turn_outlet_off()`: Loggt Schaltbefehle
- `initialize_all_outlets_on_startup()`: Loggt Startup-Initialisierung

### Automatisches Logging
```python
# Beispiel: Status-Änderung loggen
PlugStatusLog.log_status_change(
    printer_id=1,
    status="on",
    source="manual",
    user_id=current_user.id,
    ip_address="192.168.1.100",
    response_time_ms=250,
    notes="Manuell eingeschaltet über Admin-Panel"
)
```

## Konfiguration

### FullCalendar-Einstellungen
- **Lokalisierung**: Deutsche Sprache und Formate
- **Höhe**: Automatische Anpassung an Container
- **Events**: Asynchrones Laden vom Server
- **Navigation**: Vor/Zurück, Heute, Ansichtswechsel

### Cache-Einstellungen
- **Session-Cache**: 30 Sekunden für schnelle Zugriffe
- **DB-Cache**: 5 Minuten für persistente Daten
- **Log-Cache**: Performance-optimierte Abfragen

### Bereinigung
- **Standard**: 30 Tage alte Logs löschen
- **Konfigurierbar**: 1-365 Tage
- **Automatisch**: Über Scheduler oder manuell

## Sicherheit

### Zugriffskontrolle
- Nur Administratoren haben Zugriff
- CSRF-Schutz für alle Änderungen
- Login-Requirement für alle API-Endpunkte

### Datenschutz
- Konfigurierbare Löschung alter Daten
- Anonymisierung nach Löschung von Druckern
- Audit-Trail für alle Änderungen

## Status-Bedeutungen

| Status | Bedeutung | Beschreibung | Farbe im Kalender |
|--------|-----------|--------------|-------------------|
| `connected` | Verbunden | Steckdose ist erreichbar und antwortet | 🔌 Blau |
| `disconnected` | Getrennt | Steckdose ist nicht erreichbar | ❌ Rot |
| `on` | Eingeschaltet | Steckdose ist an - Drucker druckt aktiv | 🟢 Grün |
| `off` | Ausgeschaltet | Steckdose ist aus - Drucker bereit | 🔴 Orange |

## Quellenarten

| Source | Bedeutung | Beschreibung |
|--------|-----------|--------------|
| `system` | System | Automatische Checks durch Monitor |
| `manual` | Manuell | Manuelle Änderung durch Administrator |
| `api` | API | Programmatische Änderung über API |
| `scheduler` | Scheduler | Geplante Aktion durch Scheduler |

## UI-Komponenten

### Statistik-Karten
- **Schaltungen (24h)**: Anzahl der Statusänderungen
- **Erfolgsrate**: Prozentsatz erfolgreicher Verbindungen
- **Ø Antwortzeit**: Durchschnittliche Reaktionszeit
- **Fehlerzahl**: Anzahl der Verbindungsfehler

### Steuerungselemente
- **Drucker-Filter**: Dropdown zur Filterung nach Drucker
- **Ansicht-Buttons**: Wechsel zwischen Monat/Woche/Tag
- **Aktualisieren**: Manuelle Datenaktualisierung
- **Bereinigen**: Löschung alter Logs

### Modal-Details
Detailansicht für Kalenderereignisse mit:
- Vollständige Event-Informationen
- Technische Parameter
- Fehlerdetails (falls vorhanden)
- Benutzernotizen

## Performance

### Optimierungen
- Asynchrone Kalender-Events mit Lazy Loading
- Intelligentes Caching auf mehreren Ebenen  
- Paginierte Datenabfrage für große Datensätze
- Index-optimierte Datenbankabfragen
- FullCalendar-Performance-Optimierung

### Monitoring-Metriken
- Durchschnittliche Antwortzeit der Steckdosen
- Fehlerrate bei Verbindungen
- Anzahl Logs pro Zeitraum
- Top-Drucker nach Aktivität

## Fehlerbehebung

### Häufige Probleme

**FullCalendar lädt nicht**
- JavaScript-Konsole auf Fehler prüfen
- CDN-Verfügbarkeit überprüfen
- Browser-Cache leeren

**Kalender-Events fehlen**
- API-Endpunkt `/api/admin/plug-schedules/calendar` testen
- Datums-Parameter überprüfen
- Administratorberechtigung validieren

**PyP100-Modul nicht verfügbar**
```bash
pip install PyP100
```

**Steckdose nicht erreichbar**
- IP-Adresse überprüfen
- Netzwerkverbindung testen
- TAPO-Anmeldedaten validieren

### Debug-Informationen
```javascript
// Kalender-Debug im Browser
console.log(calendar.getEvents());

// API-Test
fetch('/api/admin/plug-schedules/calendar?start=2025-01-01&end=2025-01-31')
  .then(r => r.json())
  .then(console.log);
```

## Wartung

### Regelmäßige Aufgaben
1. **Wöchentlich**: Logs älter als 30 Tage bereinigen
2. **Monatlich**: Cache-Performance überprüfen
3. **Quartal**: Datenbankgröße und Indizes optimieren
4. **Jährlich**: FullCalendar-Version aktualisieren

### Backup-Empfehlungen
- Steckdosen-Logs in reguläre Backups einbeziehen
- Export-Funktionen für langfristige Archivierung
- Disaster-Recovery-Tests durchführen

## Changelog

### Version 2.0.0 (Januar 2025)
- ✅ Umbenennung zu "Steckdosenschaltzeiten"
- ✅ FullCalendar-Integration implementiert
- ✅ Moderne Kalenderansicht mit deutschen Lokalisierung
- ✅ Event-Details Modal hinzugefügt
- ✅ Farbkodierte Ereignisse nach Status
- ✅ Interaktive Drucker-Filterung
- ✅ Responsive Design für mobile Geräte
- ✅ Performance-Optimierungen für Kalender-Daten

### Version 1.0.0 (Januar 2025)
- ✅ Grundlegendes Monitoring-System implementiert
- ✅ Administrator-Dashboard erstellt  
- ✅ API-Endpunkte entwickelt
- ✅ Integration in Printer Monitor
- ✅ Automatisches Logging aktiviert
- ✅ Footer-Link für Administratoren hinzugefügt
- ✅ Bereinigungsfunktionen implementiert

## Support

Für Fragen oder Probleme:
1. Logs in `/logs/printer_monitor/` prüfen
2. Administrator-Dashboard auf Fehler überprüfen  
3. Browser-Konsole auf JavaScript-Fehler prüfen
4. FullCalendar-Kompatibilität validieren
5. Bei persistenten Problemen System-Admin kontaktieren