📚 Updated project documentation and added CLAUDE setup guide 🎉

2025-06-03 22:33:10 +02:00 · 2025-06-03 22:33:10 +02:00 · 612726698a
commit 612726698a
parent db593d0b82
3 changed files with 203 additions and 59 deletions
--- a/IHK_Projektdokumentation/Dokumentation_Final_Markdown/Dokumentation.md
+++ b/IHK_Projektdokumentation/Dokumentation_Final_Markdown/Dokumentation.md
@ -163,7 +163,7 @@ Einschränkungen verhinderten bislang eine koordinierte digitale
 Verwaltung und damit auch jegliche Übersicht von Reservierungen und 
 Nutzungsplänen.

-Die Technische Berufsausbildungsstätte (TBA) der Mercedes-Benz AG am Standort Berlin verfügt über sechs 3D-Drucker verschiedener Hersteller (Prusa, Anycubic; B-Ware im Vergleich zu 3D-Druckern von Kostenstellen höherer Prioriät sozusagen). Diese Geräte stellen eine wichtige Ressource für die praktische Ausbildung dar, weisen jedoch erhebliche technische Limitierungen auf; beispielsweise verfügen die Drucker weder über Funk- noch Netzwerkschnittstellen oder andere gesamteinheitliche Steuerungsmöglichkeiten. Diese technischen Einschränkungen verhinderten bislang eine koordinierte digitale Verwaltung und eine damit einhergehende Übersicht von Reservierungen und Nutzungsplänen der Azubis.
+Die Technische Berufsausbildungsstätte (TBA) am Standort Berlin verfügt über sechs 3D-Drucker verschiedener Hersteller (Prusa, Anycubic; B-Ware im Vergleich zu 3D-Druckern von Kostenstellen höherer Prioriät sozusagen). Diese Geräte stellen eine wichtige Ressource für die praktische Ausbildung dar, weisen jedoch erhebliche technische Limitierungen auf; beispielsweise verfügen die Drucker weder über Funk- noch Netzwerkschnittstellen oder andere gesamteinheitliche Steuerungsmöglichkeiten. Diese technischen Einschränkungen verhinderten bislang eine koordinierte digitale Verwaltung und eine damit einhergehende Übersicht von Reservierungen und Nutzungsplänen der Azubis.

 Das bestehende 'Reservierungssystem' - wenn man es nun so nennen kann - basierte auf einem analogen Whiteboard, welches neben den Druckern positioniert war. Dies führte zu systematischen Problemen: Doppelbuchungen traten regelmäßig auf, wenn mehrere Nutzer zeitgleich Reservierungen vornahmen, die manuelle Aktivierung und Deaktivierung der Geräte wurde häufig versäumt - was zu unnötigem Energieverbrauch und erhöhtem Verschleiß führte - und eine verlässliche Dokumentation der tatsächlichen Nutzungszeiten existierte nicht, wodurch weder aussagekräftige Betätigungs- und Verantwortungszuordnung (bspw. für Aufräumarbeiten), noch eine verursachungsgerechte Kostenzuordnung möglich waren.

@ -184,7 +184,7 @@ technischen Limitierungen der vorhandenen 3D-Drucker. Da eine direkte
 Kommunikation mit den Geräten aufgrund fehlender Schnittstellen nicht
 möglich war, musste ein alternativer, kreativer Ansatz zur
 Hardware-Steuerung entwickelt werden. Gleichzeitig waren die strengen
-Sicherheitsrichtlinien der Mercedes-Benz AG zu berücksichtigen, die
+unternehmensinternen Sicherheitsrichtlinien zu berücksichtigen, die
 keine direkten, geschweige denn permanenten Internetverbindungen in der
 Produktionsumgebung gestatten – eine Anforderung, die das Projekt
 zusätzlich verkomplizierte.
@ -238,7 +238,7 @@ trotz der Rückschläge als gangbar erwies.
 ## 1.4 Projektumfeld

 Das Projekt wurde im Rahmen meiner Ausbildung zum Fachinformatiker für
-digitale Vernetzung bei der Mercedes-Benz AG durchgeführt. Die
+digitale Vernetzung bei Mercedes durchgeführt. Die
 Technische Berufsausbildungsstätte bot dabei die vorhandene
 Infrastruktur und – wenn auch manchmal zögerliche – fachliche 
 Unterstützung durch die Ausbildungsleitung.
@ -252,7 +252,7 @@ aufbauen und diesen zu einer Gesamtlösung erweitern – eine Konstellation,
 die sich als Segen und Fluch zugleich erweisen sollte.

 Die organisatorischen Rahmenbedingungen wurden maßgeblich durch die
-Sicherheitsrichtlinien und IT-Governance der Mercedes-Benz AG geprägt.
+konzerninternen Sicherheitsrichtlinien und IT-Governance geprägt.
 Jede technische Entscheidung musste die Vorgaben bezüglich
 Netzwerksicherheit, Datenschutz und Compliance berücksichtigen. Die
 Beantragung notwendiger Administratorrechte und die Genehmigung
@ -425,8 +425,8 @@ proprietäre API erforderte erheblichen Reverse-Engineering-Aufwand
 mittels Wireshark.

 Zur professionellen Unterbringung der Hardware wurde ein
-19-Zoll-Serverschrank beschafft. Die internen Beschaffungsprozesse der
-Mercedes-Benz AG erwiesen sich jedoch als so langwierig, dass ergänzende
+19-Zoll-Serverschrank beschafft. Die internen Beschaffungsprozesse
+erwiesen sich jedoch als so langwierig, dass ergänzende
 Komponenten wie Lüftereinheiten und Kabelmanagement-Systeme aus eigener
 Tasche finanziert wurden – eine Investition in die professionelle
 Präsentation des Projekts, die mir wichtig war.
@ -755,7 +755,7 @@ Web-Requests.

 ## 3.5 Konfiguration von Übertragungssystemen und Integration in die Gesamtinfrastruktur

-Die Integration in die Mercedes-Benz-Infrastruktur erforderte zahlreiche
+Die Integration in die Unternehmensinfrastruktur erforderte zahlreiche
 Kompromisse und kreative Lösungen. Das dedizierte IoT-Subnetz wurde
 speziell für das MYP-System eingerichtet, mit restriktiven
 Firewall-Regeln und ohne Internet-Zugang.
@ -857,7 +857,7 @@ erforderte zusätzliche Systemkonfiguration: Openbox als minimalistisches
 Desktop-Environment, Chromium im Kiosk-Modus mit automatischem Start
 dreier Instanzen – eine auf Port 443, eine auf Port 80 als Fallback für
 die API, sowie eine lokale Instanz auf Port 5000 für den Kiosk-Modus.
-Die Mercedes Root-CA-Zertifikate mussten manuell installiert werden; ein
+Die Unternehmens-Root-CA-Zertifikate mussten manuell installiert werden; ein
 Shell-Skript automatisierte diesen Prozess, eine systemd-Service-Datei
 gewährleistete den Autostart. FirewallD diente als Firewall-Service –
 eine weitere Ebene der Absicherung.
@ -904,8 +904,8 @@ Die modulare Architektur und umfassende API ermöglichen die Integration
 zusätzlicher Funktionalitäten ohne grundlegende Systemänderungen – ein
 Fundament, auf dem aufgebaut werden kann.

-Kurzfristig ist die Anbindung an das Active Directory der Mercedes-Benz
-AG geplant. Die vorbereiteten Schnittstellen ermöglichen eine nahtlose
+Kurzfristig ist die Anbindung an das unternehmenseigene Active Directory
+geplant. Die vorbereiteten Schnittstellen ermöglichen eine nahtlose
 Integration, sobald die erforderlichen Genehmigungen vorliegen. Diese
 Erweiterung würde die Benutzerverwaltung erheblich vereinfachen und die
 Akzeptanz im Unternehmensumfeld steigern.
--- a/backend/CLAUDE.md
+++ b/backend/CLAUDE.md
@ -0,0 +1,183 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+MYP (Manage Your Printers) is a comprehensive 3D printer management system for Mercedes-Benz, designed to run on Debian/Linux systems (especially Raspberry Pi) in HTTPS kiosk mode. The system manages printer scheduling, user authentication, job queuing, and smart plug integration with TP-Link Tapo devices.
+
+## Essential Commands
+
+### Development
+```bash
+# Install dependencies
+pip install -r requirements.txt --break-system-packages
+npm install
+
+# Build CSS (TailwindCSS)
+npm run build:css
+npm run watch:css  # For development with auto-reload
+
+# Run development server (HTTP on port 5000)
+python app.py --debug
+
+# Run production server (HTTPS on port 443)
+sudo python app.py
+```
+
+### Testing & Validation
+```bash
+# Lint Python code
+flake8 .
+black . --check
+isort . --check
+
+# Run tests
+pytest
+pytest -v --cov=.  # With coverage
+
+# Test SSL certificates
+python -c "from utils.ssl_config import ensure_ssl_certificates; ensure_ssl_certificates('.', True)"
+
+# Test database connection
+python -c "from models import init_database; init_database()"
+```
+
+### Deployment & Services
+```bash
+# Full installation (use setup.sh)
+sudo ./setup.sh
+
+# Service management
+sudo systemctl status myp-https
+sudo systemctl restart myp-https
+sudo systemctl enable myp-kiosk  # For kiosk mode
+
+# View logs
+sudo journalctl -u myp-https -f
+tail -f logs/app/app.log
+```
+
+### Database Operations
+```bash
+# Initialize database
+python -c "from models import init_database; init_database()"
+
+# Create backup
+python -c "from utils.backup_manager import BackupManager; BackupManager().create_backup()"
+
+# Clean up database
+python utils/database_cleanup.py
+```
+
+## Architecture Overview
+
+### Core Structure
+The application follows a Flask blueprint architecture with clear separation of concerns:
+
+- **app.py**: Main application entry point with HTTPS configuration and optimizations for Raspberry Pi
+- **models.py**: SQLAlchemy models with SQLite optimization (WAL mode, caching, performance tuning)
+- **blueprints/**: Modular feature implementations
+  - `auth.py`: Authentication and session management
+  - `admin.py` & `admin_api.py`: Administrative interfaces and APIs
+  - `printers.py`: Printer management and smart plug integration
+  - `jobs.py`: Job queue management
+  - `guest.py`: Guest access with OTP system
+  - `calendar.py`: Scheduling with conflict management
+  - `users.py` & `user.py`: User management and profiles
+
+### Key Design Patterns
+
+1. **Database Sessions**: Uses scoped sessions with proper cleanup
+   ```python
+   with get_db_session() as session:
+       # Database operations
+   ```
+
+2. **Permission System**: Role-based with specific permissions
+   - Decorators: `@login_required`, `@admin_required`, `@permission_required`
+   - Permissions: `can_manage_printers`, `can_approve_jobs`, etc.
+
+3. **Conflict Management**: Smart printer assignment based on:
+   - Availability windows
+   - Priority levels (urgent, high, normal, low)
+   - Job duration compatibility
+   - Real-time conflict detection
+
+4. **Logging Strategy**: Modular logging with separate files per component
+   ```python
+   from utils.logging_config import get_logger
+   logger = get_logger("component_name")
+   ```
+
+### Frontend Architecture
+
+- **TailwindCSS**: Utility-first CSS with custom optimizations for Raspberry Pi
+- **Vanilla JavaScript**: No heavy frameworks, optimized for performance
+- **Progressive Enhancement**: Works without JavaScript, enhanced with it
+- **Service Workers**: For offline capability and performance
+
+### Security Considerations
+
+- **SSL/TLS**: Self-signed certificates with automatic generation
+- **CSRF Protection**: Enabled globally with Flask-WTF
+- **Session Security**: Secure cookies, HTTPOnly, SameSite=Lax
+- **Rate Limiting**: Built-in for API endpoints
+- **Input Validation**: WTForms for all user inputs
+
+### Performance Optimizations
+
+1. **Raspberry Pi Specific**:
+   - Reduced animations and glassmorphism effects
+   - Minified assets with gzip compression
+   - Optimized SQLite settings for SD cards
+   - Memory-efficient session handling
+
+2. **Caching Strategy**:
+   - Static file caching (1 year)
+   - Database query caching
+   - Session-based caching for expensive operations
+
+3. **Database Optimizations**:
+   - WAL mode for concurrent access
+   - Proper indexing on foreign keys
+   - Connection pooling with StaticPool
+   - Automatic cleanup of old records
+
+### Integration Points
+
+1. **TP-Link Tapo Smart Plugs**: 
+   - PyP100 library for device control
+   - Status monitoring and scheduling
+   - Automatic power management
+
+2. **Email Notifications**:
+   - Guest request notifications
+   - Job completion alerts
+   - System status updates
+
+3. **File Uploads**:
+   - Support for STL, OBJ, 3MF, AMF, GCODE
+   - Secure file handling with validation
+   - Organized storage in uploads/ directory
+
+### Common Development Tasks
+
+When adding new features:
+
+1. **New Blueprint**: Create in `blueprints/`, register in `app.py`
+2. **Database Model**: Add to `models.py`, create migration if needed
+3. **Frontend Assets**: 
+   - CSS in `static/css/components.css`
+   - JavaScript in `static/js/` 
+   - Run `npm run build:css` after CSS changes
+4. **Logging**: Use `get_logger("component_name")` for consistent logging
+5. **Permissions**: Add new permissions to `UserPermission` model
+
+### Debugging Tips
+
+- Check logs in `logs/` directory for component-specific issues
+- Use `--debug` flag for development server
+- Database locked errors: Check for WAL files (`*.db-wal`, `*.db-shm`)
+- SSL issues: Regenerate certificates with `utils/ssl_config.py`
+- Performance issues: Check `/api/stats` endpoint for metrics
--- a/backend/setup.sh
+++ b/backend/setup.sh
@ -24,11 +24,11 @@ readonly WATCHDOG_PYTHON_SERVICE_NAME="kiosk-watchdog-python"
 readonly FIREWALL_SERVICE_NAME="myp-firewall"
 readonly KIOSK_USER="kiosk"
 readonly CURRENT_DIR="$(pwd)"
-# Log-Dateien (nicht readonly, damit wir Fallback nutzen können)
-INSTALL_LOG="logs/myp-install.log"
-ERROR_LOG="logs/myp-install-errors.log"
-WARNING_LOG="logs/myp-install-warnings.log"
-DEBUG_LOG="logs/myp-install-debug.log"
+# Log-Dateien - verwende direkt /tmp als sicheren Ort
+INSTALL_LOG="/tmp/myp-install.log"
+ERROR_LOG="/tmp/myp-install-errors.log"
+WARNING_LOG="/tmp/myp-install-warnings.log"
+DEBUG_LOG="/tmp/myp-install-debug.log"
 readonly HTTPS_PORT="443"
 readonly HTTPS_URL="https://localhost:${HTTPS_PORT}"
 readonly SYSTEMD_DIR="$CURRENT_DIR/systemd"
@ -54,35 +54,8 @@ WARNING_COUNT=0

 # Log-Dateien initialisieren
 init_logging() {
-    # Versuche logs-Verzeichnis in verschiedenen Locations zu erstellen
-    local log_dir_created=false
-    
-    # Versuch 1: Im aktuellen Arbeitsverzeichnis
-    if mkdir -p "logs" 2>/dev/null; then
-        log_dir_created=true
-    fi
-    
-    # Versuch 2: Im CURRENT_DIR (falls gesetzt und verschieden)
-    if [ "$log_dir_created" = false ] && [ -n "$CURRENT_DIR" ] && [ "$CURRENT_DIR" != "$(pwd)" ]; then
-        if mkdir -p "$CURRENT_DIR/logs" 2>/dev/null; then
-            log_dir_created=true
-            # Aktualisiere Pfade
-            INSTALL_LOG="$CURRENT_DIR/logs/myp-install.log"
-            ERROR_LOG="$CURRENT_DIR/logs/myp-install-errors.log"
-            WARNING_LOG="$CURRENT_DIR/logs/myp-install-warnings.log"
-            DEBUG_LOG="$CURRENT_DIR/logs/myp-install-debug.log"
-        fi
-    fi
-    
-    # Versuch 3: Fallback auf /tmp
-    if [ "$log_dir_created" = false ] || [ ! -w "logs" -a ! -w "$CURRENT_DIR/logs" ]; then
-        # Fallback auf /tmp wenn logs nicht schreibbar
-        export INSTALL_LOG="/tmp/myp-install.log"
-        export ERROR_LOG="/tmp/myp-install-errors.log"
-        export WARNING_LOG="/tmp/myp-install-warnings.log"
-        export DEBUG_LOG="/tmp/myp-install-debug.log"
-        echo "WARNUNG: logs-Verzeichnis nicht erstellbar, verwende /tmp" >&2
-    fi
+    # Logs gehen immer nach /tmp - das funktioniert IMMER
+    # Keine komplexen Checks mehr nötig!
    
    # Initialisiere alle Log-Dateien
    {
@ -262,7 +235,7 @@ show_error_summary() {

 # Automatische Log-Zusammenfassung erstellen
 create_log_summary() {
-    local summary_file="logs/myp-install-summary.txt"
+    local summary_file="/tmp/myp-install-summary.txt"
    
    {
        echo "================================================================="
@ -2473,10 +2446,7 @@ show_menu() {

 # =========================== INSTALLATIONS-MODI ===========================
 install_dependencies_only() {
-    # Erstelle logs-Verzeichnis SOFORT
-    mkdir -p "$CURRENT_DIR/logs" 2>/dev/null || mkdir -p "logs" 2>/dev/null || true
-    
-    # Logging initialisieren
+    # Logging initialisieren (verwendet /tmp für Logs)
    init_logging
    
    log "=== MODUS: ROBUSTE ABHÄNGIGKEITEN-INSTALLATION FÜR MANUELLES TESTEN ==="
@ -2566,10 +2536,7 @@ install_dependencies_only() {
 }

 install_full_production_system() {
-    # Erstelle logs-Verzeichnis SOFORT
-    mkdir -p "$CURRENT_DIR/logs" 2>/dev/null || mkdir -p "logs" 2>/dev/null || true
-    
-    # Logging initialisieren
+    # Logging initialisieren (verwendet /tmp für Logs)
    init_logging
    
    log "=== MODUS: VOLLSTÄNDIGE ROBUSTE KIOSK-INSTALLATION MIT REMOTE-ZUGANG ==="
@ -3481,12 +3448,6 @@ main() {
    # Stelle sicher, dass wir im richtigen Verzeichnis sind
    cd "$CURRENT_DIR" 2>/dev/null || true
    
-    # Erstelle logs-Verzeichnis im aktuellen Projektverzeichnis
-    mkdir -p "$CURRENT_DIR/logs" 2>/dev/null || {
-        # Fallback: Erstelle logs im aktuellen Verzeichnis
-        mkdir -p "logs" 2>/dev/null || true
-    }
-    
    while true; do
        show_menu
        read -r choice