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 |
|
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_idslug(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_iddisplay_order(für UI-Reihenfolge beispecific_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_atday_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_atdate(Pflicht)kind(Enum:unavailable | custom_window)start_time,end_time(nur wennkind = custom_window; nullable beiunavailable)reason(optional, Freitext z.B. „Urlaub", „Schulung")timezone(IANA, Default wie Regel)
Sonderfälle:
unavailableohne Zeiten: ganzer Tag blockiertcustom_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_atbooking_page_id(FK BookingPage)provider_user_id(FK TenantUser — wer hält den Termin)start_at(Pflicht, UTC)end_at(Pflicht, UTC; berechnet ausstart_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_reasonrescheduled_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":
- Lade alle aktiven Provider der Booking-Page
- Pro Provider:
- Standard-Verfügbarkeit aus
AvailabilityRulefürday_of_weekvon X - Überlagern mit
AvailabilityExceptionfü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) woprovider_user_idder Provider ist und Zeitraum überlappt - Subtrahieren:
min_notice_hours(keine Slots in den nächsten N Stunden) - Subtrahieren: alles außerhalb
max_advance_days
- Standard-Verfügbarkeit aus
- Slot-Increment anwenden: nur Slots an Vielfachen von
slot_increment_minutes - Nach
assignment_strategyzusammenführen:round_robin/first_available: Union aller Provider-Slots, jeder Slot mit „Provider X frei"-Markerspecific_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_atin 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 ASCfürstatus = 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 woprovider_user_id = selfbookings.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 mitrescheduled_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.writeoderbookings.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_idgesetzt: 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_bookingfalls 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: ALLOWALLfü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.demit 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:
- Email-Match-Check gegen
Contact.email-Liste:- Match gefunden →
Appointment.contact_iddirekt gesetzt, kein Lead erzeugt; Activityappointment_scheduledan Contact - Kein Match → neuer
Lead-Record erzeugt mitsource = booking,Appointment.lead_idgesetzt; Lead-Inbox zeigt diesen mit Booking-Hinweis
- Match gefunden →
- Form-Submission-Daten werden an
FormSubmissiongespeichert und mitAppointment.form_submission_idverknüpft
J.2 — Internal Calendar
- Termin wird automatisch in interne
CalendarEvent-Tabelle (Modul 25) fürprovider_user_ideingetragen - Title aus
BookingPage.internal_calendar_event_titlemit Variablen-Substitution
J.3 — External Calendar Sync (Modul 25)
- Falls Provider Google/MS-Kalender verbunden hat: bidirektionale Sync
- Beim Erstellen:
CalendarEventwird in externen Kalender geschoben, externe Event-ID inAppointment.external_calendar_event_idsgespeichert - 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=contactplusrelated_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_submittedwird 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_ownoderbookings.read_all/{tenant}/bookings/:id→bookings.read_own(Owner-Check) oderbookings.read_all/{tenant}/bookings/pages/→bookings.read_all(Liste sehen) — Edit erfordertbookings.admin/{tenant}/bookings/pages/new→bookings.admin/{tenant}/bookings/pages/:id→ Lesenbookings.read_all, Editierenbookings.admin/{tenant}/availability→bookings.write(eigene), für fremde User-Verfügbarkeit zu sehen reichtbookings.read_all, zu editieren brauchtbookings.admin
K.4 — Anwendung in Action-Buttons
- Termin als
held/no_showmarkieren:bookings.write(Owner-Check) oderbookings.admin - Termin canceln:
bookings.write(Owner-Check) oderbookings.admin - Termin reschedule:
bookings.write(Owner-Check) oderbookings.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 mitprovider_user_id = self- Booking-Pages sieht User mit
read_ownnur, wenn er als Provider inBookingPageProviderfü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
activeodertrialsein (nichtfrozen/suspended/deleted); sonst Klartext-404 - Booking-Page muss
is_published = trueundarchived_at = nullsein
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}stattapp.hivegrid.de/buch/{tenant}/...(nur Enterprise) - Pre-Payment / Deposit: Legacy-Provider-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 gistmittstzrange) 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)