Till Tomczak ff83dd186d "feat: Implement debug fix in static files

2025-05-29 20:17:53 +02:00

11 KiB

Raw Blame History

Mercedes-Benz MYP - File Management System

Übersicht

Das MYP File Management System bietet eine organisierte, sichere und skalierbare Lösung für das Hochladen, Speichern und Verwalten von Dateien in der Mercedes-Benz MYP Platform.

Verzeichnisstruktur

Das System organisiert alle hochgeladenen Dateien in einer strukturierten Hierarchie:

uploads/
├── jobs/                    # Druckjob-Dateien
│   ├── 2025/
│   │   ├── 01/
│   │   │   ├── user_1/
│   │   │   ├── user_2/
│   │   │   └── ...
│   │   ├── 02/
│   │   └── ...
│   └── 2024/
├── guests/                  # Gastauftrags-Dateien
│   ├── 2025/
│   │   ├── 01/
│   │   └── ...
│   └── 2024/
├── avatars/                 # Benutzer-Avatare
│   ├── 2025/
│   │   ├── 01/
│   │   │   ├── user_1/
│   │   │   ├── user_2/
│   │   │   └── ...
│   │   └── ...
│   └── 2024/
├── temp/                    # Temporäre Dateien
├── backups/                 # Backup-Dateien
├── logs/                    # Exportierte Logs
└── assets/                  # Statische Assets

Benennungskonventionen

Dateinamen-Schema

Alle hochgeladenen Dateien erhalten automatisch einen eindeutigen Namen:

{prefix}_{original_name}_{timestamp}.{extension}

Beispiele:

job_Druckteil_v2_20250529_143052.stl
guest_Prototyp_20250529_143052.gcode
avatar_profilbild_20250529_143052.jpg

Verzeichnis-Organisation

Jahr/Monat-Struktur: YYYY/MM/
Benutzer-spezifisch: user_{user_id}/ für persönliche Dateien
Kategorie-basiert: Trennung nach Dateityp und Verwendungszweck

API-Endpunkte

File Upload

Job-Datei hochladen

POST /api/upload/job
Content-Type: multipart/form-data

Form Data:
- file: Die hochzuladende Datei
- job_name: Name des Jobs (optional)

Antwort:

{
  "success": true,
  "message": "Datei erfolgreich hochgeladen",
  "file_path": "jobs/2025/01/user_1/job_Druckteil_20250529_143052.stl",
  "filename": "Druckteil.stl",
  "unique_filename": "job_Druckteil_20250529_143052.stl",
  "file_size": 1048576,
  "metadata": {
    "original_filename": "Druckteil.stl",
    "uploader_id": 1,
    "uploader_name": "max.mustermann",
    "upload_timestamp": "2025-05-29T14:30:52.123456"
  }
}

Gastauftrag-Datei hochladen

POST /api/upload/guest
Content-Type: multipart/form-data

Form Data:
- file: Die hochzuladende Datei
- guest_name: Name des Gasts (optional)
- guest_email: E-Mail des Gasts (optional)

Avatar hochladen

POST /api/upload/avatar
Content-Type: multipart/form-data

Form Data:
- file: Das Avatar-Bild (PNG, JPG, JPEG, GIF, WebP)

File Access

Datei abrufen

GET /api/files/{file_path}

Zugriffskontrolle:

Job-Dateien: Nur Besitzer und Administratoren
Gast-Dateien: Nur Administratoren
Avatar-Dateien: Alle angemeldeten Benutzer
Andere Dateien: Nur Administratoren

Datei löschen

DELETE /api/files/{file_path}

Admin-Funktionen

Datei-Statistiken abrufen

GET /api/admin/files/stats

Antwort:

{
  "success": true,
  "categories": {
    "jobs": {
      "file_count": 45,
      "total_size": 52428800,
      "total_size_mb": 50.0
    },
    "guests": {
      "file_count": 12,
      "total_size": 10485760,
      "total_size_mb": 10.0
    }
  },
  "totals": {
    "file_count": 57,
    "total_size": 62914560,
    "total_size_mb": 60.0
  }
}

Temporäre Dateien aufräumen

POST /api/admin/files/cleanup
Content-Type: application/json

{
  "max_age_hours": 24
}

Sicherheitsfeatures

Dateityp-Validierung

Das System erlaubt nur spezifische Dateitypen:

ALLOWED_EXTENSIONS = {
    'txt', 'pdf', 'png', 'jpg', 'jpeg', 'gif', 
    'gcode', '3mf', 'stl', 'webp'
}

Dateigrößen-Limits

Standard-Maximum: 16 MB
Konfigurierbar über MAX_CONTENT_LENGTH

Zugriffskontrolle

Benutzer-spezifische Isolation: Benutzer können nur auf ihre eigenen Dateien zugreifen
Admin-Privilegien: Administratoren haben Vollzugriff
Kategorie-basierte Beschränkungen: Verschiedene Regeln für verschiedene Dateitypen

Sichere Dateinamen

Werkzeug.secure_filename(): Entfernt schädliche Zeichen
Eindeutige Timestamps: Verhindert Namenskonflikte
Präfix-System: Kategorisierung und Identifikation

Verwendung im Code

FileManager Klasse

from utils.file_manager import file_manager

# Datei speichern
result = file_manager.save_file(
    file=uploaded_file,
    category='jobs',
    user_id=user.id,
    prefix='job',
    metadata={'job_name': 'Prototyp v1'}
)

if result:
    relative_path, absolute_path, metadata = result
    # Pfad in Datenbank speichern
    job.file_path = relative_path

Convenience-Funktionen

from utils.file_manager import save_job_file, save_guest_file, save_avatar_file

# Job-Datei speichern
result = save_job_file(file, user_id, metadata)

# Gast-Datei speichern  
result = save_guest_file(file, metadata)

# Avatar speichern
result = save_avatar_file(file, user_id)

Datei-Operationen

from utils.file_manager import delete_file, get_file_info

# Datei löschen
success = delete_file('jobs/2025/01/user_1/job_test_20250529_143052.stl')

# Datei-Informationen abrufen
info = get_file_info('jobs/2025/01/user_1/job_test_20250529_143052.stl')
if info:
    print(f"Dateigröße: {info['size']} Bytes")
    print(f"Erstellt: {info['created']}")

Wartung und Monitoring

Automatische Bereinigung

Das System bietet automatische Bereinigung von temporären Dateien:

# Dateien älter als 24 Stunden löschen
deleted_count = file_manager.cleanup_temp_files(max_age_hours=24)

Statistiken und Monitoring

# Kategorie-Statistiken abrufen
stats = file_manager.get_category_stats()

for category, info in stats.items():
    print(f"{category}: {info['file_count']} Dateien, {info['total_size_mb']} MB")

Datei-Migration

# Datei in andere Kategorie verschieben
new_path = file_manager.move_file(
    old_relative_path='temp/file.stl',
    new_category='jobs',
    new_prefix='job'
)

Error Handling

Das System implementiert umfassendes Error Handling:

Häufige Fehler

Ungültiger Dateityp

{"error": "Dateityp nicht erlaubt: example.exe"}

Datei zu groß

{"error": "Datei überschreitet maximale Größe von 16 MB"}

Unbekannte Kategorie

{"error": "Unbekannte Kategorie: invalid_category"}

Zugriff verweigert
```
{"error": "Zugriff verweigert"}
```

Logging

Alle Datei-Operationen werden vollständig geloggt:

2025-05-29 14:30:52 - [APP] - INFO - Job-Datei hochgeladen: Prototyp.stl von User 1
2025-05-29 14:31:15 - [APP] - INFO - Datei gelöscht: jobs/.../old_file.stl von User 1
2025-05-29 14:32:00 - [APP] - INFO - Temporäre Dateien aufgeräumt: 5 Dateien gelöscht

Performance-Optimierungen

Async Operations

Non-blocking File I/O: Datei-Operationen blockieren nicht die Hauptanwendung
Background Cleanup: Automatische Bereinigung läuft im Hintergrund

Storage Efficiency

Komprimierung: Automatische Komprimierung für bestimmte Dateitypen
Deduplizierung: Vermeidung von Duplikaten durch Hash-Vergleich
Archivierung: Alte Dateien werden automatisch archiviert

Caching

Metadata Caching: Datei-Metadaten werden gecacht
Path Resolution: Schnelle Pfad-Auflösung

Konfiguration

Umgebungsvariablen

MYP_UPLOAD_FOLDER=/path/to/uploads
MYP_MAX_FILE_SIZE=16777216  # 16 MB in Bytes
MYP_ALLOWED_EXTENSIONS=stl,gcode,3mf,jpg,png
MYP_AUTO_CLEANUP_HOURS=24

settings.py

UPLOAD_FOLDER = os.path.join(BASE_DIR, "uploads")
ALLOWED_EXTENSIONS = {'txt', 'pdf', 'png', 'jpg', 'jpeg', 'gif', 'gcode', '3mf', 'stl'}
MAX_CONTENT_LENGTH = 16 * 1024 * 1024  # 16MB

Integration mit Frontend

JavaScript Upload

async function uploadJobFile(file, jobName) {
    const formData = new FormData();
    formData.append('file', file);
    formData.append('job_name', jobName);
    
    const response = await fetch('/api/upload/job', {
        method: 'POST',
        body: formData,
        headers: {
            'X-CSRFToken': csrfToken
        }
    });
    
    return await response.json();
}

Progress Tracking

function uploadWithProgress(file, onProgress) {
    return new Promise((resolve, reject) => {
        const xhr = new XMLHttpRequest();
        const formData = new FormData();
        formData.append('file', file);
        
        xhr.upload.addEventListener('progress', (e) => {
            if (e.lengthComputable) {
                const percentComplete = (e.loaded / e.total) * 100;
                onProgress(percentComplete);
            }
        });
        
        xhr.addEventListener('load', () => {
            resolve(JSON.parse(xhr.responseText));
        });
        
        xhr.open('POST', '/api/upload/job');
        xhr.send(formData);
    });
}

Best Practices

Für Entwickler

Immer Dateityp validieren vor dem Upload
Benutzer-spezifische Pfade verwenden für persönliche Dateien
Metadaten speichern für bessere Nachverfolgbarkeit
Error Handling implementieren für alle Datei-Operationen
Cleanup-Routinen verwenden für temporäre Dateien

Für Administratoren

Regelmäßige Backups der Upload-Verzeichnisse
Monitoring der Speichernutzung
Periodische Bereinigung alter Dateien
Sicherheitsscans auf schädliche Dateien
Access-Log-Überwachung

Troubleshooting

Häufige Probleme

Upload schlägt fehl

# Verzeichnis-Berechtigungen prüfen
ls -la uploads/
chmod 755 uploads/
chown -R www-data:www-data uploads/

Dateien nicht gefunden

# FileManager initialisieren
python -c "from utils.file_manager import file_manager; file_manager.ensure_directories()"

Speicher voll

# Cleanup ausführen
curl -X POST http://localhost:8443/api/admin/files/cleanup \
  -H "Content-Type: application/json" \
  -d '{"max_age_hours": 1}'

Changelog

Version 1.0.0 (2025-05-29)

✅ Grundlegendes File Management System
✅ Organisierte Verzeichnisstruktur
✅ Sicherheits-Features
✅ API-Endpunkte für Upload/Download
✅ Admin-Tools für Verwaltung
✅ Umfassende Dokumentation

11 KiB Raw Blame History