"feat: Update error handling documentation and live printer system guide"
This commit is contained in:
@@ -1 +1,377 @@
|
||||
|
||||
# Live-Druckererkennungs-System - MYP Platform
|
||||
|
||||
## Übersicht
|
||||
|
||||
Das Live-Druckererkennungs-System überwacht kontinuierlich den Status aller konfigurierten Drucker und bietet Echtzeit-Updates mit Session-Caching und automatischer Steckdosen-Initialisierung.
|
||||
|
||||
## Features
|
||||
|
||||
### 🔄 Live-Monitoring
|
||||
- **Echtzeit-Status-Updates** alle 30 Sekunden
|
||||
- **Parallele Abfragen** für bessere Performance
|
||||
- **Automatische Fehlerbehandlung** mit exponential backoff
|
||||
- **Adaptive Aktualisierungsintervalle** basierend auf Seitensichtbarkeit
|
||||
|
||||
### 💾 Session-Caching
|
||||
- **Session-basierter Cache** für schnelle Zugriffe (30 Sekunden TTL)
|
||||
- **Datenbank-Cache** für persistente Daten (5 Minuten TTL)
|
||||
- **Threadsicheres Caching** mit Locks
|
||||
- **Automatische Cache-Invalidierung**
|
||||
|
||||
### 🔌 Steckdosen-Initialisierung
|
||||
- **Automatischer Start** beim Programmstart
|
||||
- **Einheitlicher Startzustand** (alle Steckdosen ausgeschaltet)
|
||||
- **Fehlertolerante Initialisierung** mit detailliertem Logging
|
||||
- **Admin-gesteuerte manuelle Initialisierung**
|
||||
|
||||
### 📊 Status-Kategorien
|
||||
- **Online**: Drucker eingeschaltet und erreichbar
|
||||
- **Standby**: Drucker ausgeschaltet aber Steckdose erreichbar
|
||||
- **Offline**: Drucker/Steckdose nicht erreichbar
|
||||
- **Unreachable**: Grundkonnektivität fehlgeschlagen
|
||||
- **Unconfigured**: Unvollständige Konfiguration
|
||||
|
||||
## Backend-Architektur
|
||||
|
||||
### PrinterMonitor Klasse (`utils/printer_monitor.py`)
|
||||
|
||||
```python
|
||||
class PrinterMonitor:
|
||||
def __init__(self):
|
||||
self.session_cache = {} # Session-Cache für schnelle Zugriffe
|
||||
self.db_cache = {} # DB-Cache für persistente Daten
|
||||
self.cache_lock = threading.Lock()
|
||||
self.session_cache_ttl = 30 # 30 Sekunden
|
||||
self.db_cache_ttl = 300 # 5 Minuten
|
||||
```
|
||||
|
||||
#### Hauptmethoden
|
||||
|
||||
##### `initialize_all_outlets_on_startup()`
|
||||
- Schaltet beim Programmstart alle Steckdosen aus
|
||||
- Setzt alle Drucker in den gleichen Startzustand
|
||||
- Protokolliert detaillierte Ergebnisse
|
||||
|
||||
##### `get_live_printer_status(use_session_cache=True)`
|
||||
- Holt Live-Status mit mehrstufigem Caching
|
||||
- Prüft Session-Cache → DB-Cache → Live-Abfrage
|
||||
- Aktualisiert beide Cache-Ebenen
|
||||
|
||||
##### `_check_single_printer_status(printer, timeout=7)`
|
||||
- Überprüft einzelnen Drucker mit umfassenden Tests
|
||||
- Ping-Test für Grundkonnektivität
|
||||
- Smart-Plug-Status-Abfrage über HTTP-APIs
|
||||
- Unterstützt verschiedene Smart-Plug-Typen
|
||||
|
||||
## API-Endpunkte
|
||||
|
||||
### GET `/api/printers/monitor/live-status`
|
||||
Holt Live-Druckerstatus mit Session-Caching.
|
||||
|
||||
**Parameter:**
|
||||
- `use_cache` (optional): Verwende Session-Cache (default: true)
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"printers": {
|
||||
"1": {
|
||||
"id": 1,
|
||||
"name": "Printer 1",
|
||||
"status": "online",
|
||||
"active": true,
|
||||
"ip_address": "192.168.0.100",
|
||||
"plug_ip": "192.168.0.110",
|
||||
"location": "Werk 040 - Berlin - TBA",
|
||||
"last_checked": "2025-01-05T10:30:00",
|
||||
"ping_successful": true,
|
||||
"outlet_reachable": true,
|
||||
"outlet_state": "on"
|
||||
}
|
||||
},
|
||||
"summary": {
|
||||
"total": 6,
|
||||
"online": 2,
|
||||
"offline": 1,
|
||||
"standby": 2,
|
||||
"unreachable": 1,
|
||||
"unconfigured": 0
|
||||
},
|
||||
"cache_used": true,
|
||||
"timestamp": "2025-01-05T10:30:00",
|
||||
"total_printers": 6
|
||||
}
|
||||
```
|
||||
|
||||
### GET `/api/printers/monitor/summary`
|
||||
Schnelle Status-Zusammenfassung ohne vollständige Details.
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"summary": {
|
||||
"total": 6,
|
||||
"online": 2,
|
||||
"offline": 1,
|
||||
"standby": 2,
|
||||
"unreachable": 1,
|
||||
"unconfigured": 0
|
||||
},
|
||||
"timestamp": "2025-01-05T10:30:00"
|
||||
}
|
||||
```
|
||||
|
||||
### POST `/api/printers/monitor/clear-cache`
|
||||
Löscht alle Monitor-Caches (Session und DB).
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "Drucker-Monitor-Cache erfolgreich geleert"
|
||||
}
|
||||
```
|
||||
|
||||
### POST `/api/printers/monitor/initialize-outlets` (Admin)
|
||||
Initialisiert alle Drucker-Steckdosen (schaltet sie aus).
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "Steckdosen-Initialisierung abgeschlossen: 5/6 erfolgreich",
|
||||
"results": {
|
||||
"Printer 1": true,
|
||||
"Printer 2": true,
|
||||
"Printer 3": false,
|
||||
"Printer 4": true,
|
||||
"Printer 5": true,
|
||||
"Printer 6": true
|
||||
},
|
||||
"statistics": {
|
||||
"total": 6,
|
||||
"successful": 5,
|
||||
"failed": 1
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Frontend-Integration
|
||||
|
||||
### PrinterMonitor JavaScript-Klasse (`static/js/printer_monitor.js`)
|
||||
|
||||
#### Automatischer Start
|
||||
```javascript
|
||||
// Auto-Start auf relevanten Seiten
|
||||
const relevantPages = ['/printers', '/dashboard', '/admin'];
|
||||
if (relevantPages.some(page => currentPath.includes(page))) {
|
||||
window.printerMonitor.start();
|
||||
}
|
||||
```
|
||||
|
||||
#### Event-Handler registrieren
|
||||
```javascript
|
||||
// Status-Updates abonnieren
|
||||
window.printerMonitor.onUpdate((data) => {
|
||||
if (data.type === 'update') {
|
||||
updatePrinterDisplay(data.printers);
|
||||
updateSummary(data.summary);
|
||||
|
||||
// Änderungen anzeigen
|
||||
data.changes.forEach(change => {
|
||||
if (change.type === 'status_change') {
|
||||
showStatusChangeNotification(change);
|
||||
}
|
||||
});
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
#### Schnelle Updates aktivieren
|
||||
```javascript
|
||||
// Für kritische Operationen
|
||||
window.printerMonitor.enableFastUpdates(); // 5 Sekunden Intervall
|
||||
|
||||
// Später wieder deaktivieren
|
||||
window.printerMonitor.disableFastUpdates(); // 30 Sekunden Intervall
|
||||
```
|
||||
|
||||
#### Cache-Management
|
||||
```javascript
|
||||
// Cache leeren und neu laden
|
||||
await window.printerMonitor.clearCache();
|
||||
|
||||
// Sofortige Aktualisierung ohne Cache
|
||||
await window.printerMonitor.forceUpdate();
|
||||
```
|
||||
|
||||
#### Admin-Funktionen
|
||||
```javascript
|
||||
// Steckdosen initialisieren (nur für Admins)
|
||||
try {
|
||||
const result = await window.printerMonitor.initializeAllOutlets();
|
||||
console.log('Initialisierung erfolgreich:', result.statistics);
|
||||
} catch (error) {
|
||||
console.error('Initialisierung fehlgeschlagen:', error);
|
||||
}
|
||||
```
|
||||
|
||||
## Smart-Plug-Unterstützung
|
||||
|
||||
Das System unterstützt verschiedene Smart-Plug-APIs:
|
||||
|
||||
### TP-Link Tapo
|
||||
```http
|
||||
GET http://192.168.0.110/status
|
||||
Authorization: Basic dXNlcjpwYXNzd29yZA==
|
||||
|
||||
Response:
|
||||
{
|
||||
"system": {
|
||||
"get_sysinfo": {
|
||||
"relay_state": 1 // 1 = on, 0 = off
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Generische APIs
|
||||
```http
|
||||
# Status-Abfrage
|
||||
GET http://192.168.0.110/api/status
|
||||
GET http://192.168.0.110/relay/status
|
||||
GET http://192.168.0.110/state
|
||||
|
||||
# Steckdose ausschalten
|
||||
POST http://192.168.0.110/relay/off
|
||||
POST http://192.168.0.110/api/relay/off
|
||||
POST http://192.168.0.110/set?relay=off
|
||||
```
|
||||
|
||||
## Konfiguration
|
||||
|
||||
### Drucker-Modell erweitern
|
||||
```python
|
||||
# models.py
|
||||
class Printer(Base):
|
||||
# ... bestehende Felder ...
|
||||
plug_ip = Column(String(50), nullable=False)
|
||||
plug_username = Column(String(100), nullable=False)
|
||||
plug_password = Column(String(100), nullable=False)
|
||||
last_checked = Column(DateTime, nullable=True)
|
||||
```
|
||||
|
||||
### Rate-Limiting
|
||||
```python
|
||||
# Rate-Limits für API-Endpunkte
|
||||
@limit_requests("printer_monitor_live", 60, 5) # 5/min für Live-Status
|
||||
@limit_requests("printer_monitor_summary", 30, 10) # 10/30s für Summary
|
||||
@limit_requests("printer_monitor_cache", 120, 3) # 3/2min für Cache-Clear
|
||||
@limit_requests("printer_monitor_init", 300, 2) # 2/5min für Initialisierung
|
||||
```
|
||||
|
||||
## Logging
|
||||
|
||||
### Log-Kategorien
|
||||
- **INFO**: Normale Operationen, Status-Updates
|
||||
- **WARNING**: Fehlerhafte Konfigurationen, Initialisierungsprobleme
|
||||
- **ERROR**: Kritische Fehler, Netzwerkprobleme
|
||||
- **DEBUG**: Detaillierte Ping/HTTP-Informationen
|
||||
|
||||
### Beispiel-Logs
|
||||
```
|
||||
2025-01-05 10:30:00 - printer_monitor - INFO - 🖨️ Drucker-Monitor initialisiert
|
||||
2025-01-05 10:30:01 - printer_monitor - INFO - 🚀 Starte Steckdosen-Initialisierung beim Programmstart...
|
||||
2025-01-05 10:30:02 - printer_monitor - INFO - ✅ Printer 1: Steckdose ausgeschaltet
|
||||
2025-01-05 10:30:03 - printer_monitor - WARNING - ❌ Printer 3: Steckdose konnte nicht ausgeschaltet werden
|
||||
2025-01-05 10:30:05 - printer_monitor - INFO - 🎯 Steckdosen-Initialisierung abgeschlossen: 5/6 erfolgreich
|
||||
```
|
||||
|
||||
## Performance-Optimierungen
|
||||
|
||||
### Threading
|
||||
- **Parallele Drucker-Abfragen** mit ThreadPoolExecutor
|
||||
- **Maximale Worker**: min(anzahl_drucker, 8)
|
||||
- **Timeout-Handling** für hängende Anfragen
|
||||
|
||||
### Caching-Strategie
|
||||
1. **Session-Cache** (30s): Sofortige Antworten für wiederholte Anfragen
|
||||
2. **DB-Cache** (5min): Reduziert Datenbankzugriffe
|
||||
3. **Adaptive TTL**: Längere Cache-Zeiten bei Fehlern
|
||||
|
||||
### Netzwerk-Optimierungen
|
||||
- **Kurze Ping-Timeouts** (3s) für schnelle Konnektivitätsprüfung
|
||||
- **HTTP-Timeouts** (5-7s) für Smart-Plug-APIs
|
||||
- **Exponential Backoff** bei wiederholten Fehlern
|
||||
|
||||
## Fehlerbehandlung
|
||||
|
||||
### Automatische Wiederherstellung
|
||||
- **Fehler-Zähler** mit maximal 3 Versuchen
|
||||
- **Intervall-Erhöhung** bei wiederholten Fehlern
|
||||
- **Cache-Fallback** bei Netzwerkproblemen
|
||||
|
||||
### Graceful Degradation
|
||||
- **Teilweise Ergebnisse** bei einzelnen Drucker-Fehlern
|
||||
- **Letzte bekannte Werte** aus Cache bei Totalausfall
|
||||
- **Benutzerbenachrichtigung** über Systemprobleme
|
||||
|
||||
## Wartung und Monitoring
|
||||
|
||||
### System-Health-Checks
|
||||
```bash
|
||||
# Cache-Status prüfen
|
||||
curl -X GET /api/printers/monitor/summary
|
||||
|
||||
# Cache leeren
|
||||
curl -X POST /api/printers/monitor/clear-cache
|
||||
|
||||
# Vollständige Aktualisierung
|
||||
curl -X GET "/api/printers/monitor/live-status?use_cache=false"
|
||||
```
|
||||
|
||||
### Database-Wartung
|
||||
```sql
|
||||
-- Alte last_checked Werte bereinigen
|
||||
UPDATE printers SET last_checked = NULL WHERE last_checked < datetime('now', '-1 day');
|
||||
|
||||
-- Drucker-Status-Statistiken
|
||||
SELECT status, COUNT(*) FROM printers GROUP BY status;
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Häufige Probleme
|
||||
|
||||
#### Problem: Drucker werden als "unreachable" angezeigt
|
||||
**Lösung:**
|
||||
1. Netzwerkverbindung prüfen
|
||||
2. IP-Adressen in Datenbank validieren
|
||||
3. Firewall-Regeln überprüfen
|
||||
|
||||
#### Problem: Steckdosen-Initialisierung schlägt fehl
|
||||
**Lösung:**
|
||||
1. Smart-Plug-Konfiguration prüfen (IP, Username, Password)
|
||||
2. API-Endpunkte testen
|
||||
3. Timeout-Werte erhöhen
|
||||
|
||||
#### Problem: Cache funktioniert nicht
|
||||
**Lösung:**
|
||||
1. Session-Konfiguration prüfen
|
||||
2. Cache manuell leeren
|
||||
3. Speicher-Limits überprüfen
|
||||
|
||||
### Debug-Befehle
|
||||
```python
|
||||
# Einzelnen Drucker testen
|
||||
from utils.printer_monitor import printer_monitor
|
||||
status = printer_monitor._check_single_printer_status(printer)
|
||||
|
||||
# Cache-Inhalt prüfen
|
||||
print(printer_monitor.db_cache)
|
||||
|
||||
# Steckdose manuell testen
|
||||
success = printer_monitor._turn_outlet_off("192.168.0.110", "user", "pass")
|
||||
```
|
||||
Reference in New Issue
Block a user