Files
fewo-stommer/docs/DATENMODELL-KONZEPT.md
T
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

7.1 KiB
Raw Blame History

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

  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).