Projektarbeit-MYP/backend/docs/STECKDOSEN_TEST_DOKUMENTATION.md

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

GET /api/printers/test/socket/{printer_id}

Beschreibung: Liefert detaillierten Status einer spezifischen Steckdose mit Sicherheitsbewertung.

Berechtigung: Admin-Rechte erforderlich

Response-Struktur:

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

GET /api/printers/test/all-sockets

Beschreibung: Liefert Status aller konfigurierten Steckdosen mit Zusammenfassung.

Berechtigung: Admin-Rechte erforderlich

Response-Struktur:

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

POST /api/printers/test/socket/{printer_id}/control

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

Berechtigung: Admin-Rechte erforderlich

Request-Body:

{
  "action": "on",  // "on" oder "off"
  "force": false,  // Sicherheitswarnungen überschreiben
  "test_reason": "Routinetest der Steckdose"
}

Response-Struktur:

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

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

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:

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