Korrekturen K1-K10 in die Dokumente 00-06 eingearbeitet: abhaengigkeitsbasierter ProcessRunner mit Nachweisszenario, Kriterien fuer Modulgrenzen, vier Versionierungsebenen mit Bestandsfall-Tests, Stufen M1-M4 und Ereignisvertraege, Prozess-Tester in eigener Sandbox-Anfrage mit Negativtests, Verantwortungsmatrix A1-A6, Deploymentweg ueber develop/stommer.info, Loyalty nur im Tester, Verhaltensvergleich in acht Dimensionen, Kanalereignisse als Ergaenzung. E1-E9 als entschieden gekennzeichnet; offen nur O1-O5. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
18 KiB
01 – Architekturbewertung: kontrolliert modulare Prozessarchitektur
Stand: 04.11.2026, Review V2 · Grundlage: Branch feature/aufenthalt (86f2d0a; Anwendungscode = develop 7e4e208), Prozessarchitektur v0.11, Vorschlag Vorschläge/KANALKONFIGURATOR.md
Status: Planung, nach Review V2 implementierungsreif – keine Codeänderung, keine Migration, keine Änderung an Buchungen oder Kanälen.
Review V2: Die Variante V2 ist vom Betreiber angenommen. Die Korrekturen K1–K10 sind eingearbeitet:
| Korrektur | Ort |
|---|---|
| K1 Runner mit unabhängigen und wartenden Schritten | 02 §7 |
| K2 Kriterien für Modulgrenzen | 02 §2 |
| K3 vier Versionierungsebenen, Bestandsfall-Tests | 02 §5.3–5.4, 05 §4.5 |
| K4 Meldung ≠ Geschäftshandlung, Ereignisverträge | 02 §8.2–8.3 |
| K5 eigene Sandbox-Anfrage, standardmäßig gesperrt | 04 §3 |
| K6 Verantwortungsmatrix | 03 §2.3 |
| K7 Deploymentweg | 06 §3 (U-0, U-F) |
| K8 Loyalty nur im Tester | 02 §6 |
| K9 Verhaltensvergleich in acht Dimensionen | 05 §4 |
| K10 Ereignisse als Ergänzung | 02 §8.4 |
Aussagen des ersten Entwurfs, die nicht trugen, sind in §2.8 benannt.
Kennzeichnung in allen Dokumenten dieser Reihe:
- [Befund] – im Code oder in Tests nachgewiesen (mit Klasse/Methode)
- [Vorschlag] – begründete Architekturempfehlung
- [Entschieden] – vom Betreiber festgelegt (gesammelt in
06§9.1) - [Entscheidung offen] – vor dem genannten Paket zu treffen (
06§9.2, O1–O5)
1. Bestand in Zahlen [Befund]
| Bereich | Umfang |
|---|---|
Actions (app/Actions) |
56 Klassen, 35 davon mit DB::transaction |
Ablaufsteuerung (app/Process) |
13 Klassen. Davon CaseActivities 459 Zeilen, CaseAutomation 75, ProcessSettings 120, ProcessProfile 213 |
| Einstellungen | ProcessSetting: 16 Werte (8 seit v0.10, 8 seit v0.11) |
| Kanalanbindung | ChannelConnector (nur iCal-Import), PortalIntake (489 Zeilen), ProcessPortalMail, MailboxReader |
| Tests | 683 Feature-Testmethoden; die PHPUnit-Suite läuft vollständig auf SQLite in-memory (phpunit.xml) |
| Zeitgesteuert | 15 Scheduler-Einträge (routes/console.php), angestoßen von n8n jede Minute über HTTP (ChannelController, Artisan::call('schedule:run')) |
2. Soll-Ist-Abgleich
2.1 Bereits sauber gekapselte Fähigkeiten [Befund]
Jede Action prüft ihre Voraussetzungen selbst, arbeitet transaktional und protokolliert über CaseLog::record.
| Fähigkeit | Kapselung | Bewertung |
|---|---|---|
| Preis berechnen | PriceCalculator::calculate(Property, StayRequest) → unveränderliches PriceQuote mit QuoteLines |
sehr gut; seiteneffektfrei, stark getestet |
| Verfügbarkeit | AvailabilityChecker::isAvailable, CalendarClearance::reasons/refresh |
gut; einzige Stelle für Kalenderwahrheit |
| Verbindliches Angebot | SendOffer::handle (versioniert, quoteFor), deliver |
gut; Preisfestlegung an einer Stelle |
| Annahme / Ablehnung | AcceptOffer, RejectOffer (Versionsprüfung) |
gut |
| Verbindlichkeit | ConfirmBooking, TakeOverExternalBooking |
gut |
| Fakten und Herkunft | ContributeCaseFacts → case_facts (Quelle, Beleg, Sicherheit, Konflikt) |
sehr gut; ein Eingang für alle Quellen |
| Datenbeschaffung | RequestCaseData + data_requests + GuestDataController |
gut |
| Halten | RequestHold (Zweck offer/clarification), ExpireReservations, ReleaseReservation |
gut |
| Dokumente | DocumentComposer, SendBookingDocuments, RentalContract |
gut |
| Portalbeträge | RecordPortalAmounts, CaseMoney |
gut |
| Nachrichteneingang | ReceiveInboundMessage, MessageMatcher, ExtractMessageFacts, LlmClient (BYOK) |
gut; KI liefert nur Vorschläge |
| Mail-Schranke | EnforceMailTestMode; MailTestModeGateTest |
sehr gut; zentraler Effektpunkt |
| Nachweis | CaseLog, CaseRecorder, BookingEvent |
gut |
Folgerung: Die Fachmodule existieren inhaltlich schon. Es fehlt eine Beschreibung und Komposition dieser Logik.
2.2 Über mehrere Komponenten verteilte Geschäftsregeln [Befund]
| Regel | Fundstellen |
|---|---|
| „Wer liefert die Dokumente?“ | CaseActivities, CaseAutomation, ViewBooking, BookingInfolist, DocumentKind |
| „Wer kassiert?“ | CaseActivities, CancelBooking, DocumentComposer, PaymentsRelationManager, Booking::needsPaymentMonitoring |
| „Wer schreibt dem Gast?“ | CaseActivities, RequestReviews, SendBookingReminders |
Anfrage oder Buchung (IntakeKind::Booking) |
14 Dateien |
Vorreservierung ja/nein (preReservation()) |
15 Dateien |
Interne Belegung (isInternal()) |
11 Dateien |
| Pflichtangaben je Schritt | CaseRequirements (zentral), ausgewertet in CaseActivities, AutoOffer::blockers, RequestCaseData |
2.3 Fest verdrahtete Prozesse und Archetypen [Befund]
- Ablaufliste:
CaseActivities::for()baut die Schritte als Folge vonif-Blöcken. Reihenfolge, Bedingung, Zustand und Aktion stehen inline. Die Schlüssel sind Zeichenketten (intake,contact,information,wish,offer,acceptance,binding,documents,payment,payout,arrival_info,stay,review,closure,settlement,task_*…). - Automatik:
CaseAutomation::step()kennt genau zwei Fälle, nämlich Angebot/Auskunft und Unterlagen. - Archetyp:
ProcessProfile::caseTypeFor()leitet A1–A6 aus Eingangsart, „über Kanal“ und zwei Verantwortungen ab:Documents = Portal→ A5,Payments = Portal→ A4, sonst A3. Der Archetyp steuert nichts. - Schrittdetails:
ActivityDetails::EVENT_TYPESist eine zweite, parallel gepflegte Liste. - Aktionen der Oberfläche:
ViewBookingbildet Aktionsnamen auf Schritte ab.
2.4 Vorhandene Konfiguration [Befund]
- Die Hierarchie in
ProcessSettings::resolvelautet: System → Vermieter → Wohnung → Kanal × Eingangsart bzw. Webseite. - Nicht gesetzte Werte erben; ein bewusst gesetztes
0/„nein“/„manuell“ bleibt erhalten. Jeder Wert trägt seine Herkunft. - Eingefroren wird beim Eingang (
CaseRecorder::freeze→bookings.profile). Ausnahme:ProcessProfile::LIVE = [ContractTemplate]; die tatsächliche Vorlagenversion friertoffer_termsbeim Angebot ein. - Oberflächen:
HandlingSettings,PropertyForm,ChannelForm/EditChannel,EffectiveSettings.
Ebene C ist damit zur Hälfte vorhanden. Es fehlen die Wahl eines Ablaufs und die Darstellung entlang der Schritte.
2.5 Spezifizierte, nicht umgesetzte Freiheitsgrade [Befund]
| Freiheitsgrad | Stand |
|---|---|
| Ablaufmodell je Kanal × Eingangsart | fehlt; implizit aus booking_model und Verantwortungen |
| Optionale Schritte | nur über Einzelwerte; Bewertungsbitte hängt an guestMessages() |
| Ausführungsart je Schritt | nur global Processing sowie DataRequest |
| Ausführende je Schritt im Rahmen des Archetyps | nur über GuestMessages, Documents, Payments als Kanalwerte, ohne Schrittbezug |
| Nachweisstufe für übertragene Schritte | fehlt (Muster vorhanden: ChannelTaskProof) |
| Vorschau | fehlt |
| Erweiterungspunkte | fehlen |
| Prozess durchspielen ohne Auswirkungen | fehlt |
2.6 Weiterverwendbar [Befund → Vorschlag]
In ihrer Fachlogik bleiben erhalten:
- die Actions aus 2.1,
PriceCalculator,CaseRequirements,ContributeCaseFacts; CaseLog/CaseRecorder,ProcessSettings,ProcessProfile;EnforceMailTestMode;PortalIntake(Entscheidungsregeln),SyncChannel,ProcessPortalMail, Connectors und Parser;- die JSON-Spalten
bookings.profileundchannels.process_overrides(ohne Migration); - die Testsuite.
Nicht unverändert bleiben die Aufrufstellen, über die Ablauf und Preis gesteuert werden. Sie sind vollständig in 06 §1 aufgeführt.
2.7 Notwendige Architekturänderungen [Vorschlag]
CaseActivitiesundCaseAutomationwerden zu einer Ablaufsteuerung über Module.- Was laufen darf, folgt aus fachlichen Abhängigkeiten, nicht aus der Position (
02§7). - Die verteilten direkten Automatik-Aufrufe gehen über
ProcessRunner::advance.
- Was laufen darf, folgt aus fachlichen Abhängigkeiten, nicht aus der Position (
- Ein Erweiterungspunkt im Preisweg: Die Fassade
CasePricingruftPriceCalculatorunverändert und ergänzt Preisbeiträge aktiver Module. Ihre Aufrufer werden umgestellt. - Kanalereignisse als zusätzlicher Eingang für künftige Adapter. Sie werden auf den vorhandenen Eingang abgebildet; iCal und Mail bleiben (
02§8.4). - Prozess-Tester in einer eigenen Sandbox-Anfrage, in der nur Sandbox-Speicher und simulierte Effekte konfiguriert sind (
04§3). - Kanalkonfigurator am Schritt mit Verantwortungsmatrix, gespeichert in den bestehenden JSON-Spalten (
03).
2.8 Ergänzende Befunde (Review V2) und korrigierte Aussagen
Neue Befunde:
| Thema | Befund | Folge |
|---|---|---|
| Automatik ist verteilt | CaseAutomation::advance wird von 5 Stellen gerufen, kennt aber nur 2 Fälle. CreateReservation, SubmitBookingWish und TakeOverExternalBooking rufen AutoOffer/RequestCaseData::forNextStep direkt. Zeitgesteuert laufen bookings:auto-offers, cases:data-requests und bookings:expire-holds (ohne advance). |
Runner übernimmt diese Auslöser ohne neuen Scheduler (02 §7.4) |
| Klärungsreservierung | Gesetzt wird sie von RequestHold::for im Eingang unter Kalendersperre. ExpireReservations lässt Klärungsfälle offen. AutoOffer akzeptiert eine abgelaufene Klärungsreservierung und prüft nur den freien Zeitraum. |
Szenario K1 ist fachlich heute schon angelegt; der Runner darf es nicht verhindern |
| Eingefrorene Vertragsdaten | Eingefroren sind quote, total, offer_terms (inkl. Stornoregel), acceptance.terms_sha256, Fälligkeiten und contract_path. Ausgewertet werden sie durch veränderlichen Code: CancellationCost (zählt Discount-Zeilen zur Stornogrundlage), CancellationPolicy::tierFor, ContractPlaceholders. |
Regel R1 und Bestandsfall-Tests (02 §5.3–5.4) |
| Portalmeldungen | PortalIntake storniert, ändert oder gibt nie frei (E-019). Stornomails heben nur die Mail-Sperre auf. Portalzahlungen sind GuestViaPortal. Die Mail-Zuordnung erfolgt nur über die Absenderdomain, also ohne Authentifizierung. |
Stufen M1–M4 und Ereignisverträge (02 §8) |
| Seiteneffektwege | Datenbank (Eloquent/Query Builder; getPdo nur in BackupDatabase), Mail (53 Dateien), Http (KI, iCal, n8n-Webhook in CreateChannelTasks), IMAP (MailboxReader), Storage (5), Cache (10, u. a. Cache::lock, rememberForever), Sessions (database), encrypted-Casts, signierte Links (16), statische Zwischenspeicher, 18 rescue(). Keine Queue-Jobs, kein exec, kein Octane. |
Tester „standardmäßig gesperrt“ (04 §3) |
| Deployment | Push auf develop → automatisches Deployment staging (stommer.info); main → production. Ein freizugebendes Produktivsystem gibt es derzeit nicht. |
Umsetzungsweg K7 (06 U-F) |
Korrigierte Aussagen des ersten Entwurfs:
| Erster Entwurf | Korrektur |
|---|---|
| „Alle 56 Actions unverändert“ | Fachlogik unverändert; Aufrufstellen in mehreren Actions werden geändert (06 §1) |
| Runner führt „den ersten offenen automatischen Schritt“ aus | abhängigkeitsbasierte Bereitschaft; unabhängige Schritte laufen (02 §7) |
| Eingefrorener Plan schützt laufende Vorgänge | Er schützt die Definition. Vertragsdaten und ihre Auswertung brauchen R1–R6 und eigene Tests. |
Provenance.trust = Nachweisstufe |
verworfen: Quelle ≠ Nachweis (02 §8.2) |
| Jede Schutzschicht verhindert für sich jeden Schaden | zurückgenommen; eigene Sandbox-Anfrage, benannte Grenze für native PHP-Aufrufe (04 §3.5) |
PortalIntake auf Ereignisse umbauen |
nicht nötig; Ergänzung reicht (02 §8.4) |
| 22 Module als Ergebnis | Startkatalog, Zahl folgt aus Kriterien (02 §2) |
| Loyalty produktiv wählbar | nur im Tester (E7) |
Merge nach develop und main nach der Abnahme |
Merge nach develop → Deployment auf stommer.info → Abnahme; kein main (06 U-F) |
| Aufbewahrung Testberichte 90 Tage | über das Löschkonzept, Wert offen (O3) |
3. Vergleich realistischer Architekturvarianten
| V0 Status quo + mehr Einzeleinstellungen | V1 Beschreibungsschicht über bestehender Logik | V2 Modulkatalog + Prozessmodelle im Code (angenommen) | V3 Workflow-Engine / Zustandsmaschinen-Paket | |
|---|---|---|---|---|
| Idee | weitere ProcessSettings, CaseActivities erweitern |
Schrittbeschreibungen für Konfigurator und Vorschau; Logik bleibt verdrahtet | Fachmodule mit Vertrag, Modelle als versionierte PHP-Definitionen, Runner über eingefrorenen Plan | z. B. symfony/workflow oder eigene Engine mit Zuständen in der DB |
| Loyalty-Nachweis (N3) | if an mehreren Stellen |
Beschreibung und Code an mehreren Stellen | 2 Module + 1 Variante + Tests (nach einmaliger Preisfassade) | Modell in Engine + Adapter |
| Konfigurator | Feldsammlung | Beschreibung kann von Wirklichkeit abweichen | liest dieselbe Definition, nach der ausgeführt wird | möglich |
| Tester mit gleicher Logik | nein | nur Vorschau | Durchlauf über dieselben Module und Actions | zweite Steuerlogik |
| Neue Abhängigkeit | nein | nein | nein | ja |
| Risiko für laufende Vorgänge | gering | gering | mittel; beherrschbar durch Verhaltensvergleich und Bestandsfall-Tests | hoch |
| Erfüllt Auftrag | nein | nein | ja | nein |
Was V2 bewusst nicht ist
- Kein Vermieter-Designer; Modelle und Varianten entstehen nur im Code.
- Keine Bedingungen durch Endanwender – nur deklarierte Parameter, Ausführende und optionale Schritte.
- Keine Modelle in der Datenbank; dort liegen nur Auswahl und Parameter.
- Kein dynamisches Laden (fester Katalog
config/process.php). - Keine BPMN- oder Workflow-Engine: Der Runner berechnet Bereitschaft aus abgeleiteten Zuständen und Abhängigkeiten und speichert keinen Schrittzustand.
4. Risiken
| Risiko | Wirkung | Gegenmaßnahme |
|---|---|---|
| Umbau von Ablauf und Auslösern ändert Verhalten unbemerkt | falsche Schritte, Automatik oder Mails | Verhaltensvergleich in acht Dimensionen, Fehlerregister (05 §4) |
| Gemeinsame Action ändert laufende Vorgänge | andere Stornokosten, Fristen, Preise | R1–R6, OngoingCaseRegressionTest (02 §5.3–5.4) |
| Laufende Vorgänge ohne Modellangabe | Ablauf ändert sich mitten im Vorgang | Legacy-Abbildung auf Modell v1 (06 §4) |
| Tester greift auf echte Daten oder Dienste zu | Schaden an Buchungen, Mails, Portalen | Sandbox-Anfrage ohne echte Konfiguration, Aufzeichnung vor Abbruch, Negativtests (04 §3, §7) |
| SQLite auf dem Server nicht verfügbar | Tester ohne getrennte Datenhaltung | U-0 prüft V1; MariaDB nur mit getrenntem Benutzer (V6), sonst kein Tester auf diesem Server |
| Modulvertrag verspricht mehr als geprüft | Scheinsicherheit | jedes Feld mit Prüfung oder als „beschreibend“ gekennzeichnet (02 §3.2) |
| Zu feine oder zu grobe Module | Konfigurator unübersichtlich bzw. starr | Kriterien statt Sollzahl (02 §2) |
5. Abschließender Architekturcheck (Review V2)
-
Ist die Modularität echt oder nur eine neue Beschreibungsschicht? Echt, mit einer benannten Grenze.
- Konfigurator, Vorschau, Tester und Vorgang lesen dieselbe Definition, nach der der Runner ausführt. Die verdrahtete Methode
CaseActivities::forverschwindet. - Die Grenze: Actions bleiben gemeinsame Bausteine. Ein Modul kapselt ihre Komposition, nicht ihren Code. Deshalb sichern R1–R6 die gemeinsamen Actions zusätzlich.
- Konfigurator, Vorschau, Tester und Vorgang lesen dieselbe Definition, nach der der Runner ausführt. Die verdrahtete Methode
-
Ist die Steuerung bei Wartezuständen und unabhängigen Aktivitäten korrekt? Ja.
- Bereitschaft folgt aus
requires, Zustände bleiben abgeleitet, es gibt keine zweite Wahrheit. - Das Szenario K1 ist Schritt für Schritt belegt (
02§7.6) und als Test vorgesehen. - Grenze: Unabhängigkeit heißt fachliche, nicht technische Parallelität. Bereite Schritte laufen nacheinander in einer Bewertungsrunde; das genügt für diese Vorgänge.
- Bereitschaft folgt aus
-
Bleibt die Konfiguration flexibel genug? Ja.
- Das Modell legt nur die bestimmenden Verantwortungen fest.
- Ausführende, Ausführungsart, Fristen, Schalter und Nachweis werden am Schritt eingestellt (
03§2.3, §3). - Offen ist nur O1.
-
Können neue Fachmodule ohne Eingriff in unabhängige Modelle ergänzt werden? Ja, wenn ein vorhandener Erweiterungspunkt passt. Belegt ist das mit zwei Prüffällen (Loyalty, Adressprüfung). Ein neuer Punkt ist eine bewusste Architekturänderung (Stufe 4).
-
Sind bestehende Buchungen, Preise und Verpflichtungen geschützt? Ja, über vier Ebenen:
- eingefrorene Vertragsdaten;
- stabile Auswertung (R1);
- eingefrorene Prozessdefinition (E3);
- Bestandsfall-Tests in jeder CI.
Kanalereignisse ändern verbindliche Vorgänge nie selbst (M4). Grenze: Gegen Fehler in einer Action, die Vertragsdaten schreibt, schützt nur die Testabdeckung.
-
Ist der Prozess-Tester auch bei Fehlern sicher? Für alle Wege über Laravel-Fassaden ja: Die Sandbox-Anfrage kennt Betriebsdatenbank und echte Dienste nicht, Verstöße werden vor dem Abbruch aufgezeichnet, und es gibt keinen Zustand wiederherzustellen. Native PHP-Aufrufe sind nicht zur Laufzeit abfangbar, sondern durch einen statischen Test ausgeschlossen (
04§3.5). Diese Grenze ist dokumentiert. -
Sind neue Portal-APIs mit begrenztem Aufwand möglich? Ja. Ein Adapter liefert Ereignisse, die auf den vorhandenen Eingang abgebildet werden; Duplikat- und Sicherheitsregeln bleiben eine Implementierung (
02§8). -
Ist die zusätzliche Komplexität gerechtfertigt? Ja, aus drei Gründen:
- Konfigurator, Tester und Erweiterbarkeit brauchen dieselbe Grundlage.
- Gegenüber dem ersten Entwurf wurde Komplexität entfernt: kein Umbau des Kanaleingangs, keine produktive Loyalty, kein Umschalten in der Admin-Anfrage.
- Hinzugekommen ist nur, was die Sicherheit trägt: Bestandsfall-Tests, Negativtests, Sandbox-Anfrage.
Aufwand: 34–45 statt 32–41 Entwicklertage.