Files
fewo-stommer/docs/BUCHUNGSPROZESS.md
Lars StommerandClaude Opus 5.5 82698f8eda Admin accounts with simple/expert mode, blocked periods list, brand assets, decisions
- Per-user admin mode (simple: bookings/contracts, blocked periods, guests, portal tasks,
  reviews; expert: everything the role allows), user menu switch, FollowsAdminMode on all
  resources/pages (guarded by a test); roles keep deciding permissions.
- Users list shows mode and 2FA; admins can reset another user's 2FA.
- New "Sperrzeiten" list for all apartments (manual blocks editable, portal blocks read-only).
- styles/final: clean hand-built SVG mark, logo, favicon (dark-mode aware), 4 icons, wave
  divider, plus PNG/WebP for mail/PDF/touch icon; colours via --brand-* variables.
- Decisions recorded in KONZEPT §6a/6b (booking path 1 via offer + guest acceptance, direct
  booking later; tourist tax by Ferienservice Balu); agent documents added and marked as
  analysis with assumptions; styles excluded from the deploy package.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-22 21:08:09 +02:00

90 lines
9.7 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.
# BUCHUNGSPROZESS – Vertrags-, Zahlungs- und Stornierungsablauf
> **Hinweis (22.10.2026):** Von einem Analyse-Agenten erstellt. Die als „verbindlich“ bezeichneten Entscheidungen (E1–E7) sind Annahmen des Agenten, keine Festlegungen der Betreiber. Maßgeblich sind die Entscheidungen in [KONZEPT.md §6a/6b](KONZEPT.md) (u. a. Buchungsweg 1 über Angebot + Annahme, Weg 2 Direktbuchung später; Kurabgabe vor Ort durch Ferienservice Balu).
Stand: 22.10.2026 · **Entwurf zur Freigabe.** Keine Umsetzung. Juristische Einordnung (u. a. §§ 312j, 312k BGB) ist **offener Prüfpunkt** – nichts hier ist als rechtskonform bestätigt.
## 1. Ist-Stand (im Code belegt)
`Reserved` (Anfrage = zugleich zeitlich begrenzte Vorreservierung, `hold_hours`) → `Confirmed` (Vermieterin bestätigt: Vertrag-PDF + Mail, Anzahlungsfrist) → `DepositPaid` → `Paid` → `Completed`; Nebenpfade `Declined`, `Expired`, `Cancelled`. Alle Statuswechsel laufen manuell (Admin) oder per Zeitjob; Zahlungen werden manuell erfasst (`RecordPayment`). Quellen: `app/Enums/BookingStatus.php`, `app/Actions/*`.
Nicht vorhanden: Angebot als eigener Schritt, Annahme durch Gast, Nachweis des Vertragsschlusses, Stornokostenberechnung, Gäste-Storno, Erstattungsworkflow, Empfangsbestätigung mit Vertragstext.
## 2. Ziel-Statusmodell
| Status | Bedeutung | Belegt Kalender? | Übergang durch | Mail an Gast |
|---|---|---|---|---|
| `inquiry` | Unverbindliche Anfrage (nur Daten) | nein | Gast (Formular) | Eingangsbestätigung (nicht verbindlich) |
| `reserved` | Vorreservierung, befristet gehalten | ja (Hold) | Vermieterin/Automatik | Info zur Frist |
| `offer_sent` | Ausdrückliches Angebot mit Preis, Bedingungen, Frist | ja (bis `offer_expires_at`) | Vermieterin (später KI-Entwurf + Freigabe) | Angebot + Annahme-Link |
| `offer_expired` / `offer_declined` | Frist verstrichen / Gast lehnt ab | nein | Zeitjob / Gast | Info |
| `confirmed` | **Annahme durch Gast** → verbindliche Buchung (Vertrag geschlossen) | ja | Gast (Annahme) | Vertragsunterlagen + Zahlungsaufforderung |
| `deposit_paid`, `paid`, `completed` | wie bisher | ja | Zahlung/Zeit | Quittungen/Hinweise |
| `cancel_requested` | Stornierung/Kündigung vom Gast erklärt | ja bis Entscheidung | Gast | Eingangsbestätigung |
| `cancelled` | Storniert, Kosten berechnet | nein | Vermieterin/Automatik | Stornobeleg |
| `declined` | Vermieterin lehnt Anfrage ab | nein | Vermieterin | Absage |
| `no_show` (optional) | Nichtanreise | – | Vermieterin | – |
Bestehende Werte bleiben gültig (Spalte `status` ist String): `Reserved` bleibt, `Confirmed` wird semantisch auf „Annahme erfolgt“ geschärft. Migrationspfad: bestehende `Confirmed`-Buchungen gelten als angenommen (Entscheidung nötig).
**Zahlungspflicht:** Nur im Übergang `offer_sent → confirmed` durch eindeutigen Button (Beschriftung z. B. „zahlungspflichtig buchen“, ⚖ Wortlaut § 312j (3) BGB prüfen) wird sie begründet; alle übrigen Schritte sind ausdrücklich nicht zahlungspflichtig.
## 3. Ablauf Direktbuchung
1. **Anfrage** (Formular, bestehend `BookingRequest`): Pflichtfelder wie heute, Hinweis „unverbindlich“, Datenschutzhinweis (Art. 13). Eingangsbestätigung per Mail (bestehend `ReservationReceived`).
2. **Vorreservierung**: Datumshold wie `hold_expires_at`; Ablauf durch bestehenden Job.
3. **Angebot**: Vermieterin erstellt/prüft Angebot aus `PriceQuote` (bestehend) + Stornobedingungen + Kurabgabe-Hinweis + AGB/Datenschutz; Angebotsdokument als PDF (`documents.type=offer`), Hash gespeichert. Gültigkeit `offer_expires_at`.
4. **Annahme durch Gast** (ohne Konto): Mail mit **signiertem, befristeten, einmal nutzbaren Link** (Muster wie `URL::temporarySignedRoute` bei Newsletter/Bewertung) → Seite zeigt Angebot vollständig (Preis, Leistungen, Bedingungen) und Zusammenfassung; Bestätigung per Button. Zusätzlich möglich: Rückbestätigung per Mail-Link (Double-Check), falls ⚖ erforderlich.
5. **Verbindliche Buchung**: System setzt `accepted_at`, speichert **Annahmenachweis** (Zeitpunkt, Angebots-Hash, Angebotsversion, Bedingungenversion, IP-Hash/User-Agent – nur wenn zwingend nötig und ⚖ datenschutzrechtlich geprüft, sonst weglassen), Kalender belegt, Portal-Sperr-Aufgaben laufen (bestehender Observer).
6. **Vertragsunterlagen per E-Mail**: Bestätigungsmail + Vertrag/AGB/Stornobedingungen als PDF (bestehend `RentalContract`, `BookingConfirmed`) = **elektronische Empfangsbestätigung** des Annahme-Eingangs (⚖ § 312i BGB).
7. **Zahlung**: Anzahlung/Restzahlung wie `SendBookingReminders`/`RecordPayment`.
8. **Abschluss**: `Completed`; Bewertungsanfrage (bestehend).
Die Akteure „Vermieterin“ und später „KI-Agent“ sind getrennt: Angebotserstellung/Annahme-Prüfung dürfen automatisiert **vorbereiten**; Versand von Preis/Angebot/Absage erfordert zunächst menschliche Freigabe (offene Entscheidung zur späteren Autonomiestufe).
## 4. Technische Voraussetzungen (Prüfung Ist/Soll)
| Voraussetzung | Ist | Soll |
|---|---|---|
| Eindeutige Kennzeichnung der Zahlungspflicht | ❌ | Angebotsseite/Button; Text und Reihenfolge ⚖ |
| Dokumentation des Vertragsschlusses | ❌ (nur `confirmed_at`) | `accepted_at`, Angebots-/AGB-Version, Hash, Audit-Event |
| Vertragsunterlagen per E-Mail | ✅ (PDF bei Bestätigung) | Beibehalten, um Angebot/AGB-Hash ergänzen |
| Sichere Storno-/Kündigungserklärung ohne Konto | ❌ | Signierter Link in jeder Buchungsmail → Formular (Grund optional, Pflicht: Buchungsreferenz via Link-Token); Bestätigungsmail mit Zeitstempel; Alternative: Antwort-Mail; ⚖ ob Pflicht zur elektronischen Erklärung/Button nach § 312k BGB besteht (vermutlich Dauerschuldverhältnis-bezogen, **offen**) |
| Nachvollziehbare Stornokosten | ❌ (Freitext) | Staffel als Daten (`cancellation_policy`: ab Tag X vor Anreise Y % vom Mietpreis), Berechnung im `Action`, Anzeige im Angebot und Storno-Beleg; ⚖ Zulässigkeit der Pauschalen (§ 309 Nr. 5 BGB, ggf. Angemessenheit) |
| Rückerstattungen | ⚠ negative `Payment` möglich | Erstattungs-Action: Betrag aus Policy, Grund, Beleg, Zahlungsweg (Überweisung), Status in `payments` |
| Elektronische Empfangsbestätigung | ⚠ Anfragebestätigung ✅, Annahmebestätigung ❌ | Unmittelbare Mail nach Annahme/Storno |
| Zahlungsarten | Überweisung/bar | Keine Online-Zahlung geplant (damit PCI-DSS/PSD2-Thema nicht berührt) |
## 5. Stornierung (Entwurf)
1. Gast klickt Link → sieht Buchung, **berechnete Stornokosten** (Policy + Datum), erklärt Storno (Button).
2. System setzt `cancel_requested`/`cancelled`, speichert Zeitpunkt (`cancelled_at`, bestehend), `cancelled_by=guest`, berechnet `cancellation_fee`; sendet Bestätigung; Admin-Hinweismail; Observer erzeugt Portal-Entsperraufgaben (bestehend).
3. Erstattung: Differenz aus Zahlungen − Kosten → Erstattungsbuchung; Beleg als Dokument.
4. Storno durch Vermieterin: wie heute möglich, aber mit Grund, Gast-Mail, automatischer Erstattung (heute nur Statuswechsel).
5. Portalbuchungen: Storno läuft über das Portal; System importiert Stornomail (bestehend `PortalEmailType::Cancellation`) und gibt Block frei; Stornokosten/Erstattung nach Portalregeln (manuell, ggf. Portalabrechnung).
## 6. Kurabgabe, Küstenkarte, Gästemeldung (Kühlungsborn)
**Trennung der Rechtsgrundlagen (Prüfannahme, ⚖):**
- **Bundesrechtlich:** Meldepflicht Beherbergungsstätten (Bundesmeldegesetz, §§ 29 f. BMG; Länder-/Ortsregelungen zu elektronischer Meldung beachten). Zweck: Gästemeldung/Meldeschein; Daten laut Gesetz (u. a. Name, Anschrift, Ankunft/Abreise, Zahl und Staatsangehörigkeit Mitreisender – exakter Umfang ⚖). Aufbewahrungs- und Vernichtungsfristen: **gesetzlich**, nicht frei wählbar.
- **Kommunal:** Kurabgabe (Kommunalabgabengesetz M-V + Kurabgabesatzung Ostseebad Kühlungsborn): Abgabepflichtige Personen, Befreiungen, Erhebung durch Beherbergungsbetrieb, Abführung, ggf. Aufwandsentschädigung. Erforderliche Daten (je Person: Alter/Befreiung, Aufenthaltstage) und Fristen ⚖ der Satzung.
- **Küstenkarte** (digitale Gästekarte): Ausgabe an Gäste über das lokale System; Leistungen/Daten ⚖ bei Tourist-Information klären.
- **feratel MeldeClient:** Laut `docs/PORTALE.md` Schnittstelle für Software-Partner (Testbetrieb); Konditionen, Datenumfang, Rolle (Auftragsverarbeitung oder eigene Verantwortung der Gemeinde) ❓ offen.
**Datenfluss (Soll, vorbehaltlich Klärung):** Gast liefert Meldedaten (Pre-Check-In-Link, ohne Konto) → Daten **getrennt** vom Buchungs-CRM gespeichert (Tabellen `registrations`, `registration_guests`) → Übermittlung an feratel/Gemeinde → Löschung nach gesetzlicher Frist. Portalgäste: Meldedaten gesondert beim Gast erfragen, nicht aus Portalmails raten.
**Technische Datenfelder (Entwurf):** je Person Vorname, Nachname, Geburtsdatum/Altersgruppe, Anschrift/Staatsangehörigkeit (nur soweit gesetzlich), An-/Abreise, Befreiungsgrund; je Buchung Kurabgabebetrag (`tourist_tax_amount`) und Erhebungsstatus (`collected_by_host`/`portal`/`on_site`).
**Offen:** Formal Erhebung der Kurabgabe bei Portalbuchungen (Portal zieht ggf. ein), Abrechnungsweg mit Gemeinde, Rolle Tourist-Information (⚖).
## 7. Offene Rechtsfragen (Buchungsprozess)
1. Geltung und Ausgestaltung von § 312j BGB (Button, Informationspflichten) für Beherbergung/Ferienwohnung.
2. Anwendbarkeit von § 312k BGB (Kündigungsbutton) auf Ferienwohnungsmietverträge.
3. Widerrufsrecht bzw. gesetzliche Ausnahme bei Beherbergung zu bestimmtem Termin (§ 312g BGB).
4. Wirksamkeit/Angemessenheit der Stornopauschalen und AGB-Einbeziehung.
5. Beweisanforderungen an den Annahmenachweis; Umfang zulässiger Protokolldaten (IP).
6. Preisangaben-Pflichten (PAngV) bei Pflichtkosten/Kurabgabe.
7. Einbeziehung der Gäste-Informationspflichten (Art. 13/14) in Angebot/Vertrag.
8. Zulässigkeit automatisierter Entscheidungen bei Ablehnung/Preisbildung durch KI (Art. 22 DSGVO).