Files
LarsandClaude Opus 5.5 750c1ed1d9 Architekturplan Review V2: Runner, Modulgrenzen, Versionierung, Kanalereignisse, Sandbox-Anfrage (Planung)
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>
2026-11-04 13:37:45 +01:00

18 KiB
Raw Permalink Blame History

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]

  1. Ablaufliste: CaseActivities::for() baut die Schritte als Folge von if-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_* …).
  2. Automatik: CaseAutomation::step() kennt genau zwei Fälle, nämlich Angebot/Auskunft und Unterlagen.
  3. 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.
  4. Schrittdetails: ActivityDetails::EVENT_TYPES ist eine zweite, parallel gepflegte Liste.
  5. Aktionen der Oberfläche: ViewBooking bildet Aktionsnamen auf Schritte ab.

2.4 Vorhandene Konfiguration [Befund]

  • Die Hierarchie in ProcessSettings::resolve lautet: 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 friert offer_terms beim 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.profile und channels.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]

  1. CaseActivities und CaseAutomation werden 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.
  2. Ein Erweiterungspunkt im Preisweg: Die Fassade CasePricing ruft PriceCalculator unverändert und ergänzt Preisbeiträge aktiver Module. Ihre Aufrufer werden umgestellt.
  3. Kanalereignisse als zusätzlicher Eingang für künftige Adapter. Sie werden auf den vorhandenen Eingang abgebildet; iCal und Mail bleiben (02 §8.4).
  4. Prozess-Tester in einer eigenen Sandbox-Anfrage, in der nur Sandbox-Speicher und simulierte Effekte konfiguriert sind (04 §3).
  5. 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)

  1. 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::for verschwindet.
    • Die Grenze: Actions bleiben gemeinsame Bausteine. Ein Modul kapselt ihre Komposition, nicht ihren Code. Deshalb sichern R1–R6 die gemeinsamen Actions zusätzlich.
  2. 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.
  3. 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.
  4. 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).

  5. 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.

  6. 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.

  7. 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).

  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.