feat: duplicate detection via perceptual hashing

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docs/superpowers/specs/2026-04-07-foto-kurator-design.md

@@ -0,0 +1,136 @@
+# Foto-Kurator — Design Spec
+
+**Datum:** 2026-04-07  
+**Status:** Genehmigt
+
+## Überblick
+
+Eine lokale Webanwendung, die den manuellen Foto-Culling-Prozess automatisiert. Das Tool analysiert einen Ordner voller Fotos und sortiert unbrauchbare Bilder (unscharf, über-/unterbelichtet, Duplikate) automatisch in einen Unterordner `_aussortiert/` aus.
+
+## Architektur
+
+```
+┌─────────────────────────────────┐
+│        Browser (Frontend)       │
+│  HTML/CSS/JS — Single Page App  │
+│  - Ordner auswählen             │
+│  - Einstellungen / Toggles      │
+│  - Fortschrittsanzeige          │
+│  - Review-Ansicht               │
+└────────────┬────────────────────┘
+             │ HTTP (localhost)
+┌────────────▼────────────────────┐
+│     Python FastAPI Backend      │
+│  - /analyze  → Fotos analysieren│
+│  - /move     → Dateien verschieben│
+│  - Pillow + OpenCV              │
+│  - optional: Claude Vision API  │
+└─────────────────────────────────┘
+             │ Dateisystem
+┌────────────▼────────────────────┐
+│  Lokaler Ordner (z.B. /Fotos/)  │
+│  ├── foto001.jpg                │
+│  ├── foto002.jpg                │
+│  └── _aussortiert/              │
+│       └── foto003.jpg           │
+└─────────────────────────────────┘
+```
+
+## Stack
+
+- **Backend:** Python 3.10+, FastAPI, Pillow, OpenCV, imagehash, anthropic SDK (optional)
+- **Frontend:** Vanilla HTML/CSS/JS (eine einzelne `index.html`)
+- **Start:** `python server.py` → öffnet automatisch den Browser
+
+## Projektstruktur
+
+```
+foto-kurator/
+├── server.py          # FastAPI Backend + Startup
+├── analyzer.py        # Bildanalyse-Logik (lokal + KI)
+├── index.html         # Frontend (Single Page App)
+├── requirements.txt
+└── .env               # ANTHROPIC_API_KEY (optional)
+```
+
+## Analysekriterien
+
+### Lokale Analyse (immer verfügbar)
+
+| Kriterium | Methode | Standardschwellenwert |
+|-----------|---------|----------------------|
+| Unschärfe | Laplacian Variance (OpenCV) | < 100 |
+| Überbelichtung | Durchschnittliche Helligkeit > Schwellenwert (Pillow) | > 240 |
+| Unterbelichtung | Durchschnittliche Helligkeit < Schwellenwert (Pillow) | < 30 |
+| Duplikate | Perceptual Hash (pHash, imagehash) | Hamming-Distanz ≤ 8 |
+
+Alle Schwellenwerte sind in der UI per Schieberegler einstellbar.
+
+### KI-Analyse (optional, Toggle)
+
+Sendet Fotos batchartig an die Claude Vision API mit einem Qualitäts-Bewertungsprompt. Erkennt auch subtilere Probleme (schlechter Bildaufbau, störende Elemente, etc.).
+
+- **Kosten:** ca. 0,002–0,005 € pro Foto
+- **Anforderung:** Internetverbindung + `ANTHROPIC_API_KEY` in `.env`
+- **Fallback:** Bei API-Fehler wird automatisch auf lokale Analyse zurückgefallen
+
+## UI & Workflow
+
+### Startseite
+- Ordner-Auswahl: Texteingabe für den lokalen Pfad (z.B. `/Fotos/Shooting-2026-04`) + Button zum Bestätigen. Optional: nativer Ordner-Dialog via `tkinter` im Backend, der den Pfad zurückgibt.
+- **Toggle:** Überprüfung vor dem Verschieben (an/aus)
+- **Toggle:** KI-Analyse (an/aus) + Hinweis zu Kosten & Internetanforderung
+- Schieberegler für alle Schwellenwerte
+- Button: "Analyse starten"
+
+### Während der Analyse
+- Fortschrittsbalken mit aktuellem Dateinamen
+- Abbruch-Button
+
+### Review-Ansicht (wenn Toggle aktiv)
+- Liste aller vorgeschlagenen Ausschüsse
+- Pro Foto: Vorschaubild + Begründung (z.B. "unterbelichtet", "Duplikat von foto002.jpg")
+- Jedes Foto einzeln bestätigen oder von der Liste entfernen
+- Button: "Alle bestätigen & verschieben"
+
+### Ohne Review (Toggle deaktiviert)
+- Direktes Verschieben nach Analyse
+- Kurze Zusammenfassung: "23 Fotos aussortiert"
+
+### Ergebnisseite
+- Anzahl analysierter Fotos
+- Anzahl aussortierter Fotos, aufgeteilt nach Grund
+- Hinweis auf `_aussortiert/`-Unterordner
+
+## Datenfluss
+
+1. Frontend schickt Ordnerpfad an `POST /analyze`
+2. Backend iteriert über alle `.jpg/.jpeg/.png` im Ordner
+3. Pro Foto: Unschärfe + Belichtung berechnen, pHash für Duplikatvergleich
+4. Optional: Fotos batchartig an Claude Vision API senden
+5. Antwort: JSON-Liste `[{ path, reasons: ["unscharf", ...] }]`
+6. Frontend zeigt Review-Ansicht oder schickt direkt `POST /move`
+7. Backend verschiebt Dateien in `_aussortiert/`
+
+## Fehlerbehandlung
+
+- Korrupte oder nicht lesbare Dateien werden übersprungen und in einem Log festgehalten
+- API-Fehler (Claude Vision) fallen automatisch auf lokale Analyse zurück
+- Kein Foto wird ohne expliziten `/move`-Aufruf verschoben — die Analyse ist immer nicht-destruktiv
+
+## Unterstützte Formate
+
+- **Primär:** `.jpg`, `.jpeg`, `.png`
+- **Selten:** RAW-Formate (`.CR2`, `.NEF`, `.ARW`) — in Phase 1 nicht unterstützt, für spätere Version vorgesehen
+
+## Setup
+
+```bash
+pip install -r requirements.txt
+python server.py
+# Browser öffnet automatisch http://localhost:8000
+```
+
+## Erweiterbarkeit
+
+Die Architektur ist so ausgelegt, dass das Tool später als echter Webserver mit mehreren Nutzern betrieben werden kann. Der einzige erforderliche Schritt ist die Umstellung der Ordnerpfad-Logik auf nutzerspezifische Upload-Verzeichnisse.