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