Files

50 KiB
Raw Permalink Blame History

02 – Fachmodul-Architektur: Module, Prozessmodelle, Erweiterungspunkte, Ausführung

Stand: 04.11.2026, Review V2 (Korrekturen K1–K4, K8, K10 eingearbeitet) · Kennzeichnung: [Befund], [Vorschlag], [Entschieden], [Entscheidung offen] (siehe 01)


1. Begriffe und Ebenen [Vorschlag]

Begriff Bedeutung Ort im Code
Archetyp (A1–A6) Geschäftsklassifikation aus Herkunft, Verbindlichkeit und den archetypbestimmenden Verantwortungen (03 §2.3). Er wird abgeleitet und plausibilisiert, er steuert keinen Schritt. CaseType, ProcessProfile::caseTypeFor (unverändert)
Fachmodul Wiederverwendbare fachliche Fähigkeit mit Vertrag. Es bietet einen oder mehrere Schritte an. app/Process/Modules/* (neu); ruft die bestehenden Actions auf
Prozessmodell Zentral definierte, versionierte Menge von Schritten mit fachlichen Abhängigkeiten und Erweiterungspunkten. Es legt den verbindlichen Rahmen fest, darunter die festen Verantwortungen. app/Process/Models/* (neu, PHP)
Prozessvariante Zulässige Ausprägung eines Modells: zusätzliche Module an Erweiterungspunkten. Sie hat denselben Archetyp. im Modell deklariert
Kanalkonfiguration Modell und Variante je Kanal × Eingangsart, dazu je Schritt: an/aus (nur optionale), Ausführungsart, Ausführende (nur innerhalb der zulässigen Menge), Parameter, Mindestnachweis channels.process_overrides[intake] (bestehende JSON-Spalte)
Prozessplan Beim Eingang eingefrorene Definition eines Vorgangs: Modell@Version, Variante, Modulversionen, Schrittschalter, Ausführende, Parameter mit Herkunft bookings.profile.plan (bestehende JSON-Spalte)

Ebene A = Module, B = Modelle/Varianten, C = Kanalkonfiguration, D = Ausführung (ProcessRunner) und Tester (04).


2. Modulgrenzen: Kriterien statt Sollzahl [Vorschlag, K2]

Der Katalog in §4 ist ein Startkatalog. Die Zahl der Module ergibt sich aus den fachlichen Verantwortungen und darf wachsen oder schrumpfen. Für jede neue Fähigkeit gilt die folgende Prüfreihenfolge. Die erste zutreffende Stufe entscheidet.

Stufe Wann Folge Beispiel
1 Parameter eines bestehenden Moduls Die Funktion nutzt dieselben Daten, dieselbe Pflichtfeldlogik und denselben Eingang wie das Modul. Sie hat kein eigenes Ergebnis mit eigener Bedeutung, keinen eigenen Wartezustand, keinen eigenen Effekt und keine eigene Fehlerbehandlung. Neuer Parameter in ModuleDefinition::parameters. Die Modulversion steigt nur, wenn sich das Verhalten bei unverändertem Parameterwert ändert. „Postleitzahl ist Pflicht“, „Anschrift erst vor dem Angebot“ → guest.details (FormRequiresAddress, CaseRequirements)
2 Erweiterung eines bestehenden Moduls Die Funktion gehört zur Verantwortung des Moduls. Sie ändert dessen Ergebnis oder Zustände, bleibt aber ohne eigenen Effekt nach außen und ohne eigenes Warten. Neue Modulversion (§5.3). Bestehende Pläne behalten die alte, falls die Änderung nicht als kompatibel deklariert ist. weitere Plausibilitätsprüfung im Fakteneingang
3 Neues Modul Mindestens zwei der folgenden Merkmale treffen zu: (a) eigenes fachliches Ergebnis, das andere Schritte lesen; (b) eigener Effekt nach außen (Netz, Mail, Dokument, Kalender); (c) eigener Warte- oder Fehlerzustand mit eigener Folge, etwa manueller Klärung; (d) eigener Nachweis; (e) soll je Kanal unabhängig an- oder abschaltbar sein. Neue Klasse, Registereintrag, Modultest, Platz an einem Erweiterungspunkt oder in einem Modell guest.loyalty_status (a, d, e); guest.address_verification (a, b, c, d, e)
4 Neuer Erweiterungspunkt Ein neues Modul muss an einer Stelle wirken, an der kein vorhandener Punkt garantiert, was es braucht: Datenlage, Phase vor oder nach einer Verbindlichkeitsgrenze. Änderung aller Modelle, die den Punkt anbieten sollen, mit Modelltests. Das ist eine Architekturänderung; sie wird im PR begründet. — (Loyalty und Adressprüfung kommen mit den vorhandenen Punkten aus)

Querschnittsdienste (Preisberechnung, Mail-Schranke, Verlauf, Mandant, Nachrichtenzuordnung) sind keine Schritte. Module nutzen sie, und im Konfigurator erscheinen sie nicht.

2.1 Prüffall Adressprüfung (nicht Teil der Umsetzung)

guest.address_verification erfüllt Stufe 3:

  • Ergebnis: verified, corrected, rejected oder unknown als Fakt mit Herkunft.
  • Effekt: HTTP-Aufruf eines Prüfdienstes über die Http-Fassade.
  • Wartezustand: Waiting (Dienst nicht erreichbar, nächster Versuch), daraus eine Aufgabe „Anschrift klären“.
  • Nachweis: Antwort des Dienstes im Verlauf.
  • Schaltbarkeit: je Kanal an oder aus.

Einbau ohne Umbau anderer Archetypen:

  1. Platz am vorhandenen Punkt AfterGuestIdentified. Das Modul hat requires: guest.details (Anschrift vorhanden) und blocksDependents: false. Ein unknown hält damit nicht das Angebot auf; ob ein rejected das Angebot aufhält, ist ein Modulparameter.
  2. Varianten mit dem Modul nur in den Modellen, die es nutzen sollen (z. B. a1.offer:address_check). A2–A6 bleiben unberührt. Für Portalbuchungen (A3–A5) bliebe die Verbindlichkeit unberührt: Das Modul darf dort nur prüfen und Aufgaben erzeugen, nie den Vorgang anhalten (Wächter respectsExternalBinding, §3.2).
  3. Der Tester simuliert den Dienst über Http::fake (04 §3).

Dasselbe Muster gilt für guest.loyalty_status (§6). Beide Prüffälle brauchen keinen neuen Erweiterungspunkt.


3. Modulvertrag [Vorschlag]

3.1 Technische Form

Der Vertrag besteht aus PHP-Klassen. Es gibt kein JSON, keine Datenbank und kein Paket.

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, derived from case data; includes what it waits for and until when (§7.2). */
    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;
}

interface ContributesToPrice
{
    /** Lines added before the price is fixed; CasePricing never calls this for a binding case. */
    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 (now(); im Tester simuliert). Module halten keinen eigenen Zustand. Der Zustand steht weiter in bookings, case_facts, booking_tasks, data_requests und booking_events.

3.2 Pflichtangaben in ModuleDefinition und wie sie geprüft werden

Ein Vertragsfeld verspricht nur, was ein Test technisch prüfen kann. Die Spalte „Prüfung“ sagt, womit. Felder ohne automatische Prüfung sind ausdrücklich beschreibend; sie werden im Review geprüft und begründen keine Sicherheitszusage.

Feld Inhalt (Beispiel offer.binding) Prüfung
key, version offer.binding / 1 process:check: eindeutig, im Register
purpose „Verbindliches Angebot mit Vertragsentwurf erstellen und senden“ beschreibend
needs CaseRequirements::OFFER, Zeitraum, Gästezahl, E-Mail Modultest: fehlt eine Angabe, ist blockers nicht leer
produces offer_version, quote, offer_terms, Status OfferSent Modultest nach run
requires Schritte, die Done sein müssen, bevor dieser bereit ist: guest.details, availability.check process:check (jedes Modell erfüllbar), Runner-Test (§7)
blocksDependents ob ein Warten oder Problem dieses Schritts abhängige Schritte aufhält (Vorgabe ja) Runner-Test
phases P02 process:check
points erlaubte Erweiterungspunkte process:check
effects CaseWrite, GuestMail, Document, CalendarHold ModuleContractTest im Tester: Effekt-Ledger enthält nur deklarierte Arten. Grenze: Das prüft nur die in den Testfällen durchlaufenen Pfade.
waits worauf der Schritt warten kann (Gast, Portal, Vermieter, Zeit) und welche Daten die Frist tragen Modultest je Wartezustand
triggers Ereignisse, nach denen der Runner neu bewertet (facts.applied, offer.accepted, Zeit) process:check gegen die Liste der Auslöser (§7.4)
idempotency expected_version; erneuter Lauf ohne Wirkung ModuleContractTest: zweiter run erzeugt keinen Effekt
parameters Processing, HoldHours process:check: gültige ProcessSetting/ModuleParameter, Grenzen
toggle Mandatory / Optional(defaultOn) / Conditional / EventDriven ConfigureChannelProcess-Test: Mandatory lässt sich nicht abschalten
performers zulässige Ausführende und welche davon das Modell festlegt (03 §2.3) process:check gegen die Verantwortungsmatrix
modes automatisch / nach Freigabe / manuell Konfigurator-Test
guards z. B. „nie ohne Verfügbarkeit“, respectsExternalBinding je Wächter ein benannter Test; ohne Test kein Wächter
availability Production oder TesterOnly (§6.3) ConfigureChannelProcess und ProcessPlan::freeze weisen TesterOnly außerhalb des Testers ab (Test)

Der generische ModuleContractTest prüft für jedes registrierte Modul:

  • Die Definition ist vollständig.
  • applies, activity und blockers schreiben nichts (Abfrageprotokoll ohne Schreibanweisung).
  • run erzeugt nur die deklarierten Effektarten.
  • Ein zweiter run ist wirkungslos.

Er ersetzt nicht die Modultests; er fängt vergessene Deklarationen.


4. Fachmodulkatalog (Startumfang)

Spalte „heute“ = [Befund], Rest = [Vorschlag]. Schlüssel in Klammern = heutige Schrittschlüssel in CaseActivities. Spalte „requires“ ist die fachliche Abhängigkeit für die Bereitschaft (§7).

P01 Eingang und Daten

Modul Aufgabe heute requires Aktivierung
intake.record (intake) Eingang festhalten, Plan einfrieren; setzt unter der Kalendersperre die Reservierung des Eingangs (RequestHold::for) CreateReservation, TakeOverPortalInquiry, TakeOverExternalBooking, CaseRecorder::freeze – Pflicht
guest.details (contact) Gast identifizieren, Angaben zusammenführen und prüfen ContributeCaseFacts, ProvideGuestContact, CaseRequirements, AssignOccupationGuest intake.record Pflicht, wenn wir mit dem Gast korrespondieren
guest.data_request (data_request) Fehlende Angaben beim Gast anfragen, erinnern, übergeben RequestCaseData (forNextStep, remindDue, handOver) intake.record; läuft nur, solange guest.details fehlt Optional
guest.loyalty_status (neu) Stammgaststatus ermitteln – guest.details (E-Mail) Optional, TesterOnly (§6)

P01/P02 Belegung und Verbindlichkeit

Modul Aufgabe heute requires Aktivierung
availability.check Zeitraum frei, Kanäle aktuell AvailabilityChecker, CalendarClearance – Pflicht
hold Klärungs- bzw. Angebotsreservierung überwachen: Frist, Ablauf, Freigabe. Gesetzt wird sie von intake.record und SendOffer. RequestHold, ExpireReservations, ReleaseReservation intake.record (nicht guest.details) Bedingt (Anfrage mit Vorreservierung)
binding.portal (binding, price) Verbindlichkeit beim Portal feststellen, Portalpreis TakeOverExternalBooking, PortalIntake, RecordPortalAmounts intake.record Pflicht bei Eingangsart Buchung
channels.block (channel_block) Andere Kanäle sperren/freigeben CreateChannelTasks, Observer, RemindChannelTasks belegungswirksamer Status Pflicht

P02 Preis, Angebot und Annahme

Modul Aufgabe heute requires Aktivierung
pricing.loyalty_discount (neu) Stammgastrabatt als Preiszeile – guest.loyalty_status Optional, TesterOnly
offer.information (information, wish, wish_check) Auskunft → Buchungswunsch → verbindlich bestätigen SendInformation, SubmitBookingWish, DecideBookingWish guest.details (E-Mail), availability.check Alternative zu offer.binding
offer.binding (offer) Verbindliches Angebot erstellen und senden SendOffer, OfferTerms, DocumentComposer, AutoOffer::blockers guest.details (alle Angebotsangaben), availability.check Alternative zu offer.information
offer.acceptance (acceptance) Annahme/Ablehnung, dann Bestätigung AcceptOffer, RejectOffer, ConfirmBooking offer.binding Pflicht nach offer.binding

P03 Abwicklung und Geld

Modul Aufgabe heute requires Aktivierung
documents.send (documents) Buchungsunterlagen an den Gast SendBookingDocuments, RentalContract, CaseAutomation::documentBlockers Verbindlichkeit, guest.details (E-Mail), Gesamtpreis Ausführende laut Modell (03 §2.3)
payments.monitor (payment, deposit, balance) Zahlungen überwachen, erinnern RecordPayment, SendBookingReminders, SendPaymentReminder Verbindlichkeit Ausführende laut Modell
portal.payout (payout) Auszahlung des Portals prüfen RecordPortalAmounts, CaseMoney Verbindlichkeit Bedingt (Payments = Portal)
change.proposal (change_proposed) Änderungsvorschlag beim Gast ChangeBooking – Ereignisgetrieben (§4.1)

P04 Aufenthalt und P05 Abschluss

Modul Aufgabe heute requires Aktivierung
arrival.details (arrival_details) Anreisedaten, Dienstleister PrepareStays Verbindlichkeit Optional
arrival.info (arrival_info) Anreise-Informationen PrepareStays, SendBookingReminders Verbindlichkeit, E-Mail Ausführende variabel
stay (stay) Aufenthalt CloseStay Verbindlichkeit Pflicht
review.request (review) Bitte um Bewertung RequestReviews stay Optional
case.closure (closure) Aufenthalt abschließen CaseClosure stay Pflicht
case.settlement (settlement) Kaufmännisch abschließen, Nachweise prüfen CaseClosure case.closure Pflicht

4.1 Ereignisgetriebene Sonderprozesse [Vorschlag]

Stornierung (CancelBooking, CancelBookingByGuest, RecordCancellation), Änderung (ChangeBooking), Portalmeldungen (Aufgaben PortalCancellationReported, PortalChangeReported) und Ablauf (ExpireReservations) laufen quer zum Plan. Sie sind Module mit toggle = EventDriven ohne festen Platz. Ihre Actions bleiben. Wie sie mit dem Runner zusammenwirken, beschreibt §7.3.

4.2 Querschnittsdienste und interne Belegungen

  • Querschnittsdienste: pricing (PriceCalculator + neue Fassade CasePricing), messages (ReceiveInboundMessage, MessageMatcher, ExtractMessageFacts), mail (Laravel-Mailer + EnforceMailTestMode), log (CaseLog, CaseRecorder), tenancy (TenantContext, TenantConfig).
  • Interne Belegungen: CaseActivities::internal() wird zum Modell a6.internal (intake.record, channels.block, documents.send optional, payments.monitor ohne Erinnerungen, stay, case.closure). Es gibt keine Kanalkonfiguration.

5. Prozessmodelle, Varianten, Erweiterungspunkte, Versionierung [Vorschlag]

5.1 Definition im Code

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']; }

    /** Responsibilities fixed by the model, and the ones the channel may choose within the frame (03 §2.3). */
    public static function responsibilities(): Responsibilities
    {
        return Responsibilities::fixed(contract: Landlord, collection: Landlord, contractDocuments: Landlord)
            ->variable(guestMessages: [Landlord], arrivalInfo: [Landlord, ServiceProvider], localServices: [Landlord, ServiceProvider]);
    }

    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 (Architekturnachweis)')
                ->testerOnly()
                ->insert(Point::AfterGuestIdentified, 'guest.loyalty_status')
                ->insert(Point::BeforePriceFixing, 'pricing.loyalty_discount'),
        ];
    }
}

Die Reihenfolge der Schritte ist die Anzeige- und Lesereihenfolge. Was wann laufen darf, bestimmen die requires der Module (§7). Die Erweiterungspunkte sind fest: AfterGuestIdentified, BeforePriceFixing, BeforeBindingOffer, AfterBinding, BeforeStay, BeforeSettlement. BeforePriceFixing garantiert, dass der Fall nicht verbindlich ist; AfterBinding garantiert das Gegenteil. ProcessCatalogue::validate() prüft Punkte, Abhängigkeiten und Verantwortungen in process:check und im Test.

5.2 Modellkatalog (Startumfang)

Modell Archetyp Eingang Ersetzt heutigen Zweig
a1.offer (Varianten standard, loyalty = nur Tester) A1 Anfrage, direkt/Webseite preReservation() = true
a1.information A1 Anfrage, direkt/Webseite preReservation() = false
a2.offer, a2.information A2 Anfrage über Portal wie A1, Eingang über TakeOverPortalInquiry
a3.portal_booking A3 Buchung Verträge, Inkasso und Dokumente beim Vermieter
a4.portal_booking A4 Buchung Inkasso beim Portal, Vertragsdokumentation beim Vermieter
a5.portal_booking A5 Buchung Inkasso und Vertragsdokumentation beim Portal
a6.internal A6 intern CaseActivities::internal()

A2 nutzt dieselben Module wie A1; gemeinsame Schrittfolgen teilt die Basisklasse. [Entschieden E1] Das gewählte Modell legt die Grundverantwortungen fest; innerhalb des Modells bleiben die ausdrücklich zugelassenen Varianten von Kommunikation, Dokumenten und lokalen Dienstleistungen konfigurierbar (03 §2.3). caseTypeFor bleibt als Plausibilitätsprüfung.

5.3 Versionierung und Schutz laufender Vorgänge (K3)

Ein eingefrorener Plan schützt die Definition, nicht das Codeverhalten. Deshalb werden vier Ebenen unterschieden:

Ebene Inhalt Wo eingefroren Darf ein neues Release sie ändern?
E-V Vertragliche Daten und Zusagen Preiszeilen (quote), Gesamtpreis (total), Bedingungen und Vorlagenversion (offer_terms: Texte, Stornoregel, Anzahlungsfrist), Annahmeprotokoll mit terms_sha256 (acceptance), Fälligkeiten (deposit_due_on, balance_due_on), Portalbeträge „laut Portal“ (booking_amounts), erzeugte Vertrags-PDFs (contract_path) [Befund] Spalten der Buchung, beim Angebot bzw. bei der Bestätigung Nie. Nur eine fachliche Action mit Protokoll (ChangeBooking, Adjustment-Zeile, RecordPortalAmounts mit Quelle)
E-P Prozessdefinition und Parameter Modell@Version, Variante, Modulversionen, Schalter, Ausführende, Parameterwerte, Fristen in Stunden/Minuten profile und profile.plan beim Eingang Nein für laufende Vorgänge [Entschieden E3]. Ausnahme: Ebene E-K.
E-I Technische Implementierung Code der Actions, Module, Dienste, Ansichten, Mail-Texte nicht eingefroren Ja, solange sie Ebene E-V nicht anders auswertet (Kompatibilitätsregel R1)
E-K Fehlerkorrektur Korrektur nachweislich falschen Verhaltens, das bestehende Vorgänge betrifft – Ja, aber nur als deklarierte Korrektur mit Wirkungsprüfung (R4)

Kompatibilitätsregeln

  • R1 – Auswertung eingefrorener Vertragsdaten ist Vertragsbestandteil. Code, der E-V-Daten auswertet, muss für vorhandene Vorgänge dasselbe Ergebnis liefern wie zuvor. Beispiele:

    • CancellationCost::calculate (Stornostaffel aus offer_terms, Grundlage aus quote-Zeilen);
    • CancellationPolicy::tierFor;
    • Anzahlungs- und Restbetrag;
    • ContractPlaceholders (Vertragstext aus offer_terms).

    Eine Änderung, die das Ergebnis ändern würde, wird versioniert: Die neue Logik gilt ab einem Merkmal im eingefrorenen Datensatz, etwa offer_terms.rules_version. Alte Datensätze ohne Merkmal werden mit der bisherigen Logik ausgewertet.

  • R2 – Modulversionen. Ein Modul mit fachlich wirksamer Änderung bekommt eine neue Version. Pläne mit der alten Version führen die alte Klasse weiter (z. B. LoyaltyDiscountV1), außer das neue Modul deklariert compatibleWith: [1] und besteht den Bestandsfall-Test (§5.4) für Version 1.

  • R3 – Actions bleiben gemeinsam. Es gibt keine Kopie alter Actions je Release. Eine Action-Änderung darf das Verhalten laufender Vorgänge ändern, wenn sie (a) E-V-Daten nicht anders auswertet (R1), (b) keine bereits getroffene Statusentscheidung zurücknimmt und (c) die Bestandsfall-Tests unverändert bestehen.

  • R4 – Fehlerkorrektur mit Wirkung auf Bestandsfälle ist zulässig, wenn

    • der Fehler im Fehlerregister steht (05 §4.3),
    • der PR die betroffenen Bestandsfälle zählt (Abfrage, keine Datenänderung),
    • die geänderte Erwartung im Bestandsfall-Test begründet ist.

    Geld- und Fristwirkungen auf bereits verbindliche Vorgänge werden nicht durch Code korrigiert, sondern als Aufgabe für den Vermieter ausgewiesen.

  • R5 – Kein Neuberechnen. Kein Release berechnet Preise, Rabatte, Fristen oder Status bestehender Vorgänge neu, außer eine fachliche Action wird ausdrücklich ausgelöst.

  • R6 – Aufbewahrung alter Versionen (T3, entschieden). Eine Modellversion bleibt registriert, solange irgendein Vorgang – auch ein abgeschlossener – sie im Plan trägt; process:check --cases prüft das. Der Plan speichert zusätzlich die Bezeichnungen seiner Schritte. Wird ein Modul dennoch einmal entfernt, erscheint sein Schritt bei abgeschlossenen Vorgängen als „(frühere Fassung)“; eine fehlende Modellversion fällt beim Lesen auf die aktuelle Definition desselben Modells zurück (ProcessPlan::isHistoric). Alte Programmlogik muss nicht ausführbar bleiben; offene Vorgänge brauchen ihre Modulversion (oder eine als kompatibel erklärte, config/process.php › compatible).

Es wird nicht verlangt, frühere Anwendungsversionen vollständig zu betreiben. Ältere Vorgänge werden sicher weitergeführt, weil

  1. ihre Vertragsdaten eingefroren sind,
  2. deren Auswertung nach R1 stabil bleibt,
  3. ihre Prozessdefinition eingefroren ist,
  4. die Bestandsfall-Tests das bei jedem Release prüfen.

5.4 Bestandsfall-Tests (Regression für laufende Vorgänge)

OngoingCaseRegressionTest arbeitet mit eingefrorenen Bestandsfällen, nicht mit Factories des aktuellen Codes:

  • Fixtures: Etwa 40 Buchungsdatensätze als JSON-Fixtures (tests/Fixtures/ongoing/*.json). Sie wurden einmalig mit dem v0.11-Stand erzeugt und enthalten die Zeilen von bookings, case_facts, data_requests, booking_amounts, payments und booking_tasks. Es sind synthetische Daten, keine Kundendaten.
  • Abdeckung: jeder Archetyp × die Status Reserved (Klärungs- und Angebotsreservierung), OfferSent, Confirmed mit offener Anzahlung, Confirmed nach Anreise, Cancelled mit Stornoregel, A4 mit Portalraten, origin = migration.
  • Prüfungen je Fixture, bei fester Uhr:
    • unverändert: total, quote-Zeilen, offer_terms, acceptance;
    • gleich wie die gespeicherte Erwartung: CancellationCost::calculate an drei Stichtagen, Anzahlungs- und Restbetrag, Fälligkeiten, Hash des gerenderten Vertragstexts (RentalContract::render, Entwurf);
    • gleich wie die gespeicherte Erwartung: ProcessRunner::activities und die Entscheidung von advance (läuft/läuft nicht, Blocker);
    • nach advance keine Änderung an E-V-Spalten.
  • Ausführung: Der Test läuft in jeder CI. Eine Abweichung ist nur mit Eintrag intended und Verweis auf R1–R4 zulässig.

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


6. Architektur-Nachweis Loyalty (N3, K8)

6.1 Status

[Entschieden E5–E7] Loyalty ist ein Erweiterbarkeitsnachweis, kein freigegebenes Rabattprogramm:

  • Die Variante a1.offer:loyalty und beide Module tragen availability = TesterOnly. Für echte Buchungen sind sie nicht aktivierbar.
  • Berechtigung, Gastidentifikation, Staffel, Kombination mit Sonderangeboten und Umbuchung sind nicht als Geschäftsregel freigegeben.
  • Die Tests arbeiten mit ausdrücklich vorgegebenem Verhalten, das als Testannahme gekennzeichnet ist.
  • Für eine spätere produktive Freigabe braucht es eigene fachliche Regeln, Tests und eine Entscheidung. Technisch genügt dann der Wechsel auf Production (neue Modulversion).

6.2 Ablauf in der Variante (Testannahmen)

  1. guest.details identifiziert den Gast (E-Mail).
  2. guest.loyalty_status (Punkt AfterGuestIdentified) zählt abgeschlossene, nicht stornierte Aufenthalte desselben Gastes beim selben Mandanten.
    • Ergebnis Qualified, NotQualified oder Unknown als Fakt loyalty_status über ContributeCaseFacts (neue FactSource::System), mit Beleg (Referenzen der Aufenthalte).
    • blocksDependents = false: Ein Unknown hält den Angebotsschritt nicht auf.
  3. pricing.loyalty_discount (Punkt BeforePriceFixing, ContributesToPrice) liefert bei Qualified eine QuoteLine(QuoteLineType::Discount, …).
    • Testannahme E6: Bei Sonderangebot keine Zeile.
    • Bei NotQualified/Unknown keine Zeile; bei Unknown ein Hinweis im Schritt.
    • Der Angebotsversand wird nie blockiert.
  4. offer.binding → SendOffer; SendOffer::quoteFor holt den Preis über CasePricing::quote($booking, $stay). Die Zeile steht damit in quote, im Vertragsentwurf und im Verlauf.
  5. Ab Verbindlichkeit ist der Preis fest. CasePricing ruft für verbindliche Fälle keine Beiträge auf (Test). Bei ChangeBooking bleibt die gespeicherte Rabattzeile eingefroren (E5); die spätere Regel ist offen.
  6. Hinweis R1: CancellationCost::rent zählt Discount-Zeilen zur Stornogrundlage [Befund]. Eine Rabattzeile senkt also auch die Stornogebühr. Für den Nachweis ist das Testannahme; vor einer Freigabe ist es fachlich zu entscheiden.

6.3 Nicht aktivierbar für echte Buchungen – technische Umsetzung

Stelle Prüfung Test
ConfigureChannelProcess weist Speichern einer TesterOnly-Variante oder eines TesterOnly-Moduls ab LoyaltyNotActivatableTest::configurator_rejects
ProcessPlan::freeze weist TesterOnly ab, außer im Sandbox-Kontext (04 §3.3) LoyaltyNotActivatableTest::freeze_rejects_outside_sandbox
Konfigurator zeigt Variante und Schritte mit Kennzeichen „nur im Prozess-Tester“; im Entwurf schaltbar, Speichern gesperrt Livewire-Test
Tester spielt standard und loyalty durch (S09, S10) Paritätstest

6.4 Was geändert wird und was unverändert bleibt

Komponente Änderung
LoyaltyStatusCheck, LoyaltyDiscount neu
A1OfferModel::variants() +1 Variante
config/process.php +2 Einträge
FactSource +1 Fall System
Tests LoyaltyStatusCheckTest, LoyaltyDiscountTest, LoyaltyNotActivatableTest, Szenarien S09/S10 neu
PriceCalculator, PriceQuote, QuoteLine, QuoteLineType, CancellationCost unverändert
SendOffer, AcceptOffer, ConfirmBooking, DocumentComposer, RentalContract durch Loyalty unverändert (die Umstellung von SendOffer::quoteFor auf CasePricing geschieht vorher in U-B, siehe unten)
ProcessRunner, Konfigurator, Tester unverändert; sie lesen Variante und Parameter aus der Definition
Modelle a1.information, a2.*, a3–a6 unverändert

Einmalige Voraussetzung (kein Loyalty-Code), Paket U-B: die Fassade CasePricing mit dem Punkt BeforePriceFixing. Ihre Aufrufer werden geändert:

  • SendOffer::quoteFor;
  • SendInformation;
  • DecideBookingWish;
  • CreateReservation (Richtpreis);
  • ChangeBooking (nur nicht verbindliche Fälle).

Ohne Beiträge liefert CasePricing genau PriceCalculator::calculate (Gleichheitstest).


7. Ausführungslogik (K1) [Vorschlag]

7.0 Umsetzung T1 (entschieden)

  • Harte Abhängigkeit (Dependency::hard): Der Schritt läuft erst, wenn der andere Done ist. Ein nicht zutreffender oder (nur bei optionalen Schritten möglich) abgeschalteter Schritt erfüllt sie, weil seine Bedingung den Fall nicht betrifft. blocksDependents gibt es nicht: Die Kante entscheidet, nicht der wartende Schritt.
  • Weiche Abhängigkeit (Dependency::soft): Sind beide in derselben Runde bereit, läuft die weiche Voraussetzung zuerst. Wartet oder scheitert sie, läuft der Schritt trotzdem.
  • Unabhängig: keine Kante. Bedingt: applies().
  • Neubewertung: genau ein Schritt je Runde, danach wird der Vorgang neu gelesen. Eine Liste bereiter Schritte wird nie über eine Zustandsänderung weitergereicht.
  • Auslöser: Die Module erklären, nach welchen Ereignissen sie bewertet werden (triggers). Der Runner berücksichtigt nur passende Module.
  • Pflichttests: ProcessRunnerTest (u. a. Zustandsänderung während einer Runde), ProcessCoreTest (Klärungsreservierung parallel zur Datenbeschaffung, Adressprüfung mit Wartezustand), LoyaltyArchitectureProofTest (Preis nach Loyalty-Prüfung).

7.1 Grundsatz: eine Wahrheit, abgeleitete Bereitschaft

  • Zustand jedes Schritts wird wie heute aus den Falldaten abgeleitet: Status, Versionen, Zeitstempel, data_requests, case_facts, booking_tasks. Der Runner speichert keinen Schrittzustand. Es gibt also keine zweite Wahrheit.
  • Bereitschaft wird bei jeder Bewertung neu berechnet: Ein Schritt ist bereit, wenn
    • er im Plan aktiv ist und applies gilt,
    • sein Zustand Open ist,
    • alle requires Done sind (oder NotApplicable, wo das Modul das zulässt),
    • blockers leer ist.
  • Unabhängigkeit: Ein wartender Schritt hält nur Schritte auf, die ihn in requires führen und für die er blocksDependents = true hat. Alle anderen bereiten Schritte laufen.
  • Die Reihenfolge im Modell bestimmt nur die Ausführungsreihenfolge innerhalb einer Bewertungsrunde und die Anzeige.

7.2 Zustandsarten

Art Darstellung (ActivityState) Bedeutung für den Runner Beispiel
sequenziell Later bis die Voraussetzung Done ist nicht bereit Angebot vor vollständigen Angaben
bedingt nicht in der Liste (applies = false) oder NotApplicable übersprungen mit Grund Auszahlung nur bei Portal-Inkasso
unabhängig eigene requires läuft, auch wenn anderes wartet Klärungsreservierung überwacht ihre Frist, während die Rückfrage wartet
Warten auf Gast/Portal/Vermieter Waiting + waitsFor + until nicht bereit; bewertet neu bei Ereignis oder Frist Rückfrage offen bis next_reminder_at
Frist Waiting mit until; nach Ablauf führt die Zeit-Action die Wirkung aus nur die zuständige Action schreibt (z. B. ExpireReservations) Angebotsreservierung abgelaufen
manuelle Freigabe Open mit Aktion (approve…) bei Modus „nach Freigabe“ der Runner führt nicht aus; die Freigabe ruft dasselbe run und danach advance Rückfrage-Entwurf freigeben
Problem Problem nicht bereit; Aufgabe für den Vermieter Zeitraum inzwischen belegt

7.3 Ablauf von advance

ProcessRunner::advance(Booking): AdvanceResult
    lock case (Cache::lock "case-advance:{id}", short; actions keep their own guards)
    repeat at most |steps| rounds:
        activities = derive all steps (same derivation as activities())
        if an open urgent event task suspends automation (§7.5): stop, report it
        ready = steps in model order whose mode is automatic and that are ready (§7.1)
        if ready is empty: stop
        for step in ready:
            result = module.run(ctx) inside CaseLog::context(actor: system)
            record result (ran / blocked / failed); a failed step does not stop independent steps
        refresh booking
    return ran steps, blockers per waiting/blocked step (shown as tasks, as today)
  • Begrenzt: höchstens so viele Runden wie Schritte. Jeder run ist idempotent; ein Schritt, der in einer Runde lief, läuft in derselben Bewertung nicht erneut.
  • Fehler: Eine Ausnahme in einem Schritt wird gemeldet (report). Der Schritt erscheint als „technischer Fehler, bitte von Hand fortsetzen“, wie heute in CaseAutomation::advance. Unabhängige Schritte laufen weiter.
  • Nebenläufigkeit: Die Actions behalten ihre Schutzmechanismen (expected_version, lockForUpdate). Die Sperre je Vorgang verhindert nur doppelte Bewertung bei gleichzeitigen Auslösern.
  • origin = migration: wie heute keine Automatik.

7.4 Auslöser: vorhandene Stellen, keine neue Engine

Die Automatik ist heute verteilt [Befund]:

  • CaseAutomation::advance kennt nur zwei Fälle: Angebot/Auskunft und Unterlagen.
  • Aufgerufen wird es von ContributeCaseFacts, RecordPortalAmounts, TakeOverExternalBooking, TakeOverPortalInquiry und ViewBooking.
  • CreateReservation::sendMails ruft AutoOffer und danach RequestCaseData::forNextStep direkt auf, ebenso SubmitBookingWish und TakeOverExternalBooking die Datenanfrage.
  • Zeitgesteuert laufen bookings:auto-offers (AutoOffer direkt), cases:data-requests (RequestCaseData::remindDue) und bookings:expire-holds (ExpireReservations, ohne advance).

Umstellung in U-A:

Auslöser heute künftig
CaseAutomation::advance (5 Aufrufer) Fassade auf ProcessRunner::advance; Aufrufer unverändert
direkte Aufrufe AutoOffer + RequestCaseData::forNextStep in CreateReservation, SubmitBookingWish, TakeOverExternalBooking ein Aufruf ProcessRunner::advance. Die Datenanfrage und das Angebot sind dann zwei Schritte mit eigenen requires. Die Mailregel „Rückfrage ersetzt die Eingangsbestätigung“ bleibt in CreateReservation und liest das AdvanceResult. Gesichert ist das durch einen Golden-Master-Vergleich der Kommunikationsaufträge (05 §4).
bookings:auto-offers gleicher Eintrag und gleiche Fallauswahl; ruft advance statt AutoOffer
cases:data-requests, bookings:expire-holds, Erinnerungen, Bewertungen unverändert. Diese Actions schreiben ihre Wirkung selbst. Wo danach etwas Neues bereit werden kann (Übergabe einer stummen Rückfrage, Ablauf einer Angebotsfrist), rufen sie advance für den betroffenen Vorgang.
Eingang eines Kanalereignisses (02 §8) über die bestehenden Actions, die schon advance rufen

Es entsteht kein neuer Scheduler-Eintrag und keine Ereignis-Warteschlange.

7.5 Ereignisgetriebene Sonderprozesse im Runner

  • Storno, Änderung und Portalmeldungen haben keinen Planplatz. Sie erscheinen als Aufgabe (heute URGENT in CaseActivities) und werden zuerst angezeigt.
  • [Entscheidung offen O4] Eine offene Meldung „Portal meldet Stornierung/Änderung“ setzt automatische Außenwirkungen des Vorgangs aus, bis sie geklärt ist: Unterlagen, Erinnerungen, Anreiseinformation. Die Vorbereitung im System bleibt erlaubt. Das ist eine beabsichtigte Abweichung von v0.11 und braucht einen Test sowie einen Eintrag im Golden Master. Empfehlung: ja.
  • Nach der fachlichen Entscheidung über die Meldung (CancelBooking, ChangeBooking oder Verwerfen) ruft die Action advance.

7.6 Nachweis-Szenario K1: fehlende Anschrift, Klärungsreservierung, Rückfrage, Fristablauf, spätere Antwort

Annahmen: A1, Webseite, a1.offer@1, Automatik an, FormRequiresAddress = vor dem Angebot, ClarificationHoldAutoMinutes = 120, DataRequestReminderHours = 24, DataRequestRemindersMax = 2, HoldHours = 72.

Zeit Ereignis Wirkung (Action, unverändert) Schritte danach (abgeleitet) Runner
Fr 18:00 Anfrage ohne Anschrift (CreateReservation) unter Kalendersperre: Klärungsreservierung bis 20:00 (RequestHold::for, qualifiziert: Wohnung, Zeitraum, E-Mail) guest.details Open (fehlt Anschrift); hold Waiting bis 20:00; offer.binding Later (requires guest.details) bereit: guest.data_request → Rückfrage per Link; die Rückfrage ersetzt die Eingangsbestätigung. offer.binding nicht bereit. hold läuft unabhängig.
Fr 18:00 – – guest.details Waiting (waitsFor: guest, bis Erinnerung Sa 18:00) nichts mehr bereit
Fr 20:00 Frist der Klärungsreservierung Kalender ist frei, weil isHoldActive false ist. ExpireReservations lässt den Vorgang bewusst offen (nur HOLD_OFFER läuft ab) [Befund]. hold Done („Klärungsreservierung abgelaufen, Zeitraum nicht mehr reserviert“); Anfrage bleibt Reserved –
Sa 18:00 cases:data-requests Erinnerung 1 (remindDue) guest.details Waiting bis So 18:00 –
So 11:00 Gast antwortet per Mail mit Anschrift ReceiveInboundMessage → ExtractMessageFacts → ContributeCaseFacts (Quelle E-Mail, Übernahme nach Regel) → advance guest.details Done; Rückfrage wird geschlossen (Listener ContinueDataRequest, heute) bereit: offer.binding. blockers = AutoOffer::blockers: Klärungsreservierung abgelaufen ist zulässig ($clarified), der Zeitraum wird geprüft.
So 11:00 a) Zeitraum frei SendOffer mit neuer Angebotsreservierung (72 h, HOLD_OFFER) offer.binding Done, offer.acceptance Waiting (Gast) fertig
So 11:00 b) Zeitraum inzwischen belegt kein Versand offer.binding Problem „Der Zeitraum ist inzwischen belegt.“ → Aufgabe fertig; der Vermieter entscheidet (Alternativtermin, Absage)
So 18:00 (falls keine Antwort) cases:data-requests Erinnerung 2; nach dem Maximum handOver → Aufgabe „Gast antwortet nicht“ guest.details Open (Vermieter trägt ein oder schließt ab) advance nach Übergabe: nichts bereit
Mi 11:00 Angebotsfrist (Fall a) ExpireReservations → Expired alle offenen Schritte NotApplicable ($later-Regel) –

Testnachweis: RunnerIndependentStepsTest spielt die Tabelle mit fester Uhr durch. Geprüft werden je Zeile die Schrittzustände, die Bereitschaft, die ausgeführten Actions und die Mails. Er läuft zusätzlich als Tester-Szenario S02/S04/S05 (04 §5).

7.7 Fassaden

CaseActivities::for/next/situation und CaseAutomation::advance/documentBlockers bleiben als dünne Fassaden. So bleiben ViewBooking, BookingInfolist, WorkList, ActivityDetails und die Kommandos stabil. Der Runner übernimmt zentral:

  • die Regel „nach Vorgangsende ist nichts mehr zu tun“ ($later);
  • die Ereignistypen aus ActivityDetails::EVENT_TYPES, die in die Moduldefinition (events) wandern.

8. Kanalereignisse und Vertragsverbindlichkeit (N7, K4, K10)

8.1 Befund

  • ChannelConnector kennt nur fetchOccupations (iCal).
  • Mails laufen über ProcessPortalMail → PortalMailParser → PortalIntake::process (Buchung, über eine Mail-Sperre source = email), cancellationMail oder inquiryMail.
  • Belegungen laufen über SyncChannel → BlockedPeriod (source = channel) → PortalIntake::process und afterSync.
  • Sicherheitsregeln (E-019) sind schon im Code:
    • Meldungen zu bekannten Vorgängen werden zu Aufgabe und Verlaufseintrag; der Vorgang wird nie storniert, freigegeben oder geändert.
    • Ein neuer Vorgang entsteht nur bei Sicherheit (certainty: Buchungsmail mit Nummer, Regel portal_reservation als leading_candidate, vom Vermieter eingeordnet).
    • Stornomails heben nur die Mail-Sperre auf, nicht den Vorgang.
  • Portalzahlungen werden als PaymentKind::GuestViaPortal („laut Portal“) erfasst, angekündigte Auszahlungen als AmountKind::PayoutAnnounced. Beides ist kein Eingang auf unserem Konto (PaymentKind::PortalPayout erfasst nur der Vermieter).
  • Die Zuordnung einer Mail zum Portal geschieht über die Absenderdomain (ProcessPortalMail::channelFor). Eine Mail ist also nicht authentifiziert.

8.2 Vier Stufen statt einer Vertrauensstufe

Der frühere Entwurf ordnete Provenance.trust den Nachweisstufen zu. Das wird verworfen: Die Verlässlichkeit einer Quelle belegt nicht, dass eine Geschäftshandlung erfolgt ist.

Stufe Bedeutung Wer stellt sie fest Darf bewirken
M1 Eingegangene Meldung Etwas ist angekommen (Mail, Kalendereintrag, API-Antwort, Webhook) Transportadapter Speicherung als Beleg, Duplikatprüfung, Kalender-Schutzwirkung (Sperre bei möglicher Buchung)
M2 Authentifizierte, zugeordnete Portalinformation Herkunft technisch gesichert und eindeutig einem Kanal der Wohnung und, falls genannt, einem Vorgang zugeordnet Adapter (Authentizität) + PortalIntake (Zuordnung: Nummer, Nächte, keine Mehrdeutigkeit) neuer Vorgang bei Eingangsart Buchung nach certainty; Angaben „laut Portal“ (RecordPortalAmounts, ContributeCaseFacts mit Quelle); Aufgabe zu bekanntem Vorgang
M3 Fachlich bestätigte Erledigung Ein Schritt ist tatsächlich erledigt: Beleg geprüft, Mindestnachweis erreicht Vermieter oder eine Regel, die einen Beleg auswertet (z. B. Bankeingang, vom Vermieter erfasst) Nachweisstufe eines Schritts erhöhen; case.settlement freigeben
M4 Zulässige Änderung des verbindlichen Vorgangs Rechtswirksame Änderung des Vertrags (Storno, Umbuchung, Preis) nur eine fachliche Action mit Entscheidung des Vermieters: CancelBooking, RecordCancellation, ChangeBooking; bei A3–A5 nach Portal-Nachweis Statuswechsel, Preis- und Fristwirkung

Provenance beschreibt deshalb nur Herkunft und Authentizität:

final readonly class Provenance
{
    public function __construct(
        public Channel $channel,
        public string $transport,             // 'ical' | 'email' | 'api' | 'webhook'
        public string $authenticity,          // 'unauthenticated' (ical, mail sender) | 'authenticated' (signed webhook, API with credentials)
        public ?string $externalReference,
        public string $evidenceRef,           // blocked_periods.id, portal_emails.id, stored raw payload
        public CarbonImmutable $receivedAt,
    ) {}
}

Eine Zuordnung zur Nachweisstufe gibt es nicht. authenticity beeinflusst nur, ob die Stufe M2 ohne zusätzliche Bestätigung erreicht wird (§8.3). Eine Meldung erreicht M3 oder M4 nie allein durch ihren Eingang.

8.3 Ereignisverträge

Jedes Ereignis ist ein reines Datenobjekt. Der Handler ruft nur bestehende Fachfunktionen auf.

Ereignis Pflichtdaten Sicherheitsprüfungen Erlaubte Wirkung Nie
IncomingBooking (neue verbindliche Portalbuchung) Kanal, Zeitraum, Referenz (bei Mail/API Pflicht), Belegquelle Kanal gehört zur Wohnung; booking_model erlaubt Buchungen; Duplikat über Referenz, gleiche Nächte und Spiegelung (PortalIntake::evaluate); Überschneidung → Klärung; certainty; Eingangsmodus des Kanals (case_intake) Sperre (BlockedPeriod, source = Transport); Vorgang über TakeOverExternalBooking mit Plan des gewählten Modells; Angaben „laut Portal“ Vorgang ohne Referenz aus Mail/API; Zusammenführen bei abweichender Referenz; eigene Annahme oder eigener Preis (A3–A5)
BookingCancelledByChannel Kanal, Referenz oder Zeitraum, Beleg Zuordnung eindeutig, sonst Klärung Aufgabe PortalCancellationReported + Verlauf; Aufheben einer Mail-Sperre desselben Eintrags; Aussetzen automatischer Außenwirkungen (O4) Stornieren des Vorgangs, Freigabe des Kalenders aus einer Vorgangssperre, Erstattung, Stornogebühr
BookingChangedByChannel Kanal, Referenz, neue Daten Zuordnung eindeutig; neue Nächte gegen Verfügbarkeit geprüft, nicht gesperrt Aufgabe PortalChangeReported mit Vergleich alt/neu; Vorschlag für ChangeBooking Änderung von Zeitraum, Preis oder Gästen ohne Action des Vermieters
PaymentReported (Gast hat beim Portal gezahlt) Kanal, Referenz, Betrag, Datum Zuordnung eindeutig; Betrag plausibel zum Portal-Gesamtpreis RecordPortalAmounts → PaymentKind::GuestViaPortal „laut Portal“; idempotent über Betrag + Datum + Quelle [Befund] Zahlung als Eingang auf unserem Konto (PaymentKind::Guest oder PortalPayout); Mahnstopp für eigene Forderungen (A3)
PayoutReported (Portal kündigt Auszahlung an oder meldet sie) Kanal, Referenz, Betrag, Datum, Art (angekündigt/ausgeführt laut Portal) wie oben AmountKind::PayoutAnnounced bzw. Verlaufseintrag „Auszahlung laut Portal ausgeführt“; Nachweisstufe des Schritts portal.payout = „laut Portal“ Kennzeichnung als eingegangen; case.settlement ohne Mindestnachweis (D3)
IncomingInquiry Kanal, Zeitraum, Kontakt wie heute inquiryMail TakeOverPortalInquiry –
OccupationsReported Liste ExternalPeriod wie heute SyncChannel heutiger Pfad –

Erstattungen: Kein Ereignis kennzeichnet eine Erstattung als ausgeführt. Eine Erstattung (PaymentKind::Refund) erfasst nur der Vermieter. Eine Portalmeldung „Erstattung veranlasst“ wird zur Aufgabe mit Beleg.

Duplikate zwischen iCal, Mail und API: Alle Buchungsereignisse werden auf dieselbe BlockedPeriod-Form abgebildet und durchlaufen PortalIntake::evaluate. Die Duplikatregeln bleiben deshalb eine Implementierung:

  1. bereits verknüpft;
  2. gleiche Referenz;
  3. Spiegelung;
  4. gleicher Kanal mit gleichen Nächten;
  5. Überschneidung → Klärung.

Eine Mail-Sperre und eine API-Sperre mit gleicher Referenz werden vom nächsten iCal-Abgleich bestätigt, nicht doppelt angelegt (heutiges Verhalten von SyncChannel für source = email, erweitert auf api).

8.4 Kleinster tragfähiger Ansatz (K10)

V-E1 Ergänzung (gewählt) V-E2 Komplettumbau
Idee Ereignisklassen und ChannelEventHandler als neuer Eingang für künftige Adapter. Der Handler bildet Buchungs-, Storno- und Änderungsereignisse auf die vorhandene Form ab (BlockedPeriod + PortalIntake::process bzw. reportToCase) und Geldereignisse auf RecordPortalAmounts. iCal und Mail bleiben unverändert. PortalIntake nimmt nur noch Ereignisse an; SyncChannel und ProcessPortalMail werden auf Ereignisse umgebaut
Änderungsumfang neu: app/Channels/Events/*, ChannelEventHandler, Fähigkeits-Interfaces. Geändert: PortalIntake an zwei Stellen (source-Liste um api/webhook; cancellationMail delegiert an ein allgemeines reportToCase(Channel, reference, kind, evidence)) PortalIntake, SyncChannel, ProcessPortalMail, ReconcileChannelRepresentations, Tests der Eingänge
Testaufwand neue Ereignistests + unveränderte Bestandstests alle Eingangstests anpassen
Doppelverarbeitung gering: ein Prüfpfad (evaluate) für alle Transporte gering, aber Umbaufehler im heute funktionierenden Pfad möglich
Zukunftsfähigkeit ausreichend: Ein API-Adapter liefert Ereignisse, die denselben Fachpfad nutzen gleich
Parallele Geschäftslogik? nein; der Handler enthält keine Entscheidungsregeln nein

Begründung: Ein Komplettumbau brächte keinen fachlichen Gewinn, weil BlockedPeriod ohnehin die Kalenderwahrheit jeder Buchung ist. Gleichzeitig würde er den funktionierenden Eingang gefährden. V-E2 wird erst nötig, wenn ein Portal Ereignisse liefert, die sich nicht als Belegung, Meldung oder Betrag ausdrücken lassen. Das wird dann neu bewertet.

Adapter-Fähigkeiten als kleine Zusatzschnittstellen am Connector:

  • ImportsOccupations (heute fetchOccupations);
  • DeliversEvents (fetchEvents(Channel, since));
  • ReceivesWebhooks (Route channels/{channel}/hook, Signaturprüfung im Adapter → authenticity = authenticated);
  • PushesAvailability (später).

ChannelRegistry und config/channels.php bleiben das Register. Jeder Adapter nutzt für Netzzugriffe die Http-Fassade; das prüft ein statischer Test (04 §3.5).

N7-Nachweis: Ein künftiger FewoDirektApiConnector implementiert DeliversEvents und liefert IncomingBooking mit transport = api, authenticity = authenticated. Danach laufen dieselben Prüfungen wie bei der Mail-Schnellspur:

  1. Duplikat zur iCal-Sperre über Referenz und Nächte;
  2. TakeOverExternalBooking;
  3. das gewählte Modell a4.portal_booking.

Geändert werden nur der Adapter und sein Registereintrag.