📝 "Erweiterte Dokumentation für Druckerkonflikt-Management und Steckdosenschaltzeiten hinzugefügt, einschließlich API-Endpunkte, Konfliktbehandlungsszenarien und Systemarchitektur." 📚

2025-06-02 16:04:51 +02:00
parent db6baad83d
commit 82332d2def
5 changed files with 1086 additions and 4 deletions
--- a/backend/docs/STECKDOSENSCHALTZEITEN.md
+++ b/backend/docs/STECKDOSENSCHALTZEITEN.md
@@ -1 +1,303 @@
- 
+# 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