Files
fewo-stommer/BOOKING-E2E-IMPLEMENTATION.md
T
LarsandClaude Sonnet 5.5 eafab8a2cb
Deploy FeWo mit PipelineManager / deploy (push) Failing after 3m38s
Buchungsprozess: Angebots-Snapshot, atomare Annahme, Auto-Angebot, Kanalfreigabe
- 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>
2026-10-30 12:01:02 +01:00

11 KiB
Raw Blame History

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.