📝 Commit Details:
This commit is contained in:
269
backend/docs/WARTESCHLANGEN_SYSTEM_DOKUMENTATION.md
Normal file
269
backend/docs/WARTESCHLANGEN_SYSTEM_DOKUMENTATION.md
Normal file
@@ -0,0 +1,269 @@
|
||||
# Warteschlangen-System für Offline-Drucker - Dokumentation
|
||||
|
||||
## Übersicht
|
||||
|
||||
Das Warteschlangen-System ermöglicht es Benutzern, Druckjobs auch für offline Drucker zu erstellen. Diese Jobs werden automatisch aktiviert, sobald die entsprechenden Drucker wieder online sind.
|
||||
|
||||
## 🔧 Funktionalitäten
|
||||
|
||||
### 1. **Universelle Drucker-Anzeige**
|
||||
- **Alle Drucker** werden in Dropdown-Menüs angezeigt (online und offline)
|
||||
- **Visuelle Unterscheidung**:
|
||||
- ✅ **Online-Drucker**: Grüner Hintergrund, "ONLINE - Sofortiger Start"
|
||||
- 🔄 **Offline-Drucker**: Oranger Hintergrund, "OFFLINE - Warteschlange"
|
||||
- **Status-Informationen**: Letzte Überprüfungszeit wird angezeigt
|
||||
|
||||
### 2. **Intelligente Job-Erstellung**
|
||||
- **Automatische Status-Erkennung**: System erkennt automatisch, ob Drucker online/offline ist
|
||||
- **Adaptive Job-Status**:
|
||||
- `scheduled` - für online Drucker (sofortiger Start)
|
||||
- `waiting_for_printer` - für offline Drucker (Warteschlange)
|
||||
|
||||
### 3. **Background-Überwachung (Queue-Manager)**
|
||||
- **Automatische Überwachung** alle 2 Minuten
|
||||
- **Status-Checks** für alle Drucker mit wartenden Jobs
|
||||
- **Automatische Aktivierung** von Jobs bei Online-Statuswechsel
|
||||
- **Thread-sichere Implementierung** mit Daemon-Thread
|
||||
|
||||
### 4. **Benachrichtigungssystem**
|
||||
- **Sofortige Benachrichtigungen** wenn Drucker online gehen
|
||||
- **Anti-Spam-Schutz** mit 5-Minuten-Cooldown
|
||||
- **Strukturierte Nachrichten** mit Job- und Drucker-Details
|
||||
|
||||
### 5. **Frontend-Integration**
|
||||
- **Live-Status-Anzeige** der Warteschlangen
|
||||
- **Manuelle Queue-Checks** per Button
|
||||
- **Automatische Updates** alle 30 Sekunden
|
||||
- **Benutzerfreundliche Warnungen** für offline Drucker
|
||||
|
||||
## 🚀 Implementierte Komponenten
|
||||
|
||||
### Backend-Komponenten
|
||||
|
||||
#### 1. **Queue-Manager** (`utils/queue_manager.py`)
|
||||
```python
|
||||
class PrinterQueueManager:
|
||||
- start() / stop() # Queue-Manager steuern
|
||||
- _monitor_loop() # Hauptüberwachungsschleife
|
||||
- _check_waiting_jobs() # Job-Status prüfen und aktualisieren
|
||||
- _send_job_activation_notification() # Benachrichtigungen senden
|
||||
- get_queue_status() # Aktueller Warteschlangen-Status
|
||||
```
|
||||
|
||||
**Funktionen:**
|
||||
- `start_queue_manager()` - Globalen Manager starten
|
||||
- `stop_queue_manager()` - Globalen Manager stoppen
|
||||
- `get_queue_manager()` - Manager-Instanz abrufen
|
||||
|
||||
#### 2. **Erweiterte API-Endpunkte** (`app.py`)
|
||||
```python
|
||||
/api/queue/status # GET - Queue-Status abrufen
|
||||
/api/queue/check-now # POST - Manuelle Queue-Überprüfung
|
||||
/api/jobs/check-waiting # POST - Wartende Jobs prüfen (bestehend, erweitert)
|
||||
```
|
||||
|
||||
#### 3. **Job-Erstellung mit Queue-Support**
|
||||
- Automatische Status-Erkennung bei Job-Erstellung
|
||||
- Intelligente Zuordnung zu `scheduled` oder `waiting_for_printer`
|
||||
- Drucker-Status-Check vor Job-Erstellung
|
||||
|
||||
### Frontend-Komponenten
|
||||
|
||||
#### 1. **Verbesserte Drucker-Auswahl**
|
||||
```javascript
|
||||
loadPrinters() # Lädt ALLE Drucker mit Live-Status
|
||||
populatePrinterSelect() # Zeigt alle Drucker mit Status-Indikatoren
|
||||
setupPrinterStatusWarning() # Konfiguriert Offline-Drucker-Warnungen
|
||||
```
|
||||
|
||||
#### 2. **Queue-Status-Management**
|
||||
```javascript
|
||||
loadQueueStatus() # Lädt aktuellen Warteschlangen-Status
|
||||
updateQueueStatusDisplay() # Aktualisiert Status-Anzeige im UI
|
||||
triggerQueueCheck() # Manuelle Queue-Überprüfung
|
||||
```
|
||||
|
||||
#### 3. **Automatische Updates**
|
||||
- **30-Sekunden-Intervall** für Job-Updates und Queue-Status
|
||||
- **Live-Status-Checks** für Drucker
|
||||
- **Reaktive UI-Updates** basierend auf Queue-Status
|
||||
|
||||
## 📋 Benutzer-Workflow
|
||||
|
||||
### 1. **Job für Online-Drucker erstellen**
|
||||
1. Benutzer wählt **Online-Drucker** (✅ grün markiert)
|
||||
2. Job wird mit Status `scheduled` erstellt
|
||||
3. Job startet **sofort** zur geplanten Zeit
|
||||
|
||||
### 2. **Job für Offline-Drucker erstellen**
|
||||
1. Benutzer wählt **Offline-Drucker** (🔄 orange markiert)
|
||||
2. **Ausführliche Warnung** wird angezeigt mit Details zum Warteschlangen-Modus
|
||||
3. Benutzer bestätigt **bewusst** die Warteschlangen-Erstellung
|
||||
4. Job wird mit Status `waiting_for_printer` erstellt
|
||||
5. **Automatische Überwachung** startet
|
||||
|
||||
### 3. **Automatische Job-Aktivierung**
|
||||
1. **Queue-Manager** überwacht Drucker-Status alle 2 Minuten
|
||||
2. Sobald Drucker **online** geht:
|
||||
- Job-Status wechselt zu `scheduled`
|
||||
- **Benachrichtigung** wird an Benutzer gesendet
|
||||
- Job startet zur **geplanten Zeit**
|
||||
|
||||
## 🔧 Technische Details
|
||||
|
||||
### Datenbank-Schema
|
||||
```sql
|
||||
-- Bestehende Job-Status erweitert:
|
||||
Job.status = 'waiting_for_printer' -- Neuer Status für wartende Jobs
|
||||
Job.status = 'scheduled' -- Bestehender Status für geplante Jobs
|
||||
|
||||
-- Drucker-Status:
|
||||
Printer.status = 'available'/'offline'
|
||||
Printer.last_checked = DATETIME -- Letzter Status-Check
|
||||
```
|
||||
|
||||
### Queue-Manager-Konfiguration
|
||||
```python
|
||||
check_interval = 120 # 2 Minuten zwischen Status-Checks
|
||||
timeout = 5 # 5 Sekunden Timeout für Drucker-Ping
|
||||
notification_cooldown = 300 # 5 Minuten Anti-Spam für Benachrichtigungen
|
||||
```
|
||||
|
||||
### Frontend-Update-Intervalle
|
||||
```javascript
|
||||
Auto-Updates: 30 Sekunden # Jobs, Queue-Status, Drucker-Status
|
||||
Manual-Check: Sofort # Benutzer-getriggerte Überprüfung
|
||||
```
|
||||
|
||||
## 🛡️ Sicherheit & Stabilität
|
||||
|
||||
### 1. **Thread-Sicherheit**
|
||||
- **Daemon-Thread** für Queue-Manager (stoppt automatisch bei App-Shutdown)
|
||||
- **Thread-sichere Datenbank-Sessions**
|
||||
- **Exception-Handling** in allen Überwachungsschleifen
|
||||
|
||||
### 2. **Fehler-Behandlung**
|
||||
- **Graceful Degradation** bei API-Fehlern
|
||||
- **Fallback-Mechanismen** für Status-Checks
|
||||
- **Detaillierte Logging** für Debugging
|
||||
|
||||
### 3. **Performance-Optimierung**
|
||||
- **Status-Caching** verhindert redundante Checks
|
||||
- **Batch-Processing** für mehrere Jobs
|
||||
- **Optimierte Datenbankabfragen**
|
||||
|
||||
### 4. **Anti-Spam-Schutz**
|
||||
- **Cooldown-Mechanismus** für Benachrichtigungen
|
||||
- **Rate-Limiting** für manuelle Queue-Checks
|
||||
|
||||
## 📊 Monitoring & Logging
|
||||
|
||||
### Log-Kategorien
|
||||
```python
|
||||
queue_logger.info("✅ Printer Queue Manager erfolgreich gestartet")
|
||||
queue_logger.info("🟢 Drucker {name} ist ONLINE geworden")
|
||||
queue_logger.info("📧 Benachrichtigung für User {user} gesendet")
|
||||
queue_logger.error("❌ Fehler beim Überprüfen wartender Jobs")
|
||||
```
|
||||
|
||||
### Queue-Status-API
|
||||
```json
|
||||
{
|
||||
"waiting_jobs": 3,
|
||||
"offline_printers_with_queue": 2,
|
||||
"online_printers": 4,
|
||||
"total_printers": 6,
|
||||
"queue_manager_running": true,
|
||||
"last_check": "2024-01-15T10:30:00Z",
|
||||
"check_interval_seconds": 120
|
||||
}
|
||||
```
|
||||
|
||||
## 🎯 Vorteile des Systems
|
||||
|
||||
### 1. **Benutzerfreundlichkeit**
|
||||
- ✅ **Alle Drucker sichtbar** - keine versteckten Optionen
|
||||
- ✅ **Klare Status-Indikatoren** - sofort erkennbar welcher Drucker verfügbar ist
|
||||
- ✅ **Transparente Warteschlangen** - Benutzer wissen immer, was passiert
|
||||
- ✅ **Automatische Benachrichtigungen** - keine manuelle Überwachung nötig
|
||||
|
||||
### 2. **Technische Robustheit**
|
||||
- ✅ **Automatische Überwachung** - läuft im Hintergrund ohne Benutzerinteraktion
|
||||
- ✅ **Fehlerresistenz** - System funktioniert auch bei temporären Netzwerkproblemen
|
||||
- ✅ **Skalierbarkeit** - unterstützt beliebig viele Drucker und Jobs
|
||||
- ✅ **Thread-Sicherheit** - keine Konflikte bei parallelen Zugriffen
|
||||
|
||||
### 3. **Produktivitätssteigerung**
|
||||
- ✅ **Keine verlorenen Jobs** - Jobs warten automatisch auf verfügbare Drucker
|
||||
- ✅ **Optimale Ressourcennutzung** - Drucker werden sofort bei Verfügbarkeit genutzt
|
||||
- ✅ **Reduzierte Administrationsaufwände** - automatisches Management
|
||||
- ✅ **Verbesserte Planbarkeit** - transparente Warteschlangen-Informationen
|
||||
|
||||
## 🚀 Deployment & Konfiguration
|
||||
|
||||
### 1. **Automatischer Start**
|
||||
Der Queue-Manager startet automatisch beim App-Start:
|
||||
```python
|
||||
# In app.py - Startup-Sequenz
|
||||
queue_manager = start_queue_manager()
|
||||
atexit.register(cleanup_queue_manager)
|
||||
```
|
||||
|
||||
### 2. **Konfiguration**
|
||||
```python
|
||||
# In utils/queue_manager.py
|
||||
check_interval = 120 # Überwachungsintervall (Sekunden)
|
||||
notification_cooldown = 300 # Benachrichtigungs-Cooldown (Sekunden)
|
||||
timeout = 5 # Drucker-Ping-Timeout (Sekunden)
|
||||
```
|
||||
|
||||
### 3. **Dependencies**
|
||||
- Keine zusätzlichen Python-Packages erforderlich
|
||||
- Nutzt bestehende `threading`, `time`, `datetime` Module
|
||||
- Integriert sich nahtlos in vorhandene Datenbank-Struktur
|
||||
|
||||
## 📝 Wartung & Troubleshooting
|
||||
|
||||
### Häufige Probleme & Lösungen
|
||||
|
||||
#### 1. **Queue-Manager läuft nicht**
|
||||
```bash
|
||||
# Log prüfen:
|
||||
tail -f logs/queue_manager/queue_manager.log
|
||||
|
||||
# Manueller Neustart über API:
|
||||
POST /api/queue/check-now
|
||||
```
|
||||
|
||||
#### 2. **Drucker werden nicht erkannt**
|
||||
```bash
|
||||
# Drucker-Status-Check:
|
||||
GET /api/printers/status/live
|
||||
|
||||
# Netzwerk-Konnektivität prüfen:
|
||||
ping [drucker-ip]
|
||||
```
|
||||
|
||||
#### 3. **Jobs bleiben in Warteschlange**
|
||||
```bash
|
||||
# Queue-Status prüfen:
|
||||
GET /api/queue/status
|
||||
|
||||
# Manueller Check:
|
||||
POST /api/queue/check-now
|
||||
```
|
||||
|
||||
### Performance-Tuning
|
||||
```python
|
||||
# Für viele Drucker (>20):
|
||||
check_interval = 300 # 5 Minuten statt 2 Minuten
|
||||
|
||||
# Für kritische Umgebungen:
|
||||
check_interval = 60 # 1 Minute für schnellere Reaktion
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Implementiert am:** [Aktuelles Datum]
|
||||
**Version:** 1.0
|
||||
**Kompatibilität:** MYP 3D-Druck Platform v2.0+
|
||||
Reference in New Issue
Block a user