Projektarbeit-MYP/backend/docs/WARTESCHLANGEN_SYSTEM_DOKUMENTATION.md

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)

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)

/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

loadPrinters()              # Lädt ALLE Drucker mit Live-Status
populatePrinterSelect()     # Zeigt alle Drucker mit Status-Indikatoren
setupPrinterStatusWarning() # Konfiguriert Offline-Drucker-Warnungen

2. Queue-Status-Management

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

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

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

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

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

{
  "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:

# In app.py - Startup-Sequenz
queue_manager = start_queue_manager()
atexit.register(cleanup_queue_manager)

2. Konfiguration

# 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

# 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

# Drucker-Status-Check:
GET /api/printers/status/live

# Netzwerk-Konnektivität prüfen:
ping [drucker-ip]

3. Jobs bleiben in Warteschlange

# Queue-Status prüfen:
GET /api/queue/status

# Manueller Check:
POST /api/queue/check-now

Performance-Tuning

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