# 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
```http
POST /guest/api/guest/status
```

**Request Body:**
```json
{
  "otp_code": "A1B2C3D4E5F67890",
  "email": "gast@example.com"  // Optional
}
```

**Response (Erfolg):**
```json
{
  "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):**
```json
{
  "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)
```json
{
  "status": "pending",
  "message": "Ihr Auftrag wird bearbeitet. Wartezeit: 3 Stunden.",
  "hours_waiting": 3
}
```

### Approved (Genehmigt)
```json
{
  "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)
```json
{
  "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
```python
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
```python
# 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
```python
# In blueprints/guest.py
guest_request.otp_expires_at = datetime.now() + timedelta(hours=72)  # 72h
```

### Code-Format
```python
# 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
```python
# 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*