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

96 lines
7.1 KiB
Markdown
Raw 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.
# 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 = <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).