- Angebotsbedingungen und Zahlungsdaten werden je Version eingefroren (offer_terms, offer_hash) - Annahme in einer gesperrten Transaktion, idempotent, mit Nachweis; Mail- und Portalfehler machen eine gespeicherte Buchung nicht ungueltig (Postfach, Nachversand) - Je Wohnung: manuelle/automatische Angebote, optionale Vorreservierung - Automatische Freigabe abhaengig von aktuellen Importen und Feed-Abruf bei Sofortbuchungsportalen - Deutsche Fehlerseiten, Buchungsseite zeigt Angebots- und Zustellstatus - Dokumentation: BOOKING-E2E-*.md, BOOKING-COMPLIANCE-HANDOVER.md Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
11 KiB
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(manualStandard /automatic) undpre_reservation_enabled(Standardtrue), neben dem vorhandenenhold_hours. Einstellbar in der Wohnungsverwaltung (Abschnitt Zahlung/Vorreservierung). Validierung: automatisch + ohne Vorreservierung wird abgelehnt. - Ohne Vorreservierung entsteht eine
Reserved-Anfrage ohnehold_expires_at; sie sperrt nichts (occupying()-Scope), läuft nicht ab und wird erst durch Angebot/Entscheidung des Betreibers weiterbewegt. CreateReservationentscheidet ü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:
- 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.
- 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“. - 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 Tabellechannel_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. - Kanäle ohne Sofortbuchung: kein Abrufnachweis nötig.
- Verfügbarkeit erneut prüfen; Vorreservierung muss aktiv sein.
- 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). - 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)
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.…_add_offer_mode_and_pre_reservation_to_properties_table:properties.offer_mode(Defaultmanual),pre_reservation_enabled(Defaulttrue). 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
- 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).
- Veraltete Importe verhindern Annahmen (gewollt) – ein dauerhaft gestörter Kanal blockiert also Buchungen, bis er repariert oder pausiert wird. Postfach zeigt es.
- Ohne Vorreservierung zählen offene Anfragen nicht in die Obergrenze „offene Anfragen je E-Mail“ (Rate-Limits bleiben aktiv).
bookings:auto-offerssendet 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.- Eine später per Wiederholung gesendete automatische Offerte meldet dem Betreiber nichts Zusätzliches (er sieht den Status in der Buchung).
- Parallelitätsschutz beruht auf
SELECT … FOR UPDATE(InnoDB). Unter SQLite wirkt die Sperre nicht (Einzelschreiber); auf MariaDB noch nicht praktisch nachgewiesen (siehe Acceptance). - Keine Datenbank-Constraint gegen überlappende Buchungen (nicht sinnvoll realisierbar); Schutz = einheitliche Wohnungssperre in allen schreibenden Pfaden. Neue Schreibpfade müssen
lockForTransition()nutzen. - 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ürHEAD. - 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.