# Steckdosen-Test-System Dokumentation

## Übersicht

Das Steckdosen-Test-System ermöglicht es Ausbildern und Administratoren, die Stromversorgung der 3D-Drucker sicher zu testen und zu steuern. Die Funktionalität ist speziell für geschultes Personal entwickelt und beinhaltet umfassende Sicherheitsmechanismen.

## Funktionsumfang

### 🔍 Status-Überwachung
- **Echtzeit-Status** aller konfigurierten Steckdosen
- **Energieverbrauch-Monitoring** (bei unterstützten Geräten)
- **Netzwerk-Verbindungsstatus** zu jeder Steckdose
- **Geräte-Informationen** (Modell, Firmware-Version, etc.)

### ⚡ Testfunktionen
- **Einzelne Steckdose testen** - gezielter Test einer spezifischen Steckdose
- **Massenübersicht** - Status aller Steckdosen auf einen Blick
- **Ein-/Ausschalt-Tests** mit Sicherheitsprüfungen
- **Protokollierung** aller Test-Aktivitäten

### 🛡️ Sicherheitsfeatures
- **Warnsystem** bei aktiven Druckjobs
- **Force-Modus** für Notfälle mit expliziter Bestätigung
- **Risiko-Bewertung** basierend auf aktueller Nutzung
- **Audit-Trail** aller durchgeführten Tests

## API-Endpunkte

### Status-Abfrage

#### Einzelne Steckdose prüfen
```http
GET /api/printers/test/socket/{printer_id}
```

**Beschreibung:** Liefert detaillierten Status einer spezifischen Steckdose mit Sicherheitsbewertung.

**Berechtigung:** Admin-Rechte erforderlich

**Response-Struktur:**
```json
{
  "success": true,
  "printer": {
    "id": 1,
    "name": "Prusa i3 MK3S",
    "model": "Prusa i3 MK3S+",
    "location": "Werkstatt A",
    "status": "online"
  },
  "socket": {
    "status": "online",
    "info": {
      "device_on": true,
      "signal_level": 3,
      "current_power": 45.2,
      "device_id": "TAPO_P110_ABC123",
      "model": "P110",
      "hw_ver": "1.0",
      "fw_ver": "1.2.3"
    },
    "error": null,
    "ip_address": "192.168.1.100"
  },
  "safety": {
    "risk_level": "medium",
    "warnings": [
      "Drucker verbraucht aktuell 45.2W - vermutlich aktiv"
    ],
    "recommendations": [
      "Prüfen Sie den Druckerstatus bevor Sie die Steckdose ausschalten"
    ],
    "active_jobs_count": 0,
    "safe_to_test": false
  },
  "timestamp": "2025-01-05T10:30:00Z"
}
```

#### Alle Steckdosen prüfen
```http
GET /api/printers/test/all-sockets
```

**Beschreibung:** Liefert Status aller konfigurierten Steckdosen mit Zusammenfassung.

**Berechtigung:** Admin-Rechte erforderlich

**Response-Struktur:**
```json
{
  "success": true,
  "sockets": [
    {
      "printer": {...},
      "socket": {...},
      "warnings": [],
      "active_jobs": 0,
      "safe_to_test": true
    }
  ],
  "summary": {
    "total_sockets": 5,
    "online": 4,
    "offline": 1,
    "error": 0,
    "with_warnings": 1,
    "safe_to_test": 4
  },
  "timestamp": "2025-01-05T10:30:00Z"
}
```

### Steckdosen-Steuerung

#### Test-Steuerung
```http
POST /api/printers/test/socket/{printer_id}/control
```

**Beschreibung:** Steuert eine Steckdose für Testzwecke mit Sicherheitsprüfungen.

**Berechtigung:** Admin-Rechte erforderlich

**Request-Body:**
```json
{
  "action": "on",  // "on" oder "off"
  "force": false,  // Sicherheitswarnungen überschreiben
  "test_reason": "Routinetest der Steckdose"
}
```

**Response-Struktur:**
```json
{
  "success": true,
  "message": "Steckdose für Test erfolgreich eingeschaltet",
  "test_info": {
    "admin": "Admin Name",
    "reason": "Routinetest der Steckdose",
    "forced": false,
    "status_before": false,
    "status_after": true
  },
  "printer": {
    "id": 1,
    "name": "Prusa i3 MK3S",
    "status": "starting"
  },
  "action": "on",
  "warnings": [],
  "timestamp": "2025-01-05T10:30:00Z"
}
```

**Fehler-Response (bei Sicherheitsbedenken):**
```json
{
  "success": false,
  "error": "Aktion blockiert aufgrund von Sicherheitsbedenken",
  "warnings": [
    "WARNUNG: 1 aktive Job(s) würden abgebrochen!"
  ],
  "hint": "Verwenden Sie 'force': true um die Aktion trotzdem auszuführen",
  "requires_force": true
}
```

## Webinterface

### Zugriff
- **URL:** `/socket-test`
- **Berechtigung:** Nur für Administratoren
- **Navigation:** Admin-Menü → Steckdosen-Test

### Funktionen

#### 1. Übersicht aller Steckdosen
- **Statistik-Dashboard** mit Gesamtzahlen
- **Karten-Ansicht** aller konfigurierten Steckdosen
- **Status-Ampel** (Grün/Gelb/Rot) basierend auf Risikobewertung
- **Schnell-Aktionen** für jede Steckdose

#### 2. Einzeltest-Bereich
- **Drucker-Auswahl** via Dropdown
- **Detaillierte Status-Anzeige** mit allen verfügbaren Informationen
- **Sicherheitshinweise** und Empfehlungen
- **Test-Buttons** für Ein-/Ausschalten

#### 3. Sicherheitsfeatures
- **Bestätigungsmodal** für alle Aktionen
- **Grund-Eingabe** für Audit-Trail
- **Force-Checkbox** für Notfälle
- **Echtzeit-Warnungen** bei kritischen Zuständen

## Sicherheitskonzept

### Zugriffskontrolle
- **Authentifizierung:** Login erforderlich
- **Autorisierung:** Admin-Berechtigung erforderlich
- **Session-Management:** Automatisches Logout bei Inaktivität
- **CSRF-Schutz:** Token-basierte Anfrageverifizierung

### Risikobewertung
```python
def bewerte_risiko(aktive_jobs, stromverbrauch, steckdosen_status):
    if aktive_jobs > 0:
        return "high"  # Hoches Risiko
    elif steckdosen_status == "online" and stromverbrauch > 10:
        return "medium"  # Mittleres Risiko
    else:
        return "low"  # Geringes Risiko
```

### Sicherheitswarnungen
- **Aktive Jobs:** Warnung bei laufenden Druckaufträgen
- **Hoher Stromverbrauch:** Hinweis auf aktive Geräte
- **Netzwerkfehler:** Information über Verbindungsprobleme
- **Konfigurationsfehler:** Meldung bei fehlenden Einstellungen

### Force-Modus
Der Force-Modus erlaubt das Überschreiben von Sicherheitswarnungen:
- **Explizite Bestätigung** erforderlich
- **Zusätzliche Protokollierung** aller Force-Aktionen
- **Begründung** muss angegeben werden
- **Erweiterte Audit-Informationen** werden gespeichert

## Protokollierung

### Log-Kategorien
- **Normale Tests:** INFO-Level mit Grundinformationen
- **Force-Aktionen:** WARNING-Level mit erweiterten Details
- **Fehler:** ERROR-Level mit Fehlerbeschreibung
- **Sicherheitsereignisse:** Spezielle Security-Logs

### Log-Format
```
🧪 TEST DURCHGEFÜHRT: ON für Prusa i3 MK3S | 
Admin: Hans Müller | Grund: Routinetest | 
Force: false | Status: false → true
```

### Gespeicherte Informationen
- **Zeitstempel** der Aktion
- **Admin-Name** des ausführenden Benutzers
- **Drucker-Informationen** (Name, ID)
- **Aktion** (Ein/Aus)
- **Grund** für den Test
- **Force-Status** (verwendet/nicht verwendet)
- **Status-Änderung** (Vorher/Nachher)

## Fehlerbehebung

### Häufige Probleme

#### 1. Steckdose nicht erreichbar
**Symptome:** Status "error", Verbindungsfehler
**Lösungsansätze:**
- Netzwerkverbindung prüfen
- IP-Adresse verifizieren
- Steckdose neu starten
- Konfiguration überprüfen

#### 2. Falsche Anmeldedaten
**Symptome:** Authentifizierungsfehler
**Lösungsansätze:**
- Benutzername/Passwort in Drucker-Konfiguration prüfen
- Steckdose zurücksetzen
- Neue Anmeldedaten konfigurieren

#### 3. Keine Admin-Berechtigung
**Symptome:** 403 Forbidden-Fehler
**Lösungsansätze:**
- Benutzer-Rolle überprüfen
- Admin-Berechtigung zuweisen
- Neu anmelden

### Debug-Informationen
Bei Problemen sind folgende Informationen hilfreich:
- **Browser-Konsole** für JavaScript-Fehler
- **Netzwerk-Tab** für API-Anfragen
- **Server-Logs** für Backend-Fehler
- **Steckdosen-IP** und Erreichbarkeit

## Konfiguration

### Drucker-Steckdosen-Zuordnung
Jeder Drucker kann eine Steckdose konfiguriert haben:

```python
class Printer(Base):
    # ... andere Felder ...
    plug_ip = Column(String(50), nullable=False)        # IP der Steckdose
    plug_username = Column(String(100), nullable=False) # Benutzername
    plug_password = Column(String(100), nullable=False) # Passwort
```

### Unterstützte Steckdosen
- **TP-Link Tapo P110** (Smart Plug mit Energiemessung)
- **Kompatible PyP100-Geräte**

### Netzwerk-Anforderungen
- **Gleiche Subnetz:** Steckdosen müssen im gleichen Netzwerk erreichbar sein
- **Port 9999:** Standard-Port für TP-Link Tapo-Kommunikation
- **Keine Firewall-Blockierung:** Zwischen Server und Steckdosen

## Best Practices

### Für Administratoren
1. **Immer Status prüfen** bevor Tests durchgeführt werden
2. **Begründung angeben** für bessere Nachverfolgbarkeit
3. **Force-Modus sparsam verwenden** nur in Notfällen
4. **Regelmäßige Tests** zur Funktionsüberprüfung
5. **Dokumentation führen** über durchgeführte Wartungen

### Für Ausbilder
1. **Schulung** vor erster Nutzung
2. **Sicherheitsregeln beachten** bei aktiven Jobs
3. **Koordination** mit anderen Nutzern
4. **Protokollierung** aller Testaktivitäten
5. **Eskalation** bei Problemen an IT-Support

### Für Entwickler
1. **Error-Handling** für alle API-Calls
2. **Timeout-Behandlung** für Netzwerk-Anfragen
3. **Caching** für bessere Performance
4. **Logging** für Debug-Zwecke
5. **Testing** aller Szenarien

## Integration

### Bestehende Systeme
Das Steckdosen-Test-System integriert sich nahtlos in:
- **Drucker-Management:** Nutzung der bestehenden Drucker-Datenbank
- **Benutzer-System:** Verwendung der Admin-Berechtigungen
- **Logging-System:** Einheitliche Log-Struktur
- **API-Framework:** Konsistente REST-API

### Erweiterungsmöglichkeiten
- **Zeitgesteuerte Tests:** Automatische periodische Tests
- **Benachrichtigungen:** E-Mail/Push bei kritischen Ereignissen
- **Dashboard-Integration:** Einbindung in Haupt-Dashboard
- **Reporting:** Erweiterte Berichte und Statistiken

## Wartung

### Regelmäßige Aufgaben
- **Verbindungstests** zu allen Steckdosen
- **Log-Rotation** zur Speicherplatz-Verwaltung
- **Konfiguration-Backup** der Steckdosen-Einstellungen
- **Performance-Monitoring** der API-Endpoints

### Update-Verfahren
1. **Backup** der aktuellen Konfiguration
2. **Test-Environment** für neue Version
3. **Schrittweise Einführung** mit Fallback-Plan
4. **Dokumentation** aller Änderungen

## Support

### Kontakt
- **IT-Support:** für technische Probleme
- **Ausbilder-Team:** für fachliche Fragen
- **Entwickler-Team:** für Feature-Requests

### Dokumentation
- **API-Dokumentation:** für Entwickler
- **Benutzer-Handbuch:** für Administratoren
- **Troubleshooting-Guide:** für Support-Team

---

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