jojojojo aua
This commit is contained in:
@@ -1 +1,327 @@
|
||||
|
||||
# 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*
|
||||
Reference in New Issue
Block a user