Brancheneinstufung2/fotograf-de-scraper/README.md

Fotograf.de Scraper & Management UI

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

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, sodass langsame Scraping-Vorgänge nur bei Bedarf (Refresh) nötig sind. Speichert außerdem OAuth-Tokens (GmailToken) für persistente E-Mail-Sitzungen.
   • 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) zum Abruf von Live-Buchungsdaten sowie an die Gmail API für direkten E-Mail-Versand.

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 (Shooting-Planung, E-Mail-Kampagnen).

✨ 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.

• Dynamische Terminologie: Automatische Anpassung des Wordings basierend auf dem Profil (Kiga: "Kinder"/"Gruppen" vs. Schule: "Schüler"/"Klassen").
• Intelligentes Datum: Extraktion des echten Auftragsdatums aus der Datenbank mit automatischer Erweiterung auf einen 2-Tages-Zeitraum (z.B. "15. + 16.04.2026").

Feature 2: Shooting-Planung (QR-Karten & Terminliste)

Spezielles Modul für Familien-Mini-Shootings, direkt integriert in die Auftragsdetails:

• Dynamische Event-Auswahl: Wähle direkt aus deinen Calendly-Event-Typen (z.B. "Neuching") aus.
• Termin-Filter: Zeigt nur noch aktuelle und zukünftige Buchungen an (alte recycelte Termine werden ignoriert).
• QR-Karten-Andruck:
  • Präzises Overlay von Name, Kinderanzahl und Uhrzeit auf vorbereitete QR-Code-Bögen.
  • Einwilligungs-Checkbox (☑): Automatischer Andruck eines Häkchens, wenn in Calendly der Veröffentlichung zugestimmt wurde.
• Termin-Übersichtsliste:
  • Generiert eine A4-Tabelle für den Shooting-Tag im 6-Minuten-Takt.
  • Füllt Lücken für nicht gebuchte Slots automatisch leer auf.

Feature 3: Nachfass-E-Mails & Gmail Direkt-Versand (Vollständig)

Identifizierung von potenziellen Käufern und automatisierter Kontakt.

• Analyse-Logik: Sucht nach Personen mit 0-1 Logins, die noch keine Bilder gekauft haben.
• Supermailer Export: Generierung einer fertigen CSV-Liste.
• Direkter Gmail-Versand (Neu):
  • Volle OAuth 2.0 Integration. Einmaliger Login, das Refresh-Token hält die Sitzung aktiv.
  • Inline-Editor für Betreff und HTML-Nachricht mit Live-Platzhaltern ({Name Käufer}, {Kindernamen}, {LinksHTML}).
  • Massensendungs-API (Bulk Send) schickt Mails direkt über das verbundene Postfach.

Feature 4: Verkaufs-Statistiken (Vollständig)

• Detaillierte Analyse des Kaufverhaltens pro Album mit Echtzeit-Fortschrittsanzeige im Browser.

Feature 5: Geschwisterliste (Einrichtungsintern) (Vollständig)

Spezielles Tool zur Identifizierung von Geschwistergruppen innerhalb einer Einrichtung.

• Intelligente Erkennung: Nutzt die "Email der Eltern (1)" aus der Fotograf.de-Anmeldeliste für einen automatischen Abgleich (Zählenwenn > 1).
• Calendly-Cross-Check: Gleicht die identifizierten Familien mit allen aktuellen Calendly-Buchungen ab, um Nachmittags-Termine automatisch in der Liste zu vermerken.
• Optimiertes PDF: Generiert eine alphabetisch nach Nachnamen sortierte Liste mit Kindern, deren Gruppen, Online-Wunsch-Status und Termin-Uhrzeit (inkl. Datum) sowie einem Erledigt-Feld für die manuelle Kontrolle vor Ort.
• Geschwister-QR-Karten: Erzeugt automatisch Zugangskarten ("Geschwisterbilder Familie [Nachname]") für alle identifizierten Geschwisterfamilien, die keinen Termin am Nachmittag gebucht haben.

---

🎯 Nächste Session: "Freigabeanfragen" (Feature 6)

Das nächste große Ziel ist der automatische Versand von Freigabeanfragen via Gmail.

Der geplante Workflow (Bestätigt): Anstatt Bild für Bild auf fotograf.de zu prüfen, nutzen wir die bereits erteilte Einwilligung aus Calendly.

• Logik: Das System prüft die Calendly-Buchungen des Shootings auf die Frage "Dürfen wir einige schöne Aufnahmen veröffentlichen?".
• Alle Kunden, die hier "Ja" (bzw. eine positive Antwort) angegeben haben, werden extrahiert und erhalten automatisiert über die Gmail-API die Freigabeanfrage.
• Text & Template werden in der nächsten Sitzung definiert.

---

🛠️ Technische Details & Fixes (April 2026)

• E-Mail Signatur: Die offizielle HTML-Signatur von "Kinderfotos Erding" (inkl. Logo via Google Drive Link) ist hartcodiert hinterlegt und wird bei jedem Massen- oder Testversand unsichtbar im Hintergrund an den HTML-Body angehängt.
• Gmail OAuth Architektur: Strikt getrennt. App-Credentials (client_id, client_secret) liegen in der .env. User-Credentials (Access & Refresh Tokens) werden dynamisch in der SQLite-Datenbank (GmailToken) gespeichert.
• Routing / Reverse Proxy:
  • Das Frontend (React/Vite) nutzt den base: '/fotograf-de/' Pfad, um Assets korrekt hinter dem Nginx-Proxy zu laden.
  • API-Aufrufe nutzen relative Pfade (/fotograf-de-api/), welche von Nginx sauber zum internen Backend-Port 8000 umgeschrieben (rewrite) werden. Dies verhindert Mixed-Content und CORS-Fehler im Produktionsbetrieb.
• Zeitzonen: Automatische Konversion von Calendly-UTC-Zeiten in die lokale Zeit (Europe/Berlin).
• Pagination Fix: Das Backend blättert durch alle Calendly-Seiten für lückenlose Daten.

🚀 Deployment & Konfiguration

Der Service wird über eine eigene docker-compose.yml im Unterverzeichnis gestartet.

Umgebungsvariablen (.env)

Folgende Variablen müssen in der .env im Verzeichnis /fotograf-de-scraper/ definiert sein:

• KIGA_USER / KIGA_PW / SCHULE_USER / SCHULE_PW: Logins für Fotograf.de.
• CALENDLY_TOKEN: Personal Access Token (JWT) von Calendly.
• google_fotograf_client_id / google_fotograf_secret: Die OAuth-App-Credentials aus der Google Cloud Console.
• GOOGLE_REDIRECT_URI: (Optional) Standard ist https://floke-ai.duckdns.org/fotograf-de-api/api/auth/callback.

URLs & Ports

• Produktion / Nginx: https://floke-ai.duckdns.org/fotograf-de/
• Persistenz: Datenbank unter ./backend/data/fotograf_jobs.db.