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 & 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