Files
HiveGrid-Wireframes/hivegrid-cloud/_bmad-output/specs/M06-booking.md
T

30 KiB

module, title, phase, status, last_updated, session_source, related_lps, spec_style
module title phase status last_updated session_source related_lps spec_style
6 Booking / Termin-Buchung (Calendly-Style) 1 detail-spec-draft 2026-05-08 brainstorming-session-2026-05-07-2206.md
LP-4
LP-7
LP-9
LP-10
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:

<iframe
  src="https://app.hivegrid.de/buch/{tenant}/{slug}/embed"
  width="100%"
  height="700"
  frameborder="0"
  style="border:none">
</iframe>

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:

<script src="https://app.hivegrid.de/embed/booking.js"></script>
<button data-hivegrid-booking="{tenant}/{slug}">Termin buchen</button>

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)