Files
fewo-stommer/BOOKING-COMPLIANCE-HANDOVER.md
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

75 lines
9.0 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# BOOKING-COMPLIANCE-HANDOVER
Technische Fakten für die nachgelagerte Compliance-Prüfung. **Keine rechtlichen Bewertungen**, keine Änderung von CMS-Rechtstexten. Stand: 30.10.2026, Entwicklungsstand Branch `feature/buchung-e2e` (nicht deployt). Details: `BOOKING-E2E-IMPLEMENTATION.md`.
## 1. Tatsächlicher Ablauf des Vertragsschlusses (Direktbuchung)
1. Gast sendet das Anfrageformular (`/buchen`, Livewire; Bot-Schutz: Honeypot, Zeitsperre, Rate-Limits). Eingabe: Name, E-Mail, optional Telefon/Adresse, Nachricht, Zeitraum, Personen, optional Rabattcode, Einwilligungs-Checkbox Datenschutz, optional Newsletter-Opt-in.
2. System prüft Verfügbarkeit und berechnet den Preis (`PriceCalculator`). Je Wohnung: **Vorreservierung** an (Kalender wird bis zum Ablauf der Haltefrist gesperrt) oder aus (keine Sperre).
3. **Manueller Modus (Standard):** Eingangsbestätigung an den Gast (unverbindlich, ggf. mit Ablaufzeit der Vormerkung), Mitteilung an den Betreiber; Betreiber erstellt/sendet das Angebot im Admin.
**Automatischer Modus:** Angebot geht sofort an den Gast, wenn alle Prüfungen bestanden sind (Details Implementation §Phase 3); sonst Rückfall auf manuell.
4. Angebot (Version n): E-Mail mit Preisaufstellung und PDF-Entwurf (Angebot/Mietvertrag) im Anhang und einem **signierten, befristeten Link** (`/angebot/{id}?v=n`, Ablauf = Angebotsfrist).
5. Der Link öffnet die Angebotsseite (GET, ändert nichts). Sie zeigt Zeitraum, Preiszeilen, Zahlungsplan, Mietbedingungen, Stornobedingungen, „Gültig bis“, Hinweistext (`offer.accept_note`), Checkbox „Ich habe die Angaben und Bedingungen dieses Angebots gelesen“ und die Schaltfläche (Beschriftung `offer.accept_button`, CMS; Standardtext aktuell „Angebot zahlungspflichtig annehmen“). Daneben „Angebot ablehnen“.
6. Annahme = POST auf eine signierte URL (CSRF-geschützt, Rate-Limit 10/min). Eine Transaktion prüft Version, Status, Frist, Prüfsumme des Angebots, Verfügbarkeit (und vorher Aktualität der Portalkalender), schreibt den Nachweis und setzt die Buchung auf `Confirmed`.
7. Danach: Vertrags-PDF (final) wird erzeugt; Bestätigungs-E-Mail mit PDF geht an den Gast; Betreiber erhält eine Annahme-Mail. Fristen: Anzahlung = Annahmetag + `deposit_due_days` (Standard 7), Rest zum vereinbarten Termin.
8. Der Kalender ist sofort belegt (iCal-Ausgangsfeed wird bei jedem Abruf live berechnet); für Portale mit manueller Sperre entstehen Aufgaben (+ optionaler Webhook).
## 2. Angebots- und Annahmenachweise (Datenbank `bookings`)
| Feld | Inhalt |
|---|---|
| `offer_version`, `offer_sent_at`, `hold_expires_at` | Version, Versandzeit, Gültigkeit (nach Annahme `null`) |
| `quote`, `total`, `deposit`, `balance_due_on` | Preis und Zahlungsplan der Version |
| `offer_terms` (JSON) | eingefrorene Texte: Mietbedingungen, Storno, Hausordnung, Vertragseinleitung/-schluss, Vertragshinweis, Annahmehinweis, Button-Beschriftung; Anzahlungsfrist; Vermieter- und Bankdaten; `captured_at` |
| `offer_hash` | SHA-256 über Version, Termine, Personen, Quote, Beträge, Zahlungstermin, Snapshot |
| `acceptance` (JSON), `accepted_at` | Version, Zeitpunkt, Gültigkeit, Gesamtbetrag, `offer_hash`, `quote_sha256`, `terms_sha256` (Hash der **angezeigten** Texte), Button-Text, `via=offer_link` |
| `confirmed_at`, `deposit_due_on`, `contract_path`, `offer_path` | Bestätigungszeit, Fälligkeit, Pfade der PDFs |
| `confirmation_sent_at`, `confirmation_failed_at` | Zustellstatus der Bestätigungsmail (nur Versand an den Mailserver, kein Lesenachweis) |
Es wird **keine IP-Adresse, kein User-Agent und kein Token** im Nachweis gespeichert. Der Nachweis zeigt „diese Angebotsversion mit diesem Inhalt wurde über den signierten Link angenommen“; er identifiziert den Handelnden nur über den Besitz des Links.
Nach Versand geänderte CMS-Texte wirken **nicht** auf bestehende Angebote (Snapshot). Eine Änderung der gespeicherten Angebotsdaten verhindert die Annahme (Hash-Prüfung, Postfachmeldung).
## 3. Technische Darstellung der Vertragsinformationen
- Angebotsseite (HTML) und PDF (Angebot/Entwurf → final) werden aus demselben Snapshot gerendert. PDFs liegen als Dateien (nicht neu gerendert beim Abruf); „Mietvertrag neu erzeugen“ im Admin nutzt den Snapshot.
- Das Angebots-PDF hängt an der Angebotsmail (dauerhaft speicherbar); das finale Vertrags-PDF an der Bestätigungsmail. Auf der Angebotsseite selbst gibt es keinen PDF-Download-Link (Hinweis auf den Anhang).
- Hausordnung steht im PDF, nicht auf der Angebotsseite. Die Texte sind **noch Mustertexte** im CMS (`[MUSTER …]`); im Livebetrieb werden automatische Angebote nur bei freigegebenen (nicht-Muster) Texten und gefüllter IBAN gesendet.
- Zahlungspflicht-Hinweis und Button-Beschriftung sind CMS-Felder (`offer.accept_note`, `offer.accept_button`).
## 4. Speicherorte und Aufbewahrung
- PDFs: `storage/app/private/contracts/tenants/{tenant}/bookings/{booking}/` (nicht per Web erreichbar). Buchungsdaten/Nachweise: Datenbank, Tabelle `bookings`; Gäste: `guests`.
- Löschung/Anonymisierung (`guests:anonymize`, täglich): nie bestätigte Anfragen nach 6 Monaten (`FEWO_RETENTION_INQUIRY_MONTHS`); Gästedaten bestätigter Buchungen 10 Jahre (`FEWO_GUEST_RETENTION_YEARS`) – Vorschlagswerte laut `docs/LOESCHKONZEPT.md`. **Vertragsdokumente haben dort noch keine Löschfrist (als Lücke vermerkt).** `internal_notes`/`acceptance` werden nicht gesondert gelöscht.
- Datenbank-Backup täglich (`backup:database`, 14 Dateien), enthält Gäste- und Buchungsdaten.
- Logs: bei Mail-/Sync-/Auto-Angebot-Fehlern nur Meldungstext, Exception-Klasse und Buchungs-ID, keine Adressen, Links oder Tokens (Laufzeit: Laravel-Log, Kanal `daily`, 14 Tage).
## 5. Automatisch versendete Nachrichtentypen
| Klasse | Empfänger | Auslöser |
|---|---|---|
| `ReservationReceived` | Gast | Anfrage (nicht bei erfolgreichem Auto-Angebot) |
| `NewReservation` | Betreiber | Anfrage (inkl. Hinweis „Angebot automatisch versendet“ bzw. Gründe) |
| `OfferMade` | Gast | Angebot (manuell/automatisch) |
| `OfferAnswered` | Betreiber | Annahme/Ablehnung durch den Gast |
| `BookingConfirmed` (+ Vertrag-PDF) | Gast | Annahme / direkte Bestätigung; Nachversand durch Admin/Befehl |
| `BookingDeclined`, `ReservationExpired` | Gast / Betreiber | Ablehnung durch Betreiber / Ablauf |
| `PaymentReminder`, `ArrivalInformation`, `ReviewRequest` | Gast | Fristen (bestehend, unverändert) |
| `MarketingConsentRequest` | Gast | nur bei Newsletter-Opt-in (bestehend) |
| Digest/Kanal-/Postfach-Meldungen | Betreiber | bestehend |
Im **Testbetrieb** gehen alle Mails ausschließlich an die Testadresse (`App\Support\Settings`, unverändert).
## 6. Technische Stornierungs-/Kündigungsmöglichkeiten
- Gast: Angebot **ablehnen** (Angebotsseite, bis zur Annahme). Eine Stornierung/Kündigung **nach** Annahme ist im Gastbereich **nicht** vorgesehen (kein Kundenkonto, kein Stornolink); sie läuft über Kontakt (Telefon/E-Mail).
- Betreiber: Aktionen *Ablehnen*, *Stornieren* (setzt `Cancelled`, gibt den Kalender frei), Vormerkung verlängern. Eine automatische Berechnung von Stornokosten gibt es nicht; die Stornobedingungen sind reiner CMS-Text im Snapshot.
- Es gibt keine automatische Stornierung bei Nichtzahlung (nur Zahlungserinnerungen).
## 7. Externe Datenquellen und Empfänger
- Eingehend: iCal-Feeds der Portale (nur Zeiträume, ggf. Titel/Beschreibungstexte), Portal-Benachrichtigungs-Mails aus dem Betreiber-Postfach (IMAP) – können Gästedaten enthalten (Aufbewahrung 90 Tage laut Löschkonzept).
- Ausgehend: iCal-Feeds je Portal (nur Belegungen, ohne Gästedaten, Zugriff über zufälligen Token pro Kanal); optional signierter Webhook an die Betreiber-Automation (n8n) mit Aufgabendaten (Zeitraum, Kanal); Mailserver (Strato SMTP).
- Aufgezeichnet: Abrufe der Export-Feeds je Kanal (Zeit, Methode, User-Agent, Status) in `channel_export_requests`.
- Keine externen Dienste im Buchungsweg (kein Captcha, keine Zahlungs-/Tracking-Dienste).
## 8. Cookies / Technologien (neu betroffen)
Keine neuen Cookies oder Browser-Speicher. Die Angebotsseite nutzt die bestehende Laravel-Sitzung und das XSRF-Cookie (CSRF-Schutz des Annahmeformulars). Neue deutsche Fehlerseiten (403/404/419/429/500/503) laden keine externen Ressourcen.
Die Angebotsseite ist `noindex`; Links stehen in Zugriffsprotokollen des Webservers (signierte URL) – Aufbewahrung dort liegt bei Strato.
## 9. Bekannte technische Einschränkungen, die für die Prüfung relevant sind
- Der Nachweis enthält keine IP/Geräteangabe (Entscheidung offen, siehe READINESS Frage 5).
- Standard-Buttontext enthält „zahlungspflichtig annehmen“, nicht wörtlich „Zahlungspflichtig buchen“ (CMS, Betreiber).
- Bestätigungsseite nach Annahme (Erfolgsmeldung) und Bestätigungs-E-Mail sind die einzigen unverzüglichen Bestätigungen; Zustellung der Mail kann scheitern (Statusfeld, Nachversand).
- Widerrufsinformationen, AGB-Link, Datenschutzlink auf der Angebotsseite sind **nicht** automatisch eingebaut (nur CMS-Texte `contract.terms`/`stay.cancellation`); der Datenschutzlink am Anfrageformular ist laut MVP-TECHNICAL-GATE Blocker #2 offen.