50 KiB
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,rejectedoderunknownals 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:
- Platz am vorhandenen Punkt
AfterGuestIdentified. Das Modul hatrequires: guest.details(Anschrift vorhanden) undblocksDependents: false. Einunknownhält damit nicht das Angebot auf; ob einrejecteddas Angebot aufhält, ist ein Modulparameter. - 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ächterrespectsExternalBinding, §3.2). - 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,activityundblockersschreiben nichts (Abfrageprotokoll ohne Schreibanweisung).runerzeugt nur die deklarierten Effektarten.- Ein zweiter
runist 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 FassadeCasePricing),messages(ReceiveInboundMessage,MessageMatcher,ExtractMessageFacts),mail(Laravel-Mailer +EnforceMailTestMode),log(CaseLog,CaseRecorder),tenancy(TenantContext,TenantConfig). - Interne Belegungen:
CaseActivities::internal()wird zum Modella6.internal(intake.record,channels.block,documents.sendoptional,payments.monitorohne 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 ausoffer_terms, Grundlage ausquote-Zeilen);CancellationPolicy::tierFor;- Anzahlungs- und Restbetrag;
ContractPlaceholders(Vertragstext ausoffer_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 deklariertcompatibleWith: [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.
- der Fehler im Fehlerregister steht (
-
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 --casesprü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
- ihre Vertragsdaten eingefroren sind,
- deren Auswertung nach R1 stabil bleibt,
- ihre Prozessdefinition eingefroren ist,
- 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 vonbookings,case_facts,data_requests,booking_amounts,paymentsundbooking_tasks. Es sind synthetische Daten, keine Kundendaten. - Abdeckung: jeder Archetyp × die Status
Reserved(Klärungs- und Angebotsreservierung),OfferSent,Confirmedmit offener Anzahlung,Confirmednach Anreise,Cancelledmit 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::calculatean drei Stichtagen, Anzahlungs- und Restbetrag, Fälligkeiten, Hash des gerenderten Vertragstexts (RentalContract::render, Entwurf); - gleich wie die gespeicherte Erwartung:
ProcessRunner::activitiesund die Entscheidung vonadvance(läuft/läuft nicht, Blocker); - nach
advancekeine Änderung an E-V-Spalten.
- unverändert:
- Ausführung: Der Test läuft in jeder CI. Eine Abweichung ist nur mit Eintrag
intendedund 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:loyaltyund beide Module tragenavailability = 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)
guest.detailsidentifiziert den Gast (E-Mail).guest.loyalty_status(PunktAfterGuestIdentified) zählt abgeschlossene, nicht stornierte Aufenthalte desselben Gastes beim selben Mandanten.- Ergebnis
Qualified,NotQualifiedoderUnknownals Faktloyalty_statusüberContributeCaseFacts(neueFactSource::System), mit Beleg (Referenzen der Aufenthalte). blocksDependents = false: EinUnknownhält den Angebotsschritt nicht auf.
- Ergebnis
pricing.loyalty_discount(PunktBeforePriceFixing,ContributesToPrice) liefert beiQualifiedeineQuoteLine(QuoteLineType::Discount, …).- Testannahme E6: Bei Sonderangebot keine Zeile.
- Bei
NotQualified/Unknownkeine Zeile; beiUnknownein Hinweis im Schritt. - Der Angebotsversand wird nie blockiert.
offer.binding→SendOffer;SendOffer::quoteForholt den Preis überCasePricing::quote($booking, $stay). Die Zeile steht damit inquote, im Vertragsentwurf und im Verlauf.- Ab Verbindlichkeit ist der Preis fest.
CasePricingruft für verbindliche Fälle keine Beiträge auf (Test). BeiChangeBookingbleibt die gespeicherte Rabattzeile eingefroren (E5); die spätere Regel ist offen. - Hinweis R1:
CancellationCost::rentzähltDiscount-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 andereDoneist. Ein nicht zutreffender oder (nur bei optionalen Schritten möglich) abgeschalteter Schritt erfüllt sie, weil seine Bedingung den Fall nicht betrifft.blocksDependentsgibt 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
appliesgilt, - sein Zustand
Openist, - alle
requiresDonesind (oderNotApplicable, wo das Modul das zulässt), blockersleer ist.
- er im Plan aktiv ist und
- Unabhängigkeit: Ein wartender Schritt hält nur Schritte auf, die ihn in
requiresführen und für die erblocksDependents = truehat. 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
runist 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 inCaseAutomation::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::advancekennt nur zwei Fälle: Angebot/Auskunft und Unterlagen.- Aufgerufen wird es von
ContributeCaseFacts,RecordPortalAmounts,TakeOverExternalBooking,TakeOverPortalInquiryundViewBooking. CreateReservation::sendMailsruftAutoOfferund danachRequestCaseData::forNextStepdirekt auf, ebensoSubmitBookingWishundTakeOverExternalBookingdie Datenanfrage.- Zeitgesteuert laufen
bookings:auto-offers(AutoOfferdirekt),cases:data-requests(RequestCaseData::remindDue) undbookings:expire-holds(ExpireReservations, ohneadvance).
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
URGENTinCaseActivities) 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,ChangeBookingoder Verwerfen) ruft die Actionadvance.
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
ChannelConnectorkennt nurfetchOccupations(iCal).- Mails laufen über
ProcessPortalMail→PortalMailParser→PortalIntake::process(Buchung, über eine Mail-Sperresource = email),cancellationMailoderinquiryMail. - Belegungen laufen über
SyncChannel→BlockedPeriod(source = channel) →PortalIntake::processundafterSync. - 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, Regelportal_reservationalsleading_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 alsAmountKind::PayoutAnnounced. Beides ist kein Eingang auf unserem Konto (PaymentKind::PortalPayouterfasst 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:
- bereits verknüpft;
- gleiche Referenz;
- Spiegelung;
- gleicher Kanal mit gleichen Nächten;
- Ü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(heutefetchOccupations);DeliversEvents(fetchEvents(Channel, since));ReceivesWebhooks(Routechannels/{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:
- Duplikat zur iCal-Sperre über Referenz und Nächte;
TakeOverExternalBooking;- das gewählte Modell
a4.portal_booking.
Geändert werden nur der Adapter und sein Registereintrag.