From 86f2d0aa07df203c1c74a815fba1e40f84765f59 Mon Sep 17 00:00:00 2001 From: Lars Date: Wed, 4 Nov 2026 09:59:14 +0100 Subject: [PATCH] Architekturplan: kontrolliert modulare Prozessarchitektur, Kanalkonfigurator, Prozess-Tester (Planung) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Bewertung, Fachmodulkatalog mit Verträgen, Prozessmodelle und Erweiterungspunkte (Loyalty-Nachweis), Kanalkonfigurator, isolierter Prozess-Tester, Änderungsanalyse, Migrations- und Umsetzungsplan sowie Management-Zusammenfassung. Keine Codeänderung. Co-Authored-By: Claude Opus 5.5 --- .../00_MANAGEMENT_ZUSAMMENFASSUNG.md | 79 ++++ .../Architektur/01_ARCHITEKTURBEWERTUNG.md | 159 ++++++++ .../Architektur/02_FACHMODUL_ARCHITEKTUR.md | 370 ++++++++++++++++++ .../Architektur/03_KANALKONFIGURATOR.md | 173 ++++++++ .../Architektur/04_PROZESS_TESTER.md | 206 ++++++++++ .../05_AENDERUNGSANALYSE_UND_TESTS.md | 119 ++++++ .../06_MIGRATIONS_UND_UMSETZUNGSPLAN.md | 220 +++++++++++ docs/Prozessarchitektur/README.md | 1 + .../Vorschläge/KANALKONFIGURATOR.md | 2 + docs/STATUS.md | 1 + 10 files changed, 1330 insertions(+) create mode 100644 docs/Prozessarchitektur/Architektur/00_MANAGEMENT_ZUSAMMENFASSUNG.md create mode 100644 docs/Prozessarchitektur/Architektur/01_ARCHITEKTURBEWERTUNG.md create mode 100644 docs/Prozessarchitektur/Architektur/02_FACHMODUL_ARCHITEKTUR.md create mode 100644 docs/Prozessarchitektur/Architektur/03_KANALKONFIGURATOR.md create mode 100644 docs/Prozessarchitektur/Architektur/04_PROZESS_TESTER.md create mode 100644 docs/Prozessarchitektur/Architektur/05_AENDERUNGSANALYSE_UND_TESTS.md create mode 100644 docs/Prozessarchitektur/Architektur/06_MIGRATIONS_UND_UMSETZUNGSPLAN.md diff --git a/docs/Prozessarchitektur/Architektur/00_MANAGEMENT_ZUSAMMENFASSUNG.md b/docs/Prozessarchitektur/Architektur/00_MANAGEMENT_ZUSAMMENFASSUNG.md new file mode 100644 index 0000000..c0fa5f5 --- /dev/null +++ b/docs/Prozessarchitektur/Architektur/00_MANAGEMENT_ZUSAMMENFASSUNG.md @@ -0,0 +1,79 @@ +# Management-Zusammenfassung: Kontrolliert modulare Prozessarchitektur + +Stand: 04.11.2026 · Analyse- und Planungsergebnis. Es wurden kein Code, keine Migration und keine Buchung oder Kanalkonfiguration geändert. + +Dokumente: + +1. [01 Architekturbewertung](01_ARCHITEKTURBEWERTUNG.md) +2. [02 Fachmodul-Architektur](02_FACHMODUL_ARCHITEKTUR.md) +3. [03 Kanalkonfigurator](03_KANALKONFIGURATOR.md) +4. [04 Prozess-Tester](04_PROZESS_TESTER.md) +5. [05 Änderungsanalyse und Tests](05_AENDERUNGSANALYSE_UND_TESTS.md) +6. [06 Migrations- und Umsetzungsplan](06_MIGRATIONS_UND_UMSETZUNGSPLAN.md) + +Kennzeichnung: **[Befund]** (im Code nachgewiesen), **[Vorschlag]**, **[Entscheidung offen]**. + +--- + +## Empfohlener Ansatz [Vorschlag] + +Empfohlen wird ein **Modulkatalog mit Prozessmodellen im Code**. Es gibt keine Workflow-Engine und keine Modellpflege in der Datenbank. + +- Rund **20 Fachmodule** entlang P01–P05. Jedes Modul hat einen Vertrag: Aufgabe, Daten, Ergebnisse, Voraussetzungen, Seiteneffekte, Parameter, Abschaltbarkeit und Tests. Die Module rufen die **bestehenden Actions** auf. +- **Versionierte Prozessmodelle** (`a1.offer`, `a2.information`, `a4.portal_booking` …) mit festen **Erweiterungspunkten**. Varianten entstehen durch Einfügen vorhandener Module. Die Archetypen A1–A6 bleiben reine Klassifikation. +- **Kanalkonfigurator:** Je Kanal und Eingangsart wählt der Vermieter ein zulässiges Modell. Er stellt die Schritte direkt am Schritt ein und sieht sofort eine Vorschau. Gespeichert wird in den **bestehenden JSON-Spalten**. Laufende Vorgänge behalten ihren eingefrorenen Plan. +- **Prozess-Tester „Ablauf testen“:** Er nutzt dieselben Module und Actions. Isoliert wird durch einen eigenen synthetischen Datenspeicher (SQLite-Datei je Lauf), einen Schreibwächter auf der echten Datenbank, simulierte Mail/HTTP/Dateien/Connectors und eine simulierte Uhr. Ein Rollback allein reicht nicht. +- **Kanalereignisse** (`IncomingBooking`, `PaymentReported` …) trennen iCal, Mail und künftige APIs vom Fachprozess. + +Einfachere Ansätze wurden geprüft und verworfen, siehe `01` §3. Zusätzliche Einstellungen allein oder eine Beschreibungsschicht über unverändertem Code erfüllen Konfigurator und Tester nicht. Konfigurator und Vorschau würden dann einen anderen Ablauf zeigen als den ausgeführten. + +## Was erhalten bleibt [Befund] + +Unverändert bleiben: + +- alle 56 Actions; +- `PriceCalculator` und `PriceQuote`; +- die Faktenaufnahme mit Herkunft (`ContributeCaseFacts`); +- Datenbeschaffung, Nachrichteneingang und KI-Auswertung (BYOK); +- die Mail-Schranke (`EnforceMailTestMode`); +- die Vererbung der Einstellungen samt Herkunft und Einfrieren (`ProcessSettings`, `ProcessProfile`); +- Connectors und Parser; +- die Datenmodelle; +- die gesamte Testsuite (683 Feature-Tests) als Regressionsnetz. + +## Was sich tatsächlich ändert [Vorschlag] + +1. `CaseActivities::for` und `CaseAutomation::step` sind heute fest verdrahtet [Befund]. Sie werden zu **einem Ablaufkern über Module**. Die öffentlichen Methoden bleiben, damit Oberfläche und Kommandos stabil bleiben. Abgesichert wird das per Golden-Master-Vergleich über etwa 150 Fallkonstellationen. +2. Ein **Preis-Erweiterungspunkt** (`CasePricing`) vor der Preisfestlegung. Er ist die einzige Änderung im Preisweg. +3. `PortalIntake` nimmt **Ereignisse** statt `BlockedPeriod` an. +4. Neu hinzu kommen der Konfigurator, der Tester und die Analysebefehle `process:impact` und `process:check`. +5. Datenmodell: **eine** neue Tabelle für Testberichte. Alles andere passt in bestehende JSON-Spalten. + +**Loyalty-Nachweis:** Nötig sind zwei neue Module, eine Variante von `a1.offer`, ein Registereintrag und Tests. A2–A6, `PriceCalculator`, `SendOffer`, Dokumente, Konfigurator und Tester bleiben unverändert (`02` §6.2). + +## Aufwand (Schätzung) + +Geschätzt sind **32–41 Entwicklertage** einschließlich Tests und Abnahme. Hinzu kommen 1–2 Tage Betreiberzeit. Die größte Unsicherheit liegt im Umbau des Ablaufkerns (U-A). + +Es gibt eine **gemeinsame Betreiberfreigabe** nach der Ende-zu-Ende-Abnahme auf stommer.info. Konfigurator und schadensfreier Tester werden zusammen abgenommen. + +## Wichtigste technische Risiken + +1. **Unbemerkte Verhaltensänderung beim Umbau.** Gegenmaßnahmen: Golden Master, unveränderte Bestandstests, Abnahme je Kanal. +2. **`pdo_sqlite` auf Strato ungeklärt.** Das ist vor Beginn zu prüfen. Andernfalls dient eine eigene MariaDB-Datenbank als Sandbox. +3. **Leck im Tester durch einen künftigen neuen Effektweg.** Gegenmaßnahmen: Schreibwächter, Sperre fremder HTTP-Aufrufe, generischer Modul-Vertragstest. +4. **Laufzeit des Testers auf Shared Hosting.** Gegenmaßnahmen: vorbereitete Sandbox-Vorlage, Laufzeitgrenzen, schrittweise Läufe. + +## Vor der Implementierung zu entscheiden [Entscheidung offen] + +| # | Frage | Empfehlung | +|---|---|---| +| E1 | Legt das gewählte Modell die Verantwortungen (Dokumente/Zahlungen) fest? | ja | +| E2 | Zulässige Modelle je Portal | FeWo-direkt: Anfrage A2, Buchung A4/A5; Destination Solutions: A3 – bitte bestätigen | +| E3 | Kanaländerung in laufende Vorgänge übernehmen? | nein | +| E4 | Sandbox: SQLite oder eigene MariaDB-Datenbank | SQLite, falls verfügbar | +| E5–E7 | Loyalty: Verhalten bei Änderung, Kombination mit Sonderangeboten, produktiv wählbar? | übernehmen statt neu rechnen; nicht kombinierbar; wählbar, Vorgabe aus | +| E8–E9 | Testerberechtigung, Aufbewahrung, Szenario-Freiheit | Administratoren, 90 Tage, nur vorgegebene Eingaben | +| D3, D4, D6 | Mindestnachweise, akzeptierte Angaben je Kanal, Direktbuchung | aus dem Vorschlag Kanalkonfigurator übernommen, weiter offen | + +Weitere Voraussetzungen: v0.11 ist auf stommer.info abgenommen, und die offenen Feature-Zweige sind zusammengeführt. Erst dann beginnt U-A. diff --git a/docs/Prozessarchitektur/Architektur/01_ARCHITEKTURBEWERTUNG.md b/docs/Prozessarchitektur/Architektur/01_ARCHITEKTURBEWERTUNG.md new file mode 100644 index 0000000..421091e --- /dev/null +++ b/docs/Prozessarchitektur/Architektur/01_ARCHITEKTURBEWERTUNG.md @@ -0,0 +1,159 @@ +# 01 – Architekturbewertung: kontrolliert modulare Prozessarchitektur + +Stand: 04.11.2026 · Grundlage: Branch `feature/aufenthalt` (Commit `ef2783e`), Prozessarchitektur v0.11, Vorschlag `Vorschläge/KANALKONFIGURATOR.md` +Status: **Analyse und Planung** – keine Codeänderung, keine Migration, keine Änderung an Buchungen oder Kanälen. + +Kennzeichnung in allen Dokumenten dieser Reihe: + +- **[Befund]** – im Code oder in Tests nachgewiesen (mit Klasse/Methode) +- **[Vorschlag]** – begründete Architekturempfehlung +- **[Entscheidung offen]** – vor der Umsetzung vom Betreiber zu treffen (gesammelt in `06`, Abschnitt 9) + +--- + +## 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 Zeilen | +| 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`: `DB_CONNECTION=sqlite`) | +| Zeitgesteuert | 15 Scheduler-Einträge (`routes/console.php`), angestoßen von n8n jede Minute | + +--- + +## 2. Verpflichtender Soll-Ist-Abgleich + +### 2.1 Bereits sauber gekapselte Fähigkeiten [Befund] + +Die einzelnen Geschäftsoperationen sind gut gekapselt: 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 `QuoteLine`s (Typen u. a. `Discount`, `Adjustment`) | sehr gut; seiteneffektfrei, stark getestet (`PriceCalculatorTest`, `SpecialOfferPricingTest`, `MinimumStayRulesTest`) | +| Verfügbarkeit | `AvailabilityChecker::isAvailable`, `CalendarClearance::reasons/refresh` | gut; die einzige Stelle für Kalenderwahrheit | +| Verbindliches Angebot | `SendOffer::handle` (versioniert, `quoteFor` mit `Adjustment`-Zeile), `deliver` (Mail getrennt) | 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; einheitlicher Eingang für alle Quellen (`FactSource`) | +| Datenbeschaffung | `RequestCaseData` + `data_requests` + `GuestDataController` | gut | +| Halten | `RequestHold` (Zweck offer/clarification), `ExpireReservations`, `ReleaseReservation` | gut | +| Dokumente | `DocumentComposer` → `DocumentComposition::toConfirm`, `SendBookingDocuments`, `RentalContract` | gut | +| Portalbeträge | `RecordPortalAmounts`, `CaseMoney` | gut | +| Nachrichteneingang | `ReceiveInboundMessage`, `MessageMatcher`, `ExtractMessageFacts`, `LlmClient` (BYOK) | gut; KI liefert nur Vorschläge in `ContributeCaseFacts` | +| Mail-Schranke | `EnforceMailTestMode` (MessageSending, jeder Mailer); `MailTestModeGateTest` verhindert Umgehungen | sehr gut; ein zentraler Effektpunkt | +| Nachweis | `CaseLog`, `CaseRecorder` (Observer-gestützt), `BookingEvent` | gut | + +**Folgerung:** Die Fachmodule existieren inhaltlich schon. Es fehlt nicht die Logik, sondern eine **Beschreibung und Komposition** dieser Logik. + +### 2.2 Über mehrere Komponenten verteilte Geschäftsregeln [Befund] + +| Regel | Fundstellen | +|---|---| +| „Wer liefert die Dokumente?“ (`documents() ===`) | `CaseActivities`, `CaseAutomation`, `ViewBooking`, `BookingInfolist`, `DocumentKind` | +| „Wer kassiert?“ (`payments() ===`) | `CaseActivities`, `CancelBooking`, `DocumentComposer`, `PaymentsRelationManager`, `Booking::needsPaymentMonitoring` (Z. 472) | +| „Wer schreibt dem Gast?“ (`guestMessages() ===`) | `CaseActivities`, `RequestReviews`, `SendBookingReminders` | +| Anfrage oder Buchung (`IntakeKind::Booking`) | 14 Dateien, u. a. `PortalIntake`, `RequestCaseData`, `ProvideGuestContact`, `DocumentComposer` | +| Vorreservierung ja/nein (`preReservation()`) | 15 Dateien, u. a. `AutoOffer`, `RequestCaseData`, `DocumentComposer`, `SendPendingAutoOffers` | +| Interne Belegung (`isInternal()`) | 11 Dateien | +| Pflichtangaben je Schritt | `CaseRequirements` (zentral) – aber das Warten auf diese Angaben ist in `CaseActivities` (Kontakt-, Angebots- und Wunschschritt), `AutoOffer::blockers` und `RequestCaseData` jeweils eigens ausgewertet | + +Diese Regeln sind **korrekt**, aber nur implizit ein „Prozess“. Ein neuer Schritt (z. B. Loyalty) müsste heute an mehreren dieser Stellen bedacht werden. + +### 2.3 Fest verdrahtete Prozesse und Archetypen [Befund] + +1. **Ablaufliste:** `CaseActivities::for()` baut die Schritte als eine lange Folge von `if`-Blöcken. Sie verzweigt nach `$inquiry`, `$binding`, `preReservation()`, `documents()`, `payments()` und `isInternal()`; Letzteres führt nach `internal()`. Reihenfolge, Bedingung, Zustand und Aktion jedes Schritts stehen inline. Die Schlüssel sind Zeichenketten: `intake`, `contact`, `information`, `wish`, `wish_check`, `offer`, `acceptance`, `binding`, `price`, `documents`, `channel_block`, `payment`, `payout`, `deposit`, `balance`, `change_proposed`, `arrival_details`, `arrival_info`, `data_request`, `stay`, `review`, `closure`, `settlement`, `task_*`. +2. **Automatik:** `CaseAutomation::step()` kennt genau zwei Fälle (Angebot/Auskunft einer Anfrage, Unterlagen einer verbindlichen Buchung). Beide sind als eigene Bedingungen codiert und laufen nicht entlang der Ablaufliste. +3. **Archetyp:** `ProcessProfile::caseTypeFor()` leitet A1–A6 aus Eingangsart, „über Kanal“ und Verantwortungen ab. **Der Archetyp steuert nichts** (`CaseType::A` kommt nur in `ProcessProfile` vor). Er ist eine reine Klassifikation – genau das, was der Auftrag für Archetypen vorsieht. +4. **Schrittdetails:** `ActivityDetails::EVENT_TYPES` ordnet Verlaufsereignisse über die Schritt-Zeichenketten zu. Das ist eine zweite, parallel gepflegte Liste. +5. **Aktionen der Oberfläche:** `ViewBooking` bildet Aktionsnamen (`provideContact`, `approveDataRequest`, `portalPrice` …) auf Schritte ab. + +### 2.4 Tatsächlich vorhandene Konfiguration [Befund] + +- Hierarchie `ProcessSettings::resolve`: System (`ProcessSetting::default`) → Vermieter (`tenants.process_defaults`) → Wohnung (`properties.process_overrides`, Vertragsvorlage) → Kanal × Eingangsart (`channels.process_overrides[intake]`) beziehungsweise Webseite (`forWebsite`). +- Nicht gesetzte Werte erben; ein bewusst gesetztes `0`/„nein“/„manuell“ bleibt erhalten (`ProcessSetting::normalize`). Jeder Wert trägt seine Herkunft (`ProcessProfile::source`, `sourceLabel`). +- Die Einstellungen werden beim Eingang eingefroren (`CaseRecorder::freeze` → `bookings.profile`). Ausnahme: `ProcessProfile::LIVE = [ContractTemplate]`. +- Kanalebene: `ProcessSetting::channelIntakes()` begrenzt, welche Einstellung je Eingangsart überhaupt am Kanal gilt. +- Oberflächen: `HandlingSettings` (Vermieter), `PropertyForm` (Wohnung), `ChannelForm`/`EditChannel` (Kanal), `EffectiveSettings` (Wirksamkeit). + +**Damit ist Ebene C (Kanalkonfiguration) zur Hälfte vorhanden:** Vererbung, Herkunft und Einfrieren sind gelöst. Es fehlen die Auswahl eines Ablaufs und die Darstellung entlang der Schritte. + +### 2.5 Spezifizierte, aber nicht umgesetzte Freiheitsgrade [Befund] + +| Freiheitsgrad (v0.10/v0.11, Vorschlag Kanalkonfigurator) | Stand | +|---|---| +| Ablaufmodell je Kanal × Eingangsart wählen | fehlt; ergibt sich implizit aus `booking_model` und Verantwortungen | +| Optionale Schritte an-/abschalten (Bewertungsbitte, Erinnerungen, Adressprüfung) | nur teilweise über Einzelwerte (`GuestMessages`, `FormRequiresAddress`); Bewertungsbitte hängt an `guestMessages()` | +| Schrittweise Automatik (automatisch / nach Freigabe / manuell je Schritt) | nur global `Processing` sowie `DataRequest` (eigener Modus) | +| Nachweisstufe für ans Portal übertragene Schritte | fehlt (Vorschlag §5: angekündigt / laut Portal erledigt / nachgewiesen) | +| Vorschau „was passiert bei diesem Kanal“ | fehlt (`EffectiveSettings` zeigt Werte, keinen Ablauf) | +| Erweiterungspunkte (z. B. vor Preisfestlegung) | fehlen; Preis kommt direkt aus `PriceCalculator` in `CreateReservation`, `SendOffer::quoteFor`, `ChangeBooking` | +| Prozess durchspielen ohne Auswirkungen | fehlt; einzig die Testsuite (Entwickler) und der Mail-Testbetrieb (keine Datenisolation) | + +### 2.6 Ohne grundlegenden Umbau weiterverwendbar [Befund → Vorschlag] + +Alle Actions aus 2.1, `PriceCalculator`, `CaseRequirements`, `ContributeCaseFacts`, `CaseLog`/`CaseRecorder`, `ProcessSettings` samt Vererbung, `ProcessProfile` samt Einfrieren, `EnforceMailTestMode`, `PortalIntake` (fachliche Annahme), die Connectors und Parser, die Datenmodelle (`bookings.profile`, `channels.process_overrides` sind JSON-Spalten und nehmen die neuen Angaben **ohne Migration** auf) sowie die gesamte Testsuite als Regressionsnetz. + +### 2.7 Wirklich notwendige Architekturänderungen [Vorschlag] + +1. **`CaseActivities` und `CaseAutomation` werden zu einer Ablaufsteuerung über Module.** Jeder heutige `if`-Block wird zu einem Schritt eines Fachmoduls mit eigenem Vertrag. Die Reihenfolge kommt aus einem versionierten Prozessmodell, nicht mehr aus der Methode. Das ist der Kern und keine bloße Abstraktionsschicht: Die alte Methode verschwindet. +2. **Ein Erweiterungspunkt im Preisweg:** `SendOffer::quoteFor` (und die anderen Aufrufer für verbindliche Preise) holen den Preis über eine kleine Fassade `CasePricing`. Sie ruft `PriceCalculator` unverändert und ergänzt Preisbeiträge aktiver Module als `QuoteLine`s. +3. **Kanalereignisse statt `BlockedPeriod`-zentrierter Annahme:** `PortalIntake` nimmt künftig ein normalisiertes Ereignis an (`IncomingBooking` …). iCal, Mail und spätere APIs liefern dieses Ereignis. +4. **Isolierte Ausführungsumgebung für den Prozess-Tester** (getrennte Datenverbindung + Effekt-Ports + simulierte Zeit). +5. **Kanalkonfigurator als Oberfläche über dem Prozessmodell**, gespeichert in den bestehenden JSON-Spalten. + +Alles andere bleibt. + +--- + +## 3. Vergleich realistischer Architekturvarianten + +| | V0 Status quo + mehr Einzeleinstellungen | V1 Beschreibungsschicht über bestehender Logik | **V2 Modulkatalog + Prozessmodelle im Code (empfohlen)** | V3 Workflow-Engine / Zustandsmaschinen-Paket | +|---|---|---|---|---| +| Idee | weitere `ProcessSetting`s, `CaseActivities` erweitern | Schrittbeschreibungen für Konfigurator und Vorschau; `CaseActivities` bleibt verdrahtet | Fachmodule mit Vertrag; Modelle als versionierte PHP-Definitionen; `CaseActivities`/`CaseAutomation` iterieren das eingefrorene Modell | z. B. `symfony/workflow` oder eigene Engine mit Zuständen/Übergängen in DB | +| Loyalty-Nachweis (N3) | `if` in `CaseActivities`, `SendOffer`, `AutoOffer`; Einstellungswildwuchs | Beschreibung **und** Code an mehreren Stellen – Doppelpflege | 2 Module + 1 Variante + Test; Kern unverändert | Modell in Engine + Adapter auf Actions | +| Konfigurator | Feldsammlung (heutiges Problem) | möglich, aber Beschreibung kann von Wirklichkeit abweichen | Oberfläche liest dieselbe Definition, nach der ausgeführt wird | möglich | +| Tester mit gleicher Logik | nicht möglich | nur Vorschau, kein Durchlauf | Durchlauf über dieselben Module und Actions | möglich, aber zweite Steuerlogik neben Actions | +| Neue Abhängigkeit | nein | nein | nein | ja (Auftrag: nicht erwünscht) | +| Risiko für laufende Vorgänge | gering | gering | mittel, beherrschbar durch Referenzvergleich (Golden Master, `05` §4) | hoch (zweite Engine, Datenmigration) | +| Aufwand | klein, wächst je Änderung | klein–mittel | mittel (einmalig) | hoch | +| Erfüllt Auftrag | nein (§2, §11) | nein („bloße Abstraktionsschicht genügt nicht“, §6) | ja | nein (§6 „keine zweite Engine“, §11) | + +**Empfehlung: V2.** V1 ist als Rückfallebene ungeeignet: Der Konfigurator würde einen Ablauf zeigen, der nicht der ausgeführte ist. Für den Tester gilt dasselbe. + +### Was V2 bewusst nicht ist + +- Kein Vermieter-Designer; Modelle und Varianten entstehen nur im Code (Pull Request, Tests). +- Keine Bedingungen durch Endanwender – nur deklarierte Parameter und deklarierte optionale Schritte. +- Keine Speicherung von Modellen in der Datenbank; dort liegen nur **Auswahl und Parameter** (bestehende JSON-Spalten). +- Kein dynamisches Laden: Module sind in einem festen Katalog (`config/process.php`) registriert, wie heute die Connectors in `config/channels.php`. + +--- + +## 4. Risiken + +| Risiko | Wirkung | Gegenmaßnahme | +|---|---|---| +| Umbau von `CaseActivities` ändert Verhalten unbemerkt | falsche nächste Schritte, falsche Automatik | Golden-Master-Vergleich alt/neu über alle Testfälle und eine Fallmatrix (`05` §4); Umstellung erst, wenn identisch | +| Laufende Vorgänge ohne Modellangabe | Ablauf ändert sich mitten im Vorgang | Abbildung `legacy` → Modell v1 aus `caseType`+`intake`+Profilwerten; v1 reproduziert heutige Liste exakt (`06` §4) | +| Tester greift doch auf echte Daten zu | Schaden an Buchungen, Mails, Portalen | mehrschichtige Isolation, Schreibwächter auf der echten Verbindung, Sicherheitstests (`04` §3) | +| SQLite auf Strato nicht verfügbar | Tester ohne getrennte Datenhaltung | Voraussetzung vorab prüfen (`php -m`); Ausweichlösung eigene MariaDB-Datenbank des Tarifs (`04` §3.6) | +| Modulvertrag wird zu formal | Mehraufwand ohne Nutzen | Vertrag als PHP-Definition mit wenigen Pflichtfeldern; Prüfung automatisch im Vertragstest | +| Zu feine Module | Konfigurator unübersichtlich | ca. 20 Module entlang der Prozesslandkarte, nicht je Methode (`02` §2) | + +--- + +## 5. Abschließende kritische Prüfung (Auftrag §15) + +1. **Sinnvoll gekapselt oder umbenannt?** Die Actions bleiben, wie sie sind – das ist gewollt, sie sind gut. Neu ist, was heute fehlt: Jeder Schritt erhält Bedingung, Zustand, Automatik, Parameter, Seiteneffekte und Nachweis an einer Stelle (Modul) statt verteilt über `CaseActivities`, `CaseAutomation`, `ActivityDetails::EVENT_TYPES` und `ViewBooking`. Die Verteilung aus 2.2 wird beseitigt, nicht umbenannt. +2. **Varianten ohne Sonderprogrammierung?** Ja, solange die Variante nur vorhandene Module kombiniert oder an Erweiterungspunkten ergänzt (N3). Ein neues Fachmodul braucht weiterhin Code und Tests – so verlangt. +3. **Modellauswahl praktisch nutzbar?** Die Auswahl ist je Kanal × Eingangsart auf die zulässigen Modelle eingeschränkt, meist 1–2 Optionen. Ein Standard wird aus dem heutigen Verhalten vorbelegt (`03` §2). +4. **Schritte verständlich, Einstellungen am Schritt?** Ja: Der Konfigurator rendert die Schrittliste aus dem Modell; Parameter hängen am Modul (`03` §3). +5. **Loyalty ohne Eingriff in andere Archetypen?** Ja; nachgewiesen in `02` §6 mit vollständiger Liste geänderter und unveränderter Komponenten. Einmalig nötig ist der generische Preis-Erweiterungspunkt; er ist kein Loyalty-Code. +6. **Änderungen nachvollziehbar?** Ja über den Katalog: Modell × Modul × Parameter × Testgruppe (`05` §2); `php artisan process:impact ` liest dieselben Definitionen. +7. **Tester mit derselben Logik?** Ja: Er führt dieselben Actions und dieselbe Ablaufsteuerung aus, nur mit getrennter Datenverbindung und ausgetauschten Effekt-Ports (`04` §2). +8. **Seiteneffekte technisch ausgeschlossen?** Mehrschichtig: andere Datenverbindung (physisch andere Datei), Schreibwächter auf der echten Verbindung, Mail/HTTP/Dateien/Warteschlange auf Fakes, keine Connector-Netzzugriffe, Abbruch bei jeder unerwarteten Effektart. Ein Rollback allein wird nicht verwendet. +9. **Neue Portal-APIs?** Ja über Kanalereignisse; ein API-Adapter liefert `IncomingBooking` wie heute iCal/Mail (N7, `02` §8). +10. **Komplexität gerechtfertigt?** Ja, weil drei Ziele (Konfigurator, Tester, Erweiterbarkeit) dieselbe Grundlage brauchen, die Actions erhalten bleiben und keine neue Abhängigkeit, keine Engine und keine Datenbankmigration für Modelle entsteht. Einfachere Varianten (V0/V1) erfüllen Konfigurator **und** Tester nicht. Bewusst weggelassen: frei kombinierbare Bedingungen, grafische Modelle, Modellpflege in der Datenbank, eine eigene Ereignis-/Zustandsmaschine. diff --git a/docs/Prozessarchitektur/Architektur/02_FACHMODUL_ARCHITEKTUR.md b/docs/Prozessarchitektur/Architektur/02_FACHMODUL_ARCHITEKTUR.md new file mode 100644 index 0000000..660d0df --- /dev/null +++ b/docs/Prozessarchitektur/Architektur/02_FACHMODUL_ARCHITEKTUR.md @@ -0,0 +1,370 @@ +# 02 – Fachmodul-Architektur: Module, Prozessmodelle, Erweiterungspunkte, Ausführung + +Stand: 04.11.2026 · Kennzeichnung: **[Befund]**, **[Vorschlag]**, **[Entscheidung offen]** (siehe `01`) + +--- + +## 1. Begriffe und Ebenen [Vorschlag] + +| Begriff | Bedeutung | Ort im Code | +|---|---|---| +| **Archetyp** (A1–A6) | Geschäftsklassifikation aus Herkunft, Verbindlichkeit und Verantwortung. Er **steuert nichts**, sondern dient nur der Klassifikation und Plausibilisierung. | `CaseType`, `ProcessProfile::caseTypeFor` (unverändert) | +| **Fachmodul** | Wiederverwendbare fachliche Fähigkeit mit Vertrag. Es bietet einen oder mehrere **Schritte** an. | `app/Process/Modules/*` (neu); nutzt die bestehenden Actions | +| **Prozessmodell** | Zentral definierte, versionierte, geordnete Folge von Schritten mit Erweiterungspunkten. Es ist für bestimmte Archetypen und Eingangsarten zulässig. | `app/Process/Models/*` (neu, PHP) | +| **Prozessvariante** | Zulässige Ausprägung eines Modells: zusätzliche Module an Erweiterungspunkten und/oder andere Vorgaben. Sie hat **denselben Archetyp**. | im Modell deklariert | +| **Kanalkonfiguration** | Auswahl Modell/Variante je Kanal × Eingangsart, dazu Parameter und optionale Schritte | `channels.process_overrides[intake]` (bestehende JSON-Spalte) | +| **Vorgangsinstanz** | Ein Fall mit eingefrorenem **Prozessplan** (Modell@Version, Variante, Modul-Versionen, aktive Schritte, Parameter mit Herkunft) | `bookings.profile` (bestehende JSON-Spalte, Schlüssel `plan`) | + +Ebene A = Module, B = Modelle/Varianten, C = Kanalkonfiguration, D = Ausführung (`ProcessRunner`) und Tester (`04`). + +--- + +## 2. Granularität [Vorschlag] + +**Regel:** Ein Modul entspricht einer fachlichen Verantwortung, die im Vorgang als eigener Schritt sichtbar ist. Es kann eigenständig aktiv oder inaktiv sein, oder es hat eigene Parameter. Was nur gemeinsam sinnvoll ist, bleibt ein Modul, auch wenn es mehrere Actions nutzt (Beispiel `offer.binding`: Angebot erstellen und versenden). „Anschrift prüfen“, „Gast identifizieren“ und „Gastdaten validieren“ werden **Parameter** von `guest.details`, keine eigenen Module. Sie teilen dieselben Daten (`case_facts`), dieselbe Pflichtfeldlogik (`CaseRequirements`) und denselben Eingang (`ContributeCaseFacts`). Eine Trennung würde nur Übergaben erzeugen. + +Querschnittsdienste wie Preisberechnung, Mail-Schranke, Verlauf, Mandant und Nachrichtenzuordnung sind **keine Schritte**. Module nutzen sie, und im Konfigurator erscheinen sie nicht als Schritt. + +Ergebnis: **22 Module** (20 aus dem Bestand, 2 neu für Loyalty) und **5 Querschnittsdienste**, entlang P01–P05. + +--- + +## 3. Modulvertrag [Vorschlag] + +### 3.1 Technische Form + +Der Vertrag besteht aus PHP-Klassen. Es gibt kein JSON, keine Datenbank und kein Paket. + +```php +namespace App\Process\Modules; + +interface ProcessModule +{ + /** Stable key and version, e.g. 'offer.binding' / 2. */ + public static function key(): string; + public static function version(): int; + + /** Everything the configurator, the impact analysis and the contract tests read (pure data, no I/O). */ + public static function definition(): ModuleDefinition; + + /** Whether the step belongs to this case at all (condition), from case data and plan parameters. */ + public function applies(CaseContext $case): bool; + + /** Where the step stands – today's inline match blocks in CaseActivities. */ + public function activity(CaseContext $case): Activity; + + /** What keeps the step from being carried out now (plain words, empty = may run). */ + public function blockers(CaseContext $case): array; + + /** Carry the step out by calling the existing Action(s); only for steps with an automatic mode. */ + public function run(CaseContext $case): StepResult; +} +``` + +Zusätzlich gibt es einen optionalen Untervertrag für Preisbeiträge: + +```php +interface ContributesToPrice +{ + /** Lines added before the price is fixed; never touches a binding case (enforced by CasePricing). */ + public function priceLines(CaseContext $case, PriceQuote $quote): PriceContribution; // lines + basis + outcome +} +``` + +`CaseContext` bündelt den `Booking`, den eingefrorenen `ProcessPlan`, die Parameter dieses Moduls und die aktuelle Zeit (aus `now()`; im Tester simuliert). Module halten **keinen** eigenen Zustand. Der Zustand steht weiter in `bookings`, `case_facts`, `booking_tasks`, `data_requests` und `booking_events`, genau wie heute. + +### 3.2 Pflichtangaben in `ModuleDefinition` + +| Vertragsfeld (Auftrag §4) | Feld | Beispiel `offer.binding` | +|---|---|---| +| Kennung und Version | `key()`, `version()` | `offer.binding` / 1 | +| Fachliche Aufgabe | `purpose` (Klartext für Konfigurator) | „Verbindliches Angebot mit Vertragsentwurf erstellen und dem Gast senden“ | +| Benötigte Eingabedaten | `needs`: Felder aus `CaseRequirements` / Fallattribute | `CaseRequirements::OFFER`, Zeitraum, Gästezahl, E-Mail | +| Produzierte Ergebnisse | `produces` | `offer_version`, `offer_terms`, `total`, Status `OfferSent`, signierter Link | +| Voraussetzungen | `requires`: Module, die vorher `Done` sein müssen | `availability.check`, `guest.details` | +| Zulässige Phasen | `phases` (P01–P05) | P02 | +| Erlaubte Seiteneffekte | `effects`: Aufzählung `Effect` | `CaseWrite`, `GuestMail`, `Document`, `CalendarHold` | +| Fehler- und Wartezustände | `states`: erlaubte `ActivityState`s + Bedeutung | `Later` = „wartet auf Angaben“, `Problem` = Zeitraum belegt | +| Auslösende Ereignisse | `triggers` | `facts.complete`, `hold.started`, Hand: `sendOffer` | +| Idempotenz/Wiederholung | `idempotency` | `expected_version`; erneuter Lauf ohne Wirkung (heute in `SendOffer` per Versionsprüfung) | +| Abhängigkeiten | `uses`: Dienste/Module | `pricing` (Dienst), `documents` (Dienst) | +| Konfigurierbare Parameter | `parameters`: `ProcessSetting`s oder `ModuleParameter`s mit Frage, Typ, Grenzen | `Processing`, `HoldHours` | +| Aktivierung | `toggle`: `Mandatory` / `Optional(defaultOn)` / `Conditional` / `Transferable` | `Mandatory` | +| Sicherheits-/Vertragsgrenzen | `guards` (Klartext + Test) | nie ohne Verfügbarkeit; nie ohne freigegebene Mietbedingungen im Livebetrieb (`AutoOffer::contractTextsReleased`) | +| Vertragstests | `#[Group('module:offer.binding')]` + generischer `ModuleContractTest` | siehe `05` §3 | + +Der **generische Vertragstest** prüft für jedes registrierte Modul automatisch: + +- Die Definition ist vollständig, und die Parameter sind gültige `ProcessSetting`s. +- `applies`/`activity`/`blockers` schreiben nichts. +- `run` erzeugt nur die deklarierten `effects`. Gemessen wird das im Tester-Sandkasten über die Effekt-Ports (`04` §3). +- Ein zweiter `run` ist wirkungslos (Idempotenz). + +So wird der Vertrag nicht zu Papier: Ein Verstoß bricht die Suite. + +--- + +## 4. Fachmodulkatalog + +Spalte „heute“ = **[Befund]**, Rest = **[Vorschlag]**. Schlüssel in Klammern = heutige Schrittschlüssel in `CaseActivities`. + +### P01 Eingang und Daten + +| Modul | Aufgabe | heute | Aktivierung | Parameter | +|---|---|---|---|---| +| `intake.record` (`intake`) | Eingang festhalten, Plan einfrieren | `CreateReservation`, `TakeOverPortalInquiry`, `TakeOverExternalBooking`, `CaseRecorder::freeze` | Pflicht | – | +| `guest.details` (`contact`) | Gast identifizieren, Angaben zusammenführen und prüfen (inkl. Anschrift) | `ContributeCaseFacts`, `ProvideGuestContact`, `CaseRequirements`, `AssignOccupationGuest` | Pflicht, wenn wir mit dem Gast korrespondieren (heute `$needsContact`) | `FormRequiresAddress`, Pflichtfelder je Folgeschritt (fest) | +| `guest.data_request` (`data_request`) | Fehlende Angaben beim Gast anfragen | `RequestCaseData`, `DataRequest`, `GuestDataController` | Optional (Modus „aus“ = entfällt) | `DataRequest`, `DataRequestRemindersMax`, `DataRequestFollowupsMax`, `DataRequestReminderHours`, `GuestLinkValidDays` | +| `guest.loyalty_status` (neu) | Stammgaststatus ermitteln | – | Optional (nur Variante „Stammgast“) | Mindestaufenthalte, Rückblick in Jahren | + +### P01/P02 Belegung und Verbindlichkeit + +| Modul | Aufgabe | heute | Aktivierung | Parameter | +|---|---|---|---|---| +| `availability.check` | Zeitraum frei, Kanäle aktuell | `AvailabilityChecker`, `CalendarClearance` | **Pflicht, nicht abschaltbar** | – | +| `hold` | Klärungs- bzw. Angebotsvorreservierung | `RequestHold`, `ExpireReservations`, `ReleaseReservation` | Bedingt (Anfrage) | `PreReservation`, `HoldHours`, `ClarificationHoldAutoMinutes`, `ClarificationHoldManualMinutes` | +| `binding.portal` (`binding`, `price`) | Verbindlichkeit beim Portal feststellen, Portalpreis | `TakeOverExternalBooking`, `PortalIntake`, `RecordPortalAmounts` | Pflicht bei Eingangsart Buchung | Nachweisstufe | +| `channels.block` (`channel_block`) | Andere Kanäle sperren/freigeben | `CreateChannelTasks`, Observer, `RemindChannelTasks`, `ICalFeed` | **Pflicht** (nicht abschaltbar, wirkt je Kanal mit `requires_manual_blocking`) | – | + +### P02 Preis, Angebot und Annahme + +| Modul | Aufgabe | heute | Aktivierung | Parameter | +|---|---|---|---|---| +| `pricing.loyalty_discount` (neu) | Stammgastrabatt als Preiszeile | – | Optional (Variante) | Prozent, Höchstbetrag, mit Sonderangeboten kombinierbar | +| `offer.information` (`information`, `wish`, `wish_check`) | Unverbindliche Auskunft → Buchungswunsch → verbindlich bestätigen | `SendInformation`, `SubmitBookingWish`, `DecideBookingWish` | Alternative zu `offer.binding` (Modellwahl) | `Processing` | +| `offer.binding` (`offer`) | Verbindliches Angebot erstellen und senden | `SendOffer`, `OfferTerms`, `DocumentComposer` | Alternative zu `offer.information` | `Processing`, `ContractTemplate` | +| `offer.acceptance` (`acceptance`) | Annahme/Ablehnung, dann Bestätigung | `AcceptOffer`, `RejectOffer`, `ConfirmBooking` | Pflicht nach `offer.binding` | – | + +### P03 Abwicklung und Geld + +| Modul | Aufgabe | heute | Aktivierung | Parameter | +|---|---|---|---|---| +| `documents.send` (`documents`) | Buchungsunterlagen an den Gast | `SendBookingDocuments`, `RentalContract`, `CaseAutomation::documentBlockers` | Übertragbar (Portal) | `Documents`, Nachweisstufe | +| `payments.monitor` (`payment`, `deposit`, `balance`) | Zahlungen überwachen, erinnern | `RecordPayment`, `SendBookingReminders`, `SendPaymentReminder` | Übertragbar (Portal) | `Payments`, Erinnerungen an/aus (heute in `GuestMessages`) | +| `portal.payout` (`payout`) | Auszahlung des Portals prüfen | `RecordPortalAmounts`, `CaseMoney` | Bedingt (`Payments = Portal`) | – | +| `change.proposal` (`change_proposed`) | Änderungsvorschlag beim Gast | `ChangeBooking` | Ereignisgetrieben (kein Planplatz, s. 4.1) | – | + +### P04 Aufenthalt + +| Modul | Aufgabe | heute | Aktivierung | Parameter | +|---|---|---|---|---| +| `arrival.details` (`arrival_details`) | Anreisedaten, Dienstleister | `PrepareStays` (Aufgaben, `services`) | Optional | – | +| `arrival.info` (`arrival_info`) | Anreise-Informationen | `PrepareStays` | Übertragbar | `GuestMessages`, `ArrivalInfoDaysBefore` | +| `stay` (`stay`) | Aufenthalt | `CloseStay` | Pflicht | – | + +### P05 Abschluss + +| Modul | Aufgabe | heute | Aktivierung | Parameter | +|---|---|---|---|---| +| `review.request` (`review`) | Bitte um Bewertung | `RequestReviews` | **Optional** | an/aus (heute an `GuestMessages` gekoppelt) | +| `case.closure` (`closure`) | Aufenthalt abschließen | `CaseClosure` | Pflicht | – | +| `case.settlement` (`settlement`) | Kaufmännisch abschließen | `CaseClosure` | Pflicht | – | + +### 4.1 Ereignisgetriebene Sonderprozesse [Vorschlag] + +Stornierung (`CancelBooking`, `CancelBookingByGuest`, `RecordCancellation`), Änderung (`ChangeBooking`) und Ablauf (`ExpireReservations`) laufen **quer** zum Plan. Sie bleiben Actions und erscheinen als Module ohne festen Planplatz (`toggle = EventDriven`). Der Plan zeigt sie, wenn ihr Ereignis vorliegt. Ihr Code bleibt unverändert. + +### 4.2 Querschnittsdienste (keine Schritte) + +`pricing` (`PriceCalculator` + neue Fassade `CasePricing`), `messages` (`ReceiveInboundMessage`, `MessageMatcher`, `ExtractMessageFacts`), `mail` (Laravel-Mailer + `EnforceMailTestMode`), `log` (`CaseLog`, `CaseRecorder`), `tenancy` (`TenantContext`, `TenantConfig`). + +### 4.3 Interne Belegungen (A6) + +`CaseActivities::internal()` wird zum Modell `a6.internal` (Module `intake.record`, `channels.block`, `documents.send` optional, `payments.monitor` ohne Erinnerungen, `stay`, `case.closure`). Ein Kanal kommt hier nicht vor, also gibt es keine Kanalkonfiguration. + +--- + +## 5. Prozessmodelle, Varianten, Erweiterungspunkte [Vorschlag] + +### 5.1 Definition im Code + +```php +final class A1OfferModel extends ProcessModel +{ + public static function key(): string { return 'a1.offer'; } + public static function version(): int { return 1; } + public static function caseTypes(): array { return [CaseType::A1]; } // plausibility, never derived from the model + public static function intakes(): array { return [IntakeKind::Inquiry]; } + public static function channelKinds(): array { return [Channel::KIND_WEBSITE, 'direct']; } + + public function steps(): array + { + return [ + Step::module('intake.record'), + Step::module('guest.details'), + Step::module('guest.data_request'), + Step::point(Point::AfterGuestIdentified), + Step::module('hold'), + Step::module('availability.check'), + Step::point(Point::BeforePriceFixing), + Step::module('offer.binding'), + Step::point(Point::BeforeBindingOffer), + Step::module('offer.acceptance'), + Step::point(Point::AfterBinding), + Step::module('channels.block'), + Step::module('documents.send'), + Step::module('payments.monitor'), + Step::module('arrival.details'), Step::module('arrival.info'), + Step::point(Point::BeforeStay), + Step::module('stay'), + Step::module('review.request'), + Step::point(Point::BeforeSettlement), + Step::module('case.closure'), Step::module('case.settlement'), + ]; + } + + public function variants(): array + { + return [ + Variant::make('standard', 'Angebot mit Vorreservierung'), + Variant::make('loyalty', 'Angebot mit Stammgastrabatt') + ->insert(Point::AfterGuestIdentified, 'guest.loyalty_status') + ->insert(Point::BeforePriceFixing, 'pricing.loyalty_discount'), + ]; + } +} +``` + +**Erweiterungspunkte** (fest, Auftrag §5): `AfterGuestIdentified`, `BeforePriceFixing`, `BeforeBindingOffer`, `AfterBinding`, `BeforeStay`, `BeforeSettlement`. Jedes Modul deklariert, an welchen Punkten es stehen darf. `ProcessCatalogue::validate()` prüft das beim Booten im Test sowie in `php artisan process:check`. + +### 5.2 Modellkatalog (Startumfang) + +| Modell | Archetyp | Eingang | Ersetzt heutigen Zweig | +|---|---|---|---| +| `a1.offer` (Varianten `standard`, `loyalty`) | A1 | Anfrage, direkt/Webseite | `preReservation() = true` | +| `a1.information` | A1 | Anfrage, direkt/Webseite | `preReservation() = false` (Auskunft → Wunsch) | +| `a2.offer`, `a2.information` | A2 | Anfrage über Portal | wie A1, mit `intake` über `TakeOverPortalInquiry` | +| `a3.portal_booking` | A3 | Buchung | `documents = Landlord`, `payments = Landlord` | +| `a4.portal_booking` | A4 | Buchung | `payments = Portal` | +| `a5.portal_booking` | A5 | Buchung | `documents = Portal` | +| `a6.internal` | A6 | intern | `CaseActivities::internal()` | + +A2 nutzt dieselben Module wie A1. Die Modelle sind getrennt, weil Eingang und Kanalbezug fachlich verschieden sind (A2 bleibt A2). Gemeinsame Schrittfolgen werden als PHP-Methode der Basisklasse geteilt, nicht kopiert. + +**[Entscheidung offen E1]** Für A3–A5 gibt es zwei Möglichkeiten: Entweder steuern die Verantwortungs-Einstellungen `Documents`/`Payments` weiter, welches Modell gilt (Modell wird abgeleitet), oder der Vermieter wählt das Modell, und dieses legt die Verantwortungen fest. Empfehlung: **Modell wählen, Verantwortungen folgen aus dem Modell.** Das entspricht dem Auftrag (§7.1) und verhindert unzulässige Kombinationen. `caseTypeFor` bleibt als Plausibilitätsprüfung erhalten. + +### 5.3 Versionierung + +- Modell und Modul tragen je eine ganze Zahl als Version. Erhöht wird bei jeder fachlich wirksamen Änderung der Schrittfolge oder des Modulverhaltens. Reine Textänderungen erhöhen nicht. +- Beim Eingang wird ein **Prozessplan** eingefroren: `profile.plan = {model: 'a1.offer@1', variant: 'loyalty', modules: {'guest.loyalty_status': {v: 1, on: true, params: {...}, source: {...}}}, configured_at}`. Das erweitert den bestehenden `CaseRecorder::freeze` und braucht keine Migration. +- Die Klassen alter Modellversionen bleiben im Code, solange offene Vorgänge sie nutzen. `php artisan process:check` meldet Versionen ohne offene Vorgänge, und erst dann wird entfernt. +- Modulversionen ändern das Verhalten laufender Vorgänge **nur**, wenn das Modul eine abwärtskompatible Korrektur deklariert (`compatibleWith: [1]`). Sonst bleibt die alte Klasse aktiv (z. B. `LoyaltyDiscountV1`). Das ist selten: Die meisten Module rufen Actions auf, und deren Fehlerkorrekturen gelten wie heute für alle Vorgänge. + +### 5.4 Eine Variante täuscht keine Geschäftsart vor + +Das Modell deklariert `caseTypes()`. Beim Einfrieren prüft `ProcessPlan::freeze`, ob `caseTypeFor(...)` darin liegt. Bei Abweichung gibt es einen klaren Fehler und **kein** stilles Umdeuten. Der Archetyp bleibt immer die abgeleitete Klassifikation. + +--- + +## 6. Architektur-Nachweis Loyalty (N3) + +### 6.1 Ablauf in der Variante `a1.offer:loyalty` + +1. `guest.details` identifiziert den Gast (E-Mail, wie heute über `CreateReservation`/`Guest`). +2. **`guest.loyalty_status`** (Punkt `AfterGuestIdentified`) zählt abgeschlossene Aufenthalte desselben Gastes beim selben Mandanten. Gezählt werden `BookingStatus::Completed`, nicht storniert, im Rückblickzeitraum. Das Ergebnis wird als Fakt `loyalty_status` über `ContributeCaseFacts` gespeichert (neue `FactSource::System`), mit Beleg „3 Aufenthalte: 2024-0012, 2025-0031, 2026-0007“. + - Ergebnisse: `Qualified` / `NotQualified` / `Unknown`. `Unknown` gilt bei fehlender E-Mail, mehrdeutiger Zuordnung oder technischem Fehler. +3. **`pricing.loyalty_discount`** (Punkt `BeforePriceFixing`, `ContributesToPrice`). Bei `Qualified` entsteht eine `QuoteLine(QuoteLineType::Discount, 'Stammgastrabatt (3 frühere Aufenthalte)', …)`, berechnet auf `PriceQuote::rent()` mit Höchstbetrag. + - Bei `NotQualified` gibt es keine Zeile. Bei `Unknown` auch keine Zeile; zusätzlich erscheint die Schrittanzeige „Status nicht feststellbar – kein Rabatt“ sowie eine optionale Aufgabe „Stammgast prüfen“. + - **Der Angebotsversand wird nie blockiert.** Das ist das definierte fachliche Ergebnis eines Fehlers. +4. `offer.binding` ruft `SendOffer` auf. `SendOffer::quoteFor` holt den Preis nun über `CasePricing::quote($booking, $stay)`. Die Rabattzeile steht damit im versionierten Angebot (`offer_terms`), im Vertragsentwurf und im Verlauf (`CaseLog::record($booking, 'price', …, data: ['basis' => …])`). +5. Ab `offer.acceptance`/`ConfirmBooking` ist der Preis fest. `CasePricing` ruft für verbindliche Vorgänge (`$booking->isBinding()`) **keine** Beiträge mehr auf. Bei `ChangeBooking` wird die gespeicherte Rabattzeile übernommen, nicht neu berechnet. **[Entscheidung offen E5]**: Soll bei einer Verlängerung der Rabatt auf die neuen Nächte ausgedehnt werden? Empfehlung: nein, stattdessen ein Hinweis für eine manuelle `Adjustment`-Zeile. + +### 6.2 Was geändert wird und was unverändert bleibt + +| Komponente | Änderung | +|---|---| +| `app/Process/Modules/Guest/LoyaltyStatusCheck.php` | **neu** | +| `app/Process/Modules/Pricing/LoyaltyDiscount.php` | **neu** | +| `A1OfferModel::variants()` | **+1 Variante** (3 Zeilen) | +| `config/process.php` (Modulregister) | **+2 Einträge** | +| `FactSource` | **+1 Fall** `System`, falls bis dahin nicht vorhanden; wird auch von anderen Systemfeststellungen genutzt | +| Tests `LoyaltyStatusCheckTest`, `LoyaltyDiscountTest`, Tester-Szenario „Stammgast“ | **neu** | +| `PriceCalculator`, `PriceQuote`, `QuoteLine`, `QuoteLineType` | unverändert | +| `SendOffer`, `AcceptOffer`, `ConfirmBooking`, `DocumentComposer`, `RentalContract` | unverändert. Die Rabattzeile ist eine normale `Discount`-Zeile und wird schon heute gedruckt. | +| `CaseActivities`/`ProcessRunner`, `CaseAutomation` | unverändert. Beide iterieren den Plan. | +| Modelle `a1.information`, `a2.*`, `a3`–`a6` | unverändert | +| Kanalkonfigurator | unverändert. Er rendert Variante und Parameter aus der Definition. | +| Prozess-Tester | unverändert. Nur ein Szenario wird ergänzt. | + +**Einmalige Voraussetzung (kein Loyalty-Code):** die Fassade `CasePricing` mit dem Erweiterungspunkt `BeforePriceFixing`. Ihre Aufrufer sind `SendOffer::quoteFor`, der Preis der Auskunft in `SendInformation` und `DecideBookingWish`. `CreateReservation` (Richtpreis der Anfrage) und `ChangeBooking` für nicht verbindliche Fälle kommen hinzu. Sie wird mit Paket U-B gebaut (`06`) und dort mit einem Testmodul geprüft, das eine Preiszeile ergänzt. + +**[Entscheidung offen E6]** Ist ein Stammgastrabatt mit Sonderangeboten kombinierbar? `PriceCalculator::bestOffers` wählt das beste Angebot je Nacht; Loyalty steht außerhalb. Empfehlung: Der Parameter „mit Sonderangeboten kombinierbar“ steht per Vorgabe auf **nein**, dann gilt der höhere Nachlass. + +--- + +## 7. Ausführungslogik [Vorschlag] + +### 7.1 Ein Ablaufkern statt zwei verdrahteter Klassen + +`ProcessRunner` ersetzt die Inhalte von `CaseActivities::for` und `CaseAutomation::step`. Die öffentlichen Methoden bleiben als dünne Fassaden erhalten: `CaseActivities::for/next/situation` und `CaseAutomation::advance/documentBlockers`. So bleiben `ViewBooking`, `BookingInfolist`, `WorkList`, `ActivityDetails`, Kommandos und Tests stabil. + +``` +ProcessRunner::activities(Booking): list + plan = ProcessPlan::of(booking) // frozen plan or legacy mapping (06 §4) + for step in plan.steps (in order): + module = registry.module(step) // exact frozen version + if not step.enabled or not module.applies(ctx): continue (recorded as skipped + reason) + activity = module.activity(ctx) + apply the over/closed rule (today's $later closure in CaseActivities::for) centrally + + event-driven modules with an open event, + open BookingTasks (today's tasks()) + +ProcessRunner::advance(Booking): list // today's CaseAutomation::advance + only when processing() is automatic (or the step's own mode is automatic, see 03 §3.3) + first step with state Open whose mode is automatic: + blockers = module.blockers(ctx); if blockers: return blockers (shown as task, as today) + result = module.run(ctx) inside CaseLog::context(actor: system) + repeat for the next step until nothing runs (bounded loop, max = number of steps) +``` + +- Die Zustandsermittlung bleibt **abgeleitet**, wie heute: aus Falldaten, nicht aus einer gespeicherten Zustandsmaschine. Es gibt also keine zweite Wahrheit, die auseinanderlaufen kann. +- Die Regel „nach Vorgangsende ist nichts mehr zu tun“ (`$later` in `CaseActivities::for`) liegt zentral im Runner. +- `ActivityDetails::EVENT_TYPES` wandert in die Moduldefinition (`events`). +- `ViewBooking` liest den Aktionsnamen aus `Activity::$action`, wie heute. + +### 7.2 Auslöser + +Es kommen keine neuen hinzu. Die heutigen Stellen rufen weiter `CaseAutomation::advance` auf: nach Eingang, nach `ContributeCaseFacts`, Scheduler `bookings:auto-offers`, `cases:data-requests` und `bookings:expire-holds`. `triggers` in der Definition dokumentiert sie und wird vom Tester zur Ereignissimulation genutzt (`04` §4). + +--- + +## 8. Trennung von Kanaladaptern und Fachprozess (N7) + +### 8.1 Befund + +- `ChannelConnector` kennt nur `fetchOccupations` (iCal). +- Mails laufen über `ProcessPortalMail` → `PortalMailParser` → `PortalIntake::inquiryMail/cancellationMail`. +- Belegungen laufen über `SyncChannel` → `BlockedPeriod` → `PortalIntake::process(BlockedPeriod)`. +- Die fachliche Annahme (`PortalIntake::evaluate/process/adopt`: Duplikat über `caseByReference`/`caseWithSameNights`, `certainty`) ist also schon vom Transport getrennt. Sie ist aber an die **Form** `BlockedPeriod` gebunden. + +### 8.2 Vorschlag: Kanalereignisse + +```php +namespace App\Channels\Events; + +final readonly class Provenance // where an event came from and how far it can be trusted +{ + public function __construct( + public Channel $channel, + public string $transport, // 'ical' | 'email' | 'api' | 'webhook' + public string $trust, // 'announced' | 'stated_by_portal' | 'verified' (= evidence levels, 03 §5) + public ?string $externalReference, + public ?string $evidenceRef, // portal_emails.id, blocked_periods.id, raw payload id + public CarbonImmutable $receivedAt, + ) {} +} + +// One class per business event, all plain data: +IncomingBooking(Provenance, arrival, departure, guests?, guest facts[], amounts?, binding: bool) +IncomingInquiry(Provenance, arrival, departure, guests?, guest facts[], message?) +BookingCancelledByChannel(Provenance, reference, cancelledOn) +BookingChangedByChannel(Provenance, reference, new dates?, new guests?) +PaymentReported(Provenance, reference, amounts[], paidOn) // → RecordPortalAmounts +PayoutReported(Provenance, reference, amount, paidOn) // → RecordPortalAmounts / CaseMoney +OccupationsReported(Provenance, list) // → SyncChannel (today's path) +``` + +- **Ein Eingang:** `ChannelEventHandler::handle(ChannelEvent)` verteilt an die bestehenden Fachfunktionen: `PortalIntake` (umgestellt von `BlockedPeriod` auf `IncomingBooking`/`IncomingInquiry`; die Sperre im Kalender entsteht weiterhin als `BlockedPeriod` mit `source = transport`), `CancelBooking`, `ChangeBooking`-Vorschlag sowie `RecordPortalAmounts`. +- **Prüfungen bleiben im Fachprozess**, unabhängig vom Transport: Herkunft (`Provenance.channel` gehört zur Wohnung des Mandanten), Vertrauensstufe, Duplikate (Referenz, gleiche Nächte) und Verbindlichkeit (`binding` + `trust`). +- **Adapter-Fähigkeiten** als kleine Zusatzschnittstellen am Connector: `ImportsOccupations` (heute `fetchOccupations`), `DeliversEvents` (Abruf, `fetchEvents(Channel, since): list`), `ReceivesWebhooks` (Route `channels/{channel}/hook` → Adapter → Ereignisse), `PushesAvailability` (später). `ChannelRegistry` und `config/channels.php` bleiben das Register. + +**N7-Nachweis:** Ein künftiger `FewoDirektApiConnector` implementiert `DeliversEvents` und liefert `IncomingBooking` mit `transport = 'api'` und `trust = 'stated_by_portal'`. Danach laufen dieselben Schritte wie bei der Mail-Schnellspur: Duplikat zur iCal-Sperre über Referenz/Nächte, dann `TakeOverExternalBooking`, dann das gewählte Modell `a4.portal_booking`. Geändert werden müssen nur der Adapter und sein Registereintrag. **Unverändert** bleiben `PortalIntake`, `TakeOverExternalBooking`, die Modelle und der Konfigurator. diff --git a/docs/Prozessarchitektur/Architektur/03_KANALKONFIGURATOR.md b/docs/Prozessarchitektur/Architektur/03_KANALKONFIGURATOR.md new file mode 100644 index 0000000..02c6317 --- /dev/null +++ b/docs/Prozessarchitektur/Architektur/03_KANALKONFIGURATOR.md @@ -0,0 +1,173 @@ +# 03 – Kanalkonfigurator: Modellauswahl, Konfiguration entlang der Schritte, Vorschau + +Stand: 04.11.2026 · Kennzeichnung: **[Befund]**, **[Vorschlag]**, **[Entscheidung offen]** + +Dieses Dokument **ersetzt** `Vorschläge/KANALKONFIGURATOR.md` als Zielbild. Dessen Inhalte werden übernommen und auf die Fachmodul-Architektur (`02`) gestellt: + +- Die „Schablone“ wird zu Prozessmodell und Variante. +- Die Schritte sind die Module des Modells. +- Die Nachweisregel wird ein Modulparameter. +- Die Vorschau wird Teil des Prozess-Testers. + +Die offenen Punkte D1–D6 des Vorschlags sind in `06` §9 eingeordnet. + +--- + +## 1. Ausgangslage [Befund] + +- `EditChannel`/`ChannelForm` zeigen technische Kanaldaten: Import, Export, Echo, Regeln. Dazu kommt je Eingangsart eine flache Liste von `ProcessSetting`-Feldern, die in `channels.process_overrides[intake]` gespeichert werden. +- `HandlingSettings` (Vermieter) und `PropertyForm` (Wohnung) zeigen dieselben Felder auf ihrer Ebene. `EffectiveSettings` zeigt die wirksamen Werte mit Herkunft. +- Was ein Vorgang dieses Kanals **tut**, ist nirgends sichtbar. Ebenso wenig ist erkennbar, welche Einstellung welchen Schritt betrifft. Das ist die Kritik aus dem Auftrag (§1). + +--- + +## 2. Auswahl nach Kanal und Eingangsart [Vorschlag] + +### 2.1 Aufbau + +Neue Seite **Kanal › Ablauf** (`ChannelProcess`, Unterseite der `ChannelResource` wie heute `ChannelRules`). Ein Reiter je Eingangsart, die der Kanal liefert: + +- Die zulässigen Eingangsarten folgen aus dem Kanal. `booking_model`: `Inquiry` → nur Anfrage, `PortalBooking` → nur Buchung, `Mixed` → beide. Die eigene Webseite (`isWebsite()`) liefert nur Anfrage, bis die Direktbuchung freigegeben ist (D6). +- Je Reiter steht oben eine Frage: **„Wie wird eine Anfrage über FeWo-direkt abgewickelt?“** Darunter stehen die **zulässigen Modelle** als Karten, jeweils mit Kurzbeschreibung, Archetyp-Kennzeichen und den wichtigsten Folgen in einem Satz. + +| Kanal (Beispiel) | Eingangsart | wählbare Modelle (Varianten) | Vorbelegung bei Umstellung | +|---|---|---|---| +| Eigene Webseite | Anfrage | `a1.offer` (standard, loyalty), `a1.information` | aus heutigem `PreReservation` | +| FeWo-direkt (`Mixed`) | Anfrage | `a2.offer`, `a2.information` | aus `PreReservation` des Kanals | +| FeWo-direkt (`Mixed`) | Buchung | `a4.portal_booking`, `a5.portal_booking`, `a3.portal_booking` | aus `Documents`/`Payments` des Kanals | +| Destination Solutions | Buchung | `a3.portal_booking`, `a4.portal_booking` | aus `Documents`/`Payments` | + +Die Zuordnungen in der Tabelle sind Beispiele. Ob ein Modell für einen Kanal zulässig ist, legt das Modell fest (`intakes()`, `channelKinds()`). Darüber hinaus kann ein Connector die Auswahl einschränken (`ChannelConnector::allowedModels()`, optional). Beispiel: Destination Solutions zahlt nie aus, also ist dort kein A4 möglich. **[Entscheidung offen E2]** Diese Einschränkungen je Portal müssen anhand `docs/PORTALE.md` und `Szenarien/R08`/`R09` verbindlich festgelegt werden. + +### 2.2 Keine unzulässigen Kombinationen + +- Angeboten werden nur Modelle, deren `intakes()` die Eingangsart und deren `channelKinds()` die Kanalart enthält. +- Parameter, die einem Modell widersprechen, gibt es nicht. Ein Beispiel ist „Dokumente: Portal“ in `a3`: Die Verantwortungen sind im Modell festgelegt (E1). +- Speichern läuft über die Action `ConfigureChannelProcess`. Sie validiert gegen `ProcessCatalogue::validate($model, $variant, $config)`. Die Filament-Seite ändert nichts selbst; das entspricht der Projektregel, dass Geschäftsoperationen in `app/Actions` liegen. + +--- + +## 3. Konfiguration entlang des Ablaufs [Vorschlag] + +### 3.1 Schrittliste + +Nach der Modellwahl zeigt die Seite die Schritte **in der Reihenfolge des Modells**, gruppiert nach P01–P05 („Eingang und Daten“, „Angebot und Verbindlichkeit“, „Abwicklung“, „Aufenthalt“, „Abschluss“). Jeder Schritt ist eine aufklappbare Karte: + +``` +┌ 3 Fehlende Angaben beim Gast anfragen [ optional ● an ] +│ Was: Fragt fehlende Pflichtangaben per Link beim Gast an und erinnert. +│ Wann: Sobald Angaben für das Angebot fehlen – vor dem Angebot. +│ Wer: System · Ausführung: ( ) automatisch (●) nach Freigabe ( ) manuell +│ Fristen: Erinnerung nach 24 h (geerbt: Ihre Standards) · höchstens 2 Erinnerungen (hier gesetzt) +│ Braucht: E-Mail-Adresse des Gastes +│ Nachweis: Anfrage und Antworten im Verlauf (automatisch) +│ Folgen: Ist der Schritt aus, wartet das Angebot, bis Sie die Angaben selbst eintragen. +└ +``` + +| Auftrag §7.2 | Quelle in der Karte | +|---|---| +| Aufgabe | `ModuleDefinition::purpose` | +| Wann | Phase und Position im Modell sowie `triggers` als Klartext | +| verbindlich / bedingt / optional, kann entfallen | `toggle` (Pflicht = Schloss-Symbol, kein Schalter) | +| Wer führt aus | `performer`: System / Vermieter / Gast / Portal (übertragbare Schritte) | +| automatisch / nach Freigabe / manuell | `modes` des Moduls; wirkt nur, wo deklariert | +| Fristen | Parameter mit Zeitbezug (`HoldHours`, `DataRequestReminderHours`, `ArrivalInfoDaysBefore` …) | +| Daten | `needs` (Feldnamen aus `CaseRequirements::label`) | +| Nachweise | `evidence` beziehungsweise Mindest-Nachweisstufe für übertragene Schritte (§5) | +| geerbt oder gesetzt | Herkunft je Wert aus `ProcessSettings::resolve` (`ProcessProfile::sourceLabel`), plus Knopf „auf geerbten Wert zurücksetzen“ | +| Folgen für nachgelagerte Schritte | `consequences` (deklarierter Klartext je Schalterstellung) **und** die Vorschau (§6), die den Ablauf neu rechnet | + +### 3.2 Einfache Ansicht und Expertenansicht + +- **Einfach** (Standard, `AdminMode::Simple`): Modellwahl, Schalter für optionale Schritte, Ausführungsart, die wichtigsten Fristen, Vorschau. +- **Experte**: Hier sind zusätzlich zu sehen: + - alle Parameter; + - Modul- und Modellversion; + - Herkunft je Wert; + - der Vergleich mit dem Vermieterstandard; + - der Link „Wirksame Einstellungen“ (`EffectiveSettings` bleibt als Prüfsicht). +- Technische Schlüssel erscheinen nur im Experten-Tooltip, JSON nie. + +### 3.3 Ausführungsart je Schritt + +Heute gibt es nur `Processing` (global automatisch/manuell) und `DataRequest` (eigener Modus) **[Befund]**. Vorschlag: + +- Module deklarieren ihre zulässigen Arten. Beispiele: `offer.binding`: automatisch / nach Freigabe / manuell; `availability.check`: nur automatisch. +- Gespeichert wird je Modul unter `process_overrides[intake].steps[].mode`. `Processing` bleibt der Standard, wenn nichts gesetzt ist. So bleibt die Vererbung erhalten. +- Diese Lösung beantwortet die frühere Frage des Betreibers: „Datenanfrage automatisch, Rest manuell“. + +--- + +## 4. Optionale Schritte [Vorschlag] + +- Ein Schalter erscheint **nur**, wenn das Modul `Optional` deklariert. Im Startumfang sind das `guest.data_request`, `arrival.details`, `review.request` und in Variante `loyalty` die beiden Loyalty-Module. Hinzu kommt die Zahlungserinnerung als Parameter von `payments.monitor`. +- **Nie abschaltbar**, weil sie im Modell als `Mandatory` stehen und `ConfigureChannelProcess` die Prüfung verweigert: + - `availability.check` + - `channels.block` + - Pflichtangaben vor dem verbindlichen Angebot (`guest.details`) + - `offer.acceptance` + - Verbindlichkeitsprüfung externer Buchungen (`binding.portal`) + - Mail-Schranke (kein Schritt) +- Wird ein optionaler Schritt abgeschaltet, steht er im Plan als `enabled = false` mit Grund „im Kanal abgeschaltet“. Der Vorgang zeigt ihn nicht. Der Prozess-Tester führt ihn als „übersprungen (Konfiguration)“ (N5). + +--- + +## 5. Übertragene Schritte und Nachweis [Vorschlag] + +Übernahme aus dem Vorschlag §5: Für Module mit `toggle = Transferable` gilt Folgendes, wenn das Modell sie dem Portal zuweist (A4: `payments.monitor`; A5: `documents.send`, `arrival.info`): + +- Der Schritt bleibt **im Plan** mit `performer = Portal`. +- Die Mindest-Nachweisstufe ist ein Modulparameter: angekündigt / laut Portal erledigt / nachgewiesen. Vorgaben je Modell gemäß D3. +- Nachweise werden als Verlaufseintrag `CaseLog::record($booking, 'evidence', …, data: {module, level, source, ref})` geführt. Ein Beleg kann eine Portal-Mail, ein Eintrag der Vermieterin oder eine Datei sein. Das Muster entspricht `ChannelTaskProof` (Initiated/Observed/Confirmed) und `RecordPortalAmounts`. +- `Kanalereignisse` (`02` §8) liefern ihre Stufe über `Provenance.trust` und heben den Nachweis automatisch an. +- Ist die Mindeststufe nicht erreicht, bleibt der Schritt offen mit „Nachweis fehlt“ und erscheint beim kaufmännischen Abschluss (`case.settlement`). Ein begründeter Abschluss bleibt möglich. + +--- + +## 6. Vererbung und Wirkung auf laufende Vorgänge [Vorschlag] + +- Die Hierarchie bleibt **Vermieterstandard → Wohnung → Kanal × Eingangsart → Vorgang**. Die bestehende `ProcessSettings::resolve` wird um zwei Schlüssel ergänzt: + - `model` und `variant`: nur auf Kanalebene, mit Vorgabe aus dem Vermieterstandard je Eingangsart; + - `steps..{on, mode, params}`: auf allen Ebenen. +- Leer bedeutet geerbt; ein gesetzter Wert bleibt ein Wert. Auch `false`, `0` und „entfällt“ sind Werte, wie es `ProcessSetting::normalize` heute schon handhabt. +- Die Speicherung erfolgt in den **bestehenden JSON-Spalten**: `tenants.process_defaults`, `properties.process_overrides`, `channels.process_overrides`. Es gibt keine neue Tabelle und keine zweite Konfigurationsdatenbank. +- Laufende Vorgänge sind geschützt: Der Plan wird beim Eingang eingefroren (`CaseRecorder::freeze` → `profile.plan`). Eine Kanaländerung wirkt nur auf neue Vorgänge. + - Beim Speichern zeigt die Seite „Gilt für neue Vorgänge. 4 laufende Vorgänge behalten ihren bisherigen Ablauf.“ + - Eine bewusste Übernahme in einen laufenden Vorgang wird **nicht** angeboten. **[Entscheidung offen E3]** Empfehlung: Sie wird nicht angeboten, weil sonst Angebote und Verträge mit abweichenden Regeln entstehen. +- Jede Speicherung schreibt `configured_at` und einen Eintrag im Aktivitätsprotokoll des Kanals (`ConfigureChannelProcess`). Im eingefrorenen Plan eines Vorgangs ist damit nachvollziehbar, welcher Konfigurationsstand galt. + +--- + +## 7. Vorschau und Übergang zum Prozess-Tester [Vorschlag] + +- **Vorschau** (immer sichtbar, rechte Spalte): der Ablauf eines typischen Vorgangs mit den aktuellen, noch nicht gespeicherten Einstellungen. + - Technisch ist das `ProcessRunner::plan(...)` ohne Fall, also rein aus Definition und Konfiguration. + - Die Liste zeigt je Schritt: aktiv / übersprungen mit Grund; wer, wann, Ausführungsart. + - Es wird nichts geschrieben und nichts ausgeführt. +- **„Ablauf testen“** (Knopf unter der Vorschau) öffnet den Prozess-Tester (`04`) mit derselben, auch ungespeicherten Konfiguration. Dort wird ein synthetischer Vorgang mit den echten Modulen durchgespielt. +- Widersprüche werden sofort angezeigt. Beispiel: Ein Kanal liefert laut Import nur Buchungen, aber nur der Reiter „Anfrage“ ist konfiguriert. Die bekannte Lücke aus `KONFIGURATION_UND_WIRKSAMKEIT.md` §7 wird so geschlossen. + +--- + +## 8. Berechtigungen und Navigation [Vorschlag] + +- Es gilt die bestehende Policy der `ChannelResource`; ändern dürfen Administratoren des Mandanten (D5). Die Seite nutzt `FollowsAdminMode`. +- `HandlingSettings` („So arbeite ich“) nutzt **dieselbe** Schrittansicht ohne Kanalbezug, nämlich als Vermieterstandard je Eingangsart. +- `PropertyForm` zeigt nur die Abweichungen der Wohnung (Expertenansicht). +- Die heutige flache Feldliste am Kanal entfällt als Hauptansicht. + +--- + +## 9. Abnahmekriterien Konfigurator + +| # | Kriterium (prüfbar auf stommer.info) | +|---|---| +| K01 | Je Kanal und Eingangsart ist genau ein Modell wählbar, und zwar nur ein zulässiges. Ein danach eingehender Vorgang erhält Modell, Variante und den erwarteten Archetyp. | +| K02 | Jeder Schritt zeigt Aufgabe, Zeitpunkt, Ausführende, Ausführungsart, Fristen, Daten, Nachweis, Herkunft der Werte und Folgen. Pflichtschritte haben keinen Schalter. | +| K03 | Die Vorschau entspricht der Ablaufliste eines danach eingehenden echten Vorgangs. Das wird automatisch geprüft durch den Vergleich `ProcessRunner::plan` gegen `CaseActivities::for` eines frisch angelegten Falls. | +| K04 | Ein übertragener Schritt ohne Mindestnachweis bleibt offen und erscheint beim kaufmännischen Abschluss. | +| K05 | Eine Konfigurationsänderung verändert keinen laufenden Vorgang. Das zeigen der Plan in `bookings.profile` vorher und nachher sowie ein Test. | +| K06 | `EffectiveSettings` und Konfigurator zeigen dieselben Werte und dieselbe Herkunft. | +| K07 | Pflichtangaben, Verfügbarkeit, Verbindlichkeit externer Buchungen und Mail-Schranke lassen sich durch keine Konfiguration umgehen. Die v0.11-Regressionstests bleiben grün, ergänzt um einen Test, der jede `Mandatory`-Abschaltung abweist. | +| K08 | Die Einrichtung eines Kanals in der einfachen Ansicht kommt ohne technische Schlüssel aus. Geprüft wird das durch Bedienung mit dem Betreiber in der Abnahme. | diff --git a/docs/Prozessarchitektur/Architektur/04_PROZESS_TESTER.md b/docs/Prozessarchitektur/Architektur/04_PROZESS_TESTER.md new file mode 100644 index 0000000..9b2bf7c --- /dev/null +++ b/docs/Prozessarchitektur/Architektur/04_PROZESS_TESTER.md @@ -0,0 +1,206 @@ +# 04 – Prozess-Tester „Ablauf testen“: gleiche Logik, technische Isolation, Ereignissimulation, Bericht + +Stand: 04.11.2026 · Kennzeichnung: **[Befund]**, **[Vorschlag]**, **[Entscheidung offen]** + +--- + +## 1. Zweck und Grenzen [Vorschlag] + +Der Vermieter spielt mit der gerade bearbeiteten Kanalkonfiguration einen **synthetischen Vorgang** durch. Die Konfiguration darf auch ungespeichert sein. Er sieht Schritt für Schritt: + +- welche Module liefen und mit welchem Ergebnis; +- welche übersprungen wurden und warum; +- was als Nächstes kommt; +- welche Aufgaben offen sind; +- welche Wirkungen **simuliert** wurden: Mails, Sperren, Dokumente, Zahlungen. + +Der Tester ist Teil des Kanalkonfigurators (`03` §7) und gemeinsames Abnahmekriterium. + +Nicht Ziel: Lasttests, Prüfung des echten Portals oder der echten KI-Anbindung. Für die Verbindungsprüfung gibt es die Prüfknöpfe in `AiConnection::check` und `Operations::checkMailbox`. + +--- + +## 2. Dieselbe fachliche Logik [Vorschlag] + +### 2.1 Prinzip + +Der Tester enthält **keine** Fachregeln. Er ist ein Treiber, der drei Dinge tut: + +1. Er legt den Ausgangszustand in einem isolierten Datenspeicher an (§3). +2. Er löst Ereignisse über **dieselben Einstiegspunkte** aus, die im Betrieb Controller, Kommandos und Connectors verwenden. +3. Er liest nach jedem Ereignis den Ablauf über `ProcessRunner::activities` aus, also dieselbe Methode, die `ViewBooking` nutzt. + +| Szenario-Ereignis | Einstiegspunkt im Betrieb (unverändert) | +|---|---| +| Gast sendet Anfrage über die Webseite | `CreateReservation::handle` (wie das Livewire-Buchungsformular) | +| Anfrage per Portal-Mail | `ProcessPortalMail::handle(PortalMail)` mit synthetischer `PortalMail` | +| Portalbuchung über iCal | `SyncChannel::handle` mit `ScriptedConnector` (liefert `ExternalPeriod`s) | +| Portalbuchung über künftige API | `ChannelEventHandler::handle(IncomingBooking)` (`02` §8) | +| Gast ergänzt Angaben per Formular | dieselbe Action wie `GuestDataController` (`ContributeCaseFacts` mit `FactSource::GuestLink`) | +| Gast antwortet per E-Mail | `ReceiveInboundMessage::handle(PortalMail)` → `MessageMatcher` → `ExtractMessageFacts` mit Skript-Antwort der KI | +| Vermieter gibt frei / sendet | Modul-`run` bzw. dieselbe Action wie die Kopfaktion in `ViewBooking` | +| Gast nimmt an / lehnt ab | `AcceptOffer::handle` / `RejectOffer::handle` | +| Zeit vergeht (Frist, Erinnerung, Anreise) | simulierte Uhr (§4) + dieselben Scheduler-Handler: `ExpireReservations::handle`, `SendPendingAutoOffers`, `cases:data-requests`, `SendBookingReminders::handle`, `PrepareStays::handle`, `RequestReviews::handle` | +| Portal meldet Zahlung/Auszahlung | `RecordPortalAmounts::handle` (bzw. `PaymentReported` über den Ereigniseingang) | +| Kommunikation oder Schnittstelle fällt aus | Effekt-Port wirft den echten Fehlertyp: `TransportException`, `AccessRejected`, `ChannelSyncException` | + +### 2.2 Nachweis der Gleichheit + +- Jedes mitgelieferte Szenario (§5) existiert zusätzlich als PHPUnit-Test (`ProcessTesterParityTest`). Der Test führt dasselbe Szenario **ohne** Tester auf der normalen Testdatenbank aus, über dieselben Actions, und vergleicht Ablauf, Status und Effektliste mit dem Testerbericht. Weichen sie ab, schlägt der Test fehl. +- Außerdem wird die Vorschau im Konfigurator (`ProcessRunner::plan`) gegen die Ablaufliste eines danach eingehenden echten Vorgangs geprüft (K03). +- Ein Architekturtest stellt sicher, dass Tester-Klassen keine Fachklassen ersetzen. Unter `app/Process/Tester` dürfen keine Klassen liegen, die `ProcessModule` implementieren oder `PriceCalculator`, `AvailabilityChecker` oder Actions ableiten. + +--- + +## 3. Technische Isolation [Vorschlag] + +### 3.1 Warum nicht Rollback oder `dryRun` + +Ein Transaktions-Rollback schützt nur die Datenbank, und selbst die nur unvollständig. Es bleiben: + +- Mails: Sie gehen beim Senden raus, nicht beim Commit. +- HTTP-Aufrufe an KI und iCal. +- Dateien: Vertrags-PDFs über `RentalContract` auf `Storage::disk`. +- Warteschlangen-Einträge. +- Sitzungs- und Cache-Schreibvorgänge: `SESSION_DRIVER=database` und `CACHE_STORE=database` laufen auf derselben Verbindung. +- Sperren: `lockForUpdate` an 28 Stellen hält echte Vorgänge auf. +- Ein versehentlicher Commit durch verschachtelte `DB::transaction` mit Fehlerbehandlung. + +Ein `dryRun`-Schalter müsste an jeder Effektstelle beachtet werden und versagt beim ersten vergessenen Aufruf. + +Der Tester verwendet daher **mehrere unabhängige Schutzschichten**. Jede einzelne verhindert schon für sich operativen Schaden. + +### 3.2 Schicht 1: getrennter synthetischer Datenspeicher + +- Eigene Verbindung `sandbox` (`config/database.php`): **SQLite-Datei je Testlauf** unter `storage/app/sandbox/.sqlite`, nach dem Lauf gelöscht. Das passt zur Strato-Dateiquote, siehe `BETRIEB.md`. +- **[Befund]** Die gesamte Testsuite (683 Feature-Tests) läuft auf SQLite (`phpunit.xml`). Die Fachlogik ist also auf SQLite lauffähig und geprüft. +- **Vorlage:** Beim Deployment erzeugt `php artisan process:sandbox-template` eine migrierte, leere SQLite-Vorlage im Release. Jeder Lauf kopiert sie. Es gibt keine Migration zur Laufzeit; das dauert unter 100 ms. +- **Befüllung:** Der `SandboxSeeder` liest vor Aktivierung der Schutzschichten **lesend** aus der echten Datenbank und schreibt nur in die Sandbox-Verbindung. Übernommen werden: + - der aktuelle Mandant (Einstellungen, Texte, Bankangaben laut `TenantConfig`); + - die gewählte Wohnung mit Saisons, Sonderangeboten, Extras, Vertragsvorlagen und den Kanälen dieser Wohnung; + - der zu testende Kanal mit der **Entwurfskonfiguration** aus dem Konfigurator; + - optional die Belegung als anonymisierte Sperrzeiten, damit die Verfügbarkeit realistisch ist. + - **Keine** Gäste, keine Buchungen, keine Nachrichten, keine Zugangsdaten. KI-Schlüssel und Postfach-Passwörter werden nicht kopiert. +- Während des Laufs ist `sandbox` die **Standardverbindung**: `config(['database.default' => 'sandbox'])`, `DB::purge`, `DB::setDefaultConnection`. Kein Modell setzt eine eigene `$connection` **[Befund: keine Fundstelle in `app/`]**. Damit landen alle Eloquent- und Query-Builder-Zugriffe in der Sandbox. + +### 3.3 Schicht 2: Schreibwächter auf der echten Verbindung + +- Vor dem Lauf registriert `ProcessSandbox` auf der echten Verbindung (Standardverbindung des Servers, MariaDB) einen `beforeExecuting`-Rückruf. Er bricht **jede** Anweisung mit `SandboxViolation` ab, auch Lesezugriffe, solange der Lauf aktiv ist. Ein Zugriff auf die echte Datenbank ist im Lauf ein Fehler, keine Kleinigkeit. +- Der Wächter wird erst nach dem Lauf entfernt, im `finally`, und erst dann wird die Standardverbindung zurückgesetzt. Sitzung und Cache der Admin-Anfrage schreiben erst nach Ende der Anfrage, also nach dem Lauf. Das deckt der Sicherheitstest in §7 ab. + +### 3.4 Schicht 3: Effekt-Ports auf Simulation + +Jeder Weg nach außen wird für die Dauer des Laufs auf eine aufzeichnende Simulation umgestellt. Die Aufzeichnung (`EffectLedger`) ist zugleich der Bericht der „simulierten Seiteneffekte“. + +| Effekt | Betrieb [Befund] | im Tester | +|---|---|---| +| E-Mail | Laravel-Mailer → `EnforceMailTestMode` → SMTP | Mailer `array` (Framework-Transport, keine Zustellung). Ein Listener auf `MessageSending` zeichnet Empfänger, Betreff und gerenderten Text auf. `EnforceMailTestMode` bleibt zusätzlich aktiv, mit Sandbox-Mandant im Testbetrieb und Testadresse `tester@invalid`. | +| HTTP (KI, iCal-Abruf) | `Http`-Client (`LlmClient`, `ICalConnector`) | `Http::preventStrayRequests()` + `Http::fake` mit Szenario-Antworten. Jeder nicht vorgesehene Aufruf bricht den Lauf ab. | +| IMAP | `MailboxReader` (Webklex) | Container-Bindung auf `SandboxMailboxReader`, das bei Aufruf `SandboxViolation` wirft. Eingehende Mails werden als `PortalMail` direkt eingespielt (§2.1). | +| Connectors | `ChannelRegistry` (`config/channels.php`) | Registry-Bindung auf `ScriptedConnector`/Ereignisquelle des Szenarios | +| Dateien | `Storage::disk('local'/'public')` | `Storage::fake` je Disk auf `storage/app/sandbox//…`. PDFs werden erzeugt und verworfen; die Größe wird im Bericht genannt. | +| Warteschlange | `QUEUE_CONNECTION=database` | Verbindung `sync`, jobs laufen im Lauf, also ebenfalls in der Sandbox | +| Cache, Rate-Limiter | `CACHE_STORE=database` | Store `array` | +| Kanal-Export (iCal-Feed) | `ICalFeed` | wird nicht ausgeliefert. Der Tester berechnet den Feed der Sandbox vorher/nachher und zeigt „würde im Export von FeWo-direkt erscheinen“. | +| Zahlungen | – (keine Zahlungsintegration) [Befund] | nur Datensätze in der Sandbox | +| Zeit | `now()` | simulierte Uhr (§4) | + +### 3.5 Schicht 4: Ausführungsrahmen + +- Es gibt genau **einen** Einstieg: `ProcessSandbox::run(Scenario, ConfigDraft): TestReport`. + - Er aktiviert die Schichten 1 bis 3 in fester Reihenfolge, prüft sie und führt erst dann aus. + - Schlägt eine Prüfung fehl, bricht er vor dem ersten Ereignis ab. Beispiel: Die Standardverbindung ist nicht `sandbox`, oder der Mailer ist nicht `array`. +- Eine Sperre pro Mandant (`Cache::lock` auf dem echten Store, **vor** Aktivierung) verhindert parallele Läufe derselben Person. Eine Laufzeitgrenze (z. B. 20 s) und eine Ereignisgrenze (z. B. 60) verhindern Endlosschleifen. +- Der Lauf findet **innerhalb der Admin-Anfrage** statt, ohne Hintergrundprozess. Strato startet keine Arbeiterprozesse dauerhaft. Der Scheduler über n8n bleibt unberührt; seine Läufe sehen die Sandbox nie, weil sie in einem anderen PHP-Prozess mit der echten Standardverbindung laufen. +- Den Bericht speichert erst **nach** dem Lauf der Tester selbst, in der echten Datenbank (§6). Kein Modul kann das beeinflussen. + +### 3.6 Ausweichlösung [Entscheidung offen E4] + +Falls `pdo_sqlite` auf Strato nicht verfügbar ist (Voraussetzung V1, mit `php -m` zu prüfen), wird statt der SQLite-Datei eine **eigene MariaDB-Datenbank** des Strato-Tarifs als Sandbox genutzt. Sie wird je Lauf geleert, mit Vorlage per `schema:dump`. Alle anderen Schichten bleiben gleich. Das ist eine Datenhaltung für synthetische Testfälle, **keine** zweite Konfigurationsdatenbank. + +### 3.7 Grenzen der Gleichheit + +SQLite und MariaDB unterscheiden sich in wenigen Punkten: Datumsfunktionen in rohem SQL (28 `DB::raw`/`whereRaw`/`selectRaw`-Fundstellen), Sortierung und Sperrsemantik. Die Fachlogik ist auf SQLite getestet. Die Stellen mit rohem SQL werden in Paket U-D einmal gesichtet und notfalls datenbankneutral gefasst. Die Testsuite deckt beides bereits ab. + +--- + +## 4. Ereignis- und Zeitsimulation [Vorschlag] + +- **Simulierte Uhr:** `Date::setTestNow()` (Carbon), gesetzt durch den Treiber und im `finally` zurückgesetzt. Startzeit ist „jetzt“ oder vom Szenario vorgegeben, etwa „Anfrage am Freitag 18 Uhr“ für Klärungsfristen am Wochenende. +- **Zeitsprung** (`advance(hours: 25)`) führt die zeitgesteuerten Handler in der Reihenfolge von `routes/console.php` aus. Ausgeführt werden nur die für Vorgänge relevanten (§2.1), nicht `channels:sync` oder `channels:fetch-mail`. +- **Ereignisse** sind kleine Treiberklassen, eine je Zeile in §2.1. Szenarien sind Listen solcher Ereignisse mit Daten. Der Vermieter wählt vorbereitete Szenarien und kann einige Daten ändern: Zeitraum, Personen, fehlende Felder, „Gast ist Stammgast“, „KI nicht erreichbar“. Eigene Ablauflogik kann er nicht schreiben. +- **Interaktiv:** Ereignisse sind schrittweise auslösbar („Weiter: Gast antwortet per Mail“). Jeder Schritt startet einen neuen Lauf aus Ausgangszustand und Ereignisliste bis zu diesem Punkt; die Läufe sind deterministisch. So wird nichts zwischen Anfragen im Speicher gehalten, was auf Shared Hosting ohnehin nicht trägt. + +--- + +## 5. Szenarienkatalog (Startumfang) + +| # | Szenario | Prüft | +|---|---|---| +| S01 | Vollständige Anfrage (A1/A2) | Klärungsreservierung, Angebot, Annahme, Bestätigung | +| S02 | Fehlende Gastdaten | `guest.data_request`, Warten des Angebots, Erinnerung nach Fristsprung | +| S03 | Gast antwortet über Formular | Fakten mit Quelle `GuestLink`, Angebot wird frei | +| S04 | Gast antwortet per E-Mail | Zuordnung, Skript-KI liefert Anschrift, Übernahme bzw. Vorschlag | +| S05 | Frist läuft ab | `ExpireReservations`, Status, Kalender wieder frei | +| S06 | Angebot wird angenommen | `AcceptOffer` → `ConfirmBooking`, Sperraufgaben für Kanäle | +| S07 | Portalbuchung wird übernommen (A3/A4/A5) | Duplikaterkennung iCal + Mail, `binding.portal` | +| S08 | Portal übernimmt Zahlung und Dokumente (A4/A5) | übertragene Schritte, Nachweisstufe, Abschlussprüfung | +| S09 | Loyalty-Status wird festgestellt | `guest.loyalty_status` mit synthetischen Vorgängen in der Sandbox | +| S10 | Rabatt wird angewendet | `Discount`-Zeile im Angebot, Grundlage im Verlauf | +| S11 | Optionaler Schritt deaktiviert | „übersprungen (Konfiguration)“, Ablauf bleibt gültig | +| S12 | Kommunikation oder Schnittstelle fällt aus | Mail-Port wirft `TransportException`, KI liefert 401 → `AccessRejected`, iCal-Abruf liefert Fehler. Danach definierte Zustände: Aufgabe, Postfach-Hinweis, kein Absturz. | + +--- + +## 6. Testbericht [Vorschlag] + +Inhalt nach Auftrag §8: + +1. **Kopf:** + - Prozessmodell und Version, Variante, Modulversionen; + - Kanal und Eingangsart; + - Release (`deploy//`): Die Release-Kennung legt `scripts/deploy.sh` als Datei im Release ab, neu in U-D. Heute gibt es dafür keine Anzeige in der Anwendung. + - Startzeit (simuliert), Szenario und Eingaben. +2. **Wirksame Konfiguration:** jeder Wert mit Herkunft (Vermieter, Wohnung, Kanal, Entwurf). „Entwurf“ markiert ungespeicherte Änderungen. +3. **Zeitleiste:** je Ereignis + - ausgeführte Module mit Ergebnis (`StepResult`: erledigt / wartet / Problem + Klartext); + - übersprungene Module mit Grund (`applies = false`, abgeschaltet, nicht zuständig); + - fachliche Prüfungen (`blockers`) mit Ergebnis; + - Statuswechsel; + - entstandene Aufgaben. +4. **Simulierte Seiteneffekte** aus dem `EffectLedger`: Mails mit Vorschau, Kalenderhalt, Sperraufgaben je Kanal, Dokumente, KI-Aufrufe (nur „simuliert, Antwort laut Szenario“), Exportänderungen. +5. **Ergebnis:** Endzustand, offene Punkte, nächster Schritt (`CaseActivities::next`-Äquivalent) und Hinweise. Beispiel: „Ohne E-Mail-Adresse kann das Angebot nicht automatisch gehen.“ + +**Speicherung:** neue Tabelle `process_test_runs` (Mandant, Kanal, Benutzer, Szenario, Konfigurationsschnappschuss, Modellversionen, Release, Bericht als JSON, Ergebnis). Die Löschfrist richtet sich nach der Mandanteneinstellung für Protokolle, Vorgabe 90 Tage. + +**Reproduzierbarkeit:** +- „Erneut ausführen“ startet mit dem gespeicherten Schnappschuss. +- Ist das Release neuer, zeigt der Bericht die Unterschiede zum vorigen Lauf. Das dient auch als Regressionshinweis nach Updates. +- Die Wohnungsdaten des Schnappschusses (Preise, Saisons) werden mit gespeichert. So ist ein Lauf auch nach Preisänderungen gleich wiederholbar. + +--- + +## 7. Sicherheitstests (Pflicht, Teil der Suite) + +| Test | Prüft | +|---|---| +| `ProcessSandboxIsolationTest` | Für jedes Szenario S01–S12 vergleicht der Test die Zeilenzahlen und Prüfsummen aller Tabellen der echten Verbindung vor und nach dem Lauf; sie sind identisch. Ausnahme ist `process_test_runs` (+1). | +| `ProcessSandboxViolationTest` | Ein Testmodul greift absichtlich auf die echte Verbindung zu und startet echte HTTP- bzw. IMAP-Aufrufe. Erwartet werden `SandboxViolation`, abgebrochener Lauf, Bericht „Lauf abgebrochen“ und keine Änderung. | +| `ProcessSandboxMailTest` | Kein Aufruf des echten Transports. Geprüft wird das mit einem Spionage-Transport auf dem Standard-Mailer. `MailTestModeGateTest` bleibt grün. | +| `ProcessSandboxRestoreTest` | Nach dem Lauf, auch nach einer Ausnahme, sind Standardverbindung, Mailer, Disks, Queue, Cache, Uhr und Bindungen wiederhergestellt. Eine anschließende normale Aktion schreibt wieder in die echte Datenbank. | +| `ProcessSandboxTenantTest` | Der Lauf sieht nur Daten des eigenen Mandanten. Ein zweiter Mandant bleibt unberührt (`TenantIsolationTest`-Muster). | +| `ProcessTesterParityTest` | Gleichheit Tester ↔ echter Ablauf (§2.2) | +| `ModuleContractTest` | Jedes Modul erzeugt im Sandkasten nur die Effekte, die es deklariert hat (`02` §3.2) | + +--- + +## 8. Abnahmekriterien Tester (N6) + +| # | Kriterium (auf stommer.info) | +|---|---| +| T01 | Aus dem Kanalkonfigurator lässt sich mit der aktuellen, auch ungespeicherten Konfiguration jedes Szenario S01–S12 starten und schrittweise weiterführen. | +| T02 | Der Bericht enthält Modell und Version, Kanal und Eingangsart, wirksame Konfiguration, ausgeführte und übersprungene Module mit Gründen, Prüfungen, simulierte Effekte, Ergebnis und offene Punkte, in verständlicher Sprache. | +| T03 | Nach einer Testreihe sind in der echten Datenbank keine Buchungen, Gäste, Aufgaben, Kanalaufgaben, Sperren oder Nachrichten hinzugekommen oder verändert; einzige Ausnahme sind die Testberichte. Geprüft wird das per Zählabfrage vorher/nachher im Abnahmeprotokoll. | +| T04 | Im Testpostfach und beim Mail-Anbieter ist keine Mail aus Testläufen angekommen. Der Export-Feed der Kanäle ist byte-gleich vor und nach der Testreihe. | +| T05 | Ein Lauf mit gleichem Schnappschuss liefert denselben Bericht. | +| T06 | Ein Ausfall von Mail, KI oder iCal im Szenario führt zu dem definierten Zustand, den auch der echte Vorgang zeigt. Das wird durch S12 und den Paritätstest belegt. | diff --git a/docs/Prozessarchitektur/Architektur/05_AENDERUNGSANALYSE_UND_TESTS.md b/docs/Prozessarchitektur/Architektur/05_AENDERUNGSANALYSE_UND_TESTS.md new file mode 100644 index 0000000..38ee41b --- /dev/null +++ b/docs/Prozessarchitektur/Architektur/05_AENDERUNGSANALYSE_UND_TESTS.md @@ -0,0 +1,119 @@ +# 05 – Änderungsanalyse und Teststrategie + +Stand: 04.11.2026 · Kennzeichnung: **[Befund]**, **[Vorschlag]**, **[Entscheidung offen]** + +--- + +## 1. Ausgangslage [Befund] + +- Es gibt 683 Feature-Testmethoden, gruppiert nach Fachthema, etwa `OfferWorkflowTest`, `PortalBookingTest`, `CaseCoreTest`, `GuidedCaseHandlingTest`, `ClarificationHoldTest`, `DataRequestTest`, `EndToEndAcceptanceTest` (15 Ende-zu-Ende-Fälle) und `TenantIsolationTest`. +- Eine Zuordnung „welcher Test sichert welchen Schritt eines welchen Ablaufs“ gibt es nicht. Wer heute einen Schritt ändert, sucht die Fundstellen per Volltextsuche; vgl. die Streuung in `01` §2.2. + +--- + +## 2. Abhängigkeitsmodell [Vorschlag] + +### 2.1 Die Quelle ist der Code + +Alle Angaben stehen bereits in den Definitionen aus `02`. Sie werden **nicht** zusätzlich gepflegt: + +| Frage (Auftrag §9) | Quelle | +|---|---| +| 1. In welchen Modellen wird ein Modul verwendet? | `ProcessModel::steps()` und `variants()` aller registrierten Modelle | +| 2. An welchen Erweiterungspunkten? | `Step::point` / `Variant::insert` | +| 3. Wer braucht seine Ergebnisse? | `produces` des Moduls ∩ `needs`/`requires` anderer Module | +| 4. Welche Konfiguration beeinflusst es? | `parameters` + `toggle` + `modes`, dazu Kanäle/Wohnungen, die diese Modelle gewählt haben (Abfrage auf `channels.process_overrides`) | +| 5. Welche Tests decken es ab? | PHPUnit-Gruppen `#[Group('module:')]` und `#[Group('model:')]`. Das ist ein vorhandenes PHPUnit-Merkmal, keine neue Abhängigkeit. | +| 6. Auswirkung auf andere Archetypen? | `caseTypes()` der Modelle, die das Modul enthalten. Dazu kommen die genutzten Querschnittsdienste (`uses`), z. B. `pricing`. | + +### 2.2 Werkzeuge + +- **`php artisan process:impact `** liest die Definitionen und gibt aus: + - Modelle und Varianten mit Archetyp; + - Erweiterungspunkte; + - abhängige Module; + - Parameter; + - die Zahl der Kanäle je Mandant mit diesem Modell (nur Zahl, keine Daten); + - die Testgruppen samt fertigem Aufruf `php artisan test --group=module:`. +- **`php artisan process:check`** prüft den Katalog: + - Jedes Modul ist registriert und hat eine vollständige Definition. + - Pflichtmodule sind nicht abschaltbar. + - Erweiterungspunkte sind zulässig. + - `requires` ist in jeder Modellreihenfolge erfüllt. + - Jedes Modul und jedes Modell hat mindestens eine Testgruppe. + - Alte Versionen ohne offene Vorgänge werden gemeldet. + - Der Befehl läuft in der CI vor den Tests. +- **Modulmatrix** `docs/Prozessarchitektur/Architektur/MODULMATRIX.md`: Sie wird von `process:check --matrix` erzeugt und in der CI auf Aktualität geprüft. Sie ist die lesbare Übersicht Modell × Modul × Parameter × Testgruppe. + +### 2.3 Beispiel `pricing.loyalty_discount` + +``` +$ php artisan process:impact pricing.loyalty_discount +Modul pricing.loyalty_discount v1 (Preis und Angebot, optional) +Modelle a1.offer:loyalty (A1) +Punkt BeforePriceFixing +Benötigt guest.loyalty_status (Ergebnis loyalty_status) +Benötigt von – (Ergebnis: Preiszeile; gelesen von offer.binding über CasePricing) +Dienste pricing (CasePricing → PriceCalculator unverändert) +Parameter loyalty_discount_percent, loyalty_discount_max, loyalty_combinable +Kanäle 1 Kanal (Mandant 1) +Archetypen nur A1 betroffen; A2–A6 enthalten das Modul nicht +Tests --group=module:pricing.loyalty_discount (LoyaltyDiscountTest, ProcessTesterParityTest S10) + --group=service:pricing (PriceCalculatorTest, SpecialOfferPricingTest, OfferWorkflowTest …) +``` + +--- + +## 3. Testebenen [Vorschlag] + +| Ebene | Inhalt | Gruppe | Wann | +|---|---|---|---| +| **Modultest** | Ein Modul isoliert: `applies`/`activity`/`blockers`/`run` für seine Zustände, Fehlerfälle, Idempotenz | `module:` | bei jeder Änderung des Moduls | +| **Vertragstest** (generisch) | `ModuleContractTest` mit Datenquelle „alle registrierten Module“: Definition vollständig, Lesemethoden ohne Schreibzugriff, nur deklarierte Effekte (im Sandkasten gemessen), zweiter `run` wirkungslos | `contract` | immer (schnell) | +| **Modelltest** | Je Modell/Variante: Schrittfolge, zulässige Kombinationen, Abschaltung optionaler Schritte (N5), Plan einfrieren und lesen | `model:` | bei Änderung des Modells oder seiner Module | +| **Szenario-/Paritätstest** | S01–S12 als Ende-zu-Ende über Actions, gleich mit Tester-Bericht (`04` §2.2) | `scenario` | immer | +| **Sicherheitstests Tester** | `04` §7 | `sandbox` | immer | +| **Übergreifende Regression** | bestehende Suite, unverändert; siehe §5 | – | immer, vollständig vor jedem Deployment | + +Gezielte Läufe beschleunigen die Entwicklung, ersetzen aber **nicht** den vollständigen Lauf vor dem Deployment. Die Modularität verringert die Unsicherheit, sie ersetzt keine Sicherheitsprüfung (Auftrag §9). + +--- + +## 4. Absicherung des Umbaus: Golden Master [Vorschlag] + +Der Umbau von `CaseActivities`/`CaseAutomation` auf `ProcessRunner` (`06`, U-A) ist die riskanteste Änderung. Absicherung: + +1. **Vor dem Umbau** wird die heutige Ausgabe festgehalten: + - Gesammelt werden `CaseActivities::for`, `next` und `situation` sowie das Ergebnis von `CaseAutomation::advance`. + - Grundlage ist eine **Fallmatrix**: A1–A6 × Status × Verbindlichkeit × Verantwortungen × Datenlage × Vorgangsende. Das sind etwa 150 Konstellationen, erzeugt über die vorhandenen Factories. + - Die Ausgabe wird als Fixture-Datei unter `tests/Fixtures/process/golden.json` gespeichert. +2. **Nach dem Umbau** prüft `ProcessRunnerGoldenMasterTest`, dass der neue Runner für jede Konstellation ein **identisches** Ergebnis liefert. Verglichen werden Schlüssel, Titel, Zustand, Detail und Aktion. +3. Abweichungen sind nur zulässig, wenn sie in der Fixture-Datei begründet sind (Feld `intended`). Ein Beispiel: `ActivityDetails::EVENT_TYPES` wird ins Modul übernommen. Jede begründete Abweichung wird im Umsetzungsbericht aufgeführt. +4. Die bestehenden Tests (`CaseCoreTest`, `GuidedCaseHandlingTest`, `AutoOfferTest` …) laufen unverändert weiter. + +--- + +## 5. Übergreifende Regressionen (bleiben Pflicht) + +| Bereich | bestehende Tests [Befund] | Ergänzung [Vorschlag] | +|---|---|---| +| Verbindlichkeit | `PortalBookingTest`, `BookingAcceptanceTest`, `OfferWorkflowTest` | kein Modell oder Parameter umgeht `offer.acceptance`/`binding.portal` (K07) | +| Preise | `PriceCalculatorTest`, `SpecialOfferPricingTest`, `MinimumStayRulesTest` | `CasePricing` ohne Beiträge = `PriceCalculator` (Gleichheitstest); keine Beiträge für verbindliche Fälle | +| Mandantentrennung | `TenantIsolationTest`, `TenantSeparationTest` | Konfigurator und Tester je Mandant | +| Reservierungen/Halte | `ReservationWorkflowTest`, `ClarificationHoldTest` | – | +| Externe Portale | `ChannelSyncTest`, `PortalMailTest`, `GenericChannelIntegrationTest` | Kanalereignisse: gleiche Entscheidung für iCal-, Mail- und API-Ereignis desselben Inhalts | +| Mail-Schranke | `MailTestModeGateTest` | Tester-Mailer wird mit geprüft | + +--- + +## 6. Konkrete Nachweisfälle N1–N7 + +| # | Betroffene Komponenten | Schnittstellen | Änderungen | Abnahmekriterien | +|---|---|---|---|---| +| **N1** A1-Bestand: Anfrage → Klärungsreservierung → Datenbeschaffung → Angebot → Annahme | Modell `a1.offer`; Module `intake.record`, `guest.details`, `guest.data_request`, `hold`, `availability.check`, `offer.binding`, `offer.acceptance` | `ProcessModule`, `ProcessRunner`, bestehende Actions `CreateReservation`, `RequestHold`, `RequestCaseData`, `SendOffer`, `AcceptOffer`, `ConfirmBooking` | Schritte aus `CaseActivities` in Module überführt; **keine** Änderung der Actions | Golden Master identisch; `EndToEndAcceptanceTest` grün; Szenarien S01–S03, S05, S06 im Tester mit gleichem Ergebnis wie auf stommer.info von Hand | +| **N2** A4-Bestand: Portalbuchung → Gastdatenanreicherung → Dokumente → Portalzahlung → Auszahlungskontrolle | Modell `a4.portal_booking`; Module `binding.portal`, `guest.details`, `documents.send`, `payments.monitor` (performer Portal), `portal.payout` | wie N1 + `PortalIntake`, `TakeOverExternalBooking`, `RecordPortalAmounts`, `CaseMoney` | wie N1; Nachweisstufe je übertragenem Schritt neu (Verlaufseintrag `evidence`) | Golden Master identisch; S07/S08; fehlender Auszahlungsnachweis erscheint beim kaufmännischen Abschluss (K04) | +| **N3** A1 mit Loyalty | `a1.offer:loyalty`; neue Module `guest.loyalty_status`, `pricing.loyalty_discount`; Dienst `CasePricing` | `ContributesToPrice`, `PriceContribution`, `QuoteLineType::Discount` | siehe `02` §6.2; A2–A6 unverändert | `process:impact` zeigt nur A1; S09/S10; Rabattzeile im Angebot und Vertrag, Grundlage im Verlauf; Status `Unknown` → Angebot ohne Rabatt + Hinweis; verbindliche Buchung ändert sich bei `ChangeBooking` nicht; **Diff des Umsetzungs-PR berührt keine Datei von A2–A6** | +| **N4** Gemischter Kanal | Kanal mit `booking_model = Mixed`; Reiter Anfrage (`a2.offer`) und Buchung (`a4.portal_booking`) | `ConfigureChannelProcess`, `ProcessSettings::resolve` (Schlüssel `model` je Eingangsart) | keine über U-C hinaus | eingehende Anfrage-Mail → A2-Plan, iCal-Buchung → A4-Plan; beide im selben Kanal; Tester S01 und S07 mit demselben Kanal | +| **N5** Optionales Modul aus | z. B. `review.request` oder `guest.data_request` | `toggle = Optional`, `steps..on = false` | keine | Plan zeigt Schritt nicht; Tester: „übersprungen (Konfiguration)“; `RequestReviews` sendet für den Fall keine Bitte; Versuch, `availability.check` abzuschalten, wird abgewiesen (K07) | +| **N6** Prozess-Tester | `ProcessSandbox`, `EffectLedger`, Szenarien | §3–§7 in `04` | neu | T01–T06 | +| **N7** Neue Portal-API | hypothetischer `ExampleApiConnector`; `ChannelEventHandler`; `PortalIntake` | `DeliversEvents::fetchEvents`, `IncomingBooking`, `Provenance` | nur Adapter + Registereintrag | **Testadapter** in der Suite (`tests/Support/FakeApiConnector`) liefert `IncomingBooking`. Erwartet wird dieselbe Entscheidung wie für Mail/iCal desselben Inhalts: Duplikat zur bestehenden iCal-Sperre erkannt, gleicher Plan `a4`. `PortalIntake` und Modelle werden durch den Adapter-PR nicht geändert. | diff --git a/docs/Prozessarchitektur/Architektur/06_MIGRATIONS_UND_UMSETZUNGSPLAN.md b/docs/Prozessarchitektur/Architektur/06_MIGRATIONS_UND_UMSETZUNGSPLAN.md new file mode 100644 index 0000000..770d67d --- /dev/null +++ b/docs/Prozessarchitektur/Architektur/06_MIGRATIONS_UND_UMSETZUNGSPLAN.md @@ -0,0 +1,220 @@ +# 06 – Migrations- und Umsetzungsplan + +Stand: 04.11.2026 · Kennzeichnung: **[Befund]**, **[Vorschlag]**, **[Entscheidung offen]** + +Grundsatz: **v0.11 bleibt erhalten.** Die Actions, die Preisberechnung, die Faktenaufnahme, die Nachrichtenverarbeitung, die Connectors und die Testsuite bleiben unverändert. Umgebaut wird die Ablaufsteuerung. Neu hinzu kommen Konfigurator, Tester, Kanalereignisse und ein Preis-Erweiterungspunkt. + +--- + +## 1. Notwendige Codeänderungen (Überblick) + +| Bereich | neu | geändert | unverändert | +|---|---|---|---| +| Ablauf | `app/Process/Modules/*` (20 + 2), `ProcessModule`, `ModuleDefinition`, `CaseContext`, `StepResult`, `app/Process/Models/*` (8 Modelle), `ProcessModel`, `Variant`, `Step`, `Point`, `ProcessPlan`, `ProcessRunner`, `ProcessCatalogue`, `config/process.php` | `CaseActivities` (wird Fassade), `CaseAutomation` (Fassade), `ActivityDetails` (Ereignistypen aus Modul), `CaseRecorder::freeze` (Plan mit einfrieren), `ProcessSettings::resolve` (Schlüssel `model`/`variant`/`steps`) | `Activity`, `ActivityState`, `CaseRequirements`, `CaseLog`, `WorkList`, `CaseClosure`, alle Actions | +| Preis | `CasePricing`, `ContributesToPrice`, `PriceContribution` | Aufrufer: `SendOffer::quoteFor`, `SendInformation`, `DecideBookingWish`, `CreateReservation` (Richtpreis), `ChangeBooking` (nicht verbindlich) | `PriceCalculator`, `PriceQuote`, `QuoteLine`, `QuoteLineType` | +| Konfigurator | Seite `ChannelProcess`, Action `ConfigureChannelProcess`, Blade-Komponente Schrittkarte | `HandlingSettings` (dieselbe Schrittansicht), `ChannelForm` (Prozessfelder entfallen), `EffectiveSettings` (liest Plan) | `ChannelRules`, Export, Regeln | +| Tester | `app/Process/Tester/*`: `ProcessSandbox`, `SandboxSeeder`, `EffectLedger`, `ScriptedConnector`, `SandboxMailboxReader`, Ereignistreiber, Szenarien; Seite/Modal „Ablauf testen“; Modell `ProcessTestRun`; Kommando `process:sandbox-template` | `config/database.php` (Verbindung `sandbox`), `scripts/deploy.sh` (Vorlage erzeugen, Release-Kennung ablegen) | `EnforceMailTestMode` (bleibt Schicht im Tester) | +| Kanäle | `app/Channels/Events/*` (Ereignisse, `Provenance`), `ChannelEventHandler`, Fähigkeits-Interfaces `ImportsOccupations`/`DeliversEvents`/`ReceivesWebhooks` | `PortalIntake` (nimmt Ereignis statt `BlockedPeriod`; interne Prüfungen gleich), `SyncChannel` und `ProcessPortalMail` (erzeugen Ereignisse) | `ICalParser`, `PortalMailParser`, `ICalFeed`, `ChannelRegistry` | +| Analyse | `process:impact`, `process:check` (+ `--matrix`) | CI-Workflow `.gitea/workflows/deploy.yml` (ruft `process:check`) | – | +| Loyalty (Nachweis) | `LoyaltyStatusCheck`, `LoyaltyDiscount`, Variante `a1.offer:loyalty`, `FactSource::System` | – | alles andere (`02` §6.2) | + +Neue Abhängigkeiten: **keine.** Verwendet werden nur Framework-Mittel: SQLite-PDO, `Http::fake`, `Storage::fake`, Mailer `array`, `Date::setTestNow` und PHPUnit-Gruppen. + +--- + +## 2. Datenmodelländerungen + +| Änderung | Art | Migration | +|---|---|---| +| Eingefrorener Plan im Vorgang | neuer Schlüssel `plan` in `bookings.profile` (JSON) | **keine** | +| Modellwahl, Schritte, Ausführungsart, Parameter | neue Schlüssel in `channels.process_overrides[intake]`, `properties.process_overrides`, `tenants.process_defaults` (JSON) | **keine** | +| Nachweise übertragener Schritte | Verlaufseintrag `booking_events.type = 'evidence'`; Datei auf dem privaten Disk, Pfad im Ereignis | **keine** | +| Faktquelle `System` | neuer Wert im Enum `FactSource`; Spalte `case_facts.source` ist `string(30)` [Befund] | **keine** | +| Testberichte | neue Tabelle `process_test_runs` (`tenant_id`, `channel_id`, `user_id`, `scenario`, `snapshot` JSON, `report` JSON, `outcome`, `release`, Zeitstempel; Index `tenant_id, created_at`) | **1 Migration** | +| Sandbox | Verbindung `sandbox` (SQLite-Datei je Lauf), Vorlage im Release | keine Migration der echten DB | + +Es gibt **eine** neue Tabelle und keine Änderung bestehender Spalten. + +--- + +## 3. Arbeitspakete + +Die Pakete sind technische Einheiten mit eigenem Nutzen und eigener Testabdeckung. Die **Betreiberfreigabe** erfolgt gemeinsam nach U-F; Teilfreigaben gibt es nicht (Auftrag §14). Bis dahin liegen alle Pakete auf einem Integrationszweig und werden erst nach der Abnahme nach `develop` zusammengeführt. + +### U-A Ablaufkern und Modulkatalog (Grundlage) + +- Modulvertrag, Registry und `config/process.php`. +- Überführung **aller** Schritte aus `CaseActivities::for`, `internal()`, `closing()` und `tasks()` sowie aus `CaseAutomation::step` in 20 Module. +- Die Modelle `a1.*`, `a2.*`, `a3`–`a5`, `a6` jeweils in Version 1. +- `ProcessPlan` mit Einfrieren und Legacy-Abbildung (§4). +- `ProcessRunner`. +- Die Fassaden `CaseActivities` und `CaseAutomation` behalten ihre öffentlichen Methoden. +- `process:check`/`process:impact`, PHPUnit-Gruppen an den bestehenden Tests, Golden Master (`05` §4). +- **Abnahme (technisch):** + - Golden Master identisch. + - Volle Suite grün. + - `process:check` ohne Befund. + - N1, N2 und N5 in Modelltests. + +### U-B Erweiterungspunkte, Preisfassade und Loyalty-Nachweis + +- Erweiterungspunkte im Runner. +- `CasePricing` mit Gleichheitstest gegen `PriceCalculator` (ohne Beiträge). +- `LoyaltyStatusCheck`, `LoyaltyDiscount` und Variante `a1.offer:loyalty`, je nach E7 wählbar oder nur Test. +- **Abnahme (technisch):** N3 inklusive des Nachweises, dass A2–A6 nicht verändert wurden: Der Diff berührt keine Modelldatei außer `A1OfferModel`. + +### U-C Kanalkonfigurator + +- `ChannelProcess` mit Reitern je Eingangsart, Modellwahl, Schrittkarten, Ausführungsart je Schritt, optionalen Schritten, Nachweisstufen, Herkunft, Vorschau. +- `ConfigureChannelProcess` mit Validierung. +- `HandlingSettings` auf dieselbe Ansicht umgestellt; Prozessfelder in `ChannelForm` entfernt. +- `EffectiveSettings` liest den Plan. +- Prüfung „Nachweis fehlt“ beim kaufmännischen Abschluss. +- **Abnahme (technisch):** K01–K07 automatisiert, N4. + +### U-D Prozess-Tester + +- Sandbox-Verbindung und Vorlage, Schutzschichten 1–4, `EffectLedger`, Ereignistreiber, Szenarien S01–S12, Bericht und `process_test_runs`. +- „Ablauf testen“ im Konfigurator. +- Sicherheitstests (`04` §7), Paritätstest. +- Sichtung der 28 Rohabfragen auf SQLite/MariaDB-Gleichheit. +- Release-Kennung im Deployment. +- **Abnahme (technisch):** alle Sandbox-Tests grün; T01–T06 lokal. + +### U-E Kanalereignisse + +- Ereignisklassen und `Provenance`, `ChannelEventHandler`. +- `PortalIntake` auf Ereignisse umgestellt; `SyncChannel` und `ProcessPortalMail` liefern Ereignisse. +- Vertrauensstufe → Nachweisstufe (U-C). +- Testadapter für N7. +- **Abnahme (technisch):** `ChannelSyncTest`, `PortalMailTest`, `PortalBookingTest` und `GenericChannelIntegrationTest` unverändert grün; N7-Test. + +### U-F Gesamtabnahme auf stommer.info + +- Deployment des Integrationszweigs auf das Testsystem; dort Zählabfrage vorher/nachher. +- Abnahmeprotokoll `Abnahme/ARCHITEKTUR_MODULAR_ABNAHME.md`: + - N1–N7, K01–K08, T01–T06; + - Konfiguration aller vorhandenen Kanäle des Testmandanten durch den Betreiber in der einfachen Ansicht; + - je Kanal und Eingangsart ein Testerlauf und ein echter Testvorgang zum Vergleich (K03). +- Aktualisierung von `docs/STATUS.md`, `KONFIGURATION_UND_WIRKSAMKEIT.md`, `MODULMATRIX.md`. +- **Abnahme (fachlich):** Freigabe durch den Betreiber; erst danach Merge nach `develop` und `main`. + +### 3.1 Abhängigkeiten + +``` +U-A ──┬── U-B + ├── U-C ──┐ + ├── U-E ──┼── U-F + └── U-D ──┘ (U-D nutzt den Konfigurationsentwurf aus U-C und die Ereignisse aus U-E für S07/S08) +``` + +U-B, U-C und U-E können nach U-A parallel laufen. U-D beginnt nach U-A mit Sandbox und Schutzschichten; Szenarien S07/S08 folgen nach U-E. + +### 3.2 Aufwand (Schätzung) + +| Paket | Entwicklertage | +|---|---| +| U-A | 8–10 | +| U-B | 3–4 | +| U-C | 6–8 | +| U-D | 8–10 | +| U-E | 4–5 | +| U-F (inkl. Fehlerbehebung aus der Abnahme) | 3–4 | +| **Summe** | **32–41** | + +Die Werte enthalten Tests und Dokumentation. Hinzu kommen etwa 1–2 Tage Betreiberzeit für Entscheidungen und die Abnahme. Größter Unsicherheitsfaktor ist U-A: Wie viele unbeabsichtigte Unterschiede zeigt der Golden Master? + +--- + +## 4. Migrationsstrategie für bestehende Vorgänge und Kanäle + +**Keine Datenänderung an bestehenden Buchungen oder Kanälen** – weder bei der Umsetzung noch beim Deployment. + +1. **Vorgänge ohne `profile.plan`** (alle bestehenden): `ProcessPlan::of($booking)` bildet beim Lesen aus dem eingefrorenen Profil ab: + - `intake = Internal` → `a6.internal@1`; + - `Inquiry` → `a1|a2` (nach `caseType`) `.offer@1` bei `preReservation()`, sonst `.information@1`; + - `Booking` → `a3|a4|a5.portal_booking@1` nach `caseType`. + - Variante `standard`. + - Optionale Schritte so, wie sie heute wirken: `review.request` an, wenn `guestMessages() = Landlord`; `guest.data_request` nach `dataRequestMode()`. + - Version 1 jedes Modells reproduziert das heutige Verhalten exakt (Golden Master). + - Das Profil wird nicht neu geschrieben. `origin = 'migration'` bleibt beachtet: `CaseAutomation` fasst solche Vorgänge heute nicht automatisch an, und das gilt weiter. +2. **Neue Vorgänge** erhalten beim Eingang den vollständigen Plan (`CaseRecorder::freeze`). +3. **Kanäle ohne `model`:** `ProcessSettings::resolve` leitet das Modell zur Laufzeit wie in Punkt 1 aus den bisherigen Werten ab. + - Der Konfigurator zeigt es als „aus Ihren bisherigen Einstellungen abgeleitet“. + - Gespeichert wird erst, wenn der Vermieter speichert. + - Damit verhält sich jeder Kanal nach dem Deployment genau wie vorher. +4. **Wegfallende Einzelwerte** (`Documents`/`Payments` am Kanal für Eingangsart Buchung, falls E1 wie empfohlen) bleiben lesbar und dienen der Ableitung. Sie werden im Konfigurator nicht mehr einzeln angeboten. Ein späteres Aufräumen ist optional und nicht Teil dieser Umsetzung. +5. **Rückweg:** Es werden keine Daten umgeschrieben, und `profile.plan` wird von der alten Version ignoriert. Ein Rollback per `scripts/deploy.sh rollback` ist deshalb ohne Datenkorrektur möglich. Ausnahme ist die neue Tabelle `process_test_runs`; sie bleibt ungenutzt stehen. + +--- + +## 5. Risiken + +| Risiko | Eintritt | Wirkung | Maßnahme | +|---|---|---|---| +| Verhaltensabweichung durch Umbau | mittel | falsche Schritte/Automatik | Golden Master, Fallmatrix, unveränderte Bestandstests, gemeinsame Abnahme | +| `pdo_sqlite` fehlt auf Strato | unbekannt | Tester ohne SQLite | V1 vor Beginn prüfen; Ausweichlösung eigene MariaDB-Datenbank (E4) | +| Sandbox-Leck durch neuen Effektweg (z. B. künftige direkte Netzverbindung) | gering | Schaden durch Tester | Schreibwächter + `preventStrayRequests` + `ModuleContractTest`; Regel: neue Effektwege nur über Framework-Fassaden (wie `MailTestModeGateTest` für Mail) | +| Laufzeit des Testers auf Shared Hosting | mittel | Zeitüberschreitung | Vorlage statt Migration, Ereignisgrenze, Laufzeitgrenze, schrittweise Läufe | +| SQLite/MariaDB-Abweichung in Rohabfragen | gering | Tester ≠ Betrieb in Randfällen | Sichtung in U-D, Paritätstest auf MariaDB in der CI (optional) | +| Konfigurator zu umfangreich | mittel | schlechte Bedienbarkeit | einfache Ansicht mit wenigen Feldern; Betreibertest in U-F (K08) | +| Parallele Arbeiten am selben Repo | mittel | Konflikte in `CaseActivities`/`ViewBooking` | Integrationszweig, `ZUSAMMENARBEIT.md`, U-A zuerst und zügig | + +--- + +## 6. Voraussetzungen + +| # | Voraussetzung | +|---|---| +| V1 | `pdo_sqlite` auf Strato (Test- und Produktivpaket) verfügbar – Prüfung mit `scripts/deploy.sh staging artisan` bzw. `php -m` auf dem Server | +| V2 | Entscheidungen E1–E9 (§9) getroffen | +| V3 | v0.11 auf stommer.info abgenommen ([Befund]: Release `7e4e208` ist auf dem Testsystem live; der Branch `feature/aufenthalt` liegt 112 Commits vor `main`, zuletzt lokal `ef2783e`) | +| V4 | Zusammenführungsstand der laufenden Feature-Zweige geklärt, damit U-A auf aktuellem Stand beginnt | +| V5 | Zuständigkeiten je Portal (welche Modelle zulässig) aus `docs/PORTALE.md` bestätigt (E2) | + +--- + +## 7. Gemeinsame Abnahmekriterien der Umsetzung + +1. N1–N7 erfüllt, wie in `05` §6 beschrieben. +2. K01–K08 (Konfigurator) und T01–T06 (Tester) auf stommer.info erfüllt. +3. Der Golden Master ist identisch. Die volle Suite und `process:check` sind ohne Befund. +4. Kein bestehender Vorgang und kein bestehender Kanal wurde durch das Deployment verändert. Das wird per Prüfsumme der Spalten `bookings.profile` und `channels.process_overrides` vorher und nachher festgestellt. +5. Betreiberfreigabe auf Grundlage des Abnahmeprotokolls. Der Konfigurator ist **betriebsfähig**, und der Tester ist **schadensfrei**; beides wird gemeinsam freigegeben. + +--- + +## 8. Was ausdrücklich nicht umgesetzt wird + +- Grafischer Designer, frei kombinierbare Bedingungen, Modellpflege in der Datenbank. +- Dynamisch geladene Fremdmodule, zweite Engine, neue Pakete. +- Konkrete Portal-API-Anbindungen. Es gibt nur Schnittstellen und einen Testadapter. +- Ein vollständiges Loyalty-Programm (Punkte, Stufen, Gastkonto). Es gibt nur die beiden Nachweismodule. +- Direktbuchung auf der Webseite (D6): Die Modellstelle `a1.direct_booking` ist vorgesehen, aber nicht wählbar. + +--- + +## 9. Offene Entscheidungen (vor der Implementierung) + +| # | Frage | Empfehlung | +|---|---|---| +| **E1** | Legt bei Buchungen (A3–A5) das gewählte Modell die Verantwortungen fest, oder bleiben die Einzelwerte `Documents`/`Payments` maßgeblich? | **Das Modell legt sie fest**: unzulässige Kombinationen sind dann ausgeschlossen. | +| **E2** | Welche Modelle sind je Portal zulässig (FeWo-direkt, Destination Solutions, weitere)? | Aus `PORTALE.md`/`R08`/`R09` ableiten und vom Betreiber bestätigen lassen. Vorschlag: FeWo-direkt Anfrage A2, Buchung A4 oder A5; Destination Solutions Buchung A3. | +| **E3** | Darf eine Kanaländerung in einen laufenden Vorgang übernommen werden? | **Nein.** Gilt nur für neue Vorgänge. | +| **E4** | Sandbox-Speicher: SQLite-Datei oder eigene MariaDB-Datenbank? | SQLite, wenn V1 erfüllt ist; sonst MariaDB. | +| **E5** | Loyalty bei Änderung einer verbindlichen Buchung? | Rabattzeile unverändert übernehmen, keine Neuberechnung; dazu ein Hinweis für eine manuelle Anpassung. | +| **E6** | Loyalty mit Sonderangeboten kombinierbar? | Vorgabe **nein**, der höhere Nachlass gilt; als Parameter einstellbar. | +| **E7** | Loyalty produktiv wählbar oder nur als Architekturnachweis? | Beide Module bauen. Variante wählbar, Vorgabe **aus**. Der Rabattsatz ist Pflichtangabe beim Einschalten. | +| **E8** | Wer darf den Tester nutzen, wie lange werden Berichte aufbewahrt? | Administratoren des Mandanten; 90 Tage. | +| **E9** | Wie viel darf der Vermieter an Szenarien verändern? | Nur vorgegebene Eingaben (Zeitraum, Personen, fehlende Felder, Stammgast ja/nein, Ausfallart); keine eigenen Ereignisfolgen. | + +### Einordnung der Punkte D1–D6 aus dem Vorschlag Kanalkonfigurator + +| # | Stand | +|---|---| +| D1 Preisanfrage als Eingangsart | bleibt: **keine** eigene Eingangsart; Modell `a1.information` / `a2.information` | +| D2 Schablone nach Anpassung | entfällt als Frage: Das Modell bleibt gewählt, abweichende Parameter tragen die Herkunft „hier gesetzt“. Die Kennzeichnung „angepasst“ zeigt der Konfigurator, wenn Werte von den Modellvorgaben abweichen. | +| D3 Mindestnachweis je Modell | **offen** (Vorgaben wie im Vorschlag empfohlen) | +| D4 akzeptierte Angaben je Kanal | **offen**; wird Parameter von `guest.details` je Kanal (nicht ausgewählte Felder → Vorschlag statt Übernahme) | +| D5 Berechtigung | bestätigt: Administratoren des Mandanten | +| D6 Direktbuchung Webseite | bleibt eigene Entscheidung nach Rechtsprüfung | diff --git a/docs/Prozessarchitektur/README.md b/docs/Prozessarchitektur/README.md index 4a71612..57c63e3 100644 --- a/docs/Prozessarchitektur/README.md +++ b/docs/Prozessarchitektur/README.md @@ -49,6 +49,7 @@ ## Geltung, Dokumente und Archiv - Die Dateien unter `Referenzen/` sind **Quellen- und Belegmaterial**, keine eigenständigen neuen Normen. Ihr historisches Versionsdatum bleibt unverändert. - Die **vollständige Original-v0.10 mit Originaldokumenten, Audit, damaligen Umsetzungs-/Abnahmeprotokollen, Screenshots und Vault-Dateien** liegt unverändert als [Historie/Prozessarchitektur_v0.10_ORIGINAL.zip](Historie/Prozessarchitektur_v0.10_ORIGINAL.zip) bei. Sie ist **nicht** parallel gültig. Ihre technischen und rechtlichen Prüfstände belegen nur v0.10. - Die Beschlussquelle für den neuen Bereich liegt in [Historie/CH_Entscheidungsstand_2026-11-03_v4.md](Historie/CH_Entscheidungsstand_2026-11-03_v4.md). Die normative aktuelle Regel ist die CH-Querschnittsdatei. +- Unter [Architektur/](Architektur/00_MANAGEMENT_ZUSAMMENFASSUNG.md) liegt der **Architektur- und Umsetzungsplan** für die modulare Prozessarchitektur (Fachmodule, Prozessmodelle, Kanalkonfigurator, Prozess-Tester). Er ist eine Planung und noch nicht normativ; er löst `Vorschläge/KANALKONFIGURATOR.md` als Zielbild ab. - Die [Konsolidierungsprüfung](KONSOLIDIERUNGSBERICHT_v0.11.md) erklärt Herkunft, Änderungen und technische Freigabevorbehalte. **Es wurde kein aktueller Repository-Code geprüft.** ## Offene Nachweise vor produktivem Go-live diff --git a/docs/Prozessarchitektur/Vorschläge/KANALKONFIGURATOR.md b/docs/Prozessarchitektur/Vorschläge/KANALKONFIGURATOR.md index 67d3143..21cc4d1 100644 --- a/docs/Prozessarchitektur/Vorschläge/KANALKONFIGURATOR.md +++ b/docs/Prozessarchitektur/Vorschläge/KANALKONFIGURATOR.md @@ -1,5 +1,7 @@ # Ergänzungsvorschlag: Kanalkonfigurator (Schablonen, Schritte, Nachweise, Vorschau) +> **Abgelöst als Zielbild** durch [Architektur/03_KANALKONFIGURATOR.md](../Architektur/03_KANALKONFIGURATOR.md) (Schablonen → Prozessmodelle; D1–D6 eingeordnet in [Architektur/06](../Architektur/06_MIGRATIONS_UND_UMSETZUNGSPLAN.md) §9). Dieser Text bleibt als Herleitung erhalten. + **Stand:** 04.11.2026 · **Status:** Vorschlag zur Ergänzung der Spezifikation v0.11, **nicht normativ**. Normativ wird er erst, wenn der Betreiber die offenen Entscheidungen (§9) trifft und der Inhalt in die betroffenen Kapitel übernommen ist (02 Abwicklungsprofile, Konfiguration und Wirksamkeit, Gates und Nachweise, Archetypen). Anlass: Abstimmung mit dem Betreiber am 03./04.11.2026. Heute gibt es am Kanal eine flache Liste von Einstellungen, deren Wirkung auf den Ablauf nicht erkennbar ist. Die Spezifikation fordert dagegen: „die konkreten Wirkungen und Herkunftswerte müssen sichtbar bleiben“ (02). Neue Portale verhalten sich unterschiedlich; künftig soll auch eine Direktbuchung auf der eigenen Webseite möglich sein. diff --git a/docs/STATUS.md b/docs/STATUS.md index 9c79757..51d1f28 100644 --- a/docs/STATUS.md +++ b/docs/STATUS.md @@ -24,6 +24,7 @@ ## Aktueller Stand (03.11.2026) - [Umsetzungsergebnis v0.11](Prozessarchitektur/Implementierungsstände/UMSETZUNGSERGEBNIS_V011.md) (Rückverfolgung, Entscheidungen, Einschränkungen, Go-live-Bedingungen); - [Abnahme auf dem Testsystem](Prozessarchitektur/Abnahme/V011_ABNAHME_TESTSYSTEM.md) (Dienste, Konfiguration, Drehbuch); - Planung: [Soll-Ist](Prozessarchitektur/Implementierungsstände/V011_SOLL_IST_ANALYSE.md), [Zielarchitektur](Prozessarchitektur/Implementierungsstände/V011_TECHNISCHE_ZIELARCHITEKTUR.md), [Umsetzungsplan](Prozessarchitektur/Implementierungsstände/V011_UMSETZUNGSPLAN.md). +- Nachfolgeplanung (04.11.2026, noch nicht umgesetzt): [Kontrolliert modulare Prozessarchitektur, Kanalkonfigurator und Prozess-Tester](Prozessarchitektur/Architektur/00_MANAGEMENT_ZUSAMMENFASSUNG.md) – Entscheidungen E1–E9 offen. **Nächste Schritte:** 1. Abstimmung mit dem Betreiber: Auslieferung von `feature/aufenthalt` über `develop` auf das Testsystem (vier neue Migrationen), eigenes IMAP-Postfach, KI-Zugang des Mandanten unter „System › KI-Anbindung“ (Dienst vorher im Betreiberbereich einschalten).