- 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>
7.1 KiB
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 (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 = <Kanal>, 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
- Exakter Treffer: normalisierte E-Mail (bestehend) → vorschlagen, nicht stillschweigend überschreiben.
- Weiche Treffer: Name + Zeitraum/Portal-Referenz, Telefonnummer normalisiert → nur als Kandidat.
- Zusammenführung manuell: Zielgast wählen, Felder einzeln übernehmen, Buchungen umhängen, Quellgast
merged_into_id, Audit-Eintrag; keine Löschung der Historie. - Direktanfragen mit bekannter E-Mail aktualisieren Stammdaten nur nach Bestätigung (Fix für D8).
6. Wiederverwendung / Umsetzungsreihenfolge (nach Freigabe)
- Felder/Migrationen (additiv, rückwärtskompatibel). 2.
documents+ Umzug voncontract_path. 3. Importpfad Portal-Mail →Booking(Parser bleibt). 4. Merge-Kandidaten + Admin-Aktion. 5. Finanzfelder (Gebühren, Kurtaxe). 6. API-Connector überChannelConnector(nur nach Anbieter-/AVV-Klärung).