--- module: 6 title: Booking / Termin-Buchung (Calendly-Style) phase: 1 status: detail-spec-draft last_updated: 2026-05-08 session_source: brainstorming-session-2026-05-07-2206.md related_lps: [LP-4, LP-7, LP-9, LP-10] spec_style: requirements-pur --- # Modul 6 — Booking / Termin-Buchung > **Detail-Spec gemäß LP-9.** Calendly-Style öffentliche Buchungs-Seiten pro Tenant. Löst HubSpot-Booking-Tool ab (LP-7). Multi-Provider, Verfügbarkeits-Sync mit Google/MS-Kalender, Embed-Code für externe Websites, Auto-Bestätigungsmail, Auto-Eintrag in internen Kalender. Buchungen erzeugen Leads (neuer Kunde) oder Activities (Bestandskunde). ## Themenblöcke ``` A. Datenmodell B. Menü-Struktur und Routes C. Listen-View / Übersicht aller Buchungen D. Detail-View / Einzelne Buchung E. Booking-Page-Verwaltung (Editor) F. Verfügbarkeits-Verwaltung (Pro-User) G. Öffentliche Booking-Page (Endkunden-Flow) H. Embed-Code / iFrame I. Auto-Bestätigungsmail J. Verknüpfungen (CRM, Kalender, Lead-Inbox, Activity-Stream) K. Permissions L. Klartext-Hinweise M. Phase 2 ``` --- ## Block A — Datenmodell ### A.1 — BookingPage Tabelle: `BookingPage`. Tenant-scoped (RLS). **Felder:** - `id`, `tenant_id`, `created_at`, `updated_at`, `created_by_user_id` - `slug` (Pflicht, unique pro Tenant; URL-safe `[a-z0-9-]`, min. 3, max. 60 Zeichen — z.B. `wartungstermin`) - `title` (Pflicht, User-sichtbarer Name z.B. „Wartungstermin Beratung") - `description` (Markdown-Freitext, wird auf öffentlicher Page angezeigt) - `duration_minutes` (Pflicht, Enum: `15 | 30 | 45 | 60 | 90 | 120`) - `buffer_before_minutes` (Default 0; Pufferzeit vor Termin) - `buffer_after_minutes` (Default 0; Pufferzeit nach Termin) - `slot_increment_minutes` (Default 15; in welchen Schritten Slots angeboten werden) - `min_notice_hours` (Default 4; minimaler Vorlauf für Buchung) - `max_advance_days` (Default 60; wie weit in die Zukunft buchbar) - `assignment_strategy` (Enum: `round_robin | specific_provider_choice | first_available`; siehe A.2) - `confirmation_email_subject` (Pflicht, Liquid/Handlebars-Template-Strings erlaubt) - `confirmation_email_body` (Pflicht, Markdown + Template-Strings, siehe Block I) - `internal_calendar_event_title` (Template-String für Kalender-Eintrag-Titel; Default „Termin: {{contact.name}} — {{booking_page.title}}") - `redirect_url_after_booking` (optional, externe URL z.B. Tenant-Website-Danke-Page) - `intake_form_id` (FK auf Form aus Modul 5, optional — wenn gesetzt wird dieses Form als Intake genommen statt Standard-Mini-Form) - `is_published` (Boolean — nur publizierte Pages sind öffentlich erreichbar) - `archived_at` **Indizes:** - `(tenant_id, slug)` UNIQUE - `(tenant_id, archived_at, is_published)` für Liste ### A.2 — BookingPageProvider M:N-Tabelle zwischen `BookingPage` und `User` (Tenant-User). Eine Booking-Page hat einen oder mehrere Provider (Mitarbeiter, deren Verfügbarkeit angezeigt wird). **Felder:** - `booking_page_id`, `tenant_user_id`, `tenant_id` - `display_order` (für UI-Reihenfolge bei `specific_provider_choice`) - `is_active` (Provider zeigt aktuell Verfügbarkeit; falls deaktiviert: bestehende Termine bleiben, neue Buchungen schließen ihn aus) **Assignment-Strategien:** | Strategie | Verhalten | |---|---| | `round_robin` | System wählt Provider mit den wenigsten Buchungen in den letzten 30 Tagen aus den verfügbaren | | `specific_provider_choice` | Endkunde sieht Provider-Auswahl auf öffentlicher Page, wählt selbst | | `first_available` | Slot-Picker zeigt zusammengeführte Verfügbarkeit; bei Buchung wird dem Provider zugewiesen, der zuerst frei ist | ### A.3 — AvailabilityRule Tabelle: `AvailabilityRule`. Pro Tenant-User. Definiert wöchentliche Standard-Verfügbarkeit. **Felder:** - `id`, `tenant_id`, `tenant_user_id`, `created_at`, `updated_at` - `day_of_week` (Enum: `monday | tuesday | ... | sunday`) - `start_time` (Time, z.B. `09:00`) - `end_time` (Time, z.B. `17:00`) - `timezone` (IANA, z.B. `Europe/Berlin`; Default aus User-Profil) **Sonderfall:** mehrere Regeln pro Tag möglich (z.B. 09:00-12:00 + 14:00-17:00 mit Mittagspause). **Indizes:** - `(tenant_user_id, day_of_week)` ### A.4 — AvailabilityException Tabelle: `AvailabilityException`. Datum-spezifische Overrides der Standard-Regeln. **Felder:** - `id`, `tenant_id`, `tenant_user_id`, `created_at`, `updated_at` - `date` (Pflicht) - `kind` (Enum: `unavailable | custom_window`) - `start_time`, `end_time` (nur wenn `kind = custom_window`; nullable bei `unavailable`) - `reason` (optional, Freitext z.B. „Urlaub", „Schulung") - `timezone` (IANA, Default wie Regel) **Sonderfälle:** - `unavailable` ohne Zeiten: ganzer Tag blockiert - `custom_window`: ersetzt Standard-Regel für diesen Tag (mehrere Exceptions pro Tag erlaubt für mehrere Fenster) **Indizes:** - `(tenant_user_id, date)` ### A.5 — Appointment Tabelle: `Appointment`. Tenant-scoped. **Felder:** - `id`, `tenant_id`, `created_at`, `updated_at` - `booking_page_id` (FK BookingPage) - `provider_user_id` (FK TenantUser — wer hält den Termin) - `start_at` (Pflicht, UTC) - `end_at` (Pflicht, UTC; berechnet aus `start_at + duration_minutes`) - `timezone` (IANA, in welcher Zeitzone der Endkunde gebucht hat — für Anzeige) - `status` (Enum: `scheduled | held | cancelled | no_show | rescheduled`) - `contact_id` (FK Contact, nullable — gesetzt sobald gematcht/promoted) - `lead_id` (FK Lead, nullable — bei Buchung von neuem Endkunden zunächst Lead) - `form_submission_id` (FK FormSubmission — die Intake-Daten der Buchung) - `external_calendar_event_ids` (JSON-Array mit Provider-Calendar-Event-IDs aus Google/MS — siehe Block J) - `cancelled_at`, `cancelled_by_kind` (Enum: `customer | provider | system`), `cancellation_reason` - `rescheduled_from_id` (FK Appointment, nullable — bei Reschedule) - `notes_internal` (Markdown, nur intern sichtbar) **Status-Lifecycle:** ``` scheduled → gebucht, in Zukunft held → vergangener Termin, fand statt cancelled → storniert (Kunde oder Provider) no_show → Kunde nicht erschienen (Provider markiert manuell) rescheduled → durch neueren Termin ersetzt (alter bleibt zur Historie) ``` **Indizes:** - `(tenant_id, provider_user_id, start_at)` - `(tenant_id, contact_id, start_at)` - `(tenant_id, status, start_at)` für Übersichten - `(booking_page_id, start_at)` ### A.6 — Slot-Berechnungs-Logik (zur Laufzeit, kein eigenes Modell) Bei Anfrage „verfügbare Slots am Datum X für Booking-Page Y": 1. Lade alle aktiven Provider der Booking-Page 2. Pro Provider: - Standard-Verfügbarkeit aus `AvailabilityRule` für `day_of_week` von X - Überlagern mit `AvailabilityException` für Datum X (falls vorhanden) - Subtrahieren: bestehende `Appointment`-Records (mit Buffer-Zeiten) für Provider in Zeitraum - Subtrahieren: externe Kalender-Events aus `CalendarEvent`-Tabelle (Modul 25) wo `provider_user_id` der Provider ist und Zeitraum überlappt - Subtrahieren: `min_notice_hours` (keine Slots in den nächsten N Stunden) - Subtrahieren: alles außerhalb `max_advance_days` 3. Slot-Increment anwenden: nur Slots an Vielfachen von `slot_increment_minutes` 4. Nach `assignment_strategy` zusammenführen: - `round_robin` / `first_available`: Union aller Provider-Slots, jeder Slot mit „Provider X frei"-Marker - `specific_provider_choice`: pro Provider getrennt zurückgeben **Performance:** - Slot-Berechnung server-side, gecacht für 60 Sekunden pro `(booking_page_id, date)` mit Redis - Cache-Invalidation bei: neue/gelöschte Appointment, neue/geänderte AvailabilityRule/Exception, neue Calendar-Event-Sync --- ## Block B — Menü-Struktur und Routes **Sidebar-Hauptpunkt:** *Buchungen*. Sub-Punkte: Übersicht / Booking-Pages / Meine Verfügbarkeit. **Routen (Tenant-intern, eingeloggt):** ``` /{tenant}/bookings → Übersicht aller Buchungen (Liste) /{tenant}/bookings/:id → Einzelne Buchung Detail-View /{tenant}/bookings/pages/ → Liste aller Booking-Pages /{tenant}/bookings/pages/new → Neue Booking-Page /{tenant}/bookings/pages/:id → Booking-Page editieren /{tenant}/availability → Eigene Verfügbarkeit pflegen (pro User) ``` **Routen (öffentlich, kein Login):** ``` app.hivegrid.de/buch/{tenant}/{slug} → Öffentliche Booking-Page app.hivegrid.de/buch/{tenant}/{slug}/embed → Embed-Variante (iFrame, ohne Tenant-Branding-Header) ``` **Cancel-/Reschedule-Tokens (Phase 2):** Phase 1 noch nicht im Scope; Cancel nur intern + via Antwort auf Bestätigungsmail. --- ## Block C — Listen-View / Übersicht aller Buchungen (`/{tenant}/bookings`) **Zu zeigende Daten pro Eintrag:** - Datum + Uhrzeit (`start_at` in Tenant-User-Timezone) - Dauer - Endkunden-Name (aus Contact oder Lead) - Endkunden-Email - Booking-Page-Title - Provider (Tenant-User der den Termin hält) - Status **Benötigte UI-Elemente:** - Tabellarische Liste, sortierbar - Default-Sortierung: `start_at ASC` für `status = scheduled`, dann historisch nach Datum - Filter: - Status (Multi-Select) - Provider (Multi-Select) - Booking-Page (Multi-Select) - Zeitraum (Date-Range-Picker) - Volltext-Suche über Endkunden-Name/-Email - Tabs/Toggle: „Anstehende" / „Vergangene" / „Stornierte" / „Alle" - Pagination (Cursor-basiert, 50 pro Page) - Bulk-Auswahl + Bulk-Cancel - Spalten-Konfiguration (User wählt sichtbare Spalten) **Operationen:** - Klick auf Zeile → Detail-View - Bulk-Cancel (mit Klartext-Confirm und automatischer Cancel-Mail) - Export als CSV (gefilterte Auswahl) **Permissions-Wirkung:** - `bookings.read_own`: nur Termine wo `provider_user_id = self` - `bookings.read_all`: alle Termine **Performance:** - Index auf `(tenant_id, status, start_at)` für Default-Liste - Server-side-Filter --- ## Block D — Detail-View / Einzelne Buchung (`/{tenant}/bookings/:id`) **Zu zeigende Daten:** - Termin-Details (Datum, Uhrzeit, Dauer, Status, Booking-Page-Title) - Provider (User-Avatar + Name) - Endkunde (Contact- oder Lead-Verlinkung mit Stammdaten-Vorschau) - Form-Submission-Daten (Antworten aus Intake-Form) - Cancellation-Info (falls cancelled): wer, wann, warum - Reschedule-Info (falls reschedules) - Externe-Kalender-Sync-Status (synced/pending/error pro Provider-Kalender) - Notes (intern) - Activity-Stream-Sektion (Termin-bezogene Activities) **Benötigte UI-Elemente:** - Sektionierte Anzeige der Termin-Daten + Endkunden-Verknüpfung + Form-Antworten + Notes + Activity-Stream - Inline-Edit für Notes - Action-Buttons für die Operationen (siehe unten) - Kalender-Sync-Status-Badge mit Klartext-Tooltip bei Fehler - Direkt-Link zum verknüpften Contact/Lead **Operationen:** - Status setzen: `held` (manuell als „fand statt"), `no_show` (Kunde nicht erschienen) - Cancel (mit Cancellation-Reason-Eingabe + Auto-Cancel-Mail an Endkunde) - Reschedule → öffnet Slot-Picker, wählt neuen Slot, alter Termin bekommt `status=rescheduled`, neuer Termin verlinkt rückwärts mit `rescheduled_from_id` - Notiz hinzufügen (intern) - Provider neu zuweisen (mit Klartext-Warnung über Kalender-Resync) - Hard-Delete (nur `bookings.admin`, mit Klartext-Warnung) - Endkunde re-/an-mailen (öffnet Compose mit vorausgefülltem Empfänger) **Klartext-Hinweise:** - Provider-Wechsel: *„Termin wird im Kalender von [alter Provider] entfernt und bei [neuer Provider] eingetragen. Endkunde bekommt automatisch eine Update-Mail."* - Cancel: *„Endkunde bekommt eine Storno-Mail mit Begründung."* - Reschedule: *„Termin wird verschoben. Endkunde bekommt eine Update-Mail mit neuen Slot."* - Kalender-Sync-Fehler: *„Konnte Termin nicht in Google-Kalender von [Provider] eintragen ({reason}). [Erneut versuchen]"* --- ## Block E — Booking-Page-Verwaltung ### E.1 — Listen-View (`/{tenant}/bookings/pages/`) **Zu zeigende Daten pro Booking-Page:** - Title, Slug - Anzahl aktive Provider - Dauer - Anzahl Buchungen (gesamt + letzte 30 Tage) - Status (publiziert / nicht publiziert) - Public-URL mit Copy-to-Clipboard **Benötigte UI-Elemente:** - Liste mit Suchfunktion + Filter (publiziert/nicht/archived) - Action: neue Page anlegen - Pro Page: Edit-Funktion, Duplizieren, Archivieren, Hard-Delete ### E.2 — Editor (`/{tenant}/bookings/pages/:id` und `/new`) **Zu zeigende Daten:** - Alle Felder von `BookingPage` - Provider-Auswahl (Multi-Select aus aktiven Tenant-Usern) - Vorschau-Funktion (öffnet öffentliche Page in neuem Tab) - Embed-Code-Generator (siehe Block H) **Benötigte UI-Elemente:** - Sektionierte Anzeige für: Grunddaten / Verfügbarkeits-Konfiguration / Provider / Bestätigungsmail / Erweitert - Slug-Eingabe mit Live-Validation (eindeutigkeit + Reserved-Words-Check, Auto-Slug-Vorschlag aus Title) - Markdown-Editor für Beschreibung + Bestätigungsmail-Body - Multi-Select für Provider mit Drag&Drop für `display_order` - Intake-Form-Auswahl (Dropdown mit allen Forms aus Modul 5, oder „Standard-Mini-Form" als Default) - Toggle für Publish-Status - Public-URL-Anzeige (sobald publiziert) - Embed-Code-Generator (siehe Block H) **Operationen:** - Anlegen / Editieren / Speichern (mit Concurrent-Update-Check) - Vorschau öffnen - Embed-Code generieren - Duplizieren (mit Suffix „(Kopie)") - Archivieren / Reaktivieren - Hard-Delete (mit Klartext über bestehende Termine) **Validierungen:** - Slug eindeutig pro Tenant + URL-safe - Mindestens 1 aktiver Provider - Standard-Verfügbarkeits-Regel auf mindestens 1 Provider vorhanden, sonst Klartext-Warnung *„Kein Provider hat Verfügbarkeit hinterlegt — Endkunden würden keine freien Slots sehen."* - `min_notice_hours < max_advance_days * 24` (sonst Klartext-Fehler) **Klartext-Fehler:** - Slug-Konflikt: *„Diese URL ist schon vergeben — wähle eine andere."* - Reserved-Slug: *„'{slug}' ist reserviert. Wähle einen anderen."* - Booking-Page hard-löschen mit zukünftigen Terminen: *„Diese Booking-Page hat noch {n} anstehende Termine. Beim Löschen werden diese storniert. Stattdessen archivieren? [Archivieren] [Trotzdem löschen]"* **Permissions:** - Anlegen/Editieren: `bookings.admin` - Vorschau lesen: `bookings.read_*` --- ## Block F — Verfügbarkeits-Verwaltung (`/{tenant}/availability`) Pro-User-Page (jeder Tenant-User pflegt seine eigene). Kein Admin-Recht zum Editieren fremder Verfügbarkeiten in Phase 1 (außer über Direct-API als `bookings.admin`). **Zu zeigende Daten:** - Aktuelle wöchentliche Standard-Regeln (`AvailabilityRule`-Liste) - Aktuelle Datums-Ausnahmen (`AvailabilityException`-Liste, ab heute aufwärts) - Hinweis: welche Booking-Pages aktuell auf diesen User zugreifen (read-only Information) **Benötigte UI-Elemente:** - Wöchentliche Verfügbarkeits-Editor (pro Wochentag mehrere Zeit-Fenster definierbar mit Start/End) - Ausnahmen-Editor (Datum + Toggle „nicht verfügbar" oder Custom-Window mit Zeit-Fenster) - Timezone-Auswahl (Default aus User-Profil, änderbar pro Regel) - Liste der Ausnahmen mit Filter „nur künftige" und Edit/Delete pro Eintrag - Klartext-Hinweis bei leerer Standard-Verfügbarkeit *„Du bist auf keiner Booking-Page als verfügbar markiert — du kannst keine Termine bekommen."* **Operationen:** - Standard-Regeln anlegen / editieren / löschen - Ausnahmen anlegen / editieren / löschen - Bulk-Aktion „Diese Woche bin ich nicht verfügbar" (erzeugt 7 Exceptions mit `kind=unavailable`) **Permissions:** - Eigene: jeder eingeloggte Tenant-User mit `bookings.write` oder `bookings.read_own` - Fremde: nur `bookings.admin` (für Backoffice-Korrektur) **Klartext-Hinweise:** - Überlappende Zeit-Fenster: *„Diese Fenster überschneiden sich — wir haben sie zusammengeführt: 09:00-17:00."* (auto-merge mit Hinweis) - Zeit-Fenster außerhalb des Tages: *„Endzeit muss nach Startzeit liegen."* - Exception in Vergangenheit: *„Datum liegt in der Vergangenheit — Eintrag wird gespeichert, hat aber keine Wirkung mehr."* --- ## Block G — Öffentliche Booking-Page (`app.hivegrid.de/buch/{tenant}/{slug}`) ### G.1 — Endkunden-Flow **Schritt 1 — Page-Anzeige:** - Title + Beschreibung der Booking-Page - Dauer - Bei `assignment_strategy = specific_provider_choice`: Provider-Auswahl mit Avatar + Name (+ optional Kurz-Bio in Phase 2) - Bei anderen Strategien: nur Booking-Page-Titel ohne Provider-Auswahl - Slot-Picker: - Datum-Auswahl (Kalender-Komponente, Tage ohne Verfügbarkeit ausgegraut) - Zeitslots am gewählten Tag (Liste mit Uhrzeiten in Endkunden-Timezone) - Timezone-Anzeige + Wechsler (Default aus Browser-Locale) **Schritt 2 — Intake-Form:** - Pflicht-Felder Standard-Mini-Form: Vor-/Nachname, Email, Telefon (optional) - Falls `intake_form_id` gesetzt: das verknüpfte Form aus Modul 5 wird angezeigt mit allen Custom-Feldern - DSGVO-Hinweis und Daten-Verarbeitungs-Akzeptanz (Pflicht-Checkbox) **Schritt 3 — Bestätigung:** - Klartext-Bestätigung *„Termin {{title}} am {{date}} um {{time}} mit {{provider}}"* - Hinweis dass Bestätigungsmail unterwegs ist - Optional: Redirect auf `redirect_url_after_booking` falls gesetzt - Add-to-Calendar-Funktion (.ics-Download für Endkunde) ### G.2 — Endkunden-UI-Anforderungen **Benötigte UI-Elemente:** - Multi-Step-Flow (Slot wählen → Daten eingeben → Bestätigung) - Kalender-Komponente mit Verfügbarkeits-Indikator pro Tag - Timezone-Wechsler - Form-Renderer für Intake-Form (analog Modul 5 Renderer) - DSGVO-Checkbox + verlinkte Datenschutzerklärung - Loading-States während Slot-Refresh und Submit - Error-States mit Klartext (siehe G.4) ### G.3 — Konkurrenz-/Race-Condition - Beim finalen Submit prüft Server erneut Slot-Verfügbarkeit (Slots können zwischen Anzeige und Submit von anderen gebucht werden) - Bei Konflikt: Klartext *„Ohje, dieser Slot wurde gerade gebucht. Hier sind aktuelle Alternativen: ..."* mit aktualisierter Slot-Liste - DB-Level: Unique-Constraint via `EXCLUDE USING gist`-Range-Constraint pro Provider verhindert echte Doppelbuchung ### G.4 — Klartext-Hinweise - Booking-Page nicht publiziert: 404 mit Klartext *„Diese Buchungsseite gibt's nicht (mehr)."* - Tenant inaktiv: 404 mit gleichem Klartext (keine Tenant-Existenz preisgeben) - Keine freien Slots: *„Aktuell sind alle Termine belegt — schreib uns direkt an [Tenant-Email] oder probier später nochmal."* - Submit-Fehler 5xx: *„Buchung fehlgeschlagen — bitte erneut versuchen oder direkt anrufen."* - DSGVO-Checkbox nicht gesetzt: *„Bitte akzeptiere die Datenverarbeitungs-Hinweise um zu buchen."* --- ## Block H — Embed-Code ### H.1 — iFrame-Variante Im Booking-Page-Editor generierter Code: ``` ``` **Embed-spezifisch:** - Ohne Tenant-Branding-Header (kein Logo, kein Footer) - Responsive - `X-Frame-Options: ALLOWALL` für `/embed`-Route (CSP-konfiguriert) ### H.2 — JS-Snippet-Variante (nice-to-have Phase 1, sonst Phase 2) Lightweight-Loader für Pop-up-Buchung: ``` ``` **Phase-1-Empfehlung:** nur iFrame. JS-Snippet als Phase 2 oder als optionales Feature falls Aufwand klein. ### H.3 — UI-Anforderungen Embed-Code-Generator - Auswahl iFrame vs. JS-Snippet (falls beides angeboten) - Vorschau-Funktion - Copy-to-Clipboard-Funktion - Klartext-Hinweis: *„Copy-Paste in deine Website. Bei WordPress: HTML-Block. Bei Webflow: Embed-Element."* --- ## Block I — Auto-Bestätigungsmail ### I.1 — Template Tenant-Admin definiert Subject + Body pro Booking-Page. Defaults werden geseedet: ``` Subject: Bestätigung: {{booking_page.title}} am {{appointment.date}} Hallo {{contact.first_name}}, dein Termin ist bestätigt: 📅 {{appointment.date}} um {{appointment.time}} ⏱ {{booking_page.duration_minutes}} Minuten 👤 mit {{provider.full_name}} 📍 {{appointment.location}} {{booking_page.description}} Falls du den Termin verschieben oder absagen musst, antworte einfach auf diese Mail. Bis bald, {{tenant.company_name}} ``` ### I.2 — Verfügbare Template-Variablen - `{{appointment.date}}`, `{{appointment.time}}`, `{{appointment.duration}}`, `{{appointment.location}}` - `{{booking_page.title}}`, `{{booking_page.description}}`, `{{booking_page.duration_minutes}}` - `{{provider.full_name}}`, `{{provider.email}}`, `{{provider.phone}}` - `{{contact.first_name}}`, `{{contact.last_name}}`, `{{contact.email}}` - `{{tenant.company_name}}` ### I.3 — Sende-Mechanik - Auslösung: direkt nach erfolgreichem Submit (synchron) - Versand über Tenant-Sending-Domain (Modul 9) - Fallback wenn Sending-Domain nicht konfiguriert: System-Domain `noreply@hivegrid.de` mit Klartext-Hinweis im Editor *„Konfiguriere eine Absender-Domain für professionellere Mails."* - Fehler beim Versand: Termin bleibt gebucht, Internal-Note an Provider („Bestätigungsmail an {email} fehlgeschlagen — bitte manuell kontaktieren"), zudem Activity `email_send_failed` ### I.4 — Reminder-Mails (Phase 2) Nicht in Phase 1 — Erinnerungen 24h/1h vor Termin sind Phase 2. --- ## Block J — Verknüpfungen ### J.1 — Lead-Inbox / CRM Beim Submit: 1. Email-Match-Check gegen `Contact.email`-Liste: - **Match gefunden** → `Appointment.contact_id` direkt gesetzt, kein Lead erzeugt; Activity `appointment_scheduled` an Contact - **Kein Match** → neuer `Lead`-Record erzeugt mit `source = booking`, `Appointment.lead_id` gesetzt; Lead-Inbox zeigt diesen mit Booking-Hinweis 2. Form-Submission-Daten werden an `FormSubmission` gespeichert und mit `Appointment.form_submission_id` verknüpft ### J.2 — Internal Calendar - Termin wird automatisch in interne `CalendarEvent`-Tabelle (Modul 25) für `provider_user_id` eingetragen - Title aus `BookingPage.internal_calendar_event_title` mit Variablen-Substitution ### J.3 — External Calendar Sync (Modul 25) - Falls Provider Google/MS-Kalender verbunden hat: bidirektionale Sync - Beim Erstellen: `CalendarEvent` wird in externen Kalender geschoben, externe Event-ID in `Appointment.external_calendar_event_ids` gespeichert - Beim Cancel: externes Event gelöscht - Beim Reschedule: externes Event aktualisiert - Bei Sync-Fehler (z.B. Token abgelaufen): Klartext-Status im Termin-Detail + automatische Re-Try-Queue - Wichtig: externe Calendar-Events des Providers werden auch **gegen** Slot-Berechnung gerechnet (siehe A.6) — d.h. wenn der Provider in seinem Google-Kalender einen privaten Termin anlegt, wird dieser Slot automatisch in der Booking-Page ausgegraut ### J.4 — Activity-Stream-Integration Activity-Typen produziert von Modul 6: | Activity-Typ | Wann | Subject | |---|---|---| | `appointment_scheduled` | bei Buchung | Contact (oder Lead falls neu) | | `appointment_held` | bei manueller Status-Änderung auf `held` | Contact | | `appointment_cancelled` | bei Stornierung | Contact / Lead | | `appointment_rescheduled` | bei Verschiebung | Contact | | `appointment_no_show` | bei Status `no_show` | Contact | **Verknüpfung mit anderen Modulen:** - Activity am Contact (Modul 1) - Activity am Lead (Modul 2) - Activity am Provider-Pro-User-Dashboard - Activity in zugeordnetem Deal (falls Contact in einem Deal ist) — automatisch via `subject_type=contact` plus `related_entity_refs` ### J.5 — Form-Submission-Integration - Bei Buchung wird ein Form-Submission erzeugt (entweder Standard-Mini-Form oder Custom-Form aus `intake_form_id`) - FormSubmission ist vollwertig in Modul 5 sichtbar mit allen Antworten - Activity `form_submitted` wird zusätzlich erzeugt (für CRM-Stream-Konsistenz) --- ## Block K — Permissions-Anwendung ### K.1 — Permission-IDs | Permission | Erlaubt | |---|---| | `bookings.read_own` | Termine sehen wo `provider_user_id = self`; eigene Booking-Pages und Verfügbarkeit sehen | | `bookings.read_all` | Alle Termine, alle Booking-Pages, alle Verfügbarkeiten lesen | | `bookings.write` | Eigene Verfügbarkeit pflegen, eigene Termine als `held`/`no_show` markieren, eigene Termine canceln/reschedule, Booking-Page anlegen wenn auch `bookings.admin` | | `bookings.admin` | Booking-Pages anlegen/editieren/löschen, fremde Verfügbarkeiten pflegen, alle Termine canceln/hard-löschen | ### K.2 — Bundle-Mapping (Variante 2) | Bundle | Atomare Permissions | |---|---| | `bookings.none` | (keine) | | `bookings.read_own` | `bookings.read_own` | | `bookings.read_all` | `bookings.read_own` + `bookings.read_all` | | `bookings.write` | `bookings.read_all` + `bookings.write` | | `bookings.admin` | `bookings.read_all` + `bookings.write` + `bookings.admin` | ### K.3 — Anwendung in Routes - `/{tenant}/bookings` → `bookings.read_own` oder `bookings.read_all` - `/{tenant}/bookings/:id` → `bookings.read_own` (Owner-Check) oder `bookings.read_all` - `/{tenant}/bookings/pages/` → `bookings.read_all` (Liste sehen) — Edit erfordert `bookings.admin` - `/{tenant}/bookings/pages/new` → `bookings.admin` - `/{tenant}/bookings/pages/:id` → Lesen `bookings.read_all`, Editieren `bookings.admin` - `/{tenant}/availability` → `bookings.write` (eigene), für fremde User-Verfügbarkeit zu sehen reicht `bookings.read_all`, zu editieren braucht `bookings.admin` ### K.4 — Anwendung in Action-Buttons - Termin als `held`/`no_show` markieren: `bookings.write` (Owner-Check) oder `bookings.admin` - Termin canceln: `bookings.write` (Owner-Check) oder `bookings.admin` - Termin reschedule: `bookings.write` (Owner-Check) oder `bookings.admin` - Provider eines Termins ändern: `bookings.admin` - Termin hard-löschen: `bookings.admin` - Booking-Page anlegen/editieren: `bookings.admin` - Embed-Code generieren: `bookings.admin` ### K.5 — Owner-Check-Logik für `read_own` - `bookings.read_own`-User sehen nur Appointments mit `provider_user_id = self` - Booking-Pages sieht User mit `read_own` nur, wenn er als Provider in `BookingPageProvider` für diese Page eingetragen ist - Filter wird server-side angewendet (AV #5 — Permissions-aware-Default) ### K.6 — Öffentliche Booking-Page - Keine Permission-Prüfung — `app.hivegrid.de/buch/{tenant}/{slug}` ist öffentlich - Tenant muss `active` oder `trial` sein (nicht `frozen`/`suspended`/`deleted`); sonst Klartext-404 - Booking-Page muss `is_published = true` und `archived_at = null` sein --- ## Block L — Klartext-Hinweise / Fehler-Cases - Slug-Konflikt im Editor: *„Diese URL ist schon vergeben — wähle eine andere."* - Reserved-Slug: *„'{slug}' ist reserviert. Wähle einen anderen."* - Booking-Page ohne Provider speichern: *„Mindestens 1 Provider muss zugewiesen sein, sonst können Endkunden nicht buchen."* - Provider ohne Verfügbarkeits-Regeln: *„{Provider} hat keine Verfügbarkeit hinterlegt — er wird auf der Booking-Page nicht angezeigt."* - Slot beim Submit nicht mehr frei: *„Ohje, dieser Slot wurde gerade gebucht. Hier sind aktuelle Alternativen."* - Calendar-Sync-Fehler: *„Konnte Termin nicht in {Provider}-Kalender eintragen ({reason}). [Erneut versuchen]"* - Bestätigungsmail-Fehler: *„Bestätigungsmail an {email} ist nicht durchgekommen ({reason}). Bitte den Endkunden direkt informieren."* - Booking-Page archivieren mit zukünftigen Terminen: *„Diese Page hat noch {n} anstehende Termine. Bei Archivierung bleiben sie bestehen, aber neue Buchungen sind nicht mehr möglich."* - Provider-Wechsel im Termin: *„Termin wird im Kalender von [alter Provider] entfernt und bei [neuer Provider] eingetragen. Endkunde bekommt automatisch eine Update-Mail."* --- ## Block M — Phase 2 / spätere Features - **Conditional Slots:** „Slot nur freigeben wenn Frage X mit Y beantwortet" (z.B. „nur Wartungstermine wenn Anlage-Typ = Gas") - **Group-Bookings:** mehrere Teilnehmer pro Slot (Webinar-Style oder Beratungsrunde) - **Reschedule-/Cancel-Link mit Token:** Endkunde kann ohne Login über Magic-Link-Token verschieben/stornieren (Phase 1 nur via Antwort auf Bestätigungsmail manuell durch Tenant-Mitarbeiter) - **Reminder-Mails:** 24h/1h vor Termin automatisch - **SMS-Reminder:** via Twilio/Sipgate (kostenpflichtige Add-on-Funktion) - **Custom-Domain für Booking-Pages:** `termine.{tenant-domain}` statt `app.hivegrid.de/buch/{tenant}/...` (nur Enterprise) - **Pre-Payment / Deposit:** Stripe-Vorauszahlung beim Buchen - **Round-Robin mit Gewichtung:** Provider mit höherem Faktor bekommt mehr Termine - **Workload-Cap pro Provider:** „max. 5 Termine pro Tag" - **Tenant-Branding-Customization** auf öffentlicher Page (Logo, Farben — kommt aus Modul 31 in Phase 2) - **Collective-Bookings:** mehrere Provider gemeinsam für einen Termin - **CRM-Auto-Tag bei Buchung:** Tag X wird automatisch dem Contact gesetzt (Phase-2-Form-Action-Erweiterung) - **JS-Snippet-Embed** mit Pop-up-Modal-Variante (falls in Phase 1 nicht geliefert) - **Buchungs-Limit pro Endkunde:** „max. 1 offener Termin pro Email" zur Spam-Verhinderung --- ## Block N — Architektur-Vorschriften (Querschnitt) - **LP-7:** ist Pflicht-Modul (HubSpot-Booking-Ablösung) - **LP-9:** Spec-Tiefe — alle Felder, Validierungen, Verknüpfungen explizit - **LP-10:** Klartext-Diagnostik überall (Slot-Konflikt, Sync-Fehler, Mail-Fehler) - **AV #5 — Permissions-aware-Default:** alle Listen/Slots filtern automatisch nach User-Permissions - **AV #6 — Audit-Trail-Default:** alle Termin-Änderungen, Booking-Page-Änderungen geloggt (Modul 21) - **LP-11 — Adapter-Pattern:** Calendar-Sync läuft über Modul-25-Calendar-Adapter, nicht direkt gegen Google/MS - **AV #20 — Action-Boundary für KI:** KI darf Termine vorschlagen aber nicht direkt anlegen — User-Bestätigung Pflicht (relevant für Phase-2-KI-Booking-Assistent) --- ## Detail-Spec-Status: DRAFT Erste vollständige Detail-Spec für Modul 6. **Vor Bau:** - Slot-Berechnungs-Algorithmus mit echten Geerkens-Anwendungsfällen testen (Mehrere Provider, mehrere parallele Booking-Pages, KWP-Termine in Google-Kalender als Blocker) - Doppelbuchungs-Schutz auf DB-Ebene (PostgreSQL `EXCLUDE USING gist` mit `tstzrange`) verifizieren - Bestätigungsmail-Template-Engine festlegen (Liquid vs. Handlebars vs. Mustache — sollte konsistent mit Modul 10 Email-Marketing sein) - Embed-Route Sicherheits-Setup (X-Frame-Options, CSP, CORS) **Offene Detail-Punkte (nicht-blockierend):** - Standard-Mini-Form-Definition (welche Felder genau Pflicht sind, welche optional) — mit Designer/Noah finalisieren - Konkrete Default-Bestätigungsmail-Texte für Branchen-Template SHK - Workload-Cap als optionales Feld im BookingPage-Modell auch schon Phase 1 mitnehmen? - JS-Snippet-Embed Phase 1 oder Phase 2 (Aufwand-Schätzung beim Bau) - Add-to-Calendar-.ics-Generierung am Endpoint des Endkunden-Flows - Reschedule-Token mit kurzer Lebenszeit als Phase-1-„Lite"-Variante prüfen (statt voller Phase 2)