# 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+