Files
HiveGrid-Wireframes/hivegrid-cloud/docs/boilerplate-mapping/M06-booking.md
T

20 KiB
Raw Blame History

Boilerplate-Abgleich: M06 — Booking / Termin-Buchung (Calendly-Style)

Feld Wert
Modul-ID M06 (Block 6, Modul 6)
Name Booking / Termin-Buchung (Calendly-Style)
Milestones M126 (Buchungs-Seite + Time-Slot-Engine), M127 (Verfügbarkeits-Berechnung), M128 (Bestätigungs-Flow + Verknüpfungen), M129 (Stornierung + Verschiebung + No-Show)
Pflichtenheft-Block block6.md §6.1–6.12
Detail-Spec _bmad-output/specs/M06-booking.md
Reuse-Level low

Reuse-Verdikt (Kurzfassung)

Das gesamte Booking-Domänen-Modell fehlt in der Boilerplate. Es gibt kein Prisma-Modell für BookingPage, BookingPageProvider, AvailabilityRule, AvailabilityException oder Appointment — verifiziert mit grep '^model (Booking|Appointment|Availability|Slot|Calendar|...)' über alle 27 prisma/schema/*.prisma-Dateien (Treffer: 0). Auch die im Spec als Dependency genannte Calendar-Sync (Modul 25, Google/MS) existiert in der Boilerplate NICHT (kein googleapis, kein @microsoft/microsoft-graph, kein Calendar-Service). Die Slot-Berechnungs-Engine und der Doppelbuchungs-Schutz (EXCLUDE USING gist/tstzrange/btree_gist — 0 Treffer in prisma/migrations) sind komplett neu zu bauen.

Was die Boilerplate liefert, ist ausschließlich das Querschnitt-Fundament (Permissions/Audit/Notify/Idempotenz/Adapter/CatalogError/View-Models/Feature-Flags/i18n), der Mail-Stack (für Bestätigungs-/Storno-Mails inkl. handlebars als Template-Engine), das Form-Widget (für Intake-Form-Renderer/Submissions, deckt M5-Kopplung), das Lead-Modell (für die „neuer Lead bei unbekannter Email"-Verknüpfung) und Infrastruktur (Queue/Outbox/Redis-Cache für die Slot-Cache-TTL, Public-Site-Pattern, Storage). Die Geschäftslogik des Moduls — Slots, Verfügbarkeit, Provider-Zuteilung, Public-Booking-Flow, iFrame-Embed, .ics, Kalender-Sync — ist vollständig HiveGrid-Neubau.


Übernehmbar aus Boilerplate

Boilerplate-Pfad Was Wie nutzbar
packages/foundation/src/permissions.ts withTenantScope(), withPermission(), withOwnerCheck(), requirePermission() — RLS-Tenant-Scope, Permission-Gate, Owner-Check für bookings.read_own (A.5/K.5); 404-statt-403 bei Denied 1:1
packages/foundation/src/audit.ts auditEvent(), withAuditMiddleware() — Audit-Trail für Termin-/Booking-Page-Änderungen (AV #6); Hash-Kette über AuditEvent 1:1
packages/foundation/src/notifications.ts notify(), notifyMany(), bundleNotifications() — interne Notifications (z.B. „Bestätigungsmail fehlgeschlagen — bitte manuell kontaktieren", I.3) statt Direkt-Mail 1:1
packages/foundation/src/idempotency.ts withIdempotency() — replay-sicherer Booking-Submit (verhindert Doppel-POST des Public-Flows) 1:1
packages/foundation/src/errors.ts CatalogError, foundationErrors (notFound 404, forbidden, idempotencyConflict 409) — Klartext-Diagnostik (LP-10): 404 für nicht-publizierte Page (G.4), 409 bei Slot-Race (G.3) als-vorlage (HiveGrid-Catalog-Errors ergänzen, z.B. Slot-Konflikt, Sync-Fehler, Slug-Konflikt)
packages/foundation/src/adapters.ts defineAdapter(), getAdapter() mit Status — Adapter-Pattern für Calendar-Sync (LP-11: Sync über Modul-25-Adapter, nicht direkt gegen Google/MS) als-vorlage (Calendar-Adapter selbst existiert nicht)
packages/view-models/src/index.ts VMState<T>, ActionCallbacks<T>, RegistryGate, SidebarRegistryItem, ready/empty, assertI18nLabel — VM-Status/Action-Vertrag für Listen-View (C), Detail-View (D), Editor (E), Verfügbarkeits-Page (F) 1:1
packages/feature-flags/src/* + packages/foundation/src/flags.ts evaluateFlag() / featureFlag() — Modul ohne Deploy abschaltbar (DoD „Feature-Flag-fähig") 1:1
packages/i18n/src/* Locale-Config (de/en), formatDate/formatNumber/ICU, useTranslate — alle UI-Texte + Datums-/Zeitformat in Endkunden-/Tenant-Timezone (A.3/G) 1:1
packages/mail/src/mailersend.ts + src/queue.ts + src/templates-react/* MailerSend-Provider (EU) + Queued-Mail + React-Email-Layout-Primitives (BaseLayout/Header/Footer/Button mit assertSafeUrl) — Bestätigungs-/Storno-/Update-Mail (I, 6.5, 6.8.4/6.8.5) anpassen (Booking-spezifische Templates neu; Layout 1:1)
handlebars (Root-Dependency, package.json) Template-Engine für confirmation_email_subject/_body + internal_calendar_event_title mit {{...}}-Variablen (I.1/I.2) — löst die im Spec offene Frage „Liquid vs. Handlebars vs. Mustache" zugunsten Handlebars (bereits vorhanden) 1:1 (Engine), anpassen (Variablen-Resolver für Booking-Kontext)
packages/shared-store/src/* (createCacheStore, TTL, Cross-Instance-Invalidation) Redis-KV für Slot-Cache (A.6: 60s-TTL pro (booking_page_id, date) + Invalidation bei neuer/gelöschter Appointment etc.) 1:1 (Engine), anpassen (Booking-Cache-Keys/Invalidation)
packages/queue/src/* + packages/db/src/outbox.ts (OutboxEvent) BullMQ + transaktionaler Outbox-Publisher — async Kalender-Sync-Re-Try-Queue (J.3, 6.4.4), Outbox für Activity-/Sync-Side-Effects in der Submit-Transaktion 1:1 (Infra), anpassen (Booking-Jobs/Event-Typen neu)
packages/form-widget/src/* + prisma/schema/formWidget.prisma (Form, FormSubmission) Form-Definition/Renderer/Submission-Inbox inkl. ipHash, Honeypot, Origin-Allowlist — Intake-Form (G.2): Standard-Mini-Form ODER intake_form_id→Modul-5-Form; FormSubmission ist das von Appointment.form_submission_id referenzierte Modell anpassen (Renderer wiederverwenden; Booking-Submit erzeugt FormSubmission + Activity form_submitted, J.5)
apps/web/app/modules/formWidget/builder/* (FormBuilder.tsx, PreviewTab.tsx, SettingsTab.tsx) Editor-/Preview-/Settings-Tab-Muster — Vorlage für Booking-Page-Editor (E.2: sektionierte Anzeige, Live-Preview, Publish-Toggle, Embed-Generator) als-vorlage
prisma/schema/marketingLeads.prisma (Lead, LeadEvent) Lead-Modell — „unbekannte Email → neuer Lead mit Quelle Buchung" (J.1, 6.9.1). Achtung: Lead ist operator-scoped, NICHT tenant-scoped (email @unique global). HiveGrid braucht hier ggf. einen tenant-scoped Lead — Abgleich mit M047 (Lead-Inbox) nötig anpassen / Klärung mit M047
prisma/schema/sites.prisma (Site, type = "booking", serverResolution domain/path/subdomain) Multi-Site-Konfig-Record mit Branding/Copy + Host-Resolution — Vorlage für Public-Booking-Site-Auflösung (/b/{tenant}/{slug}, B/G). Kein Booking-Domänenmodell, nur Site-Routing/Branding-Hülle als-vorlage
packages/url/src/canonical.ts host-aware appPath/appUrl — Public-URL-Bau für Page-Liste (E.1 Copy-to-Clipboard) + Embed-Src (H.1) 1:1
apps/web/app/components/ui/calendar.tsx (react-day-picker) Kalender-Primitive (date-fns-Locale, i18n) — Datum-Auswahl im Public-Slot-Picker (G.2) + Date-Range-Filter (C) anpassen (Verfügbarkeits-Indikator/Ausgrauen pro Tag ergänzen)
apps/web/app/components/ui/* (shadcn: table.tsx, tabs.tsx, multi-select.tsx, stepper.tsx, pagination.tsx, dialog.tsx, command.tsx, tables/ColumnSelector.tsx, tables/TablePagination.tsx) UI-Primitives — Listen-View (C: sortierbare Tabelle, Tabs, Filter, Spalten-Config, Cursor-Pagination), Multi-Step-Flow (G: Stepper), Provider-Multi-Select (E.2) 1:1 (Primitives), anpassen (Booking-Pages bauen)
apps/web/app/components/layouts/sidebars/shadcn/* + application/sidebar/SidebarItem.ts + AppSidebar.tsx Datengetriebene Sidebar mit Permission-/Feature-Gating — Sidebar-Gruppe „Arbeiten" → „Buchungs-Seiten" (INTEGRATION-CONTRACTS §1, M126-M129) 1:1 (Muster); HiveGrid-Ziel ist packages/ui-hivegrid/src/app-shell/sidebar.config.ts
packages/exports/src/csv/* + Worker export.ts CSV-Export-Framework mit Plan-Row-Caps + Injection-Safety — CSV-Export gefilterter Buchungs-Liste (C: „Export als CSV") 1:1
packages/storage/src/* (S3/Scaleway, Signed-URLs) EU-Storage — Datei-Uploads aus verknüpftem Intake-Form (falls Custom-Form Upload-Felder hat) 1:1
packages/db/src/client.server.ts + transactions.server.ts (runDbTransaction) Prisma-Client-Boundary + Transaktionen — atomarer Submit (Appointment + FormSubmission + Lead/Contact-Link + Outbox-Event in einer Tx, J/G.3) 1:1
packages/db/src/dsgvo/user-fk-map.ts DSGVO-FK-Karte — Pflicht-Eintrag für jeden neuen User-FK (Appointment.provider_user_id, AvailabilityRule.tenant_user_id, BookingPageProvider.tenant_user_id); CI-Test bricht sonst 1:1 (erweitern, kein Skip)
packages/db/src/search/indexed-entities.ts-Pattern + packages/search/* (Meilisearch, tenant-scoped) Search-Index-Registry — falls Buchungen global suchbar sein sollen (DoD „Search-Index, falls suchbar") als-vorlage
packages/ui-app + packages/ui-mock + apps/web/app/components/ui/hot-swap/* Shell-Registry-Factories + Hot-Swap-/Visual-Mock — DoD „Hot-Swap-Drill grün" + „Visual-Regression-Snapshot" 1:1 (Test-Infra)

Vorhandene Daten-Modelle (konkret)

Booking-Domäne: NICHTS vorhanden. Verifiziert: kein model BookingPage|BookingPageProvider|AvailabilityRule|AvailabilityException|Appointment in irgendeiner prisma/schema/*.prisma-Datei (grep '^model'-Treffer 0). prisma/schema/app.prisma ist der leere Platzhalter (// custom database models) — vorgesehener Ort für die neuen HiveGrid-Booking-Modelle.

Indirekt nutzbare / referenzierte Bestands-Modelle:

Modell Pfad Rolle für M06
User, TenantUser, Tenant prisma/schema/accounts.prisma Provider = TenantUser; Tenant-Scope-Anker; User-FK für provider_user_id/tenant_user_id
Form, FormSubmission prisma/schema/formWidget.prisma intake_form_id-Ziel (Custom-Intake) + Appointment.form_submission_id (Intake-Daten der Buchung)
Lead, LeadEvent prisma/schema/marketingLeads.prisma „neuer Lead bei unbekannter Email" (operator-scoped — Klärung mit M047 nötig)
Site prisma/schema/sites.prisma type="booking"-Site-Config + Host-Resolution (Routing/Branding-Hülle, KEIN Booking-Modell)
AuditEvent, IdempotencyKey prisma/schema/core.prisma Audit-Trail + idempotenter Submit
OutboxEvent prisma/schema/outbox.prisma transaktionale Side-Effects (Sync/Activity/Mail)
NotificationDelivery, UserNotificationPreference prisma/schema/notifications.prisma interne Hinweise an Provider (Mail-Fehler etc.)
FeatureFlag prisma/schema/featureFlags.prisma Modul-Abschaltung ohne Deploy
Email, OutboundEmail prisma/schema/email.prisma E-Mail-Infrastruktur (Bestätigungs-/Storno-Mail-Tracking; Tenant-Sending-Domain = Modul 9 separat)

Neu anzulegen (in app.prisma): BookingPage, BookingPageProvider, AvailabilityRule, AvailabilityException, Appointment — komplett gemäß Spec A.1–A.5, inkl. Indizes und Enums (assignment_strategy, status, cancelled_by_kind, kind, day_of_week).


Lücken / komplett neu zu bauen

  1. Komplettes Booking-Daten-Modell (A.1–A.5): BookingPage, BookingPageProvider (M:N), AvailabilityRule, AvailabilityException, Appointment — inkl. aller Felder/Enums/Indizes. Forward-Only-Migration mit Inverse-SQL als Kommentar.
  2. Doppelbuchungs-Schutz auf DB-Ebene (G.3): EXCLUDE USING gist mit tstzrange pro Provider — btree_gist-Extension muss aktiviert werden (pgvector-Migration zeigt das Muster für Extension-Aktivierung; gist/tstzrange selbst: 0 Treffer in prisma/migrations).
  3. Slot-Berechnungs-Engine (A.6, M127): Layer-Modell Standard-Regel → Exceptions → bestehende Appointments (+Buffer) → externe Calendar-Events → Plantafel → min/max-Vorlauf → Slot-Increment → Assignment-Strategy-Merge. Server-side, gecacht 60s in Redis (shared-store liefert nur die Cache-Primitive, nicht die Logik).
  4. Provider-Zuteilungs-Strategien (A.2): round_robin (wenigste Buchungen letzte 30 Tage), specific_provider_choice, first_available — reine HiveGrid-Logik.
  5. Public-Booking-Flow (G, M126): Multi-Step-Wizard (Slot → Intake → Bestätigung), Verfügbarkeits-Kalender mit ausgegrauten Tagen, Timezone-Wechsler, Race-Condition-Handling mit Klartext + aktualisierten Alternativen, .ics-Add-to-Calendar. Kein Bestandscode.
  6. Public-Route ohne Login + Embed (B/H): /b/{tenant}/{slug} und /b/{tenant}/{slug}/embed; Embed ohne Branding-Header + X-Frame-Options: ALLOWALL/CSP für /embed. Boilerplate-Public-Routes existieren (Forms /f/...), aber Booking-Routen + Embed-CSP-Setup sind neu.
  7. Embed-Code-Generator (H.3): iFrame-Snippet + Copy-to-Clipboard + Klartext-Hilfe. Optional JS-Snippet-Loader (booking.js) — Phase-2-Tendenz.
  8. Calendar-Sync (Modul 25) — fehlt komplett in der Boilerplate: kein interner Kalender (CalendarEvent), kein Google/MS-Adapter, kein googleapis/MS-Graph-Dep, kein bidirektionaler Sync, keine externen Events als Slot-Blocker (A.6/J.2/J.3). M118–M120 (Calendar) sind harte Vorbedingung von M126/M127/M128 und müssen vorher gebaut sein. M06 konsumiert sie nur über den Adapter (LP-11).
  9. Bestätigungs-/Storno-/Update-Mail-Inhalt (I, M128/M129): Booking-spezifische Handlebars-Templates + Variablen-Resolver (appointment.*, booking_page.*, provider.*, contact.*, tenant.company_name); Default-Seeds (SHK-Branche); Versand über Tenant-Sending-Domain (Modul 9) mit Fallback noreply@hivegrid.de. Mail-Stack/Layout vorhanden, Templates neu.
  10. .ics-Generator (G.3/6.5.3): Add-to-Calendar-Datei für Endkunde — keine ics/ical-generator-Dependency vorhanden.
  11. Verknüpfungs-Logik (J, M128): Email-Match gegen Contact → contact_id ODER neuer Lead; FormSubmission-Erzeugung; Activity-Typen (appointment_scheduled/held/cancelled/rescheduled/no_show, form_submitted) via logActivity (Activity-Service @hivegrid/activity ist HiveGrid-M045, nicht Boilerplate). Deal-Verknüpfung wenn Contact in Deal.
  12. Interne Termin-Verwaltung (C/D/M129): Listen-View (Filter/Tabs/Bulk-Cancel/CSV-Export/Spalten-Config/Cursor-Pagination), Detail-View (Sektionen, Inline-Notes, Sync-Status-Badge, Action-Buttons), Status-Transitions (held/no_show/cancelled/rescheduled), Reschedule mit Slot-Picker, Provider-Re-Assignment mit Kalender-Resync + Update-Mail.
  13. Verfügbarkeits-Verwaltung-UI (F, M127): Wochen-Editor (mehrere Fenster/Tag, Auto-Merge überlappender Fenster), Ausnahmen-Editor, Timezone pro Regel, Bulk „diese Woche nicht verfügbar" (7 Exceptions).
  14. Booking-Page-Editor (E, M126): sektionierter Editor, Live-Slug-Validation (Eindeutigkeit + Reserved-Words + Auto-Vorschlag), Markdown-Editor, Provider-Multi-Select mit Drag&Drop-display_order, Intake-Form-Dropdown, Publish-Toggle, Duplizieren/Archivieren/Hard-Delete mit Klartext-Warnungen.
  15. Booking-Permission-Set (K): bookings.read_own / read_all / write / admin + Bundle-Mapping in packages/entitlements/src/permissions.ts (HiveGrid-Konvention) — Boilerplate hat RBAC-Modelle (Permission/Role), aber keine Booking-Keys.
  16. packages/ui-hivegrid + packages/ui-subframe-Booking-Pages: In der Boilerplate ist ui-hivegrid nicht vorhanden und ui-subframe ist leerer Platzhalter ({ status: "empty" }). Subframe-Design + Adapter-Integration sind komplett neu (User-Memory: jede Route via Subframe).

Empfohlenes Vorgehen (Reihenfolge)

Phase 0 — Vorbedingungen prüfen (blockierend):

  • M118–M120 (Calendar: interner CalendarEvent + Google/MS-Sync-Adapter) müssen existieren, sonst sind A.6 (externe Events als Slot-Blocker) und J.2/J.3 nicht baubar. Calendar-Sync ist nicht in der Boilerplate — vor M06 sicherstellen.
  • M042/M047 (Contact/Lead-Inbox) für die Submit-Verknüpfung (J.1); Lead-Scope (operator vs. tenant) mit M047 klären.
  • M5 (Form-Builder) für intake_form_id-Renderer (G.2) — Boilerplate-form-widget ist die Basis.

Phase 1 — Querschnitt 1:1 übernehmen (kein Neubau):

  1. foundation (permissions/audit/notify/idempotency/errors/adapters) + view-models + feature-flags + i18n + url als Service-Imports verdrahten.
  2. db-Boundary (client.server, runDbTransaction, Outbox-Publisher) + queue + shared-store (Cache) als Infra einziehen.
  3. Mail-Stack (@toolctrl/mail) + handlebars als Template-Engine festschreiben (löst offene Spec-Frage).

Phase 2 — Daten-Modell + DB-Schutz (M126-Fundament): 4. Neue Modelle in prisma/schema/app.prisma (A.1–A.5) + Forward-Only-Migration; user-fk-map.ts für alle neuen User-FKs ergänzen (CI-Pflicht). 5. EXCLUDE USING gist/tstzrange + btree_gist-Extension für Doppelbuchungs-Schutz (G.3) — Muster aus pgvector-Extension-Migration. 6. Booking-Permission-Keys + Bundles (K) in entitlements/permissions.ts.

Phase 3 — Engine + Public-Flow (M126/M127, der Neubau-Kern): 7. Slot-Berechnungs-Engine (A.6) als pure Domain-Logik in app/domain/** (keine React/Prisma-UI-Kopplung) + Redis-Cache via shared-store + Invalidation. 8. Provider-Zuteilungs-Strategien (A.2). 9. Verfügbarkeits-Verwaltung (F) und Booking-Page-Editor (E) — Editor/Preview-Muster aus formWidget/builder als Vorlage. 10. Public-Booking-Flow (G) inkl. Race-Condition-Handling + .ics-Generator (neue ics/ical-generator-Dependency); Public-Route /b/{tenant}/{slug} (+/embed mit CSP), Site-Resolution via sites.prisma-Muster.

Phase 4 — Verknüpfungen + Bestätigung (M128): 11. Submit-Transaktion: Appointment + FormSubmission (form-widget) + Contact-Match/Lead-Erzeugung + Outbox-Events (Activity/Sync/Mail) atomar. 12. Bestätigungs-Mail-Templates (Handlebars + Booking-Variablen-Resolver) über Tenant-Sending-Domain (Modul 9) mit Fallback; Kalender-Eintrag intern + extern (Modul-25-Adapter) + Re-Try-Queue.

Phase 5 — Interne Verwaltung (M129): 13. Listen-View (C) mit shadcn-Tabelle/Tabs/Filter/CSV-Export (exports). 14. Detail-View (D) + Status-Transitions + Storno/Reschedule/Re-Assignment mit Auto-Mails (Storno/Update) und Kalender-Resync.

Querschnitt durchgehend (DoD/INTEGRATION-CONTRACTS): Sidebar-Eintrag „Buchungs-Seiten" (Gruppe Arbeiten), Breadcrumbs, alle Texte als i18n-Keys, withTenantScope+withPermission, Audit auto, logActivity (M045), notify (M011), Feature-Flag, Permission-Denied → 404, Unit-Test (VM + Zod), Smoke-Test, Hot-Swap-Drill, Visual-Snapshot, Forward-Only-Migration mit Inverse-SQL. Subframe-Design pro Route (User-Memory) + Adapter in packages/ui-hivegrid/src/adapters/.


Anti-Erfindungs-Hinweise (faktisch verifiziert)

  • Kein Booking/Appointment/Availability/Calendar/Slot-Prisma-Modell in der Boilerplate (grep '^model ...' über alle 27 Schemas: 0).
  • Kein Calendar-Sync (Google/MS): kein googleapis/@microsoft/microsoft-graph-Dep, kein Calendar-Service in apps/web/apps/worker.
  • Kein ics/ical-generator-Dep (Add-to-Calendar neu).
  • Kein EXCLUDE USING gist/tstzrange/btree_gist in prisma/migrations (Doppelbuchungs-Schutz neu).
  • handlebars IS vorhanden (Root-package.json) — direkt als Mail-/Title-Template-Engine nutzbar.
  • Site.type = "booking" in sites.prisma ist nur ein Site-Config/Routing-Record, kein Booking-Domänenmodell.
  • core.prisma.Event ist ein generisches Webhook-/Domain-Event, kein Kalender-Event.
  • packages/ui-subframe ist leer; packages/ui-hivegrid existiert in der Boilerplate nicht — beides HiveGrid-Neubau.
  • Lead ist operator-scoped (email @unique global), nicht tenant-scoped — Verknüpfungs-Scope mit M047 klären.