Brancheneinstufung2/fotograf-de-scraper/README.md

Fotograf.de Scraper & Management UI

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

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 mittels Personal Access Token (JWT).

2. Frontend (TypeScript / React / Vite / TailwindCSS):

   • Modernes UI: Ein vollständig responsives Dashboard mit Tailwind CSS (Kachel-Layout, Tabs für Kiga/Schule).
   • Echtzeit-Feedback: Polling-Mechanismus für langlaufende Hintergrund-Tasks (z. B. Statistiken).
   • Tools: Integrierte Formulare für PDF-Downloads und ein dedizierter QR-Karten-Generator im Header.

✨ Core Features

Feature 1: PDF-Teilnehmerlisten-Generierung (Vollständig)

Automatisierter Workflow:

1. Daten-Caching: Aufträge werden aus der lokalen DB geladen (Millisekunden-Reaktionszeit).
2. Selenium-Download: Auf Knopfdruck wird die CSV-Anmeldeliste von fotograf.de im Hintergrund geladen.
3. PDF-Erstellung: Generierung eines sortierten PDFs (Klassen/Gruppen) mit "Kinderfotos Erding" Branding.

Feature 2: QR-Karten für Familien-Shootings (Vollständig)

Spezielles Tool für Familien-Mini-Shootings:

• Workflow:
  1. Manueller Upload eines Blanko-PDFs, das bereits individuelle QR-Codes pro Seite/Karte enthält.
  2. Live-Abruf der Buchungsdaten (Name, Anzahl Kinder, Uhrzeit) via Calendly API.
  3. Präzises Overlay: Die Texte werden exakt an zwei Positionen pro A4-Seite angedruckt:
     • Element 1 (Oben): X: 72mm, Y: 22mm (vom oberen Rand).
     • Element 2 (Unten): X: 72mm, Y: 171mm (vom oberen Rand).
• Intelligente Seitenverwaltung: Das Tool erkennt die Seitenanzahl der Vorlage und beschreibt jede Seite individuell, um die eindeutigen QR-Codes zu erhalten.

Feature 3: Nachfass-E-Mails (Geplant)

• Identifizierung von Käufern/Nicht-Käufern zur Generierung von Supermailer-Listen (Anbindung an Fotograf.de Scraping-Logik).

Feature 4: Verkaufs-Statistiken (Vollständig)

• Durchforstet alle Alben eines Auftrags via Selenium.
• Liefert eine Übersicht der Verkaufszahlen pro Album (Kinder gesamt, mit Käufen, alle Bilder gekauft).
• UX: Fortschrittsanzeige in Echtzeit ("Bearbeite Album X/Y, Seite Z...") direkt im Browser.

🚀 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: Login für den Kindergarten-Account.
• SCHULE_USER / SCHULE_PW: Login für den Schul-Account.
• CALENDLY_TOKEN: Personal Access Token (JWT, startet mit eyJ...) von Calendly (erfordert Professional Abo).

URLs & Ports

• Frontend: http://<HOST_IP>:3009 (Dashboard & Tools)
• Backend: http://<HOST_IP>:8002 (API-Schnittstelle)
• Persistenz: Die Datenbank liegt unter ./backend/data/fotograf_jobs.db.