Projektarbeit-MYP/backend/docs/README.md

MYP Backend-Steuerungsplattform

Dies ist das Backend für das MYP (Manage Your Printer) Projekt, ein IHK-Abschlussprojekt für Fachinformatiker für digitale Vernetzung. Die Plattform ist mit Python und Flask implementiert und stellt eine RESTful API zur Verfügung, die es ermöglicht, 3D-Drucker zu verwalten, zu reservieren und über WLAN-Steckdosen (Tapo P115) zu steuern.

Funktionen

• Lokales Authentifizierungssystem (Offline-fähig)
• Rollen-basierte Zugriffskontrolle (Admin/User/Guest)
• Druckerverwaltung (Hinzufügen, Bearbeiten, Löschen)
• Reservierungsverwaltung (Erstellen, Abbrechen, Verlängern)
• Fernsteuerung von WLAN-Steckdosen (Tapo P115)
• Statistikerfassung und -anzeige
• RESTful API für die Kommunikation mit dem Frontend

Technologie-Stack

• Python: Programmiersprache
• Flask: Web-Framework
• SQLite: Integrierte Datenbank (kann für Produktion durch PostgreSQL ersetzt werden)
• PyP100: Python-Bibliothek zur Steuerung der Tapo P115 WLAN-Steckdosen
• Gunicorn: WSGI HTTP Server für die Produktionsumgebung
• Docker: Containerisierung der Anwendung

Projekt-Struktur

• app.py: Hauptanwendungsdatei mit allen Routen und Modellen
• requirements.txt: Liste aller Python-Abhängigkeiten
• Dockerfile: Docker-Konfiguration
• docker-compose.yml: Docker Compose Konfiguration für einfaches Deployment
• .env.example: Beispiel für die Umgebungsvariablen
• logs/: Logdateien (automatisch erstellt)
• instance/: SQLite-Datenbank (automatisch erstellt)

Installation und Ausführung

Lokal (Entwicklung)

1. Python 3.8 oder höher installieren
2. Repository klonen
3. Ins Projektverzeichnis wechseln
4. Virtuelle Umgebung erstellen (optional, aber empfohlen)

   python -m venv venv
   source venv/bin/activate  # Unter Windows: venv\Scripts\activate
   

5. Abhängigkeiten installieren

   pip install -r requirements.txt
   

6. .env.example nach .env kopieren und anpassen

   cp .env.example .env
   

7. Anwendung starten

   python app.py
   

Die Anwendung ist dann unter http://localhost:5000 erreichbar.

Mit Docker

1. Docker und Docker Compose installieren
2. Ins Projektverzeichnis wechseln
3. .env.example nach .env kopieren und anpassen

   cp .env.example .env
   

4. Anwendung starten

   docker-compose up -d
   

Die Anwendung ist dann unter http://localhost:5000 erreichbar.

API-Endpunkte

Authentifizierung

• POST /auth/register: Neuen Benutzer registrieren
• POST /auth/login: Benutzer anmelden
• POST /auth/logout: Abmelden und Session beenden
• POST /api/create-initial-admin: Initialen Administrator erstellen
• GET /api/me: Aktuelle Benutzerinformationen abrufen

Benutzer

• GET /api/users: Liste aller Benutzer (Admin)
• GET /api/users/<id>: Details zu einem Benutzer (Admin)
• PUT /api/users/<id>: Benutzer aktualisieren (Admin)
• DELETE /api/users/<id>: Benutzer löschen (Admin)

Drucker

• GET /api/printers: Liste aller Drucker
• POST /api/printers: Drucker hinzufügen (Admin)
• GET /api/printers/<id>: Details zu einem Drucker
• PUT /api/printers/<id>: Drucker aktualisieren (Admin)
• DELETE /api/printers/<id>: Drucker löschen (Admin)

Druckaufträge

• GET /api/jobs: Liste aller Druckaufträge (Admin) oder eigener Druckaufträge (Benutzer)
• POST /api/jobs: Druckauftrag erstellen
• GET /api/jobs/<id>: Details zu einem Druckauftrag
• POST /api/jobs/<id>/abort: Druckauftrag abbrechen
• POST /api/jobs/<id>/finish: Druckauftrag vorzeitig beenden
• POST /api/jobs/<id>/extend: Druckauftrag verlängern
• PUT /api/jobs/<id>/comments: Kommentare aktualisieren
• GET /api/job/<id>/remaining-time: Verbleibende Zeit für einen aktiven Druckauftrag

Statistiken

• GET /api/stats: Statistiken zu Druckern, Aufträgen und Benutzern (Admin)

Datenmodell

Benutzer (User)

• id (String UUID, Primary Key)
• username (String, Unique)
• password_hash (String)
• display_name (String)
• email (String, Unique)
• role (String, 'admin', 'user' oder 'guest')

Session

• id (String UUID, Primary Key)
• user_id (String UUID, Foreign Key zu User)
• expires_at (DateTime)

Drucker (Printer)

• id (String UUID, Primary Key)
• name (String)
• description (Text)
• status (Integer, 0=available, 1=busy, 2=maintenance)
• ip_address (String, IP-Adresse der Tapo-Steckdose)

Druckauftrag (PrintJob)

• id (String UUID, Primary Key)
• printer_id (String UUID, Foreign Key zu Printer)
• user_id (String UUID, Foreign Key zu User)
• start_at (DateTime)
• duration_in_minutes (Integer)
• comments (Text)
• aborted (Boolean)
• abort_reason (Text)

Steckdosensteuerung

Die Anwendung steuert Tapo P115 WLAN-Steckdosen, um die Drucker basierend auf Reservierungen ein- und auszuschalten:

• Bei Erstellung eines Druckauftrags wird die Steckdose des zugehörigen Druckers automatisch eingeschaltet
• Bei Abbruch oder vorzeitiger Beendigung eines Druckauftrags wird die Steckdose ausgeschaltet
• Nach Ablauf der Reservierungszeit wird die Steckdose automatisch ausgeschaltet
• Ein CLI-Befehl flask check-jobs überprüft regelmäßig abgelaufene Jobs und schaltet Steckdosen aus

Sicherheit

• Die Anwendung verwendet ein lokales Authentifizierungssystem mit Passwort-Hashing
• Sitzungsdaten werden in Server-Side-Sessions gespeichert
• Zugriffskontrollen sind implementiert, um sicherzustellen, dass Benutzer nur auf ihre eigenen Daten zugreifen können
• Admin-Benutzer haben Zugriff auf alle Daten und können Systemkonfigurationen ändern
• Der erste registrierte Benutzer wird automatisch zum Administrator

Logging

Die Anwendung protokolliert Aktivitäten in rotierenden Logdateien in einem logs Verzeichnis. Dies hilft bei der Fehlersuche und Überwachung der Anwendung im Betrieb.

Umgebungsvariablen

Die folgenden Umgebungsvariablen müssen konfiguriert werden:

• SECRET_KEY: Geheimer Schlüssel für die Session-Verschlüsselung
• DATABASE_PATH: Pfad zur Datenbank (Standard: SQLite-Datenbank im Instance-Verzeichnis)
• TAPO_USERNAME: Benutzername für die Tapo-Steckdosen
• TAPO_PASSWORD: Passwort für die Tapo-Steckdosen
• PRINTERS: JSON-Objekt mit der Zuordnung von Drucker-Namen zu IP-Adressen der Steckdosen im Format: {"Printer 1": {"ip": "192.168.1.100"}, "Printer 2": {"ip": "192.168.1.101"}, ...}

Automatisierung

Die Anwendung beinhaltet einen CLI-Befehl flask check-jobs, der regelmäßig ausgeführt werden sollte (z.B. als Cron-Job), um abgelaufene Druckaufträge zu überprüfen und die zugehörigen Steckdosen auszuschalten.

Kompatibilität mit dem Frontend

Das Backend wurde speziell für die Kompatibilität mit dem bestehenden Frontend entwickelt, welches in /packages/reservation-platform zu finden ist. Die API-Endpunkte und Datenstrukturen sind so gestaltet, dass sie nahtlos mit dem Frontend zusammenarbeiten.