# Fotograf.de Scraper & Management UI

**Status:** Production-Ready Microservice (Core Feature: PDF List Generation, QR Cards, Shooting Schedule, **Siblings List**, **Gmail API Integration** & **Automated Release Requests**)

Dieser Service modernisiert die alten `Fotograf.de` Skripte, indem er eine robuste, web-basierte UI zur Verwaltung und Automatisierung von Foto-Aufträgen bereitstellt. Er ist als eigenständiger Microservice konzipiert, der unabhängig vom Haupt-Stack läuft.

## 🏗️ Architektur

Der Service besteht aus zwei Hauptkomponenten:

1.  **Backend (Python / FastAPI / Selenium / SQLAlchemy):**
    *   **Automatisierung:** Nutzt Selenium für das Scraping von `fotograf.de`.
    *   **Persistenz:** Eine SQLite-Datenbank (`fotograf_jobs.db`) speichert die Auftragsliste, OAuth-Tokens (`GmailToken`), Gutscheincodes (`DiscountCode`) und Teilnehmerdaten (`ReleaseParticipant`).
    *   **PDF-Engine:** Nutzt WeasyPrint für Teilnehmerlisten und ReportLab/PyPDF2 für präzise PDF-Overlays (QR-Karten).
    *   **API-Integration:** Direkte Anbindung an die **Calendly API (v2)** sowie an die **Gmail API** für direkten E-Mail-Versand und automatisierte Webhook-Antworten.

2.  **Frontend (TypeScript / React / Vite / TailwindCSS):**
    *   **Modernes UI:** Ein vollständig responsives Dashboard mit Tailwind CSS (Kachel-Layout, Tabs für Kiga/Schule).
    *   **Arbeitsfluss:** Tools sind direkt in der Detailansicht des jeweiligen Auftrags integriert.

## ✨ Core Features

### Feature 1: Teilnehmerlisten (Vollständig)
Automatisierter Workflow zum Download und Formatieren der Anmeldelisten von `fotograf.de` als sortiertes PDF inkl. "Kinderfotos Erding" Branding.

### Feature 2: Shooting-Planung (QR-Karten & Terminliste) (Vollständig)
Spezielles Modul für Familien-Mini-Shootings:
*   **QR-Karten-Andruck:** Präzises Overlay von Name, Kinderanzahl und Uhrzeit inkl. automatischer **Einwilligungs-Checkbox (☑)** aus Calendly-Daten.
*   **Termin-Übersichtsliste:** Generiert eine A4-Tabelle für den Shooting-Tag im 6-Minuten-Takt inkl. Lückenfüller.

### Feature 3: Nachfass-E-Mails & Gmail Direkt-Versand (Vollständig)
Identifizierung von Nicht-Käufern und automatisierter Massenversand personalisierter E-Mails via Gmail API.

### Feature 4: Verkaufs-Statistiken (Vollständig)
Detaillierte Analyse des Kaufverhaltens pro Album mit Echtzeit-Fortschrittsanzeige.

### Feature 5: Geschwisterliste (Einrichtungsintern) (Vollständig)
Tool zur Identifizierung von Geschwistergruppen innerhalb einer Einrichtung inkl. Cross-Check mit Calendly-Buchungen und speziellen Geschwister-QR-Karten.

### Feature 6: Freigabeanfragen & Gutschein-Automation (Vollständig - Neu April 2026)
Vollautomatisierter DSGVO-Workflow zur Einholung von Veröffentlichungsgenehmigungen:
*   **Schlanker Versand:** Manuelle Eingabe von Empfängern (E-Mail, Vorname, Kindernamen) für gezielte Anfragen.
*   **Intelligente Personalisierung:** Automatische Bereinigung von Einrichtungsnamen (entfernt "Kindergarten" und Jahreszahlen).
*   **Versand-Planung:** Einstellbare Versandzeit (Berlin Timezone) via Hintergrund-Tasks.
*   **Webhook-Integration:** Direkte Anbindung an **Google Forms**. Bei Absenden des Freigabe-Formulars wird automatisch:
    1. Ein freier Gutscheincode aus der DB reserviert.
    2. Eine personalisierte Dankes-E-Mail mit dem Code und einer bebilderten Einlöse-Anleitung versendet.
*   **Gutschein-Management:** UI zum Hochladen und Überwachen des Gutschein-Pools.

---

## 🛠️ Technische Details & Sicherheit
*   **Sicherer Test-Modus:** Über die Umgebungsvariable `DEV_MODE_EMAIL_RECIPIENT` können alle ausgehenden E-Mails (Anfragen & Gutscheine) global an eine Test-Adresse umgeleitet werden.
*   **Zeitzonen:** Durchgängige Verwendung von `Europe/Berlin` für alle zeitgesteuerten Operationen.
*   **E-Mail Signatur:** Die offizielle HTML-Signatur von "Kinderfotos Erding" wird automatisch an alle ausgehenden E-Mails (auch vom Backend) angehängt.
*   **Gmail OAuth:** Persistente Speicherung der Refresh-Tokens in der Datenbank ermöglicht dauerhaften Betrieb ohne erneutes Einloggen.

## 🚀 Deployment & Konfiguration

Der Service wird über die Haupt-`docker-compose.yml` des Projekts verwaltet.

### Umgebungsvariablen (`.env`)
Wichtige neue Variablen in `/fotograf-de-scraper/.env`:
*   `DEV_MODE_EMAIL_RECIPIENT`: (Optional) E-Mail für Umleitung im Testbetrieb.
*   `google_fotograf_client_id` / `google_fotograf_secret`: OAuth Credentials.
*   `CALENDLY_TOKEN`: API Zugriff.

### URLs
*   **Frontend:** `https://floke-ai.duckdns.org/fotograf-de/`
*   **Webhook für Google Forms:** `https://floke-ai.duckdns.org/fotograf-de-api/api/publish-request/webhook`