Brancheneinstufung2/fotograf-de-scraper/README.md

Fotograf.de Scraper & Management UI

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

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

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

✨ 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 (Vollständig)

• Identifizierung von Käufern/Nicht-Käufern zur Generierung von CSV-Listen für den Supermailer.

Feature 4: Verkaufs-Statistiken (Vollständig)

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

🛠️ Technische Details & Fixes (April 2026)

• 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.
• Logo-Integration: Dynamisches Einbetten des Firmenlogos in alle generierten Dokumente.

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

URLs & Ports

• Scraper Frontend: http://192.168.178.6:3009
• Zentrales Dashboard: http://192.168.178.6:8090
• Persistenz: Datenbank unter ./backend/data/fotograf_jobs.db.