# Plan: STL-Bibliothek („PrintVault")

**Datum:** 2026-05-17
**Status:** Planung — nur Diskussion, keine Implementation

---

## 1. Ziel

Eine Web-App auf ZimaOS, die STL-Dateien speichert, schön sortiert anzeigt und automatisch analysiert. Nur Boss + Kiwi haben Zugriff. Von überall im Netzwerk erreichbar.

## 2. Vorbild: DocMaster

| Aspekt | DocMaster | PrintVault |
|---|---|---|
| Server | Next.js | Python (FastAPI) |
| Port | 3000 | 3001 |
| Speicher | `/DATA/.media/HDD_1TB/DocMaster/uploads/` | `/media/HDD_1TB/STL_Bibliothek/stls/` |
| Meta | `.metadata.json` im selben Ordner | `metadata.json` |
| Auth | Basic Auth `ahmed:…` | Basic Auth (gleiches Passwort oder eigenes) |
| Zugriff | Localhost + Netzwerk | Localhost + Netzwerk |
| Thumbnails | — | `/media/HDD_1TB/STL_Bibliothek/thumbs/` |

## 3. Architektur

```
┌─────────────────────────────────────────┐
│            Browser (any device)          │
│         http://zimaos:3001              │
└─────────────────┬───────────────────────┘
                  │ HTTP Basic Auth
┌─────────────────▼───────────────────────┐
│         FastAPI Backend (Python)        │
│  - POST /api/upload      (STL upload)   │
│  - GET  /api/files       (Liste)        │
│  - GET  /api/files/{id}  (Detail+Analyse)│
│  - DELETE /api/files/{id}               │
│  - PATCH /api/files/{id} (Tags, Name)   │
│  - GET  /api/thumbs/{id}.png            │
│  - Static: HTML/CSS/JS Frontend         │
└─────────────┬───────────────────────────┘
              │ trimesh + manifold3d
┌─────────────▼───────────────────────────┐
│              HDD Speicher               │
│  stls/       → Original STL-Dateien     │
│  thumbs/     → Generierte PNG-Previews  │
│  metadata.json → Tags, Namen, Analyse   │
└─────────────────────────────────────────┘
```

### Warum FastAPI statt Next.js?
- Python können wir direkt; trimesh ist schon im venv
- Kein Node.js/npm-Setup nötig
- Schneller zu bauen, weniger Boilerplate
- Ein einziger Prozess (kein separater Node-Server)

## 4. Features

### Core (MVP)
- **Upload:** Drag & Drop oder Button, akzeptiert nur `.stl`
- **Analyse (automatisch nach Upload):**
  - Bounding Box (X×Y×Z mm)
  - Volumen (cm³)
  - Polygon-Count (Faces)
  - Watertight ✅/❌
  - Manifold ✅/❌
- **Grid-Ansicht:** Kacheln mit Thumbnail + Name + Maße
- **Detail-Ansicht:** Alle Analyse-Daten, Vorschaubild
- **Löschen:** STL + Thumbnail entfernen
- **Sortieren:** Nach Name, Datum, Größe, Volumen
- **Suchfilter:** Textsuche im Namen

### Nice-to-have (Phase 2)
- Tags / Kategorien („Deko", „Ersatzteil", „Spielzeug", „Küche")
- Filament-Schätzung (PLA: Volumen × 1.24 g/cm³)
- 3D-Vorschau (three.js im Browser)
- Bulk-Upload

## 5. Tech-Details

### Analyse-Pipeline (trimesh)
```python
mesh = trimesh.load(path)
dims = mesh.bounding_box.extents        # X, Y, Z in mm
volume = mesh.volume / 1000             # mm³ → cm³
faces = len(mesh.faces)
is_watertight = mesh.is_watertight
is_manifold = mesh.is_manifold           # manifold3d check
```

### Thumbnail-Generierung
- Option A: `trimesh.scene.Scene` → `save_image()` → PNG
- Option B: matplotlib 3D-Plot (sieht hübscher aus, braucht kein Display)
- Empfehlung: Option A (trimesh nativ, kein X-Server nötig)

### Auth
- HTTP Basic Auth (wie DocMaster)
- Middleware in FastAPI (simple, kein Token-Management)

## 6. Deployment

```
# Als systemd-Service (empfohlen) oder manuell:
cd /DATA/AppData/hermes/projects/stl-bibliothek
source /DATA/AppData/hermes/venv/bin/activate
uvicorn main:app --host 0.0.0.0 --port 3001
```

Netzwerk-Zugriff: ZimaOS ist im lokalen Netz, Port 3001 muss offen sein.

## 7. Risiken / Offene Fragen

| Frage | Status |
|---|---|
| **Port 3001 frei?** | Müssen wir prüfen |
| **Basic Auth – eigenes PW?** | Boss-Entscheidung |
| **ZimaOS Firewall für Port 3001?** | Prüfen, ob Port nach außen offen sein muss |
| **Große STL-Dateien?** | Upload-Limit setzen (z.B. 50 MB), Streaming-Upload in FastAPI |
| **Frontend: Framework?** | Reines HTML/CSS/JS (wie DailyDose) = simpel + schnell. Oder Vue/Alpine für mehr Komfort? |
| **Speicher nur auf HDD?** | Ja, HDD ist persistent und groß genug |

## 8. Geschätzter Aufwand

- Backend (FastAPI + trimesh): ~150 Zeilen Python
- Frontend (HTML/CSS/JS Grid + Upload): ~300 Zeilen
- Thumbnail + Analyse: ~50 Zeilen
- **Total:** ~500 Zeilen, ca. 1 Session

---

## 9. Nächster Schritt

Boss muss entscheiden:
1. **Extra Passwort für PrintVault oder gleiches wie DocMaster?**
2. **Frontend-Style:** Minimal wie DailyDose, oder aufwändiger?
3. **Sofort starten oder erst planen?**