Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/ticket-docs/AK-P16b.md
T
2026-07-08 16:15:37 +02:00

12 KiB

AK-P16b · P16 Booking (Slots + Verfügbarkeit + Storno)

Typ Dev (Code)
Owner Akeshan
Phase P16 — Kalender, Booking, Forms & Signatur
Cycle/Fenster W4 — USP, Härtung & Launch · fällig 2026-07-05 · Gate W4
Status in Arbeit (~92 % gewichtet; 5/7 DoD vollständig, 2/7 teilfertig; selbst machbarer Server-Rest erledigt, Rest David D-P16/AK-P16c + Staging-DB-Ausführung)

Abhängigkeiten & Parallelität

  • Blocked by: AK-P16a (Kalender-Sync — Slot-Verfügbarkeit braucht Busy-Slots aus Google)
  • Blocks: — (Intake-Form-Wahl referenziert AK-P16c, läuft aber im selben Fenster)
  • Läuft parallel zu: Raffaels Kern-Kette + den anderen P16-Slices (c/d). Eigene prisma/schema/booking.prisma (AD-21); Buchung erzeugt Lead/Activity im CRM-Kern (R-P6/P7).
  • Konflikt-Risiko: gering — additive Tabellen; crm.prisma/calendar.prisma/forms.prisma nur über Relationen berührt.

Was wir bauen

Öffentliche Buchungsseiten im Calendly-Stil: timezone-aware Slot-Berechnung aus Verfügbarkeitsregeln, Ausnahmen, Kalender-Sync (AK-P16a) und Puffer/Vorlauf, mit iFrame-Embed. Nach der Buchung entsteht ein Lead (oder Activity bei Email-Match), eine FormSubmission (Intake-Form aus AK-P16c) und eine Bestätigungs-Email (.ics/Add-to-Calendar). Nur eine Zuteilungs-Strategie „Erster der frei ist" (Round-Robin/Provider-Wahl → v2). Der volle Lifecycle ist v1: Storno/Verschiebung/Re-Assign/No-Show (M129 explizit VOLL) inkl. Auto-Mail bei Cancel + Race-Schutz beim Submit.

Benötigte Screens (Backend bedient — Design liefert D-BOOK + D-P16)

Screen [Route] Kern-Inhalt
🌐 Booking-Page [/b/{tenant}/{slug}] Multi-Step: Slot-Picker (timezone-aware + Wechsler) → Intake-Form → Bestätigung + Add-to-Calendar (.ics), Tenant-Logo, iFrame-Variante — BESPOKE-Public
Buchungen-Liste [/bookings] Termin/Endkunde/Page/Provider/Status, Tabs Anstehend/Vergangen/Storniert/Alle, Filter, Bulk-Cancel, CSV
Buchung-Detail [/bookings/:id] Termin-Daten, verknüpfter Kontakt/Lead, Form-Antworten, Sync-Status-Badge; Aktionen held/no-show, Cancel (Grund + Auto-Mail), Reschedule (Slot-Picker), Provider-Re-Assign
Booking-Page-Editor [/bookings/pages/:id, /new] · Pages-Liste [/bookings/pages] Dauer/Puffer/Vorlauf, Provider-Auswahl, Intake-Form-Wahl, Bestätigungsmail-Template, Publish + Embed-Code-Generator
Verfügbarkeit [/availability] Wöchentliche Standard-Regeln (mehrere Zeitfenster/Tag), Datums-Ausnahmen (frei/Custom-Window), Timezone

Definition of Done

  • Öffentliche Booking-Seiten berechnen Slots timezone-aware (Regeln, Ausnahmen, Kalender-Sync, Puffer, Vorlauf)
  • [~] Nach Buchung: Lead oder Activity (Email-Match), FormSubmission, Bestätigungs-Email (.ics) — Race-Schutz beim Submit · Kontakt-Email-Match → Activity, sonst echtes InboxLead + Appointment.leadId; bei gesetzter intakeFormId echtes FormSubmission + Appointment.formSubmissionId, sonst intakeAnswers Json-Fallback
  • iFrame-Embed + Public-URL mit Copy
  • Nur eine Zuteilungs-Strategie „Erster der frei ist" (Round-Robin/Provider-Wahl → v2)
  • [~] Storno/Verschiebung/Re-Assign/No-Show (M129 VOLL) inkl. Auto-Mail bei Cancel · Service + Route-Action-Contract vollständig; Reschedule/Re-Assign-Picker-UI → David D-P16
  • Permission-Bundle bookings.* (read_own/read_all/write/admin) serverseitig Owner-gefiltert
  • Konnektor tenantHasModule('booking'); RLS auf allen Tenant-Tabellen (RLS-SQL als deferred Cutover wie Kalender)

Technische Bausteine

  • Entities (eigene prisma/schema/booking.prisma): BookingPage (slug, duration_minutes, assignment_strategy, is_published, intake_form_id), BookingPageProvider (M:N User), AvailabilityRule/AvailabilityException, Appointment (provider_user_id, start/end, status scheduled/held/cancelled/no_show/rescheduled, kontakt_id|lead_id, form_submission_id). calendar.prisma/crm.prisma/forms.prisma nur über Relationen (AD-21).
  • Slot-Engine: kombiniert Regeln/Ausnahmen + Google-Busy-Slots (AK-P16a) + Puffer/Vorlauf, timezone-aware; Race-Schutz (Transaction/Lock beim Submit gegen Doppelbuchung).
  • Post-Booking: Lead/Activity (R-P6/P7) + FormSubmission (AK-P16c) + Bestätigungs-Mail (.ics) via Email (AK-P14a-Versand).
  • Lifecycle: Cancel/Reschedule/Re-Assign/No-Show mit Status-Übergängen + Auto-Mail.
  • RLS überall; bookings.*-Bundle; is_demo_data auf Demo-Pages/-Buchungen.

Quellen (granular)

  • ENTITY-MODEL.md → Domäne 9 (BookingPage/Provider, AvailabilityRule/Exception, Appointment)
  • REQUIREMENTS.md → REQ-booking-datenmodell, REQ-booking-slot-kalkulierung, REQ-booking-integrationen
  • ROADMAP.md → Phase 16 · PHASE-SOURCES.md → Phase 16 (M126-time-slot, M127-verfuegbarkeit, M128-bestaetigung, M129-stornierung — M129 explizit VOLL)
  • designer-briefs/P16-kalender-booking-forms-signatur.md (Gruppe 2 Booking; eine Zuteilungs-Strategie v1)
  • _bmad-output/specs/M06-booking.md

Dev-Nachzug (nach Davids D-BOOK/D-P16-Delta)

  • Spec/ENTITY-MODEL an Davids UI-Entscheidungen angepasst
  • REQUIREMENTS/PHASE-SOURCES nachgezogen
  • Plane-Ticket AK-P16b aktualisiert

Umsetzungs-Notiz (2026-06-30, Akeshan) — ~85 % DoD

Branch feat/AK-P16b (von feat/AK-P16a abgezweigt, AD-21), 8 Commits (fecf6f19f → b262dabe8), nicht gepusht, Plane-Status unverändert. Alle Verifikations-Gates grün: pnpm prisma validate, @hivegrid/{web,db,view-models,entitlements,queue} + @hivegrid/activity typecheck 0 Fehler, verify:i18n (i18n-check) exit 0, 26 Booking-Unit-Tests grün (slotEngine 11, ics 5, transitions 5, VM 3, auth-boundary 2). lefthook pre-commit je Commit grün.

4 Forks (User-Freigabe 2026-06-30): (1) Lead-Gap → Kontakt-Match/Create + logActivity, leadId reserviert R-P7. (2) Intake-Gap → intakeAnswers Json am Appointment, formSubmissionId reserviert AK-P16c. (3) Modul-Gate → eigener booking Feature-Key (tenantHasModule('booking')). (4) Scope → Backend + funktionale Routen inkl. minimal-funktionaler öffentlicher Strecke.

DoD-Stand:

  • Slot-Engine timezone-aware (DoD 1) — slotEngine.ts pure (Regeln/Ausnahmen, Buffer, min-notice/max-advance, Increment, first_available-Union); Google-Busy via AK-P16a availability.ts (leak-safe). 11 Tests inkl. DST. /b/{tenant}/{slug}.
  • [~] Post-Booking + Race (DoD 2) — Serializable-Tx Slot-Re-Check + Postgres EXCLUDE USING gist-Backstop (booking-constraints.sql); Kontakt-Match/Create + appointment_scheduled-Activity; intakeAnswers Json; lokales CalendarEvent; Bestätigungsmail + .ics-Attachment (buildIcs pure). Offen: echte FormSubmission (AK-P16c), echtes CRM-Lead (R-P7) — bewusst reserviert.
  • iFrame-Embed + Public-URL (DoD 3) — /b/.../embed (frame-ancestors) + Embed-Code-Generator + Public-URL-Copy im Page-Editor.
  • Eine Strategie (DoD 4) — first_available implementiert; Enum trägt alle 3 (round_robin/specific_provider_choice → v2, additiv).
  • [~] Lifecycle M129 (DoD 5) — BookingLifecycleService: held/no_show/cancel/ reschedule/reassign mit lokalem CalendarEvent-Nachzug + Auto-Mail + Activity + notify(); Detail-Route mit held/no_show/cancel-Actions (CSRF+Owner). Offen: Reschedule-/Re-Assign-Picker-UI (Slot-/Provider-Auswahl) → David D-P16.
  • bookings. owner-gefiltert (DoD 6)* — 4 Registries, bookingAccess.server.ts (Modul-Gate + Permission + Appointment-Owner-Check, 404 statt 403), Liste server-seitig owner-gefiltert. Auth-Boundary-Test.
  • Konnektor + RLS (DoD 7) — booking Feature-Key + Gate; booking-isolation.sql (deferred Cutover wie Kalender), booking-constraints.sql (gist + btree_gist).

Selbst machbar offen (~15 %): /availability-Editor-UI (M06 F — Modelle + Slot-Engine konsumieren Verfügbarkeit bereits; nur die Pflege-Oberfläche fehlt) · Reschedule/Re-Assign-Picker-Verdrahtung. Staging-DB-blockiert: prisma db push + psql -f booking-constraints.sql + RLS-Live-Check + Race-Integrationstest (db-gated) — lokal keine DB gestartet, wie AK-P16a deferred. David D-P16-blockiert: bespoke öffentliche Booking-Page + Reschedule-Picker + Visual-Regression (DoD 21) + Hot-Swap-Drill (DoD 20).

Hinweise: Mail-Attachment-Durchreichung im Queue-Provider ergänzt (Payload trug attachments bereits, nur der Provider-Hop ließ sie fallen). 3 Booking-Activity-Typen (appointment_cancelled/rescheduled/no_show) zur Activity-Union ergänzt. Connect/ Lifecycle sind CRM-Subject-Activities (kein eigenes Booking-Subject).

Umsetzungs-Notiz (2026-07-01, Raffael) — ~90 % gewichtet, 5/7 DoD vollständig

Direkt auf main serverseitig nachgezogen, um den ohne Screens selbst machbaren P16b-Rest zu maximieren.

Nachzug:

  • Public Booking erzeugt bei fehlendem Kontakt jetzt ein echtes InboxLead über createLead(...), verknüpft es über Appointment.leadId und schreibt die Activity auf Kontakt oder Lead. Der alte automatische Kontakt-Create ist raus.
  • Detail-Route akzeptiert serverseitig die M129-Intents reschedule und reassign mit bookings.write bzw. bookings.admin; die Picker-UI bleibt D-P16-blockiert.
  • AvailabilityService.server.ts ergänzt den atomaren Replace-/Read-Contract für AvailabilityRule/AvailabilityException inkl. Zeitfenster-, Datum- und Timezone-Validierung. Die /availability-Oberfläche bleibt screen-blockiert.
  • Tests ergänzt: Availability-Service-Unit-Test, Post-Booking-Static-Guard, Lifecycle-Action-Authorization-Guard.

DoD-Stand nach Nachzug:

  • Vollständig abgehakt: DoD 1, 3, 4, 6, 7 = 5/7 vollständig.
  • Teilfertig: DoD 2 ist serverseitig bis auf echte FormSubmission erledigt (AK-P16c); DoD 5 ist serverseitig erledigt, aber Reschedule/Reassign-Picker-UI wartet auf David D-P16.
  • Offen/blockiert: echte FormSubmission (AK-P16c), D-P16-Screens/Visuals, Staging-DB-Cutover (prisma db push, booking-constraints.sql, RLS-Live-Check, Race-Integrationstest).

Proof lokal: pnpm exec vitest run apps/web/app/modules/booking/services/AvailabilityService.server.test.ts apps/web/app/modules/booking/services/booking-postbooking-boundary.test.ts apps/web/app/modules/booking/routes/booking-auth-boundary.test.ts → 8/8 grün; pnpm typecheck → grün.

Umsetzungs-Notiz (2026-07-01, Raffael) — ~92 % gewichtet, selbst machbarer Server-Rest erledigt

Noch ohne Screens nachgezogen:

  • BookingPage.intakeFormId wird im Public-Booking-Resolve mitgeladen.
  • Public Booking schreibt innerhalb derselben Serializable-Transaktion eine echte FormSubmission, sobald die BookingPage ein Intake-Form referenziert, und verlinkt Appointment.formSubmissionId. Ohne intakeFormId bleibt intakeAnswers der Fallback, damit bestehende BookingPages nicht brechen.
  • Statische DB-Artefakt-Guards ergänzt: booking-constraints.sql muss die appointment_no_overlap-Exclusion-Constraint für scheduled/held enthalten; booking-isolation.sql muss alle fünf Booking-Tabellen mit RLS/FORCE/GUC-Policy und hivegrid_app-Grant abdecken.

DoD-Stand nach Nachzug:

  • DoD 2 ist serverseitig maximal: Lead/Activity, FormSubmission bei konfiguriertem Intake-Form, .ics-Mail, Serializable Slot-Re-Check und SQL-Backstop sind vorhanden. Vollständig grün wird der Punkt erst mit AK-P16c-Renderer/Form-Auswahl und echter Staging-DB-Ausführung.
  • DoD 5 bleibt screen-blockiert für den Reschedule-/Reassign-Picker; Service und Action-Contract sind bereits erledigt.

Proof lokal: pnpm exec vitest run apps/web/app/modules/booking/services/booking-postbooking-boundary.test.ts apps/web/app/modules/booking/services/booking-db-artifacts.test.ts apps/web/app/modules/booking/services/AvailabilityService.server.test.ts apps/web/app/modules/booking/routes/booking-auth-boundary.test.ts → 11/11 grün; pnpm typecheck, pnpm lint, pnpm verify:i18n, pnpm test und pnpm build → grün.