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:
```python
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:
```python
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**:
```bash
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**:
```bash
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

```python
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**:
```bash
# 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**:
```bash
# 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**:
```python
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**
   ```bash
   sudo systemctl status myp-https
   sudo journalctl -u myp-https -f
   ```

2. **Kiosk-Browser startet nicht**
   ```bash
   sudo systemctl status myp-kiosk
   sudo journalctl -u myp-kiosk -f
   ```

3. **SSL-Zertifikat-Probleme**
   ```bash
   sudo ./setup.sh
   # Option 5 für System-Test
   ```

4. **Firewall-Probleme**
   ```bash
   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

```python
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

```bash
# 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

```bash
# 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+