Projektarbeit-MYP/backend/docs/GASTAUFTRAG_OTP_DOKUMENTATION.md

OTP-System für Gastaufträge - Dokumentation

Übersicht

Das OTP (One-Time Password) System ermöglicht es Gästen, den Status ihrer Druckaufträge sicher und ohne Anmeldung zu prüfen. Jeder Gast erhält bei der Antragsstellung einen eindeutigen 16-stelligen hexadezimalen Code.

Funktionsweise

🔐 OTP-Generierung

• Automatisch bei Antragstellung: Jeder neue Gastauftrag erhält sofort einen OTP-Code
• Sichere Speicherung: Der Code wird gehasht in der Datenbank gespeichert (bcrypt)
• Gültigkeitsdauer: 72 Stunden ab Erstellung
• Format: 16-stelliger hexadezimaler Code (z.B. "A1B2C3D4E5F67890")

📋 Status-Abfrage

• Öffentlicher Zugang: Keine Anmeldung erforderlich
• E-Mail-Verifikation: Optional für zusätzliche Sicherheit
• Einmalige Verwendung: Nach erfolgreicher Abfrage wird der Code als verwendet markiert

API-Endpunkte

Gast-Status-Abfrage

POST /guest/api/guest/status

Request Body:

{
  "otp_code": "A1B2C3D4E5F67890",
  "email": "gast@example.com"  // Optional
}

Response (Erfolg):

{
  "success": true,
  "request": {
    "id": 123,
    "name": "Max Mustermann",
    "file_name": "model.stl",
    "status": "approved",
    "created_at": "2025-01-07T10:30:00Z",
    "updated_at": "2025-01-07T12:15:00Z",
    "duration_min": 120,
    "reason": "Prototyp für Projekt XY",
    "message": "Ihr Auftrag wurde genehmigt! Sie können mit dem Drucken beginnen.",
    "can_start_job": true,
    "approved_at": "2025-01-07T12:15:00Z",
    "approval_notes": "Auftrag genehmigt - Drucker B verfügbar",
    "job": {
      "id": 456,
      "name": "3D Druck - Max Mustermann",
      "status": "scheduled",
      "start_at": "2025-01-07T14:00:00Z",
      "end_at": "2025-01-07T16:00:00Z",
      "printer_name": "Prusa i3 MK3S"
    }
  }
}

Response (Fehler):

{
  "success": false,
  "message": "Ungültiger Code oder E-Mail-Adresse"
}

Webinterface

Status-Abfrage-Seite

• URL: /guest/status-check
• Zugang: Öffentlich zugänglich
• Funktionen:
  • OTP-Code-Eingabe mit Formatierung
  • Optionale E-Mail-Verifikation
  • Detaillierte Status-Anzeige
  • Aktualisierungsfunktion

Benutzeroberfläche-Features

• Responsive Design: Optimiert für mobile Geräte
• Echtzeit-Validierung: Client-seitige Code-Formatierung
• Loading-States: Visuelles Feedback während Abfragen
• Fehlerbehandlung: Benutzerfreundliche Fehlermeldungen

Status-Informationen

Pending (In Bearbeitung)

{
  "status": "pending",
  "message": "Ihr Auftrag wird bearbeitet. Wartezeit: 3 Stunden.",
  "hours_waiting": 3
}

Approved (Genehmigt)

{
  "status": "approved",
  "message": "Ihr Auftrag wurde genehmigt! Sie können mit dem Drucken beginnen.",
  "can_start_job": true,
  "approved_at": "2025-01-07T12:15:00Z",
  "approval_notes": "Auftrag genehmigt - Drucker B verfügbar"
}

Rejected (Abgelehnt)

{
  "status": "rejected",
  "message": "Ihr Auftrag wurde leider abgelehnt.",
  "rejected_at": "2025-01-07T12:15:00Z",
  "rejection_reason": "Datei nicht kompatibel mit verfügbaren Druckern"
}

Implementation Details

OTP-Klasse in models.py

class GuestRequest(Base):
    # ... andere Felder ...
    otp_code = Column(String(200), nullable=True)  # Gehashter OTP
    otp_expires_at = Column(DateTime, nullable=True)
    otp_used_at = Column(DateTime, nullable=True)
    
    def generate_otp(self) -> str:
        """Generiert einen neuen OTP-Code und speichert den Hash."""
        otp_plain = secrets.token_hex(8)  # 16-stelliger hex Code
        otp_bytes = otp_plain.encode('utf-8')
        salt = bcrypt.gensalt()
        self.otp_code = bcrypt.hashpw(otp_bytes, salt).decode('utf-8')
        return otp_plain
    
    def verify_otp(self, otp_plain: str) -> bool:
        """Verifiziert einen OTP-Code."""
        if not self.otp_code or not otp_plain:
            return False
        try:
            otp_bytes = otp_plain.encode('utf-8')
            hash_bytes = self.otp_code.encode('utf-8')
            is_valid = bcrypt.checkpw(otp_bytes, hash_bytes)
            if is_valid:
                self.otp_used_at = datetime.now()
            return is_valid
        except Exception as e:
            return False

Automatische OTP-Generierung

# In blueprints/guest.py - guest_request_form()
guest_request = GuestRequest(...)
db_session.add(guest_request)
db_session.flush()  # Um ID zu erhalten

# OTP-Code sofort generieren für Status-Abfrage
otp_code = guest_request.generate_otp()
guest_request.otp_expires_at = datetime.now() + timedelta(hours=72)
db_session.commit()

Sicherheitsfeatures

🔒 Code-Sicherheit

• Bcrypt-Hashing: Sichere Speicherung der OTP-Codes
• Salt: Jeder Hash verwendet einen eindeutigen Salt
• One-Time-Use: Code wird nach erfolgreicher Verifikation als verwendet markiert

🛡️ Zusätzliche Sicherheit

• E-Mail-Verifikation: Optional für erhöhte Sicherheit
• Zeitliche Begrenzung: Codes laufen nach 72 Stunden ab
• Rate-Limiting: Schutz vor Brute-Force-Angriffen (falls implementiert)

🔍 Audit-Logging

• Alle OTP-Verifikationen werden protokolliert
• Fehlgeschlagene Versuche werden geloggt
• IP-Adressen werden für Sicherheitsanalysen gespeichert

Benutzer-Workflow

1. Antrag stellen

Gast füllt Antragsformular aus
    ↓
System generiert automatisch OTP-Code
    ↓
Gast erhält Code angezeigt/per E-Mail

2. Status prüfen

Gast besucht /guest/status-check
    ↓
Gibt 16-stelligen OTP-Code ein
    ↓
Optional: E-Mail zur Verifikation
    ↓
System zeigt aktuellen Status an

3. Job starten (bei Genehmigung)

Status zeigt "Genehmigt" an
    ↓
Link zu "Jetzt drucken" erscheint
    ↓
Gast kann Job mit anderem Code starten

Konfiguration

Gültigkeitsdauer

# In blueprints/guest.py
guest_request.otp_expires_at = datetime.now() + timedelta(hours=72)  # 72h

Code-Format

# In models.py - generate_otp()
otp_plain = secrets.token_hex(8)  # 16 Zeichen hexadezimal

Fehlerbehebung

Häufige Probleme

1. "Ungültiger Code"

Ursachen:

• Code falsch eingegeben
• Code bereits verwendet
• Code abgelaufen
• E-Mail stimmt nicht überein

Lösungen:

• Code-Eingabe überprüfen (16 Zeichen, hex)
• Neuen Code anfordern
• E-Mail-Feld leer lassen

2. "Verbindungsfehler"

Ursachen:

• Server nicht erreichbar
• Netzwerkprobleme
• API-Endpunkt nicht verfügbar

Lösungen:

• Internet-Verbindung prüfen
• Später erneut versuchen
• Browser-Cache leeren

3. "Fehler beim Abrufen des Status"

Ursachen:

• Datenbankfehler
• Server-Überlastung
• Code-Verifikation fehlgeschlagen

Lösungen:

• Server-Logs prüfen
• Datenbank-Verbindung überprüfen
• bcrypt-Installation validieren

Debug-Informationen

# Logging für OTP-Verifikation
logger.info(f"OTP-Verifikation für Request {request_id}: {'Erfolg' if valid else 'Fehlgeschlagen'}")
logger.warning(f"Ungültiger OTP-Code: {otp_code[:4]}****")

Best Practices

Für Administratoren

1. Regelmäßige Bereinigung abgelaufener OTP-Codes
2. Monitoring fehlgeschlagener Verifikationen
3. Backup der OTP-Datenbank vor Updates
4. Schulung des Personals zur OTP-Verwendung

Für Entwickler

1. Sichere Code-Generierung mit secrets.token_hex()
2. Proper Hashing mit bcrypt und Salt
3. Input-Validierung für alle OTP-Eingaben
4. Error-Handling für alle Edge-Cases
5. Rate-Limiting implementieren

Für Gäste

1. Code sicher aufbewahren - nicht weitergeben
2. Schnelle Verifikation - Code läuft ab
3. E-Mail verwenden für zusätzliche Sicherheit
4. Bei Problemen Admin kontaktieren

Integration

Bestehende Systeme

• Guest Blueprint: Nahtlose Integration in bestehende Gastauftrags-Verwaltung
• Admin-Panel: Übersicht über OTP-Status in Admin-Bereich
• Benachrichtigungen: OTP-Codes in E-Mail-Templates einbindbar
• Audit-Logs: Einheitliche Protokollierung mit bestehendem System

Erweiterungsmöglichkeiten

• SMS-Versand: OTP-Codes per SMS senden
• QR-Codes: Codes als QR-Code für mobile Apps
• Multi-Factor: Zusätzliche Authentifizierungsfaktoren
• Push-Notifications: Browser-Benachrichtigungen bei Status-Updates

Wartung

Regelmäßige Aufgaben

• Cleanup: Alte/abgelaufene OTP-Codes löschen
• Monitoring: Verifikations-Erfolgsrate überwachen
• Updates: bcrypt-Library aktuell halten
• Backup: OTP-Daten in Backups einschließen

Metriken

• Anzahl generierter OTP-Codes
• Verifikations-Erfolgsrate
• Durchschnittliche Zeit bis zur ersten Verifikation
• Häufigste Fehler-Typen

---

Dokumentation erstellt am: 2025-01-07 Version: 1.0 Autor: KI-Assistent