From d7f789b12f72cdeed1c9baf2b4f87899fa1a726a Mon Sep 17 00:00:00 2001 From: Floke Date: Mon, 9 Mar 2026 10:37:12 +0000 Subject: [PATCH] [31988f42] Docs: Updated README with WordPress iFrame integration and Race-Condition Protection details --- lead-engine/README.md | 34 ++++++++++++---------------------- 1 file changed, 12 insertions(+), 22 deletions(-) diff --git a/lead-engine/README.md b/lead-engine/README.md index 6b30c1fb..7e9d08ee 100644 --- a/lead-engine/README.md +++ b/lead-engine/README.md @@ -63,9 +63,13 @@ Der vollautomatische "Zero Touch" Workflow für Trading Twins Anfragen. * **Problem:** Eine statische Signatur in der Konfiguration war unflexibel und konnte keine Bilder enthalten. * **Lösung:** Ein Skript (`scripts/extract_signature_assets.py`) extrahiert die vollständige HTML-Signatur und alle eingebetteten Bilder aus einer `.eml`-Datei. Die `send_email`-Funktion wurde überarbeitet, um alle Bilder dynamisch als Inline-Anhänge zu versenden, was eine professionelle Darstellung sicherstellt. -### 4. Advanced Debugging & Fehlerbehebung -* **Problem:** Hintergrund-Tasks schlugen ohne klare Fehlermeldung fehl, was die Diagnose erschwerte. -* **Lösung:** Umfassendes Logging wurde in allen kritischen Funktionen implementiert. Dadurch konnten Fehler wie ein `NameError` bei der Datumsformatierung und die `TimeZoneNotSupportedException` schnell identifiziert und behoben werden. +### 4. Race-Condition-Schutz bei Überbuchung (Live-Check) +* **Problem:** Wenn mehrere Leads E-Mails mit denselben Terminvorschlägen erhalten, konnten Doppelbuchungen entstehen. +* **Lösung:** Implementierung eines "Live-Checks" im Feedback-Server. Bevor ein Termin gebucht wird, prüft das System in Echtzeit (`is_slot_free`), ob der Slot im Kalender von `e.melcer@` noch verfügbar ist. Ist er belegt, wird die Buchung abgebrochen und ein Fallback-Szenario aktiviert. + +### 5. Seamless Website Integration (WordPress iFrame) +* **Problem:** Die API-Endpoints gaben nackten Text zurück, was für Kunden unprofessionell wirkte. +* **Lösung:** Der Server liefert nun saubere HTML-Snippets zurück. Durch Setzen der `WORDPRESS_BOOKING_URL` in der `.env` führen die Links in der Kunden-E-Mail direkt auf die Kunden-Website. Dort wird das HTML-Ergebnis (Erfolg inkl. Teams-Link ODER Fallback zum Microsoft Bookings Kalender bei Doppelbuchung) unsichtbar in einem iFrame geladen. ## 🚀 Inbetriebnahme & Test @@ -83,25 +87,9 @@ docker-compose up -d --build --force-recreate lead-engine ## 📝 Zukünftige Erweiterungen & Todos -### Task: Race-Condition-Schutz bei Überbuchung -* **Problem:** Wenn mehrere Leads E-Mails mit denselben Terminvorschlägen erhalten, kann es zu "Race Conditions" kommen, bei denen mehrere Personen denselben Slot fast zeitgleich buchen. -* **Lösung:** Implementierung eines "Live-Checks" im Feedback-Server. - 1. **Trigger:** Ein Nutzer klickt auf einen Buchungslink. - 2. **Aktion:** Bevor der Termin im Kalender erstellt wird, sendet der Server eine *erneute* `getSchedule`-Anfrage an die Graph API für exakt diesen Zeit-Slot. - 3. **Logik:** - * **Slot frei:** Der Termin wird wie geplant gebucht und der Job-Status auf `booked` gesetzt. - * **Slot belegt:** Der Nutzer erhält eine freundliche Nachricht ("Dieser Termin wurde gerade vergeben."). Idealerweise werden ihm dynamisch zwei neue, freie Termine vorgeschlagen, die er direkt auf der Seite buchen kann. -* **Ziel:** Sicherstellen, dass der Kalender die "Single Source of Truth" ist und doppelte Buchungen zuverlässig verhindert werden. - -### Task: Integration der Buchungs-Seiten in WordPress -* **Ziel:** Eine nahtlose User Experience schaffen, bei der Termin-Bestätigungen auf der Haupt-Website (`robo-planet.de`) statt auf der direkten API-URL angezeigt werden. -* **Phase 1 (Kurzfristig): Einbettung via iFrame** - * **Umsetzung:** Eine Seite in WordPress anlegen und die URL des Feedback-Servers (z.B. `https://floke-ai.duckdns.org/feedback/book_slot/...`) in einem iFrame laden. - * **Vorteil:** Kein Programmieraufwand auf unserer Seite nötig, sofort umsetzbar. -* **Phase 2 (Langfristig): Native API-Integration** - * **Umsetzung:** Die Links in der E-Mail führen direkt zu einer WordPress-Seite (z.B. `robo-planet.de/termin-bestaetigen`). Ein Skript auf dieser Seite ruft im Hintergrund unsere `/book_slot` API auf. - * **Vorteil:** Perfekte Integration ins Corporate Design, volle Kontrolle über die Erfolgs- und Fehlermeldungen. Die API ist dafür bereits ausgelegt. - +### Task: Automatisches Nachfassen (Follow-up) +* **Problem:** Wenn ein Lead nicht auf die E-Mail antwortet und auch keinen Termin bucht, geht der Kontakt verloren. +* **Lösung:** Einbindung eines Follow-up-Mechanismus nach 5 Tagen. Dies könnte entweder durch ein Flag im CRM-System oder durch eine geplante E-Mail direkt über die Lead-Engine realisiert werden. ```env # Info-Postfach (App 1 - Schreiben) @@ -117,4 +105,6 @@ CAL_SECRET=... # URLs TEAMS_WEBHOOK_URL=... FEEDBACK_SERVER_BASE_URL=https://floke-ai.duckdns.org/feedback +WORDPRESS_BOOKING_URL=https://www.robo-planet.de/terminbestaetigung +MS_BOOKINGS_URL=https://outlook.office365.com/book/KennenlernenmitRoboplanet@wackler-group.de/ ``` \ No newline at end of file