20 KiB
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
- 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. - Doppelbuchungs-Schutz auf DB-Ebene (G.3):
EXCLUDE USING gistmittstzrangepro Provider —btree_gist-Extension muss aktiviert werden (pgvector-Migration zeigt das Muster für Extension-Aktivierung; gist/tstzrange selbst: 0 Treffer inprisma/migrations). - 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-storeliefert nur die Cache-Primitive, nicht die Logik). - Provider-Zuteilungs-Strategien (A.2):
round_robin(wenigste Buchungen letzte 30 Tage),specific_provider_choice,first_available— reine HiveGrid-Logik. - 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.
- 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. - Embed-Code-Generator (H.3): iFrame-Snippet + Copy-to-Clipboard + Klartext-Hilfe. Optional JS-Snippet-Loader (
booking.js) — Phase-2-Tendenz. - Calendar-Sync (Modul 25) — fehlt komplett in der Boilerplate: kein interner Kalender (
CalendarEvent), kein Google/MS-Adapter, keingoogleapis/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). - 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 Fallbacknoreply@hivegrid.de. Mail-Stack/Layout vorhanden, Templates neu. - .ics-Generator (G.3/6.5.3): Add-to-Calendar-Datei für Endkunde — keine
ics/ical-generator-Dependency vorhanden. - Verknüpfungs-Logik (J, M128): Email-Match gegen Contact →
contact_idODER neuer Lead;FormSubmission-Erzeugung; Activity-Typen (appointment_scheduled/held/cancelled/rescheduled/no_show,form_submitted) vialogActivity(Activity-Service@hivegrid/activityist HiveGrid-M045, nicht Boilerplate). Deal-Verknüpfung wenn Contact in Deal. - 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. - 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).
- 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. - Booking-Permission-Set (K):
bookings.read_own / read_all / write / admin+ Bundle-Mapping inpackages/entitlements/src/permissions.ts(HiveGrid-Konvention) — Boilerplate hat RBAC-Modelle (Permission/Role), aber keine Booking-Keys. packages/ui-hivegrid+packages/ui-subframe-Booking-Pages: In der Boilerplate istui-hivegridnicht vorhanden undui-subframeist 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-widgetist die Basis.
Phase 1 — Querschnitt 1:1 übernehmen (kein Neubau):
foundation(permissions/audit/notify/idempotency/errors/adapters) +view-models+feature-flags+i18n+urlals Service-Imports verdrahten.db-Boundary (client.server,runDbTransaction, Outbox-Publisher) +queue+shared-store(Cache) als Infra einziehen.- Mail-Stack (
@toolctrl/mail) +handlebarsals 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 inapps/web/apps/worker. - Kein
ics/ical-generator-Dep (Add-to-Calendar neu). - Kein
EXCLUDE USING gist/tstzrange/btree_gistinprisma/migrations(Doppelbuchungs-Schutz neu). handlebarsIS vorhanden (Root-package.json) — direkt als Mail-/Title-Template-Engine nutzbar.Site.type = "booking"insites.prismaist nur ein Site-Config/Routing-Record, kein Booking-Domänenmodell.core.prisma.Eventist ein generisches Webhook-/Domain-Event, kein Kalender-Event.packages/ui-subframeist leer;packages/ui-hivegridexistiert in der Boilerplate nicht — beides HiveGrid-Neubau.Leadist operator-scoped (email @uniqueglobal), nicht tenant-scoped — Verknüpfungs-Scope mit M047 klären.