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>
22 KiB
22 KiB
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, Konfiguration und Wirksamkeit, Entscheidungen E-032 bis E-038) · Status: Analyse, keine Implementierung.
Weitere Dokumente: Technische Zielarchitektur · Umsetzungsplan
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 (ProcessSettingsundProcessProfile), 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 | 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 | 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 Z. 65, TakeOverExternalBooking Z. 99, TakeOverPortalInquiry Z. 59, ViewBooking Moduswechsel), CreateReservation ruft AutoOffer direkt. ProvideGuestContact 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, BookingTask | 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 (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 | 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 | 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 | Blocker u. a. „nicht mehr vorgemerkt“, wenn der Hold abgelaufen ist (Z. 56–57). | Anzupassen für Anfragen nach abgelaufener Klärungsreservierung. |
| ExpireReservations | 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 | 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 (Z. 310) und AvailabilityChecker | Halte-Status mit hold_expires_at > now belegen den Kalender und gehen in den iCal-Export (ICalFeed Z. 27). Holds erzeugen keine manuellen Portalaufgaben (BookingObserver nur occupying()-Status). |
Mechanik für die Klärungsreservierung wiederverwendbar; es fehlt nur die Unterscheidung des Zwecks. |
| Paket 7 (SendInformation, SubmitBookingWish, InformationController) | 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 | 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 | Überschreibt Kartenwerte ohne Abgleich und Herkunft (Z. 51). | Konflikt K2 mit CH-03 („nicht blind überschreiben“). |
| „Gast um Kontaktdaten bitten“ (ViewBooking 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 leitet im Testbetrieb alles an die Testadresse; LogBookingMail schreibt BookingMessage (nur Betreff und Empfängerkreis, keine Message-ID). |
Wiederverwendbar; für die Antwortzuordnung fehlt die Message-ID. |
| MailboxReader | 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 Z. 124), also nur ein Postfach. |
Allgemeiner Eingang (CH-01, CH-06) fehlt; Datenmodell für mehrere Postfächer (CH-05) fehlt. |
| ProcessPortalMail | 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 | Liefert Typ (Buchung, Storno, Anfrage, unbekannt), Termine und Referenz (Z. 36–57); keine Gastdaten, keine Änderung. | Bleibt; Gastdaten künftig über die Extraktion. |
| PortalIntake | 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, ICalConnector, Regeln, Export) | Eigenständig, fünf Minuten, Regeln je Kanal. | Bleibt unverändert (Grenze 4). |
2.5 Konfiguration
| Komponente | Ist | Bewertung |
|---|---|---|
| ProcessSetting | Acht Einstellungen mit Standard, Frage, erlaubten Eingangsarten je Kanal und Normalisierung. | Erweiterbar um die v0.11-Parameter, ohne neues Konfigurationsmodell. |
| ProcessSettings | 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 | A1 oder A2 je nachdem, ob es einen Kanal gibt (Z. 53). | Konflikt K3, wenn die Webseite ein Kanal-Datensatz wird. |
| Channel | 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) für Mandantenstandards; Portale (ChannelForm Z. 133–144) nur in der Expertenansicht; Wohnungsabweichungen; EffectiveSettings 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). Laravel-HTTP-Client vorhanden. | Neu. Ohne neue Abhängigkeit über den HTTP-Client möglich. |
| TenantServiceKey | Dienst ai_guest_mail („KI: Gästekommunikation“) ist vorgesehen, aber isWired() = false; Schlüssel je Mandant in TenantService (api_key), Verbrauch in ServiceUsage. |
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 Z. 98, TakeOverPortalInquiry 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 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 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 | 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 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.