# BOOKING-E2E-IMPLEMENTATION Stand: 30.10.2026 · Branch `feature/buchung-e2e` (von `develop`) · nur Entwicklungsumgebung (SQLite-Tests). **Nichts committet, nichts deployt, keine Migration auf Staging/Produktion.** Grundlage: `BOOKING-E2E-READINESS.md`. Ergebnisse der Prüfungen: `BOOKING-E2E-ACCEPTANCE.md`. ## 1. Umgesetzte Änderungen ### Phase 1 – Sicherheitskern | Thema | Umsetzung | |---|---| | Angebots-Snapshot | `SendOffer` friert pro Version in `bookings.offer_terms` ein: Mietbedingungen, Storno, Hausordnung, Vertragseinleitung/-schluss, Vertragshinweis, Annahmehinweis, Button-Beschriftung, Anzahlungsfrist, Vermieter- und Bankdaten (`App\Documents\OfferTerms`). Angebotsseite, Angebots-PDF, Final-PDF und Annahme lesen aus dem Snapshot (`Booking::offerText()/offerHtml()`); Altbuchungen ohne Snapshot fallen auf die Live-Texte zurück. Direkte Bestätigung durch den Admin friert beim Bestätigen ein. | | Angebots-Hash | `bookings.offer_hash` = SHA-256 über Version, Termine, Personen, Quote, Beträge, Zahlungstermin und Snapshot (ohne Gültigkeit, die der Betreiber verlängern darf). | | Atomare Annahme | `AcceptOffer`: eine Transaktion mit Sperre auf Wohnung **und** Buchungszeile (`Booking::lockForTransition()`), dann Version, Status, Frist, Hash und Verfügbarkeit prüfen, Nachweis schreiben **und** `Confirmed` setzen – oder nichts. Dieselbe Wohnungssperre nutzen jetzt `CreateReservation`, `SendOffer`, `ConfirmBooking`, `RejectOffer`. | | Idempotenz | Zweite Annahme derselben Version: keine zweite Buchung, keine zweite Mail, Gast sieht „bereits verbindlich bestätigt“. Auch eine veraltete Modellkopie wird über die gesperrte Zeile erkannt. | | Nachweis | `acceptance` (JSON): Angebotsversion, Annahme-/Versandzeit, Gültigkeit, Gesamtbetrag, `offer_hash`, `quote_sha256`, `terms_sha256` (über den **gezeigten** Snapshot), Button-Text, `via`. Keine IP, kein Token. | | Mail nach Commit | `ConfirmBooking::deliver()` (Vertrag + Mail) läuft nach dem Commit; Fehler setzen `confirmation_failed_at`, schreiben ins Postfach (`InboxMessageKind::ConfirmationFailed`) und lassen die Buchung bestehen. Ohne erzeugtes Vertrags-PDF wird keine Bestätigung ohne Anhang versendet. | | Nachversand | Admin-Aktion „Bestätigung erneut senden“ (Buchungsseite), Befehl `bookings:resend-confirmations` (alle 15 Min., nur Fehlversuche der letzten 3 Tage). | | Angebotsmail | `SendOffer::deliver()`: Fehler → Postfach (`OfferMailFailed`), Angebot bleibt gespeichert, Admin erhält verständliche Meldung (Link kann kopiert werden). | | Portal-Sync | `BookingObserver`: Fehler beim Anlegen von Portalaufgaben schlagen nicht mehr auf den Gast durch; Postfachmeldung `SyncFailed`. | | Logs | Fehler werden nur mit Klasse + Buchungs-ID geloggt (Mailer-Meldungen können Adressen enthalten). Keine Tokens/Links. | | Fehlerseiten | Deutsche Seiten 403/404/419/429/500/503 (`resources/views/errors`), 403 erklärt abgelaufene/ungültige Links, 419 „Sitzung abgelaufen – nichts wurde verändert“. Betrifft alle Seiten der Anwendung (vorher englische Standardseiten). | | Aufräumen | Debug-`dump()` aus `OfferWorkflowTest` entfernt. | ### Phase 2 – Betriebsmodi und Vorreservierung - Je Wohnung (`properties`): `offer_mode` (`manual` Standard / `automatic`) und `pre_reservation_enabled` (Standard `true`), neben dem vorhandenen `hold_hours`. Einstellbar in der Wohnungsverwaltung (Abschnitt Zahlung/Vorreservierung). Validierung: *automatisch* + *ohne Vorreservierung* wird abgelehnt. - Ohne Vorreservierung entsteht eine `Reserved`-Anfrage **ohne** `hold_expires_at`; sie sperrt nichts (`occupying()`-Scope), läuft nicht ab und wird erst durch Angebot/Entscheidung des Betreibers weiterbewegt. - `CreateReservation` entscheidet über Mails: *manuell* → Eingangsbestätigung an Gast + Mitteilung an Betreiber; *automatisch und freigegeben* → nur das Angebot an den Gast, Betreiber-Mail „Angebot automatisch versendet“; *automatisch, aber nicht freigegeben* → Eingangsbestätigung + Betreiber-Mail mit den Gründen, Gründe zusätzlich in den internen Notizen. Keine doppelten Gast-Mails. - Eingangsbestätigung, Betreiber-Mail und Bestätigungsseite behaupten eine Vormerkung nur, wenn tatsächlich eine aktive Haltefrist besteht (genauer Ablaufzeitpunkt), sonst „noch nicht reserviert“. - Der bestehende Testbetrieb (`Settings`, Mail-Umleitung) ist **unverändert**; Modus und Testbetrieb sind unabhängig. ### Phase 3 – Kanalabhängige Freigabe `App\Actions\AutoOffer` + `App\Availability\CalendarClearance`: 1. Stufe Betreiberfreigabe: im **Livebetrieb** müssen Mietbedingungen (kein „[MUSTER“), Storno und IBAN gefüllt sein; im Testbetrieb entfällt die Prüfung, damit der Ablauf mit Mustertexten testbar ist. 2. Import: jeder aktive Importkanal braucht einen erfolgreichen Import innerhalb von `fewo.channels.fresh_within_minutes` (15, `FEWO_CHANNEL_FRESH_WITHIN_MINUTES`); sonst wird **einmal** ein Import versucht (Netzwerk außerhalb jeder Transaktion), danach gilt „nicht aktuell“. 3. Sofortbuchung: Kanäle mit Buchungsmodell *Portalbuchung* oder *Gemischt* gelten als sofortbuchungsfähig (bestehendes Feld `booking_model`, keine neue Spalte). Freigabe nur, wenn dieser Kanal **nach Anlage der Sperre** (`created_at` + 1 s) unseren Feed mit **HTTP 200 und Zustand „live“** abgerufen hat (bestehende Tabelle `channel_export_requests`; Zuordnung über den kanaleigenen Token). Unzuordenbare Abrufe (falscher Token → 404) werden nicht protokolliert und zählen nie. Abrufe vor der Sperre, fehlgeschlagene (503) und Abrufe anderer Kanäle zählen nicht. 4. Kanäle ohne Sofortbuchung: kein Abrufnachweis nötig. 5. Verfügbarkeit erneut prüfen; Vorreservierung muss aktiv sein. 6. Nicht freigegeben → kontrollierter Rückfall auf manuell; `bookings:auto-offers` (alle 5 Min.) versucht es für noch gehaltene Anfragen erneut (z. B. sobald das Portal den Feed abgerufen hat). 7. **Bei der Annahme** (`AcceptOffer`): vor der Transaktion Import aufgefrischt; bleibt ein Importkanal veraltet, wird **nicht** gebucht, der Gast erhält eine verständliche Meldung, der Betreiber eine Postfachmeldung. Danach gesperrte Verfügbarkeitsprüfung (inkl. Portal-Sperren) in der Transaktion. ### Phase 4 – Portalanfragen / Verwaltung Weitgehend **bereits vorhanden** und durch bestehende Tests belegt (nicht neu implementiert): Portal-Mails → Sperre mit Quelle `email` (`ProcessPortalMail`, `PortalMailTest`), iCal-Einträge ohne Gastdaten bleiben anonyme Sperren mit Kanalbezug (`BlockedPeriod`), manuelle Gast-Zuordnung (`AssignOccupationGuest`), Zusammenführung nur über eindeutige UID bzw. ausdrückliche Betreiber-Entscheidung (`ChannelOccupationResolutionTest`), Doppelmeldungen/Konflikte (`ConflictDetector`, Postfach), Portalbuchungen gehen nie durch den Annahmeprozess. Neu: Buchungsseite zeigt Bearbeitungsmodus, Angebotsversion + Prüfsumme, Annahmezeitpunkt und Zustellstatus der Bestätigung. ## 2. Geänderte / neue Dateien Neu: `app/Documents/OfferTerms.php`, `app/Actions/AutoOffer.php`, `app/Availability/CalendarClearance.php`, `app/Enums/OfferMode.php`, `app/Console/Commands/ResendBookingConfirmations.php`, `app/Console/Commands/SendPendingAutoOffers.php`, `resources/views/errors/*`, `tests/Feature/BookingAcceptanceTest.php`, `tests/Feature/AutoOfferTest.php`, zwei Migrationen (unten). Geändert: `AcceptOffer`, `ConfirmBooking`, `SendOffer`, `RejectOffer`, `CreateReservation`, `BookingObserver`, `OfferController`, `Booking`, `Property`, `ReservationException`, `InboxMessageKind`, `Inbox` (optionale `propertyId`), `NewReservation`/`ReservationReceived` (Mail + Views), `offer.blade.php`, `pdf/contract.blade.php`, `booking-request.blade.php`, `PropertyForm`, `BookingInfolist`, `ViewBooking`, `config/fewo.php`, `routes/console.php`, `OfferWorkflowTest`. ### Migrationen (additiv, nullable bzw. mit Default; bestehende Daten unverändert) 1. `2026_10_30_110811_add_offer_snapshot_and_confirmation_tracking_to_bookings_table`: `bookings.offer_terms` (json), `offer_hash` (string 64), `confirmation_sent_at`, `confirmation_failed_at`. 2. `…_add_offer_mode_and_pre_reservation_to_properties_table`: `properties.offer_mode` (Default `manual`), `pre_reservation_enabled` (Default `true`). Nicht migriert zur Wahrung des Bestands: Altbuchungen bekommen **keinen** nachträglichen Snapshot/Hash. ## 3. Konfiguration der Betriebsarten - Wohnung bearbeiten → *Vorreservierung halten* (Stunden), *Anfrage blockiert den Kalender*, *Bearbeitung von Anfragen* (manuell/automatisch). - Kombination automatisch + ohne Vorreservierung ist gesperrt (Formularfehler). - Kanal bearbeiten → Buchungsmodell: *Vermittlung/Anfrage* = keine Sofortbuchung; *Portalbuchung* oder *Gemischt* = Sofortbuchung (konservativ). Export muss aktiv sein. - Testbetrieb/Livebetrieb: System › Betrieb, unverändert und unabhängig. - **Standard bleibt: manuell, Vorreservierung an** → Verhalten wie bisher. Rollback: Modus auf *manuell* stellen. - Neue Zeitpläne (Scheduler, bestehender n8n-Aufruf genügt): `bookings:auto-offers` (5 Min.), `bookings:resend-confirmations` (15 Min.). ## 4. Restrisiken 1. **Portal-Verzögerung:** Ein erfolgreicher Feed-Abruf beweist die Auslieferung, nicht die Verarbeitung im Portal. Eine gleichzeitige Sofortbuchung im Portal ist nicht ausschließbar; sie wird erst über Import/Portal-Mail erkannt und als Konflikt gemeldet (KONZEPT §7). 2. Veraltete Importe verhindern Annahmen (gewollt) – ein dauerhaft gestörter Kanal blockiert also Buchungen, bis er repariert oder pausiert wird. Postfach zeigt es. 3. Ohne Vorreservierung zählen offene Anfragen nicht in die Obergrenze „offene Anfragen je E-Mail“ (Rate-Limits bleiben aktiv). 4. `bookings:auto-offers` sendet in Automatikwohnungen auch dann, wenn der Betreiber eine vorgemerkte Anfrage noch nicht angefasst hat – wer einzelne Anfragen prüfen will, schaltet die Wohnung auf manuell. 5. Eine später per Wiederholung gesendete automatische Offerte meldet dem Betreiber nichts Zusätzliches (er sieht den Status in der Buchung). 6. Parallelitätsschutz beruht auf `SELECT … FOR UPDATE` (InnoDB). Unter SQLite wirkt die Sperre nicht (Einzelschreiber); **auf MariaDB noch nicht praktisch nachgewiesen** (siehe Acceptance). 7. Keine Datenbank-Constraint gegen überlappende Buchungen (nicht sinnvoll realisierbar); Schutz = einheitliche Wohnungssperre in allen schreibenden Pfaden. Neue Schreibpfade müssen `lockForTransition()` nutzen. 8. Das 403/419-Verhalten gilt für alle Seiten; die Formular-Session des Annahmeformulars (CSRF) läuft weiter nach 120 Min. ab (jetzt mit klarer Seite). ## 5. Nicht umgesetzt / spätere Ausbaustufen - Portal-APIs, Channel-Manager, Webhook-Bestätigung durch Portale. - Eigene Tabelle für Ereignisverlauf (Audit-Trail); aktuell JSON `acceptance` + Postfach + Statusfelder. - Gast-Nachfrage/Kommunikationsverlauf in der Buchung; E-Mail-Verifikation der Anfrage. - Auswertung `Retry-After`/Portal-Rückmeldungen; kanalspezifische Abrufnachweise für `HEAD`. - Anzeige der Bedingungen des Snapshots im Admin als Download; Hausordnung auf der Angebotsseite (steht im PDF). - Portal-Anfragen mit unvollständigen Daten: weiterhin über die bestehende Zuordnungsmaske; keine neuen Importformate.