v0.11: Soll-Ist-Analyse, technische Zielarchitektur und Umsetzungsplan

Planung zur Prozessarchitektur v0.11 (Communication Handler,
Datenbeschaffung, Klärungsreservierung, zentraler Kanalmanager) mit sechs
Umsetzungspaketen U1–U6. Betreiberentscheidungen B1–B4 vom 03.11.2026
eingearbeitet; Präzisierungen zur Zuordnung direkter Gast-Mails (CH-13)
und zur KI-Eskalation unabhängig von der Modellkonfidenz.

Keine Codeänderung.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
LarsandClaude Opus 5.5 committed 2026-11-03 12:32:48 +01:00
1 parent 9a9e5e157e
commit bfccfe7eed
3 files changed
+761

No files matched your search

@@ -0,0 +1,145 @@
# v0.11 – Soll-Ist-Analyse des Anwendungscodes
**Stand:** 03.11.2026 · **Codebasis:** Branch `feature/aufenthalt`, Commit 9a9e5e1 (identisch mit dem Stand des Testsystems plus Spezifikation v0.11), 702 Tests grün · **Grundlage:** normative v0.11 unter `docs/Prozessarchitektur/` (führend: [Communication Handler](../Querschnitt/Datenbeschaffung_und_Communication_Handler.md), [Konfiguration und Wirksamkeit](../KONFIGURATION_UND_WIRKSAMKEIT.md), [Entscheidungen](../Entscheidungen.md) E-032 bis E-038) · **Status:** Analyse, keine Implementierung.
Weitere Dokumente: [Technische Zielarchitektur](V011_TECHNISCHE_ZIELARCHITEKTUR.md) · [Umsetzungsplan](V011_UMSETZUNGSPLAN.md)
Klassen der Bewertung: **umgesetzt** · **anzupassen** (vorhanden, deckt die Anforderung aber nicht) · **neu** · **zu klären** · **nicht MVP**.
---
## 1. Ergebnis in Kürze
- Der v0.10-Kern trägt die v0.11 ohne Umbau. Das betrifft die Aktivitäten (`CaseActivities`), das Weiterführen (`CaseAutomation`), das eingefrorene Profil (`ProcessSettings` und `ProcessProfile`), Verlauf, Aufgaben, Testbetrieb und das Muster der signierten, versionierten Gastlinks. Keine der v0.11-Anforderungen verlangt eine zweite Ablaufsteuerung.
- **Vollständig neu** sind der Communication Handler, also ausgehende Rückfragen, Ergänzungslink, Erinnerungen, allgemeiner IMAP-Eingang und Zuordnung, sowie die KI-Extraktion und die Klärungsreservierung.
- **Anzupassen** sind die Angebotsvoraussetzungen (die Anschrift ist heute kein Gate), die Datenübernahme (sie überschreibt heute ohne Herkunft), der Postfachabruf (heute nur Portal-Absender), die Konfiguration (die eigene Webseite ist kein Kanal) und die Einstellungsübersicht.
- **Drei Stellen im Code stehen der v0.11 direkt entgegen** (§3): die Reservierung bei Eingang unvollständiger Anfragen, die überschreibende Kontaktübernahme und die Vorgangsart-Ableitung, falls die Webseite ein Kanal wird.
## 2. Ist-Zustand der untersuchten Komponenten
### 2.1 Vorgangskern und Fortsetzung
| Komponente | Ist | Bewertung für v0.11 |
|---|---|---|
| [CaseActivities](../../../app/Process/CaseActivities.php) | Leitet alle Aktivitäten aus dem Zustand ab; `next()` liefert den großen Schalter. Die Aktivität „contact“ prüft nur, ob eine E-Mail-Adresse da ist (Z. 64–75). | Trägt. Informationsbedarf je Aktivität fehlt (nur E-Mail). |
| [CaseAutomation](../../../app/Process/CaseAutomation.php) | `advance()` führt nur im automatischen Modus weiter: Angebot bzw. Auskunft für Anfragen, Unterlagen für verbindliche Buchungen (Z. 26–61). `documentBlockers()` kennt Gast, E-Mail und Preis (Z. 67–74). | Trägt als S6. Wird an mehreren Stellen einzeln aufgerufen ([RecordPortalAmounts](../../../app/Actions/RecordPortalAmounts.php) Z. 65, [TakeOverExternalBooking](../../../app/Actions/TakeOverExternalBooking.php) Z. 99, [TakeOverPortalInquiry](../../../app/Actions/TakeOverPortalInquiry.php) Z. 59, [ViewBooking](../../../app/Filament/Resources/Bookings/Pages/ViewBooking.php) Moduswechsel), [CreateReservation](../../../app/Actions/CreateReservation.php) ruft `AutoOffer` direkt. [ProvideGuestContact](../../../app/Actions/ProvideGuestContact.php) enthält eine eigene Kopie der Fortsetzung (Z. 56–89). |
| Phasen P1/P2/P3 | Implizit über `BookingStatus`: `Reserved` = P1, `OfferSent` = P2, `BookingStatus::occupying()` = P3. | Ausreichend; kein neuer Status nötig. |
| [CaseLog](../../../app/Process/CaseLog.php), [BookingTask](../../../app/Models/BookingTask.php) | Verlauf mit Akteur; Aufgaben mit Arten (`BookingTaskKind`) und `openOnce`. | Wiederverwendbar für Rückfrage-Freigabe, Konflikt und Änderungswunsch. |
### 2.2 Eingang, Reservierung, Angebot
| Komponente | Ist | Bewertung |
|---|---|---|
| [BookingRequest](../../../app/Livewire/BookingRequest.php) (Webformular) | Pflicht: Zeitraum, Personen, Vor-/Nachname, E-Mail, Einwilligung. Anschrift optional (Z. 332–334). Bot-Schutz vorhanden. | Erfüllt „unvollständige Anfrage zulässig“. |
| [CreateReservation](../../../app/Actions/CreateReservation.php) | Prüft die Verfügbarkeit, legt `Reserved` an und setzt **bei jeder Anfrage** `hold_expires_at = jetzt + Angebots-Haltefrist` (Standard 48 h), wenn „Angebotsreservierung ja“ gilt (Z. 98). | **Konflikt K1**, siehe §3. |
| [SendOffer](../../../app/Actions/SendOffer.php) | Prüft erneut die Verfügbarkeit (Z. 87), setzt die Angebotsfrist neu (Z. 113), versioniert, signierter Link mit Ablauf. | Bleibt unverändert (Architekturgrenze 3). |
| [AutoOffer](../../../app/Actions/AutoOffer.php) | Blocker u. a. „nicht mehr vorgemerkt“, wenn der Hold abgelaufen ist (Z. 56–57). | Anzupassen für Anfragen nach abgelaufener Klärungsreservierung. |
| [ExpireReservations](../../../app/Actions/ExpireReservations.php) | Setzt jede Anfrage mit abgelaufenem Hold auf `Expired` (Z. 18–35). | Anzupassen: Eine abgelaufene Klärungsreservierung darf den Vorgang nicht beenden (CH §4 Nr. 6). |
| [DocumentComposer](../../../app/Documents/DocumentComposer.php) | Harte Blocker: Gast, E-Mail und Preis (Z. 193–199). Eine fehlende Anschrift fällt nur als **bestätigbarer** Hinweis über leere Vertragsplatzhalter auf (Z. 214–217). | **G2a fehlt**: Die Anschrift ist übergehbar (M01 nicht erfüllt). |
| [Booking::occupying](../../../app/Models/Booking.php) (Z. 310) und [AvailabilityChecker](../../../app/Availability/AvailabilityChecker.php) | Halte-Status mit `hold_expires_at > now` belegen den Kalender und gehen in den iCal-Export ([ICalFeed](../../../app/Channels/ICal/ICalFeed.php) Z. 27). Holds erzeugen **keine** manuellen Portalaufgaben ([BookingObserver](../../../app/Observers/BookingObserver.php) nur `occupying()`-Status). | Mechanik für die Klärungsreservierung wiederverwendbar; es fehlt nur die Unterscheidung des Zwecks. |
| Paket 7 ([SendInformation](../../../app/Actions/SendInformation.php), [SubmitBookingWish](../../../app/Actions/SubmitBookingWish.php), [InformationController](../../../app/Http/Controllers/InformationController.php)) | Signierter, versionierter Link; „Lesen schreibt nicht“; idempotente Übernahme; erneute Prüfung in einer Transaktion. | Vorlage für den Ergänzungslink (CH-18). |
### 2.3 Gastdaten
| Komponente | Ist | Bewertung |
|---|---|---|
| [Guest](../../../app/Models/Guest.php) | Kartei je Mandant und E-Mail: Name, Kontakt, Straße, PLZ, Ort, Land. Wird von mehreren Vorgängen geteilt. | Ziel der Datenübernahme bleibt die Kartei; die Herkunft je Angabe fehlt. |
| `CreateReservation::guestFor` (Z. 119ff.) | Ergänzt nur leere Felder; abweichende Angaben gehen als Text in die internen Notizen, die Kartei bleibt unverändert. | Gute Teilumsetzung von CH-03 (nur für das Webformular). |
| [ProvideGuestContact](../../../app/Actions/ProvideGuestContact.php) | Überschreibt Kartenwerte ohne Abgleich und Herkunft (Z. 51). | **Konflikt K2** mit CH-03 („nicht blind überschreiben“). |
| „Gast um Kontaktdaten bitten“ ([ViewBooking](../../../app/Filament/Resources/Bookings/Pages/ViewBooking.php) Z. 334ff.) | Vermerkt nur `contact_requested_at` und liefert einen Text zum Kopieren. | Keine Rückfrage im Sinne von CH-04/CH-15. |
### 2.4 E-Mail und Portale
| Komponente | Ist | Bewertung |
|---|---|---|
| Versand | Laravel-Mailer; die Schranke [EnforceMailTestMode](../../../app/Listeners/EnforceMailTestMode.php) leitet im Testbetrieb alles an die Testadresse; [LogBookingMail](../../../app/Listeners/LogBookingMail.php) schreibt `BookingMessage` (nur Betreff und Empfängerkreis, **keine Message-ID**). | Wiederverwendbar; für die Antwortzuordnung fehlt die Message-ID. |
| [MailboxReader](../../../app/Channels/Mail/MailboxReader.php) | IMAP über `webklex/php-imap`; fragt **nur die Absender bekannter Portale** ab (Z. 79), lässt Mails ungelesen, Rückblick 3 Tage. Zugangsdaten als Spalten am Mandanten ([Tenant::mailbox](../../../app/Models/Tenant.php) Z. 124), also nur ein Postfach. | Allgemeiner Eingang (CH-01, CH-06) fehlt; Datenmodell für mehrere Postfächer (CH-05) fehlt. |
| [ProcessPortalMail](../../../app/Actions/ProcessPortalMail.php) | Doppelte Verarbeitung je `message_id` ausgeschlossen (Z. 38); Kanal anhand des Absenders (Z. 108); Parser → Sperre, Freigabe oder `PortalIntake`. | Bleibt (CH-08); fehlt: Übergabe von Gastangaben an den Fakteneingang (CH-09/12). |
| [PortalMailParser](../../../app/Channels/Mail/PortalMailParser.php) | Liefert Typ (Buchung, Storno, Anfrage, unbekannt), Termine und Referenz (Z. 36–57); keine Gastdaten, keine Änderung. | Bleibt; Gastdaten künftig über die Extraktion. |
| [PortalIntake](../../../app/Channels/Intake/PortalIntake.php) | Zuordnung über Referenz und, bei gleichem Portal, gleichen Nächten und ohne Widerspruch, über die Termine (Z. 326ff.). | **Erfüllt CH-13** (iCal-vor-Mail ist ausdrücklich zugelassen). Der frühere Auditbefund L8 ist durch die v0.11 erledigt. |
| iCal ([SyncChannel](../../../app/Actions/SyncChannel.php), [ICalConnector](../../../app/Channels/ICal/ICalConnector.php), Regeln, Export) | Eigenständig, fünf Minuten, Regeln je Kanal. | Bleibt unverändert (Grenze 4). |
### 2.5 Konfiguration
| Komponente | Ist | Bewertung |
|---|---|---|
| [ProcessSetting](../../../app/Enums/ProcessSetting.php) | Acht Einstellungen mit Standard, Frage, erlaubten Eingangsarten je Kanal und Normalisierung. | Erweiterbar um die v0.11-Parameter, ohne neues Konfigurationsmodell. |
| [ProcessSettings](../../../app/Process/ProcessSettings.php) | Vererbung System → Mandant (`tenants.process_defaults`) → Wohnung (`properties.process_overrides`) → Kanal je Eingangsart (`channels.process_overrides`). Ohne Kanal gilt keine Kanalebene (Z. 31). | Trägt E-029. Die **eigene Webseite hat keine Kanalebene**. |
| [ProcessProfile::caseTypeFor](../../../app/Process/ProcessProfile.php) | A1 oder A2 je nachdem, **ob es einen Kanal gibt** (Z. 53). | **Konflikt K3**, wenn die Webseite ein Kanal-Datensatz wird. |
| [Channel](../../../app/Models/Channel.php) | Je Wohnung; Portal mit iCal-Anbindung, Buchungsmodell, Regeln, Export, Prozessabweichungen. Etwa 15 operative Stellen arbeiten mit `active()`-Kanälen (Sync, Postfach-Absender, Überwachung, Sperraufgaben, `CalendarClearance`). | Grundlage des Kanalmanagers; ein Webseiten-Datensatz darf in diese Abläufe nicht hineinlaufen. |
| Oberflächen | „So arbeite ich“ ([HandlingSettings](../../../app/Filament/Pages/HandlingSettings.php)) für Mandantenstandards; Portale ([ChannelForm](../../../app/Filament/Resources/Channels/Schemas/ChannelForm.php) Z. 133–144) nur in der Expertenansicht; Wohnungsabweichungen; [EffectiveSettings](../../../app/Filament/Pages/EffectiveSettings.php) mit Herkunft je Wert. | Drei Orte; die Webseite fehlt. „Wirksame Einstellungen“ ist der vorgesehene Herkunftsnachweis (§3a). |
### 2.6 KI-Infrastruktur
| Komponente | Ist | Bewertung |
|---|---|---|
| Pakete | Keine LLM-Anbindung, kein SDK ([composer.json](../../../composer.json)). Laravel-HTTP-Client vorhanden. | Neu. Ohne neue Abhängigkeit über den HTTP-Client möglich. |
| [TenantServiceKey](../../../app/Enums/TenantServiceKey.php) | Dienst `ai_guest_mail` („KI: Gästekommunikation“) ist vorgesehen, aber `isWired() = false`; Schlüssel je Mandant in [TenantService](../../../app/Models/TenantService.php) (`api_key`), Verbrauch in [ServiceUsage](../../../app/Models/ServiceUsage.php). | Schalter, Schlüssel und Verbrauchszählung sind wiederverwendbar. |
| Betrieb | `QUEUE_CONNECTION=sync`, keine Worker auf Strato; Postfachabruf jede Minute über den Scheduler. | LLM-Aufrufe müssen begrenzt im Scheduler laufen und dürfen den Portal-Schnellweg nicht verzögern. |
## 3. Konflikte zwischen Code und v0.11
| # | Stelle | Konflikt | Folge für die Planung |
|---|---|---|---|
| **K1** | [CreateReservation](../../../app/Actions/CreateReservation.php) Z. 98, [TakeOverPortalInquiry](../../../app/Actions/TakeOverPortalInquiry.php) Z. 53 | Heute reserviert **jede** Anfrage beim Eingang für die volle Angebots-Haltefrist, auch eine unvollständige. Die v0.11 verlangt für unvollständige Anfragen stattdessen die kurze Klärungsreservierung (P01 Nr. 4: „Erst wenn die Angebots-Gates erfüllt sind, greift die unveränderte bestehende Angebots-Haltefrist“). | Für **unvollständige** Anfragen ändert sich das Eingangsverhalten; vollständige Anfragen und `SendOffer` bleiben unverändert. Folge für die eigene Webseite: Solange die Anschrift im Formular optional ist, erhalten die meisten Webseiten-Anfragen künftig 15 bzw. 180 Minuten statt 48 Stunden (vom Betreiber bestätigt, Umsetzungsplan B1/B2). |
| **K2** | [ProvideGuestContact](../../../app/Actions/ProvideGuestContact.php) Z. 51 | Überschreibt vorhandene Gastdaten ohne Abgleich; CH-03 und S5 verbieten blindes Überschreiben. | Die Übernahme läuft künftig über den Fakteneingang; die Eingabe der Vermieterin bleibt maßgeblich, aber mit Herkunft und Verlauf. |
| **K3** | [ProcessProfile](../../../app/Process/ProcessProfile.php) Z. 53, `Booking::isDirect()` | Würde die Webseite ein gewöhnlicher Kanal mit `origin_channel_id`, würden Webseiten-Anfragen A2 statt A1 und verlören „direkt“. | Die Webseite wird ein Kanal-Datensatz eigener Art **nur für die Konfiguration**; Vorgänge behalten `source = website` ohne Kanalbezug (Zielarchitektur §4). |
| K4 | Betreiberäußerung vom 02.11. („Gast soll alle seine Daten ansehen“) im historischen [Entscheidungspapier](ENTSCHEIDUNGSPAPIER_EINGANG_UND_GASTLINK.md) | CH-18 verlangt „minimale Dateneinsicht“. | **Es gilt die v0.11**: Der Link zeigt nur die für den Vorgang relevanten Angaben. Hinweis an den Betreiber, falls die frühere Äußerung weiter gewollt ist. |
| K5 | Entscheidungspapier: „Ändern vor Annahme → geändertes Angebot“, „Teilstorno“ | E-038 und CH §5: Änderungswünsche im MVP nur erkennen und manuell bearbeiten. | Es gilt die v0.11; nicht Teil der Planung. |
## 4. Abweichungsmatrix
| Anforderung (v0.11) | Ist | Abweichung | Betroffene Komponenten | Maßnahme | Paket |
|---|---|---|---|---|---|
| **G2a / E-032 / CH §1.3** Pflichtangaben vor eigenem Angebot und vor verbindlicher Wunschbestätigung (B3), Anschrift inkl. Land (B4) nicht übergehbar | teilweise | Anschrift, Personenzahl und vollständiger Name sind kein harter Blocker; die Anschrift lässt sich von Hand bestätigen; die Wunschbestätigung prüft keine Gastangaben | `DocumentComposer::commonFindings`, `SubmitBookingWish::findings`, `DecideBookingWish`, `CaseAutomation::documentBlockers`, `AutoOffer` | Anforderungsprüfung je Aktion; harter Blocker. Die Auskunft unter Vorbehalt bleibt ohne Gate | U2 |
| Informationsbedarf je nächster Aktivität (CH §4 Nr. 1, P04) | teilweise | Nur „E-Mail fehlt“; keine Feldliste je Aktion | `CaseActivities` (contact), `CaseAutomation` | `CaseRequirements` als einzige Quelle; Aktivität „Angaben vervollständigen“ | U2 |
| **S5 / CH-03** gemeinsamer Fakteneingang mit Herkunft, Ergänzung, Widerspruch, Änderungswunsch | fehlt | Keine Herkunft je Angabe; Überschreiben (K2); kein Änderungswunsch | `ProvideGuestContact`, `CreateReservation::guestFor`, neues `case_facts` | `ContributeCaseFacts` mit Feldklassen und Phasenregel | U2 |
| **S6** idempotente Neubewertung | teilweise | Mehrfacher, uneinheitlicher Einstieg; Kopie in `ProvideGuestContact` | `CaseAutomation::advance` und Aufrufer | Ein Einstieg nach jeder Übernahme | U2 |
| P03 administrative Ergänzung nach Vertragsschluss | fehlt | — | Fakteneingang | Feldklasse „administrativ“ auch in P3 übernehmen | U2 |
| E-038 Änderungswunsch erkennen, nicht ausführen | fehlt | — | Fakteneingang, `BookingTask` | Aufgabe „Änderungswunsch prüfen“; keine Änderung | U2 |
| **E-033 / G1a** Klärungsreservierung V0/V1, `0` möglich, 15/180 min | fehlt | K1; kein Zweck am Hold; `ExpireReservations` beendet den Vorgang | `CreateReservation`, `TakeOverPortalInquiry`, `ExpireReservations`, `AutoOffer`, `Booking` | Spalte `hold_purpose`; Eingangslogik für unvollständige Anfragen | U3 |
| Angebots-Vorreservierung unverändert | umgesetzt | — | `SendOffer`, `CreateReservation` (vollständige Anfragen) | Regressionstests | U3 |
| Kurzblock verlängert sich nicht durch Nachrichten | fehlt (nicht anwendbar) | — | Klärungsreservierung, Datenbeschaffung | Kein Schreibzugriff des Handlers auf `hold_expires_at` | U3/U4 |
| **E-036** extern verbindliche Buchung bleibt trotz fehlender Daten verbindlich | umgesetzt | — | `TakeOverExternalBooking`, `PortalIntake` | Regressionstest; Klärungsreservierung nie für `IntakeKind::Booking` | U3 |
| **S1 / CH-04** Kommunikationsauftrag nach Modus automatisch/Freigabe/manuell | fehlt | Nur Kopiertext | neu: Beschaffungsvorgang | `data_requests` und Aktion `RequestCaseData` | U4 |
| **S4 / E-034** zustandsabhängige Texte nach **tatsächlichem** Sperrstatus | fehlt | — | neue Mailables | Textbausteine aus dem realen `hold_expires_at`/`hold_purpose` | U4 |
| **CH-18** signierter Ergänzungslink, Lesen schreibt nicht, idempotent | fehlt | Muster vorhanden (P7) | neue Route und Controller | Nach P7-Muster mit eigener Version | U4 |
| **CH-15/16/17** Rückfrage, Folgefrage, Erinnerung; eine offene Rückfrage; Zähler ohne Reset; Obergrenzen | fehlt | — | Beschaffungsvorgang, Scheduler | Zähler und Plan am Beschaffungsvorgang | U4 |
| **CH-01/05/06** IMAP-Eingang, Deduplizierung, ein aktives Postfach (Modell für mehrere), Klärungsansicht mit Absenderhinweisen | teilweise | Nur Portal-Absender; ein Postfach als Mandantenspalten; keine Klärungsansicht für allgemeine Mails | `MailboxReader`, `Tenant`, `PortalEmail`, `FetchPortalMail` | Tabellen `mailboxes`, `inbound_messages`; Ansicht „Posteingang“ | U5 |
| **CH-07/13** deterministische Zuordnung: Antwortbezug, Portalreferenz, iCal-vor-Mail, Absender + Wohnung + Zeitraum (nur in Kombination; ein offener Vorgang desselben Absenders allein genügt nicht) | teilweise | Portal-Teil umgesetzt (`PortalIntake`); Antwortbezug und Gast-Mails fehlen | `LogBookingMail` (Message-ID), neue Zuordnung | Message-ID speichern; Zuordnungsregeln | U5 |
| **CH-08/09/12** Parser bleiben; Portal-Mail liefert Ereignis **und** Gastangaben | teilweise | Ereignis ja, Gastangaben nein | `ProcessPortalMail`, Fakteneingang, Extraktion | Gastangaben über Extraktion an den Fakteneingang | U5/U6 |
| **CH-11** Verifikation zweifelhafter Portal-Mailereignisse | teilweise | Unbekannte Mails → „Prüfen“; keine Absenderverifikation | `ProcessPortalMail` | Kriterien festlegen (Go-live), Prüfstatus | U5 |
| **CH-14 / E-035** KI-Kaskade, Prompts versioniert, Schema, Kritikalität im Programm; Eskalation auch bei Widerspruch oder fehlgeschlagener Plausibilität, unabhängig von der Modellkonfidenz | fehlt | — | neu: `app/Communication/Extraction` | Kleines Modell → Regeln → optional großes Modell → Kandidaten | U6 |
| **E-037 / CH §2a Nr. 4** zentraler Kanalmanager inkl. eigener Webseite, keine zweite Konfigurationsquelle | teilweise | Drei Orte; Webseite fehlt; neue Parameter fehlen | `ProcessSetting`, `ProcessSettings`, `Channel`, Filament-Seiten | Webseite als Konfigurationskanal; neue Parameter im bestehenden Enum | U1 |
| §3a neue Werte sichtbar unter „Wirksame Einstellungen“ | teilweise | Seite vorhanden, neue Werte fehlen | `EffectiveSettings` | Neue Zeilen und Spalte „Eigene Webseite“ | U1 |
| **M10** Testbetrieb: Versand nur an Testziel, Bestandsregression | umgesetzt (Versand) | Eingang im Testbetrieb nicht gekennzeichnet | `EnforceMailTestMode`, neue Eingangstabelle | Kennzeichen „im Testbetrieb eingegangen“ | U5 |
| Mandantentrennung | umgesetzt | — | `BelongsToTenant`, `TenantRunner` | Alle neuen Tabellen mit `tenant_id` und Scope | alle |
| P02-Änderung vor Annahme, Parallelangebote, Fristverlängerung | — | — | — | **nicht MVP** | — |
| Vertragsänderung, Teilstorno nach Vertragsschluss automatisch | teilweise manuell (Paket 5) | — | `ChangeBooking` | **nicht MVP**; bleibt manuell | — |
| Mehrere aktive Postfächer, Messenger, Gastkonto, V2/V3, generative Antworten | — | — | — | **nicht MVP** (nur Datenmodell für Postfächer) | — |
| Altersaufteilung Erwachsene/Jugendliche/Kinder | — | offen in v0.11 | — | **zu klären**; nicht Teil des Gates | — |
## 5. Wiederverwendbare Bausteine
| Baustein | Verwendung in v0.11 |
|---|---|
| `ProcessSetting` und `ProcessSettings` (Vererbung, `null` erbt, `0` ist ein Wert) | Alle neuen Parameter; kein zweites Konfigurationsmodell |
| `ProcessProfile` (eingefroren beim Eingang) | Der Vorgang behält Klärungs- und Rückfrageparameter seines Eingangs |
| `EffectiveSettings`, `process:settings-report` | Herkunftsnachweis (§3a) |
| `CaseActivities`, `CaseAutomation::advance` | Informationsbedarf, S6 |
| `DocumentComposer`/`DocumentFinding::blocker` | G2a als harter Blocker |
| `Booking::occupying`, `hold_expires_at`, `AvailabilityChecker`, iCal-Export | Klärungsreservierung ohne neue Belegungsmechanik |
| P7-Linkmuster (`InformationController`, `SubmitBookingWish`: Version, `ensureCurrent`, Sperre in der Transaktion, „bereits erledigt“) | Ergänzungslink |
| `EnforceMailTestMode`, `LogBookingMail`, `BookingMessage` | Ausgehende Rückfragen, Antwortbezug |
| `MailboxReader` (webklex), `ProcessPortalMail`, `PortalIntake` | Eingang; Portalpfad unverändert dahinter |
| `BookingTask::openOnce`, `Inbox`, `AppSupportInbox`, `CaseLog` | Freigaben, Konflikte, Änderungswünsche, Verlauf |
| `TenantService` (`ai_guest_mail`, `api_key`), `ServiceUsage`, `TenantFeatures` | Schalter, Schlüssel und Verbrauch für KI |
| `TenantRunner` und Scheduler | Erinnerungen, Abruf, Extraktion je Mandant |
## 6. Prüfgrenzen dieser Analyse
- Geprüft wurden Code und Tests im Repository. Der Server (Strato), echte Postfächer, die Unterstützung von Plus-Adressen beim Mailanbieter und LLM-Anbieter wurden nicht geprüft.
- Die in [Offene Prüfungen](../Offene_Fragen.md) zitierten früheren Agentenbefunde wurden nur geprüft, soweit sie v0.11 berühren. Nachgeprüft:
- Hold und Angebot sind gekoppelt: zutreffend, das ist K1.
- Hold nur je Wohnung gesteuert: nicht mehr zutreffend; seit Paket 1 je Mandant, Wohnung und Kanal.
- Gast-Pflichtfelder lösen Platzhalter aus: zutreffend, das ist der G2a-Befund.
@@ -0,0 +1,274 @@
# v0.11 – Technische Zielarchitektur
**Stand:** 03.11.2026 · **Status:** Planungsvorschlag zur Freigabe, keine Implementierung · Bezug: [Soll-Ist-Analyse](V011_SOLL_IST_ANALYSE.md), [Umsetzungsplan](V011_UMSETZUNGSPLAN.md), normativ [Communication Handler](../Querschnitt/Datenbeschaffung_und_Communication_Handler.md).
Die Namen von Klassen und Tabellen sind Vorschläge. Sie folgen den vorhandenen Konventionen: Geschäftsoperationen in `app/Actions`, Prozesslogik in `app/Process`, Kanäle in `app/Channels`.
---
## 1. Leitentscheidungen
1. **Kein neuer Kern.** `CaseActivities` und `CaseAutomation` bleiben führend. Der Communication Handler liefert nur Anlässe (S1 → Kommunikationsauftrag) und geprüfte Angaben (S5 → S6). Er ändert keinen Status, keine Frist und keinen Preis.
2. **Eine Konfigurationsquelle.** Alle neuen Parameter werden Fälle des bestehenden `ProcessSetting` und laufen durch `ProcessSettings::resolve`. Der Kanalmanager ist eine **Oberfläche** über den vorhandenen Speicherorten `tenants.process_defaults`, `properties.process_overrides` und `channels.process_overrides`.
3. **Die eigene Webseite ist ein Kanal-Datensatz eigener Art, nur für Konfiguration.** Vorgänge von der Webseite behalten `source = website` ohne `origin_channel_id`. So bleiben A1, `isDirect()`, Bezeichnungen und Auswertungen unverändert (Konflikt K3).
4. **Daten bleiben, wo sie sind.** Gastangaben stehen weiter in `guests`, Vorgangsangaben in `bookings`. Neu ist nur ein **Nachweisprotokoll** je Angabe (`case_facts`), keine zweite Datenhaltung.
5. **Reservierungen nutzen die vorhandene Belegungsmechanik.** Die Klärungsreservierung ist ein Hold mit eigenem Zweck (`hold_purpose`) und wird nicht als neuer Status abgebildet.
6. **Synchron und begrenzt.** Es gibt keine Queue-Worker (Strato). Abruf, Zuordnung, Extraktion und Erinnerungen laufen als begrenzte Scheduler-Schritte. Jeder Schritt ist idempotent und setzt bei einem Abbruch wieder auf.
7. **Keine neue Abhängigkeit ohne Freigabe.** Die LLM-Anbindung läuft über den Laravel-HTTP-Client hinter einer kleinen Schnittstelle.
## 2. Komponenten und Datenfluss
```
┌────────────── Kanalmanager (Oberfläche) ──────────────┐
│ Mandantenstandard · Wohnung · Kanal × Eingangsart │
│ (inkl. „Eigene Webseite“) → ProcessSettings::resolve │
└───────────────────────────┬───────────────────────────┘
│ wirksame Werte (eingefroren im Profil)
Eingänge ▼
Webformular ─► CreateReservation ─► Vorgang ◄──── CaseActivities / CaseAutomation (führend)
Portal/iCal ─► PortalIntake (unverändert) │ S1: CaseRequirements → fehlende Angaben
Vermieterin ─► ViewBooking ▼
RequestCaseData (Beschaffungsvorgang, Modus, Zähler)
│ S4: Rückfrage-Mail (tatsächlicher Sperrstatus) + Ergänzungslink
▼
Gast ─► Ergänzungslink (Formular) ──────────────┐
Gast ─► E-Mail ─► IMAP ─► inbound_messages ─► Zuordnung (S3) ─► Extraktion (KI, optional)
Portal-Mail ─► inbound_messages ─► ProcessPortalMail (unverändert) ─┘ │
▼
S5: ContributeCaseFacts (Validierung, Phase, Feldklasse, Konflikt)
│ übernommen → guests/bookings + case_facts + CaseLog
▼
S6: CaseAutomation::advance (idempotent, nur im Automatikmodus)
```
## 3. Bausteine im Einzelnen
### 3.1 Konfiguration und Kanalmanager (F)
**Neue Fälle in `ProcessSetting`:**
| Schlüssel | Typ | Standard | Kanal-Eingangsarten | Quelle |
|---|---|---|---|---|
| `clarification_hold_auto_minutes` | int, `0` erlaubt | 15 | Anfrage | E-033 |
| `clarification_hold_manual_minutes` | int, `0` erlaubt | 180 | Anfrage | E-033 |
| `data_request_mode` | `automatic` / `approval` / `manual` | `approval`, technischer Vorschlag (§7 T3) | Anfrage, Buchung | CH §1.6 |
| `data_request_reminders_max` | int | 2 | Anfrage, Buchung | CH §4 Nr. 5 |
| `data_request_followups_max` | int | 2, technischer Vorschlag (offen) | Anfrage, Buchung | CH-15 |
| `data_request_reminder_hours` | int | 24, technischer Vorschlag (offen) | Anfrage, Buchung | CH-17 |
| `guest_link_valid_days` | int | 14, technischer Vorschlag (Go-live) | — (Mandant, Wohnung) | CH-18 |
- `ProcessProfile` friert sie beim Eingang wie bisher ein. `EffectiveSettings` und `process:settings-report` zeigen sie automatisch, sobald sie im Enum stehen.
- Den Wert „Klärungsreservierung bei manueller oder freigegebener Datenbeschaffung“ bestimmt der wirksame `data_request_mode`: bei `automatic` gilt der Wert für automatische Beschaffung, sonst der für Freigabe/manuell.
**Eigene Webseite als Kanal:**
- Spalte `channels.kind` mit den Werten `portal` (Bestand) und `website`. Je Wohnung gibt es einen Datensatz `website`, angelegt per Migration, ohne Connector, ohne Import, Export und Sperraufgaben.
- Neuer Scope `Channel::portals()`. Er ersetzt `active()` an den operativen Stellen: Sync, Postfach-Absender, Überwachung, `CreateChannelTasks`, `CalendarClearance`, Export-Feed, Digest, Statistik. Die Stellen sind in der Soll-Ist-Analyse §2.5 gezählt, alle durch Tests abgedeckt.
- `ProcessSettings::resolve` bekommt keinen neuen Parameter. Für eine Anfrage ohne Kanal mit `source = website` nimmt `forBooking`/`CreateReservation` den Webseiten-Kanal **nur als Einstellungsebene**. `caseTypeFor` prüft künftig `$channel?->kind === portal` statt `$channel !== null` (K3).
- Telefon und E-Mail von Hand bleiben ohne Kanal: Es gilt die Mandanten- und Wohnungsebene, wie R02 vorsieht.
**Oberfläche:**
- Der bisherige Bereich „Portale“ wird „Kanäle“ und ist in der einfachen Ansicht sichtbar.
- Oben steht der Eintrag „Alle Kanäle (Ihre Standards)“; er führt zu „So arbeite ich“, das bleibt der Ort der Mandantenstandards und Dokumentfreigaben.
- Darunter steht je Wohnung „Eigene Webseite“, dann die Portale.
- Jeder Kanal hat die Bereiche „Ablauf“ (bestehende Prozessabweichungen je Eingangsart), „Datenbeschaffung und Klärungsreservierung“ (neu) und „Anbindung“ (iCal, Regeln, Export, unverändert; bei der Webseite ausgeblendet).
### 3.2 Informationsbedarf (S1-Teil) und Gate G2a
- **`App\Process\CaseRequirements`** ist die einzige Stelle, die Pflichtangaben kennt. Sie liefert für einen Vorgang und eine Aktion eine Liste fehlender Angaben (Schlüssel, Bezeichnung, Feldklasse).
- `offer` (G2a) und `wish_confirmation` (verbindliche Bestätigung eines Buchungswunsches nach Auskunft, B3): Vorname, Nachname, E-Mail, Straße mit Hausnummer, PLZ, Ort, Land (B4), Personenzahl, An- und Abreise.
- `information` (Auskunft unter Vorbehalt): **kein** Angebots-Gate (B3). Es gelten nur die bestehenden Voraussetzungen (E-Mail, Preis, Freigaben); fehlende Angaben werden vor der Wunschbestätigung beschafft.
- Land (B4): Formulare dürfen „Deutschland“ als änderbaren Standard anbieten. Als vorhanden gilt das Land nur, wenn es aus einer Quelle stammt (Eingabe des Gastes, Bestätigung des vorbelegten Werts im Formular, Portal, Vermieterin). Ein leeres Kartenfeld wird nie still mit „DE“ gefüllt.
- `documents` für verbindliche Buchungen: wie heute nur Gast, E-Mail und Preis; keine rückwirkenden Pflichtangaben (P04).
- `arrival`: Anreisezeit, nur wenn eingestellt (Bestand).
- `DocumentComposer::commonFindings` erzeugt für `Offer` aus `CaseRequirements` **`DocumentFinding::blocker`**. Dieselbe Prüfung steht vor der verbindlichen Bestätigung eines Buchungswunsches (`SubmitBookingWish::findings`, `DecideBookingWish`) und verhindert dort die automatische wie die manuelle Bestätigung. Die Auskunft unter Vorbehalt bleibt ohne dieses Gate. Damit kann auch der manuelle Versand die fehlende Anschrift nicht übergehen (M01). Der bisherige Platzhalter-Hinweis bleibt für andere Platzhalter.
- `CaseActivities`: Die Aktivität „contact“ wird zu „Angaben vervollständigen“, mit der Liste aus `CaseRequirements` und dem Zustand „wartet auf Gast“, solange eine Rückfrage offen ist.
### 3.3 Gemeinsamer Fakteneingang (S5) und Neubewertung (S6)
**Tabelle `case_facts`** (Nachweisprotokoll, nur anfügen):
| Spalte | Inhalt |
|---|---|
| `tenant_id`, `booking_id` | Mandant, Vorgang |
| `field` | Schlüssel aus `CaseRequirements` (z. B. `guest.street`, `booking.guests`) |
| `value`, `previous_value` | neuer und bisheriger Wert (verschlüsselt, wie andere personenbezogene Felder) |
| `source` | `website_form`, `guest_link`, `email`, `portal_mail`, `llm`, `landlord` |
| `inbound_message_id`, `evidence` | Beleg: Nachricht und Textstelle |
| `confidence` | nur bei KI |
| `outcome` | `applied`, `confirmed` (gleicher Wert), `conflict`, `change_request`, `rejected` (Validierung) |
| `created_at`, `actor` | Zeitpunkt, Akteur |
**Aktion `App\Actions\ContributeCaseFacts`:** `handle(Booking, array $facts, FactSource, ?InboundMessage)`
1. Sperrt den Vorgang (`lockForTransition`) und arbeitet idempotent: Gleiche Quelle, Nachricht und Werte erzeugen nichts Neues (M03).
2. Validiert je Feld (E-Mail-Format, PLZ, Personenzahl im Rahmen der Wohnung, Datumslogik).
3. Bestimmt die Phase: P1 `Reserved`, P2 `OfferSent`, P3 `occupying()`.
4. Wendet die **Feldklassen** an:
- **administrativ:** Telefon, Anreisezeit, fehlende Anschrift oder fehlender Name bei P3;
- **angebotsrelevant:** Name, Anschrift, Personenzahl, Zeitraum, Leistungen;
- **vertragsrelevant ab P2:** Zeitraum, Personenzahl, Preis, Leistungen.
5. Regel je Feld:
| Lage | P1 | P2/P3 |
|---|---|---|
| leer → Wert | übernehmen | administrativ: übernehmen; vertragsrelevant: `change_request` |
| gleicher Wert | `confirmed` | `confirmed` |
| anderer Wert | Quelle `landlord`: übernehmen; sonst `conflict` | administrativ: `conflict`; vertragsrelevant: `change_request` |
Die Vermieterin bleibt maßgeblich; ihre Eingabe überschreibt mit Verlauf (K2 gelöst).
6. Schreibt übernommene Werte in `guests` bzw. `bookings`. Bei mehreren Vorgängen derselben Kartei gilt für eine **abweichende** Angabe aus Gastquellen immer `conflict` (Schutz fremder Vorgänge).
7. Öffnet Aufgaben: `BookingTaskKind::FactConflict` (neu) und `BookingTaskKind::ChangeRequest` (neu, E-038). Schreibt `CaseLog`.
8. Ruft **einmal** `CaseAutomation::advance` (S6) und benachrichtigt den Beschaffungsvorgang (U4), der Erinnerungen stoppt bzw. eine Folgefrage plant.
`ProvideGuestContact` und die Webformular-Übernahme (`guestFor`) rufen künftig `ContributeCaseFacts`. Die doppelte Fortsetzungslogik in `ProvideGuestContact` entfällt: Der Moduswechsel bleibt, die Fortsetzung übernimmt `advance`.
### 3.4 Klärungsreservierung (E)
- **Spalte `bookings.hold_purpose`:** `offer` (Bestand, Standard für alle Altdaten) oder `clarification`.
- **Eingang einer Anfrage** (`CreateReservation`, `TakeOverPortalInquiry`):
- **vollständig** nach `CaseRequirements::for('offer')`: unverändert (Hold = Angebots-Haltefrist, falls „Angebotsreservierung ja“);
- **unvollständig, aber V1-qualifiziert** (Wohnung, Zeitraum, verwendbare E-Mail, Verfügbarkeit positiv): `hold_purpose = clarification`, `hold_expires_at = Eingang + Minuten` (nach Modus) bzw. **kein Hold bei `0`**;
- **unvollständig, nicht qualifiziert** (keine E-Mail): kein Hold, Aufgabe.
- **Ablauf:** `ExpireReservations` beendet nur `hold_purpose = offer`. Ein abgelaufener Klärungsblock lässt den Vorgang offen (`Reserved`, Kalender frei).
- **Übergang zum Angebot:** ausschließlich über `SendOffer` bzw. `AutoOffer`. `SendOffer` prüft die Verfügbarkeit ohnehin und setzt `hold_purpose = offer` mit der unveränderten Frist. Der `AutoOffer`-Blocker „nicht mehr vorgemerkt“ gilt künftig nur für `offer`-Holds; für eine Anfrage nach abgelaufenem Klärungsblock entscheidet die erneute Verfügbarkeitsprüfung.
- **Nie** verlängert: Kein Baustein des Handlers schreibt `hold_expires_at`. Das sichert ein Architekturtest ab.
- **Nie** für `IntakeKind::Booking` (E-036).
- **Sperrstatus für Texte:** `Booking::clarificationState()` gibt `none`, `active(until)`, `expired` oder `failed` zurück, berechnet aus `hold_purpose` und `hold_expires_at`. Nur daraus werden Textbausteine gewählt (S4, M11).
### 3.5 Datenbeschaffung, Rückfrage und Ergänzungslink (B ausgehend, D)
**Tabelle `data_requests`** (Beschaffungsvorgang; je Vorgang höchstens einer offen):
| Spalte | Inhalt |
|---|---|
| `booking_id`, `tenant_id`, `status` | `draft` (wartet auf Freigabe), `open`, `answered`, `completed`, `stopped`, `manual` |
| `mode` | eingefroren aus dem Profil |
| `fields` | angefragte Angaben aus `CaseRequirements` |
| `followups_sent`, `reminders_sent` | Zähler, nie zurückgesetzt (CH-16) |
| `current_message_sent_at`, `response_due_at`, `next_reminder_at` | Antwortfrist ≠ Reservierungsfrist |
| `link_version` | Ungültigmachen älterer Links |
**Aktion `RequestCaseData` (S1):**
- Sie wird von `CaseAutomation` bzw. `CaseActivities` aufgerufen, wenn `CaseRequirements` für die nächste Aktion etwas fehlen sieht.
- Je Modus:
- `automatic`: Mail sofort;
- `approval`: Entwurf und Aufgabe „Rückfrage freigeben“ mit Vorschau;
- `manual`: Aufgabe mit Kopiertext, also das heutige Verhalten.
- Ohne verwendbare E-Mail entsteht eine Aufgabe, kein fingierter Versand.
**Mails (neue Mailables über den bestehenden Mailer, damit Testbetrieb und Protokoll greifen):**
- `DataRequested`: Erstrückfrage und gezielte Folgefrage;
- `DataReminder`: Erinnerung.
Die Textbausteine hängen ab von `clarificationState()`, Phase und Eingangsart:
- Klärungsblock `0`;
- aktiv, mit realem Datum und Uhrzeit;
- abgelaufen;
- extern verbindliche Buchung;
- P2/P3.
Antwortbezug: siehe 3.6.
**Ergänzungslink (CH-18):**
- Route `GET /angaben/{booking}` und `POST /angaben/{booking}`, `signed`, Gültigkeit aus `guest_link_valid_days`, Parameter `v = link_version`.
- **GET schreibt nichts.**
- Das Formular zeigt nur die angefragten Felder und die vom Gast für diesen Vorgang selbst angegebenen Werte (minimale Einsicht, K4). Vorbefüllt wird nur, was der Gast selbst geliefert hat.
- POST prüft Version und Status, ruft `ContributeCaseFacts(source: guest_link)` und ist idempotent.
- Bei abgelaufenem Link, abgeschlossenem Vorgang oder veralteter Version folgt eine verständliche Seite ohne Wirkung und das Angebot „neuen Link anfordern“ (Mail an die hinterlegte Adresse).
**Taktung:**
- Der Scheduler-Befehl `cases:data-requests` (alle fünf Minuten, `TenantRunner`) sendet fällige Erinnerungen (höchstens `reminders_max`).
- Danach entsteht die Aufgabe „Gast antwortet nicht“ (CH-16).
- Eine Antwort (S5) stoppt die laufende Erinnerung. Bleibt etwas offen, folgt eine gezielte Folgefrage bis `followups_max`, danach eine Aufgabe.
- Vollständigkeit, Absage oder das Ende des Vorgangs stoppen alles (CH-17).
### 3.6 Posteingang, Zuordnung und Klärung (B eingehend)
- **Tabelle `mailboxes`** (CH-05): `tenant_id`, Zugangsdaten verschlüsselt, Ordner, Aliasadressen, `is_active`, `mode` (`portal_only` = heutiges Verhalten, `full` = alle Mails).
- Migration übernimmt die heutigen `tenants.mailbox_*`.
- Je Mandant ist höchstens ein Postfach aktiv (Validierung).
- **Tabelle `inbound_messages`:**
- `tenant_id`, `mailbox_id`, `message_id` (eindeutig je Mandant), `in_reply_to`/`references`, Absender, Empfänger, Betreff, Text (verschlüsselt), Eingang;
- `test_mode` (im Testbetrieb eingegangen, M10), `status` (`new`, `assigned`, `needs_review`, `ignored`, `processed`), `booking_id`, `match_reason`, `portal_email_id`.
- **Abruf** (`channels:fetch-mail`, erweitert):
- `portal_only` wie heute;
- `full`: alle neuen Mails seit dem letzten Lauf, ungelesen lassen, Rückblick wie bisher.
- Speichern geht vor Verarbeiten. Portal-Absender laufen danach **unverändert** durch `ProcessPortalMail` (CH-08).
- **Zuordnung** (`App\Communication\MessageMatcher`, deterministisch, CH-13). Die Reihenfolge:
1. `In-Reply-To`/`References` gegen gespeicherte Message-IDs ausgehender Mails (neue Spalte `booking_messages.message_id`, gefüllt in `LogBookingMail`);
2. Vorgangskennung in Betreff bzw. Antwortadresse (Plus-Adresse, falls der Anbieter sie unterstützt; Technik **T6**);
3. Portalreferenz über `PortalIntake::caseByReference`;
4. Direkte Gast-Mail ohne Antwort- oder Vorgangsbezug: nur bei eindeutiger **Kombination** aus Absender (= hinterlegte Gast-E-Mail), Wohnung **und** Zeitraum. Wohnung und Zeitraum müssen in der Nachricht erkennbar sein und zu genau einem offenen Vorgang ohne Widerspruch passen (CH-13). Ein einziger offener Vorgang desselben Absenders allein genügt **nicht**; er erscheint nur als Hinweis in der Klärungsansicht.
Mehrere Kandidaten oder Widersprüche ergeben `needs_review` mit Hinweisen (M04). Eine Zuordnung berechtigt noch nicht zur Übernahme.
- **Klärungsansicht** (Filament-Ressource „Posteingang“):
- Liste `needs_review` mit Absenderhinweisen (bekannte Gäste und Vorgänge);
- Aktionen „Vorgang zuordnen“, „Als neue Anfrage anlegen“ (vorbefüllt, ruft die bestehende Erfassung) und „Ignorieren“.
- Eine allgemeine Mail legt nie selbst einen Vorgang an (CH-06).
### 3.7 KI-Extraktion (C)
- **Schnittstelle `App\Communication\Extraction\Extractor`:** `extract(InboundMessage, ExtractionContext): ExtractionResult`.
- Implementierungen:
- `RuleExtractor`: bestehender Portalparser und einfache Muster;
- `LlmExtractor`: kleines Modell;
- `ReviewLlmExtractor`: großes Modell, sieht Original und Erstextraktion.
- Die Modellanbindung `LlmClient` läuft über den HTTP-Client; Anbieter, Modell und Endpunkt kommen aus der Konfiguration (austauschbar).
- **Prompts** liegen versioniert als Dateien unter `resources/prompts/extraction/<version>.md`, mit Platzhaltern wie `{{phase}}`, `{{requested_fields}}`, `{{known_values_masked}}`, `{{message}}`. Das JSON-Schema liegt daneben (`schema.json`). Die genutzte Version wird an jedem Ergebnis gespeichert.
- **Ausgabe:** schema-validiert. Fakten mit `field`, `value`, `evidence` (Zitat) und `confidence`; Änderungsabsichten; Unsicherheiten. Bei ungültigem Schema wird einmal wiederholt, danach geht die Nachricht in die Klärung.
- **Programmatische Risikoprüfung** (`App\Communication\Extraction\RiskAssessment`):
- Die Kritikalität ergibt sich aus Feldklasse, Phase und Art der Abweichung (vgl. 3.3).
- Eskaliert wird zum großen Modell, wenn **eine** der Bedingungen zutrifft:
- `Kritikalität × (1 − Konfidenz)` liegt über dem Schwellwert (konfigurierbar, Kalibrierung offen);
- **unabhängig von der Konfidenz:** Widerspruch zu einem vorhandenen Wert oder zu einer anderen Angabe derselben Nachricht, erkannte Änderungsabsicht in P2/P3, fehlgeschlagene Plausibilitätsprüfung (z. B. Abreise vor Anreise, Personenzahl über der Kapazität, Termine passen nicht zum zugeordneten Vorgang, Belegstelle nicht im Original).
- Die Konfidenz des Modells ist keine kalibrierte Wahrscheinlichkeit (CH-14). Sie kann eine Prüfung auslösen, aber nie eine entfallen lassen. Fakten mit Widerspruch oder fehlgeschlagener Plausibilität werden auch nach der Prüfung durch das große Modell nie automatisch übernommen, sondern der Vermieterin vorgelegt.
- **Automatische Übernahme** nur, wenn alle Bedingungen erfüllt sind: Feld bisher leer, Feldklasse administrativ oder angebotsrelevant in P1, Validierung bestanden, Belegstelle im Original gefunden (wörtlicher Abgleich), Mindestkonfidenz. Alles andere geht an die Vermieterin (`conflict` bzw. Prüfung).
- **Ergebnis:** `ContributeCaseFacts(source: llm)`. Die KI schreibt nie selbst.
- **Betrieb:**
- Schalter `ai_guest_mail` wird `isWired`;
- Schlüssel je Mandant (`Tenant::services`), Verbrauch in `ServiceUsage`;
- je Lauf höchstens N Nachrichten, Zeitlimit je Aufruf;
- bei Ausfall bleibt die Nachricht `needs_review` (sicherer Rückfall).
- **Messung (M05):** Der Befehl `ai:evaluate` führt einen Satz anonymisierter Testnachrichten mit Sollwerten aus und meldet getrennt Fehlwerte und übersehene Angaben. Er läuft ohne Netz in den Tests mit aufgezeichneten Antworten, mit Netz nur bewusst.
## 4. Datenmodelländerungen (Übersicht)
| Änderung | Rückwärtskompatibilität |
|---|---|
| `channels.kind` (Standard `portal`) und je Wohnung ein `website`-Datensatz | Bestehende Kanäle unverändert; Migration idempotent |
| `bookings.hold_purpose` (Standard `offer`) | Altdaten verhalten sich wie bisher |
| `case_facts` (neu) | Nur anfügen; kein Rückbau nötig |
| `data_requests` (neu) | — |
| `booking_messages.message_id` (nullable) | Alte Einträge ohne ID |
| `mailboxes` (neu) mit Übernahme von `tenants.mailbox_*` | Alte Spalten bleiben bis nach der Produktivmigration lesbar (wie bei `properties.hold_hours`) |
| `inbound_messages` (neu), `portal_emails.inbound_message_id` (nullable) | Portalpfad unverändert |
| `BookingTaskKind`: `FactConflict`, `ChangeRequest`, `DataRequestApproval`, `GuestUnresponsive` | Enum-Erweiterung |
## 5. Sicherheit und Datenschutz (technisch)
- Signierte Links mit Mandanten- und Vorgangsbindung (Route-Model-Binding mit Mandanten-Scope wie bei P7), Version, Ablauf, Begrenzung der Aufrufe (`throttle`). Die Sicherheitsgrenzen sind nicht abschaltbar.
- Nachrichtentexte, Faktwerte und Postfach-Zugangsdaten werden verschlüsselt gespeichert. Die Löschung folgt dem bestehenden `AnonymizeGuests`-Lauf; die Frist ist offen (Go-live).
- An das LLM gehen nur die Nachricht und die angefragten Feldnamen, bekannte Werte nur maskiert. Kein Training, kein Speichern beim Anbieter, soweit vertraglich zusicherbar (Go-live).
- Die Testbetriebs-Schranke bleibt die einzige Versandschranke. Eingehende Nachrichten im Testbetrieb werden gekennzeichnet.
## 6. Beziehung zu bestehenden Abläufen
| Bestand | Wirkung der Erweiterung |
|---|---|
| iCal-Sync, Regeln, Export | keine; nur der Scope `portals()` statt `active()` |
| Portal-Schnellweg (Mail → Sperre) | unverändert; Mails werden vorher gespeichert |
| Angebot, Auskunft, Buchungswunsch, Annahme | unverändert; neu nur das Gate G2a vor dem Angebot und vor der verbindlichen Wunschbestätigung; die Auskunft bleibt ohne Gate |
| Ändern und Stornieren (Paket 5) | unverändert; Änderungswünsche erzeugen nur eine Aufgabe |
| Aufenthalt und Abschluss (Paket 9) | unverändert; Anreisezeit kann über Link oder Mail kommen |
## 7. Technische Entscheidungen im Rahmen der Umsetzung
| # | Entscheidung | Vorschlag |
|---|---|---|
| T1 | Webseite als Kanal | `channels.kind = website`, nur Konfiguration (§3.1) |
| T2 | Nachweis je Angabe | `case_facts` als Protokoll, Daten bleiben in `guests`/`bookings` |
| T3 | Technische Standards für offene Parameter | Rückfragemodus `approval`, Folgefragen 2, Erinnerungsabstand 24 h, Link 14 Tage; überschreibbar, Go-live-Freigabe |
| T4 | LLM-Anbindung | HTTP-Client, Anbieter konfigurierbar; Vorschlag kleines/großes Modell aus derselben Modellfamilie |
| T5 | Abruf im Modus `full` | Ungelesen lassen, UID-Merkpunkt je Postfach, Deduplizierung per Message-ID |
| T6 | Antwortadresse | Message-ID-Bezug und Vorgangskennung im Betreff sicher; Plus-Adresse zusätzlich, wenn der Anbieter sie zustellt |
| T7 | Eingang im Testbetrieb | normal verarbeiten, sichtbar gekennzeichnet; Versand bleibt über die Schranke umgeleitet |
@@ -0,0 +1,342 @@
# v0.11 – Umsetzungsplan
**Stand:** 03.11.2026 · **Status:** zur Prüfung und Freigabe. Die Umsetzung wird gesondert beauftragt. · Bezug: [Soll-Ist-Analyse](V011_SOLL_IST_ANALYSE.md) · [Technische Zielarchitektur](V011_TECHNISCHE_ZIELARCHITEKTUR.md) · normativ [Communication Handler](../Querschnitt/Datenbeschaffung_und_Communication_Handler.md) (CH-01–CH-18, S1–S6, M01–M12)
---
## 1. Management-Zusammenfassung
**Umfang:** sechs Pakete. Zwei davon sind kleine Grundlagenpakete (Konfiguration, Gate und Fakteneingang), eines betrifft die Reservierung, drei den Communication Handler (Rückfrage und Link, Posteingang, KI). Grob geschätzt hat das etwa den Umfang der Pakete 1–9 der v0.10 zusammen. Der größte Einzelblock ist der Communication Handler (U4–U6).
**Wesentliche Architekturentscheidungen:**
- Keine neue Engine; `CaseAutomation` und `CaseActivities` bleiben führend.
- Alle neuen Parameter laufen im bestehenden `ProcessSetting`. Der Kanalmanager ist eine Oberfläche über den vorhandenen Speicherorten.
- Die eigene Webseite wird ein Kanal-Datensatz eigener Art nur für die Konfiguration; Vorgänge bleiben A1.
- Gastdaten bleiben in `guests` und `bookings`; neu ist ein Nachweisprotokoll je Angabe.
- Die Klärungsreservierung ist ein Hold mit Zweck `clarification` in der vorhandenen Belegungsmechanik.
- Die KI liefert nur Kandidaten an den Fakteneingang.
**Wesentliche Risiken:**
1. Das Gate G2a und die Klärungsreservierung verändern das Verhalten für Webseiten-Anfragen ohne Anschrift sichtbar (K1; vom Betreiber mit B1 bestätigt).
2. Den Postfachabruf auf „alle Mails“ umzustellen berührt den Portal-Schnellweg; das wird mit einem Modus je Postfach abgesichert.
3. LLM-Qualität, Kosten und Datenschutz sind erst mit echten Testnachrichten belastbar (M05, Go-live).
4. Ohne Queue-Worker müssen Abruf und Extraktion begrenzt im Scheduler laufen.
**Tatsächliche Implementierungsblocker:** keine mehr. Der Betreiber hat B1–B4 am 03.11.2026 entschieden (§3.1). Offen sind nur technische Entscheidungen (§3.2) und Go-live-Bedingungen (§3.3).
## 2. Pakete im Überblick
| Paket | Inhalt | Abhängig von | Größe | Abnahmefälle |
|---|---|---|---|---|
| **U1** | Neue Parameter, Webseite als Kanal, Kanalmanager, „Wirksame Einstellungen“ | – | M | M12 (Konfigurationsteil) |
| **U2** | Informationsbedarf, Gate G2a, gemeinsamer Fakteneingang, Neubewertung | – | M | M01, M06 (Teil), M03 (Teil) |
| **U3** | Klärungsreservierung V0/V1 | U1, U2 | S–M | M11 (Reservierungsteil), M12 (Bestandsschutz) |
| **U4** | Beschaffungsvorgang, Rückfrage, Folgefrage, Erinnerung, Ergänzungslink, Zustandstexte | U1–U3 | L | M02 (Formular), M03, M08, M09, M11 |
| **U5** | Postfächer, Nachrichteneingang, Zuordnung, Klärungsansicht, Antwortbezug | U2, U4 (Message-ID) | L | M02 (E-Mail), M04, M07, M10 |
| **U6** | KI-Extraktion (klein → Regeln → groß), Prompts, Schema, Messung | U5 | M–L | M05, M06 |
Reihenfolge: **U1 ∥ U2 → U3 → U4 → U5 → U6**. Nach U4 ist der Nutzen schon im Betrieb verfügbar: Die fehlende Anschrift wird automatisch per Link beschafft, Antworten per E-Mail trägt die Vermieterin bis U5 von Hand ein.
---
## 3. Offene Punkte, geordnet
### 3.1 Implementierungsblocker – am 03.11.2026 entschieden
Die Tabelle zeigt die ursprüngliche Frage und die Entscheidung des Betreibers. Es bestehen keine offenen Blocker mehr.
| # | Paket | Frage | Warum blockierend | Entscheidung des Betreibers |
|---|---|---|---|---|
| **B1** | U3 | **Eingangsverhalten unvollständiger Anfragen (K1):** Bekommt eine unvollständige Anfrage künftig statt der Angebots-Haltefrist (heute 48 h ab Eingang) nur die Klärungsreservierung (15/180 min oder `0`)? Und entsteht bei Vervollständigung **kein** neuer Hold, bis das Angebot gesendet wird? | Der Code reserviert heute jede Anfrage beim Eingang. v0.11 P01 Nr. 4 und CH §2a Nr. 1 legen das nahe, ändern aber sichtbares Bestandsverhalten. | **Bestätigt.** Unvollständige unverbindliche Anfragen erhalten nur die konfigurierte Klärungsreservierung. Eine Angebots-Vorreservierung entsteht erst über den bestehenden Angebotsprozess, nicht allein durch das Ergänzen fehlender Daten. Vollständige Anfragen bleiben unverändert. |
| **B2** | U3 | **Anschrift im Webformular:** Bleibt sie optional (dann laufen die meisten Webseiten-Anfragen über Rückfrage und Kurzblock) oder wird sie über den Kanal „Eigene Webseite“ zur Pflicht (dann bleibt das 48-h-Verhalten für die Webseite)? | Bestimmt Formular, Kanalparameter und Regressionsumfang. | **Bestätigt.** Vollständige Anschrift im Webformular als Kanaleinstellung konfigurierbar; Standard zunächst **optional**. |
| **B3** | U2 | **Gate auch vor der Auskunft unter Vorbehalt (Angebots-Hold 0)?** Die v0.11 nennt das Gate „vor eigenem verbindlichem Angebot“. Bei Hold 0 entsteht die Bindung erst mit der Bestätigung des Buchungswunsches. | Sonst kommt ein Vertrag ohne Anschrift zustande. | **Entschieden:** Das vollständige Angebots-Gate gilt vor einem eigenen verbindlichen Angebot **und** vor einer verbindlichen Buchungswunschbestätigung, automatisch wie manuell. Die ausdrücklich unverbindliche Auskunft unter Vorbehalt bleibt mit unvollständigen Gastdaten möglich. |
| **B4** | U2 | **„Vollständige Postanschrift“:** Straße mit Hausnummer, PLZ, Ort **und Land**? | Feldliste des Gates. | **Bestätigt.** Die vollständige Anschrift umfasst das Land. „Deutschland“ darf als änderbarer Formularstandard angeboten werden, ist aber keine ungeprüfte Tatsachenannahme: Ein leeres Feld gilt als fehlend und wird nie still gefüllt. Der Name ist Vor- **und** Nachname. |
Die Altersaufteilung ist ausdrücklich offen und **nicht** Teil des Gates; sie blockiert nichts.
### 3.2 Technische Entscheidungen (in der Umsetzung, siehe Zielarchitektur §7)
T1 Webseite als Kanal · T2 Nachweisprotokoll `case_facts` · T3 technische Standardwerte (Rückfragemodus „Freigabe“, Folgefragen 2, Erinnerung alle 24 h, Link 14 Tage) · T4 LLM über HTTP-Client, Anbieter konfigurierbar · T5 Abrufmodus je Postfach · T6 Antwortbezug über Message-ID und Betreffkennung, Plus-Adresse optional · T7 Eingang im Testbetrieb gekennzeichnet.
Zusätzlich vor U6: Die Aufnahme eines Anbieter-SDK ist **nicht** vorgesehen. Falls doch gewünscht, braucht das eine Freigabe, weil sich die Abhängigkeiten ändern.
### 3.3 Go-live-Freigabebedingungen (blockieren die Umsetzung nicht)
| # | Bedingung | Betrifft |
|---|---|---|
| G1 | Rechtlich geprüfte Texte: Rückfrage, Folgefrage, Erinnerung, Zustandstexte (Klärungsblock 0/aktiv/abgelaufen, Portalbuchung), Linkseite | U4 |
| G2 | Endgültige Werte: Rückfragemodus je Kanal, Erinnerungsabstand, Folgefragen-Obergrenze, Linklaufzeit, Klärungsminuten je Kanal (z. B. `0` für träge iCal-Portale) | U1, U4 |
| G3 | Eigenes Postfach je Mandant eingerichtet; Zustellung von Antworten (Plus-Adresse ja/nein) geprüft | U5 |
| G4 | Datenschutz: Lesen aller Mails des Postfachs, Speicher- und Löschfristen (kein 30-Tage-Wert beschlossen), Datenschutzhinweise | U5, U6 |
| G5 | LLM-Anbieter: Auftragsverarbeitung, Speicherort, kein Training; Kosten je Nachricht | U6 |
| G6 | Kalibrierung von Konfidenz und Eskalationsschwelle an repräsentativen, anonymisierten Nachrichten; gemessene Rate übersehener Angaben akzeptiert (M05) | U6 |
| G7 | Kriterien für verlässliche Portal-Mailereignisse (CH-11) bestätigt | U5 |
| G8 | Sicherheitsprüfung der Gastlinks und des Posteingangs; Abnahme M01–M12 auf dem Testsystem; Regression v0.10 (T01–T25) | alle |
### 3.4 Spätere Erweiterungen (nicht beauftragt)
Parallele Angebotsvarianten, Angebotsänderung vor Annahme mit neuem Angebot, Fristverlängerung, automatische Vertragsänderung und Teilstorno nach Vertragsschluss, mehrere aktive Postfächer, Messenger und Social Media, generative Antworten, Gastkonto, V2/V3 des Klärungsblocks, Altersaufteilung, Leads (V02).
---
## 4. Pakete im Detail
### U1 – Parameter, Webseite als Kanal, Kanalmanager
**Ziel:** Alle Kanäle einschließlich der eigenen Webseite werden an einer Stelle verwaltet (E-037, M12). Die v0.11-Parameter sind einstellbar und wirksam sichtbar.
**Wiederverwendung:**
- `ProcessSetting`, `ProcessSettings`, `ProcessProfile`;
- `ProcessSettingFields` (Formularfelder je Einstellung);
- `ChannelForm`, `HandlingSettings`, `EffectiveSettings`, `process:settings-report`.
**Änderungen:**
1. `ProcessSetting` um die sieben Fälle der Zielarchitektur §3.1 erweitern (Standard, Frage, Eingangsarten, `normalize`, `describe`).
2. Migration `channels.kind` (`portal`/`website`) und je Wohnung ein Webseiten-Kanal. `Channel::portals()`-Scope einführen; `active()` an den operativen Stellen durch `portals()` ersetzen (Sync, `FetchPortalMail`, `ProcessPortalMail::channelFor`, `MonitorChannels`, `CreateChannelTasks`, `ChangeBooking` Z. 424, `CalendarClearance`, `ChannelController`, `DigestReport`, `BookingStats`, `ICalRuleEngine`).
3. `ProcessProfile::caseTypeFor`: A2 nur bei `kind = portal`. `CreateReservation` und `ProcessSettings::forBooking` lesen bei `source = website` den Webseiten-Kanal als Einstellungsebene. `origin_channel_id` bleibt leer.
4. Oberfläche:
- Ressource „Kanäle“, in der einfachen Ansicht sichtbar (`FollowsAdminMode`);
- Eintrag „Alle Kanäle (Ihre Standards)“ verweist auf „So arbeite ich“;
- Bereiche „Ablauf“, „Datenbeschaffung und Klärungsreservierung“, „Anbindung“; bei der Webseite ohne Anbindung;
- Schalter „Anschrift im Formular verlangen“ nach B2.
5. „Wirksame Einstellungen“: Spalte „Eigene Webseite“ und neue Zeilen.
**Migrationen:** zwei, idempotent, rückwärtskompatibel (Standard `portal`).
**Risiken:**
- Eine vergessene `active()`-Stelle würde den Webseiten-Kanal synchronisieren oder als Portal anzeigen.
- Die Ressourcenumbenennung ändert die Navigation.
**Tests:**
- Neu: Webseiten-Kanal überschreibt den Mandantenstandard für Webseiten-Anfragen; Vorgang bleibt A1 und direkt; Webseiten-Kanal erscheint in keinem Sync, keiner Sperraufgabe, keinem Export und keiner Überwachung (je ein Test über die Scope-Stellen); neue Parameter erben bzw. `0` bleibt `0`; Profil eingefroren.
- Regression: `CaseCoreTest` (Vererbung, wirksame Einstellungen), T12/T24 in `EndToEndAcceptanceTest`, Kanal-, Sync-, Export- und Postfach-Tests vollständig.
**Voraussetzungen:** keine.
### U2 – Informationsbedarf, Gate G2a, Fakteneingang, Neubewertung
**Ziel:**
- Vor einem eigenen Angebot und vor einer verbindlichen Buchungswunschbestätigung (B3) müssen alle Pflichtangaben vorliegen; das gilt nicht übergehbar (E-032, M01). Die Auskunft unter Vorbehalt bleibt mit unvollständigen Angaben möglich.
- Alle Quellen übernehmen Angaben über einen Eingang mit Herkunft, Konflikt und Änderungswunsch (S5, CH-03, E-038).
- Danach folgt genau eine Neubewertung (S6).
**Wiederverwendung:**
- `DocumentComposer`, `DocumentFinding::blocker`, `CaseAutomation::advance`;
- `CreateReservation::guestFor` (Regeln für abweichende Angaben);
- `BookingTask::openOnce`, `CaseLog`.
**Änderungen:**
1. `App\Process\CaseRequirements` (Zielarchitektur §3.2) mit der Feldliste nach B4. Formulare können „Deutschland“ als änderbaren Standard anbieten; ein leeres Land gilt als fehlend.
2. `DocumentComposer::commonFindings`: Blocker aus `CaseRequirements` für das Angebot. `SubmitBookingWish::findings` bzw. `DecideBookingWish`: dieselbe Prüfung vor der verbindlichen Bestätigung (B3); die automatische Bestätigung unterbleibt, die manuelle ist gesperrt. Die Auskunft (`SendInformation`) bleibt ohne Angebots-Gate.
3. `CaseActivities`: „Angaben vervollständigen“ mit Liste; `CaseAutomation::documentBlockers` liest `CaseRequirements`.
4. Tabelle `case_facts`; Aktion `ContributeCaseFacts` mit Feldklassen und Phasenregeln (Zielarchitektur §3.3); neue Aufgabenarten `FactConflict` und `ChangeRequest`.
5. `ProvideGuestContact` auf `ContributeCaseFacts(source: landlord)` umstellen; die doppelte Fortsetzungslogik wird durch `advance` ersetzt, der Moduswechsel bleibt. `CreateReservation::guestFor` schreibt `case_facts(source: website_form)`.
6. Die Dialoge „Kontaktdaten eintragen“ und „Angaben ergänzen“ zeigen die Herkunft der vorhandenen Werte.
**Migrationen:** `case_facts`.
**Risiken und Regressionen:**
- Tests, die Angebote für Gäste ohne Anschrift senden (Webformular-Fälle in `GuidedCaseHandlingTest`, `EndToEndAcceptanceTest`, `BookingRequestPageTest`, `DocumentCompositionTest`), müssen Anschriften liefern. Das ist eine erwartete, fachlich gewollte Änderung.
- Die `ProvideGuestContact`-Umstellung berührt Portalbuchungen (A3/A4: Unterlagen nach Kontaktdaten). Abgesichert durch T04/T05 und `PortalBookingTest`.
**Tests:**
- M01: Webseiten-Anfrage ohne Anschrift. Kein Angebot automatisch, keines von Hand, auch nicht mit Bestätigung; mit Anschrift geht es durch.
- B3:
- Auskunft unter Vorbehalt mit unvollständigen Angaben möglich;
- Buchungswunsch ohne Anschrift → keine automatische Bestätigung, manuelle Bestätigung gesperrt, Aufgabe „Angaben vervollständigen“;
- mit Anschrift → Bestätigung wie bisher.
- B4:
- leeres Land → fehlend;
- vom Gast bestätigter vorbelegter Standard → vorhanden;
- nie stilles Auffüllen der Kartei.
- Fakten:
- leer → übernommen;
- gleich → bestätigt;
- abweichend vom Gast → Konflikt, Kartei unverändert;
- abweichend von der Vermieterin → übernommen mit `previous_value`;
- in P3 Telefon → übernommen, Zeitraum → Änderungswunsch, Buchung unverändert (M06-Kern);
- gemeinsame Kartei mehrerer Vorgänge → Konflikt.
- Idempotenz: zweimal dieselbe Übermittlung → ein Eintrag, eine Neubewertung (M03-Teil).
- Externe Buchung ohne Gastdaten bleibt verbindlich (E-036).
**Voraussetzungen:** keine (B3, B4 entschieden).
### U3 – Klärungsreservierung
**Ziel:** Optionaler Kurzblock für unvollständige unverbindliche Anfragen (E-033, G1a). Die Angebots-Vorreservierung bleibt unverändert.
**Wiederverwendung:** `hold_expires_at`, `Booking::occupying`, `AvailabilityChecker`, iCal-Export, `ExpireReservations`, `AutoOffer`, `SendOffer`.
**Änderungen:**
1. Migration `bookings.hold_purpose` (Standard `offer`).
2. `CreateReservation` und `TakeOverPortalInquiry`: Fallunterscheidung vollständig / V1-qualifiziert / nicht qualifiziert (Zielarchitektur §3.4). Minuten nach `data_request_mode` des Profils; `0` = kein Hold.
3. `ExpireReservations`: nur `offer`-Holds beenden; abgelaufene Klärungsreservierung im Verlauf vermerken, den Vorgang offen lassen.
4. `AutoOffer`: Der Blocker „nicht mehr vorgemerkt“ gilt nur für `offer`-Holds.
5. `Booking::clarificationState()`; Anzeige im Vorgang („Zeitraum zur Klärung vorläufig reserviert bis …“ bzw. „nicht reserviert“).
6. Architekturtest: Außer `CreateReservation`, `TakeOverPortalInquiry`, `SendOffer`, Paket-5-Aktionen und `ReleaseReservation` schreibt niemand `hold_expires_at`.
**Migrationen:** eine Spalte.
**Risiken:**
- Sichtbare Verhaltensänderung für Anfragen ohne Anschrift (B1/B2).
- Kurzblöcke erscheinen im iCal-Export und können in trägen Portalen länger sichtbar sein (in der v0.11 bekannt; Kanalwert `0` möglich).
**Tests:**
- vollständige Anfrage → Hold wie bisher (Regression);
- unvollständige mit Automatik → 15 min, mit Freigabe → 180 min, Kanalwert `0` → kein Hold;
- ohne E-Mail → kein Hold;
- belegter Zeitraum → keine Reservierung (bestehende Ausnahme);
- Ablauf → Vorgang offen, Kalender frei;
- Vervollständigung nach Ablauf → Angebot nur bei freiem Zeitraum;
- Portalbuchung → nie Klärungsreservierung (M12-Teil);
- `SendOffer` setzt `offer` mit unveränderter Frist.
**Voraussetzungen:** U1 (Parameter), U2 (`CaseRequirements`); B1, B2 entschieden.
### U4 – Datenbeschaffung: Rückfrage, Erinnerung, Ergänzungslink
**Ziel:**
- Fehlende Angaben werden nach wirksamem Modus automatisch, nach Freigabe oder manuell beim Gast angefragt (S1, S4, CH-04, CH-15–CH-18).
- Antworten über den Link gehen an den Fakteneingang.
**Wiederverwendung:**
- P7-Linkmuster (`InformationController`, Version, `ensureCurrent`, Transaktion, „bereits erledigt“);
- Mailer mit Testbetriebs-Schranke und `LogBookingMail`;
- `BookingTask`, `TenantRunner`, Scheduler.
**Änderungen:**
1. Tabelle `data_requests`; Aktion `RequestCaseData` (Erstrückfrage, Folgefrage); Befehl `cases:data-requests` (Erinnerungen, Grenzen, Aufgabe „Gast antwortet nicht“).
2. Auslösung: `CaseAutomation`/`CaseActivities` erkennen „Angaben fehlen für die nächste Aktion“ und rufen `RequestCaseData` auf.
- Im Modus `approval` entsteht die Aufgabe „Rückfrage freigeben“ mit Vorschau, Freigabe per Klick.
- Im Modus `manual` gibt es die Aufgabe mit Kopiertext; das bisherige „Gast um Kontaktdaten bitten“ geht darin auf.
3. Mailables `DataRequested`, `DataReminder` mit Textbausteinen je `clarificationState()`, Phase und Eingangsart (M11). Die Betreffkennung des Vorgangs wird für U5 vorbereitet.
4. Ergänzungslink: Routen, Controller, Livewire- oder Blade-Formular im Theme-System (Basistheme), minimale Einsicht (K4), `ContributeCaseFacts(source: guest_link)`, „neuen Link anfordern“.
5. Antwort stoppt die laufende Erinnerung; bleibt etwas offen, folgt eine gezielte Folgefrage; Zähler werden nie zurückgesetzt.
6. Hinweis- und Aktionsfläche im Vorgang: Stand der Rückfrage, Zähler, nächste Erinnerung, „jetzt erinnern“, „Rückfrage beenden“.
**Migrationen:** `data_requests`.
**Risiken:**
- Mailtexte sind rechtlich nicht freigegeben (G1). Bis dahin laufen sie als Arbeitsfassung über die bestehende Dokumentfreigabe-Logik und werden nie automatisch versendet, solange sie nicht freigegeben sind.
- Doppelte Rückfragen bei parallelen Auslösern werden durch eine Sperre und „höchstens eine offene Rückfrage“ verhindert.
**Tests:**
- M02 (Formular, auch teilweise);
- M03 (doppeltes Absenden, Mehrfachaufruf, GET schreibt nicht);
- M08 (Teilantwort → Folgefrage, Zähler ohne Reset, Grenzen → Aufgabe, keine Fristverlängerung);
- M09 (abgelaufener, fremder und veralteter Link, Konflikt mit geändertem Wert);
- M11 (Texte bei `0`, aktiv mit echter Uhrzeit, abgelaufen, fehlgeschlagen; nie eine unbegründete Reservierungsbehauptung);
- Modi `automatic`/`approval`/`manual`;
- ohne E-Mail → Aufgabe;
- Testbetrieb → Versand nur an die Testadresse (M10-Teil);
- Portalbuchung: Rückfrage ohne Klärungs- oder Angebotstexte.
**Voraussetzungen:** U1–U3; Arbeitsfassungen der Texte (G1 erst zum Go-live).
### U5 – Posteingang, Zuordnung, Klärungsansicht
**Ziel:** Ein aktives Postfach je Mandant (Modell für mehrere), alle Mails erfasst, dedupliziert, deterministisch zugeordnet oder zur Klärung gestellt (CH-01, CH-05–CH-08, CH-11–CH-13, M04, M07, M10).
**Wiederverwendung:** `MailboxReader` (webklex), `ProcessPortalMail`, `PortalIntake::caseByReference`, `PortalEmail`-Ansicht, `Inbox`, `Settings`, Testbetriebs-Logik.
**Änderungen:**
1. Tabelle `mailboxes` mit Übernahme von `tenants.mailbox_*`; die Einstellungsseite „System › Betrieb“ bearbeitet künftig das Postfach. Modus `portal_only` als Standard, bis `full` je Mandant bewusst eingeschaltet wird.
2. Tabelle `inbound_messages`; `FetchPortalMail` speichert zuerst und verarbeitet dann. Portal-Absender gehen weiter durch `ProcessPortalMail` (verknüpft über `inbound_message_id`).
3. `booking_messages.message_id` in `LogBookingMail` füllen; Vorgangskennung im Betreff der Rückfragen.
4. `MessageMatcher` (Reihenfolge Zielarchitektur §3.6); eine Antwort an einen Beschaffungsvorgang führt zum Stand „Antwort eingegangen“, Erinnerungen ruhen. Ohne KI (vor U6) entsteht die Aufgabe „Antwort prüfen und Angaben übernehmen“ mit vorbereitetem Dialog.
5. Filament-Ressource „Posteingang“ (Klärungsansicht) mit Absenderhinweisen und den Aktionen Zuordnen, Als Anfrage anlegen, Ignorieren.
6. Kennzeichnung `test_mode`; Anzeige „im Testbetrieb eingegangen“.
**Migrationen:** `mailboxes` (mit Datenübernahme), `inbound_messages`, Spalten an `booking_messages` und `portal_emails`.
**Risiken:**
- Regression des Portal-Schnellwegs. Abgesichert durch den Modus `portal_only` als Standard, die unveränderte Verarbeitung danach und den vollständigen Lauf von `PortalMailTest` und `CaseIntakeTest`.
- IMAP-Laufzeit im Minutentakt: Begrenzung je Lauf, UID-Merkpunkt.
- Datenschutz (G4).
**Tests:**
- M04 (mehrdeutige oder allgemeine Mail → Klärung, kein Vorgang);
- M07 (iCal vor Mail und umgekehrt; späte Mail ergänzt, keine zweite Anlage);
- Antwortbezug über `In-Reply-To`;
- Absender + Wohnung + Zeitraum eindeutig → zugeordnet;
- nur Absender mit genau einem offenen Vorgang, ohne Antwort- oder Vorgangsbezug und ohne passende Wohnungs- und Zeitraummerkmale → **keine** automatische Zuordnung, sondern Klärung mit Hinweis (CH-13);
- zwei offene Vorgänge desselben Gastes → Klärung;
- gleiche Mail zweimal → einmal;
- Testbetrieb gekennzeichnet (M10);
- `portal_only` verhält sich exakt wie heute.
**Voraussetzungen:** U2 (Fakteneingang), U4 (Message-ID, Betreffkennung); G3 für die Probe auf dem Testsystem.
### U6 – KI-Extraktion
**Ziel:** Unstrukturierte Gast- und Portalnachrichten werden zu Kandidaten mit Beleg und Konfidenz. Programmatische Regeln entscheiden über Übernahme, Eskalation oder Klärung (CH-14, E-035, M05, M06).
**Wiederverwendung:** `TenantService` (`ai_guest_mail`, `api_key`), `ServiceUsage`, `TenantFeatures`, `PortalMailParser` als `RuleExtractor`, Fakteneingang.
**Änderungen:**
1. `Extractor`-Schnittstelle, `RuleExtractor`, `LlmExtractor`, `ReviewLlmExtractor`, `LlmClient` (HTTP, konfigurierbarer Anbieter und konfigurierbares Modell).
2. Prompt-Dateien mit Version und Platzhaltern, JSON-Schema, Validierung, einmalige Wiederholung.
3. `RiskAssessment` (Kritikalität aus Feldklasse, Phase und Abweichung; Eskalationsschwelle konfigurierbar; Mindestbedingungen für die Übernahme inkl. wörtlichem Belegabgleich). Widersprüche, Änderungsabsichten in P2/P3 und fehlgeschlagene Plausibilitätsprüfungen lösen **unabhängig von der Modellkonfidenz** die weitere Prüfung aus und werden nie automatisch übernommen. Die endgültigen Schwellen folgen aus der Kalibrierung (G6).
4. Scheduler-Schritt `messages:extract` (begrenzt je Lauf, Zeitlimit); bei Ausfall bleibt `needs_review`.
5. Klärungsansicht zeigt Kandidaten mit Beleg und „übernehmen“/„verwerfen“.
6. `ai:evaluate` mit anonymisiertem Nachrichtensatz; Bericht über Fehlwerte und übersehene Angaben.
**Migrationen:** Spalten bzw. Tabelle für Extraktionsergebnisse an `inbound_messages` (Prompt-Version, Modell, Rohergebnis, Kandidaten).
**Risiken:** Qualität und Kosten (G5, G6); Modelländerungen beim Anbieter, abgefedert durch Prompt-Version und Evaluationslauf; personenbezogene Daten beim Anbieter (G5).
**Tests (ohne Netz, aufgezeichnete Antworten):**
- Schema-Verstoß → Wiederholung, dann Klärung;
- hohe Kritikalität oder niedrige Konfidenz → großes Modell;
- Widerspruch oder fehlgeschlagene Plausibilität bei **hoher** Modellkonfidenz → trotzdem großes Modell und keine automatische Übernahme;
- großes Modell widerspricht → Klärung;
- Beleg nicht im Original → keine Übernahme;
- M06 (Telefon übernommen, Änderungswunsch nur als Aufgabe);
- Ausfall → sicherer Rückfall;
- Schalter aus → keine Aufrufe;
- Verbrauch gezählt.
**Voraussetzungen:** U5; Anbieter-Zugang für das Testsystem; G5/G6 erst zum Go-live.
---
## 5. Testplanung und Regression
**Abnahmefälle M01–M12 → Pakete:**
| M | Paket | Art |
|---|---|---|
| M01 | U2 | Feature-Test und Browserprobe |
| M02 | U4 (Link), U5/U6 (E-Mail) | Feature |
| M03 | U2, U4, U5 | Feature (Idempotenz) |
| M04 | U5 | Feature |
| M05 | U6 | Evaluationslauf mit Fehlerraten |
| M06 | U2, U6 | Feature |
| M07 | U5 | Feature (auf `CaseIntakeTest` aufbauend) |
| M08 | U4 | Feature mit Zeitreise |
| M09 | U4 | Feature (signierte URLs) |
| M10 | U4, U5 | Feature und Probe auf dem Testsystem (echtes SMTP/IMAP) |
| M11 | U3, U4 | Feature (Texte je Zustand) |
| M12 | U1, U3 | Feature |
**Regression nach jedem Paket:**
- volle Testsuite (heute 702 Tests);
- End-to-End-Abnahme T01–T25 der v0.10, insbesondere T03/T04/T05 (Kontaktdaten und Portalbuchungen), T12/T24 (Wirksamkeit), T17 (Buchungswunsch) und T23 (Testbetrieb über SMTP).
**Besonders gefährdete Bestandsfunktionen:**
1. automatisches Angebot für Webseiten-Anfragen (U2/U3);
2. Portal-Schnellweg per Mail (U5);
3. iCal-Sync und Sperraufgaben (U1, Scope-Umstellung);
4. Kontaktübernahme bei Portalbuchungen (U2).
**Abnahme je Paket:**
- Testsuite grün;
- neue Fälle grün;
- Kurzbericht im Stil der bisherigen `UMSETZUNGSERGEBNIS_*.md`;
- Probe auf dem Testsystem im Testbetrieb.
Merge und Auslieferung erfolgen nur nach Freigabe.
## 6. Nicht Teil dieses Plans
Siehe §3.4 sowie die Architekturgrenzen des Auftrags: keine zweite Engine, keine Warteschlange oder Nachrückautomatik, keine Änderung von Angebots-Vorreservierung und Annahmefristen, kein Eingriff in die regelbasierte iCal-Ereignisverarbeitung, keine automatische Änderung geschützter Vertragsdaten.