Projektarbeit-MYP/backend/docs/MYP_SYSTEMDOKUMENTATION.md

MYP Platform - Systemdokumentation

Projektübersicht

MYP (Manage Your Printers) ist ein umfassendes 3D-Drucker-Verwaltungssystem für Mercedes-Benz, das für den Betrieb auf Debian/Linux-Systemen (speziell Raspberry Pi) im HTTPS-Kiosk-Modus entwickelt wurde. Das System verwaltet Drucker-Terminplanung, Benutzerauthentifizierung, Job-Warteschlangen und Smart-Plug-Integration mit TP-Link Tapo-Geräten.

Architektur-Übersicht

Core-Struktur

Die Anwendung folgt einer Flask-Blueprint-Architektur mit klarer Trennung der Zuständigkeiten:

• app.py: Hauptanwendungs-Einstiegspunkt mit HTTPS-Konfiguration und Raspberry Pi-Optimierungen
• models.py: SQLAlchemy-Modelle mit SQLite-Optimierung (WAL-Modus, Caching, Performance-Tuning)
• blueprints/: Modulare Feature-Implementierungen
  • auth.py: Authentifizierung und Session-Management
  • admin.py & admin_api.py: Administrative Schnittstellen und APIs
  • printers.py: Drucker-Verwaltung und Smart-Plug-Integration
  • jobs.py: Job-Warteschlangen-Management
  • guest.py: Gastzugang mit OTP-System
  • calendar.py: Terminplanung mit Konflikt-Management
  • users.py & user.py: Benutzerverwaltung und Profile

Design-Patterns

1. Datenbank-Sessions

Verwendet Scoped Sessions mit ordnungsgemäßer Bereinigung:

with get_db_session() as session:
    # Datenbankoperationen

2. Berechtigungssystem

Rollenbasiert mit spezifischen Berechtigungen:

• Decorators: @login_required, @admin_required, @permission_required
• Berechtigungen: can_manage_printers, can_approve_jobs, etc.

3. Konflikt-Management

Intelligente Drucker-Zuweisung basierend auf:

• Verfügbarkeitsfenstern
• Prioritätsstufen (dringend, hoch, normal, niedrig)
• Job-Dauer-Kompatibilität
• Echtzeit-Konflikterkennung

4. Logging-Strategie

Modulares Logging mit separaten Dateien pro Komponente:

from utils.logging_config import get_logger
logger = get_logger("component_name")

Installation und Setup

Systemvoraussetzungen

• Betriebssystem: Debian/Raspbian (Raspberry Pi OS)
• Berechtigung: Root-Zugriff (sudo)
• Internetverbindung: Für Paket-Downloads erforderlich
• Hardware: Raspberry Pi oder kompatibles Debian-System

Installationsmodi

1. Abhängigkeiten für manuelles Testen

Zweck: System vollständig für manuelle Tests und Entwicklung vorbereiten

Installation:

sudo ./setup.sh
# Option 1 wählen

Umfasst:

• Python 3 und pip
• Node.js und npm
• SSL-Zertifikate (inkl. Mercedes Corporate)
• Python-Pakete (Flask, SQLAlchemy, etc.)
• npm-Abhängigkeiten
• Anwendungsdeployment nach /opt/myp
• SSL-Zertifikat-Generierung
• Minimaler Funktionstest

2. Vollständige Kiosk-Installation mit Remote-Zugang

Zweck: Komplette Produktionsinstallation mit automatischem Kiosk-Modus

Installation:

sudo ./setup.sh
# Option 2 wählen

Umfasst:

• Alle Abhängigkeiten
• Desktop-Environment-Entfernung
• Minimale X11-Umgebung
• SSH-Server (user:raspberry)
• RDP-Server (xrdp) mit TLS (root:744563017196A)
• XFCE Desktop-Umgebung für RDP
• firewalld mit erweiterten Netzwerk-Regeln
• Kiosk-Benutzer-Konfiguration
• Automatischer Login und Kiosk-Start
• Systemd-Services

Systemd-Services

myp-https.service

• Zweck: HTTPS-Backend auf Port 443
• Benutzer: root (für privilegierten Port)
• SSL: Automatische Zertifikat-Generierung

myp-kiosk.service

• Zweck: Chromium-Browser im Kiosk-Modus
• Benutzer: kiosk
• Features: Vollbild, SSL-Ignorierung, automatische Auflösungserkennung

kiosk-watchdog.service

• Zweck: Intelligente Systemüberwachung
• Funktionen:
  • HTTPS-Backend-Überwachung
  • SSL-Zertifikat-Überwachung
  • Kiosk-Session-Überwachung
  • Speicher-Überwachung
  • Automatische Neustarts

myp-firewall.service

• Zweck: Automatische Firewall-Konfiguration beim Systemstart
• Zone: myp-backend für Netzwerk 192.168.0.0/24
• Ports: 443/tcp (HTTPS), 22/tcp (SSH), 3389/tcp (RDP)

Verzeichnisstruktur

/opt/myp/                    # Hauptanwendungsverzeichnis
├── app.py                   # Flask-Hauptanwendung
├── models.py                # Datenbankmodelle
├── blueprints/              # Flask-Blueprints
├── config/                  # Konfigurationsdateien
├── database/                # SQLite-Datenbank
├── static/                  # Statische Dateien (CSS, JS)
├── templates/               # HTML-Templates
├── uploads/                 # Upload-Verzeichnis
├── utils/                   # Hilfsfunktionen
├── logs/                    # Log-Dateien
└── certs/                   # SSL-Zertifikate
    └── localhost/           # Localhost-Zertifikate

Konfiguration

SSL-Zertifikate

Mercedes Corporate Zertifikate:

• Automatische Installation aus certs/mercedes/
• Unterstützte Formate: .crt, .pem, .cer
• DER-zu-PEM Konvertierung

Localhost-Zertifikat:

• Automatische Generierung für HTTPS
• Gültigkeitsdauer: 365 Tage
• Speicherort: /opt/myp/certs/localhost/

Netzwerk-Sicherheit

IPv6-Deaktivierung:

• Vollständige Deaktivierung auf Kernel-Ebene
• GRUB-Konfiguration: ipv6.disable=1
• Firewall blockiert alle IPv6-Pakete

Firewall-Konfiguration:

• Zone: myp-backend
• Quell-Netzwerke: 192.168.0.0/16, 127.0.0.1/32
• Erlaubte Ports: 443/tcp, 22/tcp, 3389/tcp
• Automatische Hostname-Integration

Sicherheitsmaßnahmen:

• IP-Spoofing-Schutz (Reverse Path Filtering)
• DDoS-Schutz (SYN-Cookies)
• TCP-Optimierungen
• Deaktivierte TCP-Timestamps (Anti-Fingerprinting)

Remote-Zugang

SSH-Zugang:

• Benutzer: user
• Passwort: raspberry
• Port: 22

RDP-Zugang:

• Benutzer: root
• Passwort: 744563017196A
• Port: 3389
• Desktop: XFCE
• Verschlüsselung: TLS 1.2/1.3

Performance-Optimierungen

Raspberry Pi-spezifische Optimierungen

1. Frontend-Optimierungen:

   • Reduzierte Animationen und Glassmorphism-Effekte
   • Minifizierte Assets mit gzip-Kompression
   • Optimierte SQLite-Einstellungen für SD-Karten
   • Speicher-effiziente Session-Behandlung

2. Caching-Strategie:

   • Statische Datei-Caching (1 Jahr)
   • Datenbank-Query-Caching
   • Session-basiertes Caching für teure Operationen

3. Datenbank-Optimierungen:

   • WAL-Modus für gleichzeitigen Zugriff
   • Ordnungsgemäße Indizierung auf Fremdschlüsseln
   • Connection Pooling mit StaticPool
   • Automatische Bereinigung alter Datensätze

Integration und Schnittstellen

TP-Link Tapo Smart Plugs

• PyP100-Bibliothek für Gerätesteuerung
• Status-Überwachung und Terminplanung
• Automatisches Energiemanagement

E-Mail-Benachrichtigungen

• Gastanfrage-Benachrichtigungen
• Job-Abschluss-Alerts
• System-Status-Updates

Datei-Uploads

• Unterstützung für STL, OBJ, 3MF, AMF, GCODE
• Sichere Dateibehandlung mit Validierung
• Organisierte Speicherung im uploads/-Verzeichnis

Sicherheit

Implementierte Maßnahmen

• SSL/TLS: Selbstsignierte Zertifikate mit automatischer Generierung
• CSRF-Schutz: Global aktiviert mit Flask-WTF
• Session-Sicherheit: Sichere Cookies, HTTPOnly, SameSite=Lax
• Rate Limiting: Eingebaut für API-Endpunkte
• Input-Validierung: WTForms für alle Benutzereingaben
• Systemd-Härtung: NoNewPrivileges, ProtectSystem

Berechtigungssystem

class UserPermission:
    can_manage_users = True
    can_manage_printers = True  
    can_approve_jobs = True
    can_view_analytics = True
    can_manage_system = True
    can_access_admin = True

Wartung und Überwachung

Logging-System

Log-Verzeichnisse:

• /opt/myp/logs/ - Anwendungs-Logs
• /var/log/myp-install.log - Installations-Log
• journalctl -u <service-name> - Service-Logs

Komponenten-spezifische Logs:

• logs/app/app.log - Hauptanwendung
• logs/admin/admin.log - Admin-Aktivitäten
• logs/printers/printers.log - Drucker-Status
• logs/security/security.log - Sicherheitsereignisse

Automatische Wartung

Tägliche Tasks:

# Cache-Bereinigung
POST /api/admin/cache/clear

# Database-Optimierung
sqlite3 database/myp.db "PRAGMA optimize;"

# Log-Rotation
logrotate /etc/logrotate.d/myp-webapp

Wöchentliche Tasks:

# Vollständige Database-Wartung
sqlite3 database/myp.db "VACUUM; ANALYZE;"

# Performance-Analyse
curl /api/admin/performance/weekly-report

System-Monitoring

Watchdog-Funktionen:

• HTTPS-Backend-Überwachung
• SSL-Zertifikat-Überwachung
• Kiosk-Session-Überwachung
• Speicher-Überwachung mit automatischen Neustarts

Performance-Metriken:

def get_performance_metrics():
    return {
        'system': {
            'cpu_usage': psutil.cpu_percent(),
            'memory_usage': psutil.virtual_memory().percent,
            'disk_usage': psutil.disk_usage('/').percent
        },
        'database': {
            'connection_pool_usage': get_db_pool_usage(),
            'slow_queries': get_slow_queries()
        }
    }

Troubleshooting

Häufige Probleme

1. HTTPS-Backend nicht erreichbar

   sudo systemctl status myp-https
   sudo journalctl -u myp-https -f
   

2. Kiosk-Browser startet nicht

   sudo systemctl status myp-kiosk
   sudo journalctl -u myp-kiosk -f
   

3. SSL-Zertifikat-Probleme

   sudo ./setup.sh
   # Option 5 für System-Test
   

4. Firewall-Probleme

   sudo systemctl status firewalld
   sudo firewall-cmd --get-active-zones
   sudo firewall-cmd --zone=myp-backend --list-all
   

Debug-Tools

• System-Status: /api/admin/system/health
• Performance-Metriken: /api/admin/performance/metrics
• Live-Logs: tail -f logs/app/app.log

Backup und Recovery

Automatisches Backup

def create_system_backup():
    timestamp = datetime.now().strftime('%Y%m%d_%H%M%S')
    
    # Database Backup
    shutil.copy('database/myp.db', f'backups/db_{timestamp}.db')
    
    # Config Backup
    backup_settings(f'backups/settings_{timestamp}.json')
    
    # Log Backup
    compress_logs(f'backups/logs_{timestamp}.tar.gz')

Recovery-Verfahren

# System-Backup wiederherstellen
sudo ./setup.sh --restore-backup backup_file.zip

# Datenbank-Recovery
sqlite3 database/myp.db ".backup backup_file.db"

# System neu starten
sudo systemctl restart myp-https

Entwicklungsumgebung

Essential Commands

# Development
pip install -r requirements.txt --break-system-packages
npm install
npm run build:css

# Run development server
python app.py --debug

# Run production server
sudo python app.py

# Testing
pytest -v --cov=.
flake8 .
black . --check

Neue Features hinzufügen

1. Neue Blueprint: Erstellen in blueprints/, registrieren in app.py
2. Datenbank-Modell: Hinzufügen zu models.py, Migration erstellen falls nötig
3. Frontend-Assets: CSS in static/css/, JavaScript in static/js/
4. Logging: get_logger("component_name") für konsistentes Logging
5. Berechtigungen: Neue Berechtigungen zum UserPermission-Modell hinzufügen

---

Status: ✅ Vollständig funktional
Letzte Aktualisierung: Januar 2025
Version: 3.1.3 - Kiosk-Fix
Kompatibilität: Python 3.9+, Flask 3.1+, SQLAlchemy 2.0+