# DATENMODELL-KONZEPT – Zielarchitektur Gäste, Buchungen, Portale > **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 Migration erstellt oder ausgeführt. Grundprinzipien: Datenminimierung, Quellenkennzeichnung, keine geratenen Daten, möglichst Wiederverwendung des Bestands. ## 1. Bestandsaufnahme (Implementiert?) | Anforderung | Bestand | Status | |---|---|---| | Portalübergreifende Gästekartei, interne ID | `guests.id` ✅; aber nur Direktgäste, Dublette nur exakt per E-Mail | Teilweise | | Herkunftsportal | `bookings.source` (Text, z. B. `website`), `referral_source` (Marketing), `blocked_periods.channel_id` + `source` | Teilweise (Portal nur am Block) | | Externe Buchungsreferenz | `blocked_periods.external_uid`, `portal_emails.reference`; nicht am Buchungsdatensatz | Teilweise | | Reservierungs-/Buchungsstatus | `BookingStatus` (8 Werte) ✅; kein Angebot/Annahme | Teilweise | | Mietpreis | `bookings.total/deposit`, `quote` JSON ✅ (nur Direkt) | Teilweise | | Portalgebühren | – | Fehlt | | Kurtaxe | nur Hinweistext | Fehlt | | Zahlungen | `payments` ✅ (Überweisung/bar/sonstige; Erstattung = negativer Betrag) | Vorhanden | | Steuerrelevante Nachweise | Vertrags-PDF (`contract_path`) ✅; keine Rechnungen/Belege/Portalabrechnungen | Teilweise | | Ein-/ausgehende Portalnachrichten | `portal_emails` (nur eingehende Benachrichtigungen, Auszug) | Teilweise | | Dublettenprüfung / Zusammenführung | – | Fehlt | | Datenquelle + Importzeitpunkt | `channel_sync_logs`, `portal_emails.received_at`; nicht am Gast/Buchung | Teilweise | ## 2. Leitentscheidung (Annahme) **Portalbuchungen werden als `Booking` geführt** (nicht länger nur als `BlockedPeriod`), mit `source = `, optionalem Gast und leeren Feldern, wo keine Daten vorliegen. `BlockedPeriod` bleibt für Eigenbelegung, Wartung und rein per iCal bekannte Sperren. Zuordnung `BlockedPeriod` → `Booking` über neue FK, sobald eine Portal-Mail/API die Buchung identifiziert. Vorteil: ein Reporting, ein Zahlungs-/Belegmodell; bestehende `Booking::occupying()`-Logik und Observer greifen weiter. *(Entscheidung/Alternative zu bestätigen.)* ## 3. Zielmodell (Änderungen am Bestand, kursiv = neu) ### 3.1 `guests` (Erweiterung) | Feld | Zweck | |---|---| | `id` (intern, bleibt) | eindeutige Gäste-ID | | *`data_source`* (`direct`, `portal_mail`, `portal_api`, `manual`) | Herkunft der Stammdaten | | *`imported_at`* | Importzeitpunkt | | *`merged_into_id`* (nullable FK) | Zusammenführung, Quelle bleibt als „gemergt“ erhalten | | *`address_verified`* / Feldquellen | Kennzeichnung, ob Daten vom Gast selbst stammen | | bestehende Felder | unverändert; `email` darf bei Portalgästen **NULL** sein (Portale liefern oft maskierte Adressen) | ### 3.2 *`guest_identities`* (optional, später) Mehrere Kennungen je Gast (E-Mail, Portal-Alias, Telefon) mit Quelle – Grundlage der Dublettenprüfung ohne Überschreiben (löst D8). ### 3.3 `bookings` (Erweiterung) | Feld | Zweck | |---|---| | `source` (bestehend) | Kanal-Schlüssel (`website`, `fewo_direkt`, …) – mit `channels` verknüpfbar | | *`channel_id`* (nullable) | exakte Portalzuordnung | | *`external_reference`* (nullable, unique je Kanal) | Portal-Buchungsnummer, nur wenn belegt | | *`imported_at`*, *`import_source`* (`ical`, `email`, `api`, `manual`) | Quelle/Zeitpunkt | | *`offer_sent_at`, `offer_expires_at`, `accepted_at`, `acceptance_evidence`* (JSON) | Angebot/Annahme, s. BUCHUNGSPROZESS.md | | *`rent_amount`* (bestehend `total` weiterverwendbar), *`portal_fee`*, *`tourist_tax_amount`*, *`tourist_tax_collected_by`* | Beträge in Euro-Cent | | *`cancellation_fee`*, *`cancelled_by`*, *`cancellation_reason`* | Storno | | `contract_path` (bestehend) | wird durch `documents` abgelöst (§3.5) | Beträge unverändert als Integer-Cent (Projektregel). ### 3.4 `payments` (Erweiterung) `type` (`deposit`, `balance`, `refund`, `portal_payout`, `tourist_tax`), `external_reference`, `currency` (EUR). Erstattungen weiter als negativer Betrag oder Typ `refund` (Entscheidung offen). ### 3.5 *`documents`* (neu) – steuerrelevante Nachweise `booking_id`, `type` (`contract`, `offer`, `invoice`, `receipt`, `portal_statement`, `registration_form`, `correspondence`), `path`, `sha256` (Unveränderbarkeitsnachweis), `created_at`, `retain_until` (aus Löschkonzept), `contains_personal_data`. Dateien auf privatem Disk, nicht öffentlich. Ablösung des Einzelfelds `contract_path`. ### 3.6 *`messages`* (neu) – Portal-/Gästekommunikation `booking_id`/`guest_id`, `direction` (`in`/`out`), `channel` (`email`, `portal`), `external_id` (z. B. Message-ID, bereits in `portal_emails.message_id`), `subject`, `body` (optional, **mit kurzer Frist**), `received_at`/`sent_at`, `source`. Bestehende `portal_emails` bleibt als Parsing-Protokoll; Auszug (`excerpt`) wird gekürzt/entfernt (D6). ### 3.7 *`guest_merge_candidates`* (neu, optional) `guest_a_id`, `guest_b_id`, `score`, `reasons` (z. B. gleiche E-Mail, gleicher Name + Zeitraum), `status` (`open`, `merged`, `rejected`). Zusammenführung nur manuell im Admin. ### 3.8 *`audit_events`* (neu) Wer/Was/Wann für Statuswechsel, Zusammenführung, Export, Anonymisierung, Dokumentabruf – ohne Inhalte, mit Löschfrist. ## 4. Datenquellen je Feld | Feld | iCal | Portal-E-Mail | Autorisierte API | Direkt (Formular) | |---|---|---|---|---| | Zeitraum | ✅ | ✅ (Parser) | ✅ | ✅ | | Portal/Kanal | ✅ (über Channel) | ✅ (Absender) | ✅ | – | | Externe Referenz | UID (nicht Buchungsnr.) | ✅ falls im Text | ✅ | – | | Gastname/E-Mail/Tel. | ❌ | ❓ nur wenn Mail sie enthält | ✅ (vertragsabhängig) | ✅ | | Preis/Gebühren | ❌ | ❓ | ✅ | ✅ (Quote) | | Zahlungen | ❌ | ❌ | ❓ | manuell | | Nachrichten | ❌ | eingeschränkt | ✅ | ✅ (Mail) | Regel: Importer schreiben **nur** belegte Felder; Unbekanntes = `NULL` + Kennzeichnung; Parser-Unsicherheit → `needs_review` (bereits so umgesetzt). ## 5. Dublettenprüfung und Zusammenführung 1. Exakter Treffer: normalisierte E-Mail (bestehend) → vorschlagen, **nicht** stillschweigend überschreiben. 2. Weiche Treffer: Name + Zeitraum/Portal-Referenz, Telefonnummer normalisiert → nur als Kandidat. 3. Zusammenführung manuell: Zielgast wählen, Felder einzeln übernehmen, Buchungen umhängen, Quellgast `merged_into_id`, Audit-Eintrag; keine Löschung der Historie. 4. Direktanfragen mit bekannter E-Mail aktualisieren Stammdaten **nur nach Bestätigung** (Fix für D8). ## 6. Wiederverwendung / Umsetzungsreihenfolge (nach Freigabe) 1. Felder/Migrationen (additiv, rückwärtskompatibel). 2. `documents` + Umzug von `contract_path`. 3. Importpfad Portal-Mail → `Booking` (Parser bleibt). 4. Merge-Kandidaten + Admin-Aktion. 5. Finanzfelder (Gebühren, Kurtaxe). 6. API-Connector über `ChannelConnector` (nur nach Anbieter-/AVV-Klärung).