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 (Klassen/Gruppen) inkl. "Kinderfotos Erding" Branding.

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.
• QR-Karten-Andruck:
  • Präzises Overlay von Name, Kinderanzahl und Uhrzeit auf vorbereitete QR-Code-Bögen.
  • Korrektur: Y-Achse um 9mm nach unten verschoben für perfekten Sitz auf den Linien.
  • Einwilligungs-Checkbox (☑): Automatischer Andruck eines Häkchens, wenn in Calendly der Veröffentlichung zugestimmt wurde.
• Termin-Übersichtsliste (Neu):
  • Generiert eine A4-Tabelle für den Shooting-Tag.
  • 6-Minuten-Takt: Erzeugt automatisch ein Raster basierend auf dem ersten und letzten Termin, füllt Lücken für nicht gebuchte Slots leer auf.
  • Inklusive Spalten für Name, Kinder, Veröffentlichungs-Status und einer Checkbox zum manuellen Abhaken.

Feature 3: Nachfass-E-Mails (Geplant)

• 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 (März 2026)

• Zeitzonen: Automatische Konversion von Calendly-UTC-Zeiten in die lokale Zeit (Europe/Berlin).
• Pagination Fix: Das Backend blättert nun durch alle Calendly-Seiten, um sicherzustellen, dass keine Buchungen (auch bei großen Event-Historien) übersehen werden.
• 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.
• CALENDLY_TOKEN: Personal Access Token (JWT) von Calendly.

URLs & Ports

• Frontend: http://<HOST_IP>:3009 | Backend: http://<HOST_IP>:8002
• Persistenz: Datenbank unter ./backend/data/fotograf_jobs.db.