3D-Organizer/README.md

# 3D Project Manager

Eine kleine Docker-basierte Webanwendung, um 3D-Druck-Projekte zu verwalten:
Projekte anlegen, STL-/3MF-Dateien per Drag & Drop hochladen und direkt im
Browser als 3D-Vorschau betrachten.

## Setup

1. `.env.example` nach `.env` kopieren und zwei Werte setzen:

   - `PROJECTS_DIR`: Ordner auf deiner Festplatte, in dem deine Projekte als
     normale Unterordner angelegt werden — den kannst du auch direkt im
     Dateimanager oder Slicer öffnen.

     ```
     PROJECTS_DIR=/home/deinname/3d-projects
     ```

   - `PASSWORD_SHA256`: SHA256-Hash deines gewünschten Login-Passworts.
     Erzeugen z. B. mit:

     ```
     echo -n "meinPasswort" | sha256sum
     ```

     Nur den resultierenden Hex-Hash in die `.env` eintragen, nicht das
     Passwort selbst.

2. Container bauen und starten:

   ```
   docker compose up --build -d
   ```

3. Im Browser öffnen: [http://localhost:8080](http://localhost:8080) —
   du wirst zur Login-Seite weitergeleitet und musst das Passwort eingeben.

## Login

- Es gibt nur ein Passwort, keinen Nutzernamen. Wer das Passwort kennt, hat
  Zugriff.
- Nach erfolgreichem Login wird eine signierte, `HttpOnly`-Session-Cookie
  gesetzt (30 Tage gültig). Der Signierschlüssel liegt im
  `app-settings`-Volume und bleibt über Container-Neustarts hinweg gleich,
  d. h. du bleibst eingeloggt.
- "Abmelden" oben rechts löscht die Session.
- Nach 5 Fehlversuchen in Folge wird der Login für 30 Sekunden gesperrt.
- **Wichtig:** Diese Anwendung ist für den Einsatz auf deinem eigenen
  Desktop/Heimnetz gedacht. Für Zugriff über das Internet solltest du
  zusätzlich HTTPS (z. B. über einen Reverse Proxy) einrichten, da das
  Passwort sonst unverschlüsselt übertragen wird.

## Wie es funktioniert

- **Projekt anlegen** → im Container wird `PROJECTS_DIR/<Projektname>`
  erstellt (durch den Bind-Mount landet das direkt auf deiner Platte).
- **Dateien hochladen** → per Drag & Drop oder Klick auf die Upload-Fläche,
  nur `.stl` und `.3mf` werden akzeptiert. Sie werden 1:1 in den
  Projektordner kopiert.
- **3D-Vorschau** → beim Öffnen eines Projekts wird für jede Datei ein
  eigener Three.js-Viewer (mit Zoom/Rotation per Maus) im Grid angezeigt.
- **App-Einstellungen/Metadaten** liegen ausschließlich im
  `app-settings`-Docker-Volume, nicht in deinem Projektordner. Aktuell
  benötigt die App noch keine eigene Konfiguration, aber der Ordner ist für
  spätere Erweiterungen (z. B. Nutzerverwaltung) bereits vorbereitet.

## Projektstruktur auf der Festplatte

```
<PROJECTS_DIR>/
  Gehäuse-Prototyp/
    deckel.stl
    boden.3mf
  Ersatzteil/
    halterung.stl
```

Reine Ordner mit deinen Dateien — du kannst sie auch außerhalb der App
öffnen, kopieren oder in deinen Slicer ziehen. Lösch- und Umbenennungen
über den Dateimanager wirken sich beim nächsten Laden der Seite ebenfalls
auf die App aus.

## Große Dateien

- Uploads laufen serverseitig in einem Hintergrund-Thread, damit auch bei
  sehr großen Dateien (mehrere GB) der Rest der App währenddessen normal
  bedienbar bleibt.
- ZIP-Downloads (einzelnes Projekt oder alle Projekte) werden auf eine
  temporäre Datei auf der Festplatte geschrieben statt komplett im
  Arbeitsspeicher gehalten zu werden, und danach automatisch wieder
  gelöscht.
- Für Dateien über **150 MB** wird die 3D-Vorschau nicht automatisch
  geladen (das würde bei sehr großen Modellen den Browser-Tab einfrieren
  lassen), sondern zeigt einen "Vorschau laden"-Button an — du entscheidest
  bewusst, ob der Browser versuchen soll, das Modell zu parsen.

## Bekannte Grenzen (erster Wurf)

- Single-User, kein Login.
- Projekt-/Dateinamen sind auf Buchstaben, Zahlen, Leerzeichen, `-` und `_`
  beschränkt (Schutz gegen Pfad-Tricks).
- Kein Undo beim Löschen — es wird aber vorher immer nachgefragt.

## Stack

- Backend: FastAPI (Python), liefert API + statische Frontend-Dateien aus
  einem einzigen Container.
- Frontend: reines HTML/CSS/JS, 3D-Rendering mit Three.js (STLLoader /
  3MFLoader) via CDN.
- Docker Compose mit Bind-Mount für Projekte und separatem Volume für
  App-Settings.