Files

125 lines
11 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# V2.1 – Fachliches Zielbild: konfigurierbarer Geschäftsprozess auf V2
Stand: 05.11.2026 · setzt `01_KONFIGURATIONSLUECKEN.md` um. Die technische Basis von V2 (Fachmodule, Modelle, `ProcessRunner`, Konfigurator, isolierter Tester) bleibt; es kommen Fähigkeiten und Einstellungen hinzu, keine zweite Engine und keine zweite Konfigurationsquelle.
Leitsatz: **Die Grenze der Konfigurierbarkeit begründet die fachliche Notwendigkeit, nicht die Struktur der heutigen Implementierung.** Vor jedem neuen Mechanismus wurde geprüft, ob Modulvertrag, Parameter, Abhängigkeiten oder Erweiterungspunkte reichen. Neu gebaut wird nur, was dort nicht darstellbar war.
## 1. Vier getrennte Dimensionen
| Dimension | Beispiele | Wo es steht |
|---|---|---|
| Geschäftskanal (Herkunft) | Eigene Webseite, Destination Solutions, FeWo-direkt | `channels`, bleibt am Vorgang (`origin_channel_id`) |
| Kommunikationsmedium | E-Mail, Formular, WhatsApp, Chat | `Medium` (neu); Eingang je Nachricht |
| Nachrichtenabsicht | Auskunft, Nachfrage, Datenlieferung, Buchungsanfrage, Stornohinweis, unklar | `Intent` (neu); vom Prozesskern bestimmt |
| Verbindlichkeit/Ereignisart | unverbindlich, extern verbindlich, Information | unverändert (`IntakeKind`, `Booking::isBinding`) |
Kein Medium und keine Absicht legt eine Verbindlichkeit fest. Eine eingehende Nachricht erzeugt **nie** selbst einen Vorgang, eine Reservierung, ein Angebot oder eine Buchung (strukturell: kein Wirkungstyp der Regeln legt einen Vorgang an).
## 2. Archetyp = Rahmen (Ausführungsvarianten statt Schlösser)
- Das Modell legt fest, **wer wofür verantwortlich ist**, wenn das die Vorgangsart bestimmt (Vertragsabschluss, Inkasso, Vertragsdokumentation; O1 unverändert).
- Jedes Modul nennt, **auf welche Weisen** seine Aufgabe erfüllt werden darf (`executions`): automatisch · mit Freigabe · von Hand · durch das Portal · durch einen Dienstleister · bereits extern erledigt und nachgewiesen · nicht erforderlich. Das Modell schränkt die Menge je Archetyp ein.
- Die Oberfläche zeigt an jedem Schritt **„So darf das erfüllt werden“** statt eines Schlosses. Eine zwingende Aufgabe bleibt zwingend; abschaltbar ist sie nicht, wohl aber ausführbar auf den zugelassenen Wegen.
- Die Auswahl landet in vorhandenen Einstellungen (`Processing`, `DataRequest`, `Documents`, `GuestMessages`) oder in den neuen unten. Dieselbe Hierarchie Vorgang ← Kanal × Eingangsart ← Wohnung ← Vermieter ← Systemstandard; eingefroren beim Eingang.
## 3. Kanalfähigkeiten und Modellzulässigkeit
### 3.1 Fähigkeiten
Gespeichert im Kanal (`channels.settings.capabilities`), je Fähigkeit: Wert, bestätigt am/von, Historie (letzte 20 Änderungen).
| Fähigkeit | Bedeutung | Wirkt auf |
|---|---|---|
| `collects_payment` | Das Portal zieht das Geld des Gastes ein | Modell A4/A5 verlangen „ja“, A3 verlangt „nein“ |
| `provides_contract_documents` | Das Portal stellt die verbindlichen Vertragsunterlagen bereit | A5 verlangt „ja“, A3/A4 „nein“ (O1) |
| `messages_guest` | Das Portal schreibt den Gast an (Anreise-Information, Erinnerungen) | Auswahl „Portal“ bei Gastkommunikation |
| `sends_confirmation_mail` | Das Portal schickt uns eine Buchungsbestätigung per E-Mail | Warten auf Portalbestätigung |
**Wert ermitteln (in dieser Reihenfolge, die Quelle wird angezeigt):**
1. *bestätigt* – vom Administrator bestätigt;
2. *abgeleitet* – aus einer ausdrücklich gespeicherten Altstellung (`payments`, `documents`, `guest_messages` am Kanal); der Administrator muss sie bestätigen oder korrigieren;
3. *Vorschlag* – aus dem Kanalprofil (`config/channels.php`, z. B. R09 für FeWo-direkt, E-016 für Destination Solutions);
4. *unbekannt* – blockiert nichts, wird als „bitte bestätigen“ gezeigt.
### 3.2 Zulässigkeit
Ein Modell ist zulässig, wenn die Eingangsart passt und jede verlangte Fähigkeit den verlangten Wert hat (unbekannt = zulässig mit Hinweis). Die feste Portalliste entfällt; sie wird zum Vorschlagsprofil. O2 bleibt als Vorgabe für FeWo-direkt erhalten (Profil: zieht Geld ein, keine Vertragsunterlagen ⇒ A4), ist aber nicht mehr dauerhaft gesperrt.
**Ein nicht zulässiges Modell bleibt sichtbar** mit Begründung: *Ursache* (fehlende Fähigkeit mit Quelle des aktuellen Werts), *Alternative* (welches Modell passt), *konkrete Änderung* (welche Fähigkeit bestätigen). Änderungen der Fähigkeiten im Entwurf wirken sofort auf die Auswahl.
### 3.3 Abgleich mit Altwerten
Beim Speichern prüft `ConfigureChannelProcess`, ob am Kanal Einstellungen stehen, die das gewählte Modell festlegt (z. B. `payments = portal` bei A3). Konflikte werden **aufgelistet** (Wert alt/Wert Modell/Folge), müssen ausdrücklich bestätigt werden und werden danach entfernt und im Verlauf des Kanals festgehalten. Ohne Bestätigung wird nicht gespeichert. Der Konfigurator wählt nie still ein anderes Modell.
### 3.4 Was auf Kanalebene bleibt
Ein/Aus optionaler Schritte (`steps[…].on`) gilt weiter nur je Kanal und Eingangsart. Grund: Ob ein Schritt für ein Portal entfällt, hängt an dessen Fähigkeiten; ein Vermieter- oder Wohnungsstandard würde Kanäle mit anderen Fähigkeiten falsch treffen. Ausführungsarten (Einstellungen) vererben dagegen über alle Ebenen.
## 4. Dokumente: Erzeugen, Ablegen, Versenden, Informieren
| Fähigkeit | Wo | Einstellung |
|---|---|---|
| Vertragsgrundlage prüfen | `documents.send` (`DocumentComposer`, Konditionsstand, Freigaben) | unverändert, nicht abschaltbar |
| Vertragsdokument erzeugen und intern ablegen | `ConfirmBooking::deliver(notifyGuest: false)` | `contract_delivery = internal` |
| Vertragsdokument an den Gast senden | `documents.send` | `contract_delivery = automatic / manual`, Vorgabe `follow` = wie `processing` |
| Buchungsinformation (ohne Vertrag) | neues Modul `documents.booking_notice` | `booking_notice = off / automatic / automatic_unless_portal_confirmed / manual` |
| Vom Portal bereitgestellte Unterlagen | Modell A5 (`Documents = Portal`) | Modellwahl (O1) |
| Ergänzende Informationen | `arrival.info` (Zeitpunkt, Ausführender) | unverändert, unabhängig von der Vertragsdokumentation |
Darstellbare Fälle: Vertrag automatisch erstellen und senden · erstellen und nur intern ablegen · nach Freigabe/von Hand senden · nur Buchungsinformation · Portal stellt Unterlagen bereit (A5) · keine eigene Nachricht, wenn das Portal die Bestätigung nachweislich geschickt hat · ergänzende Informationen unabhängig.
**Grenzen:** Der Gast bekommt nie neue, nicht vereinbarte Pflichten (Konditionsprüfung bleibt). Bei extern verbindlicher Buchung ändert keine Dokumenteinstellung die Verbindlichkeit. Ein Vertrag, der nur intern liegt, ist **nicht** „versendet“: der Schritt bleibt offen, bis er gesendet wird oder der Vermieter ihn bewusst als erledigt markiert.
## 5. Warten auf ein Ereignis: Portalbestätigung
Modul `portal.confirmation` (optional, nur für extern verbindliche Buchungen; Einstellungen `await_portal_confirmation` ja/nein, `portal_confirmation_wait_hours`, Vorschlag 48).
- **Erwartet:** eine Buchungsmail des Portals (`PortalEmailType::Booking`), die dem Vorgang **deterministisch** zugeordnet ist (CH-13: belastbare Portalreferenz oder verknüpfte Belegung desselben Kanals). Keine Zuordnung nach Name, Adresse oder Zeitraum allein.
- **Nachweis:** die Mail (Stufe „laut Portal erledigt“) oder eine ausdrückliche Bestätigung des Vermieters im Vorgang (Verlaufseintrag `portal_confirmation`). Eine Mail allein schafft keine Verbindlichkeit.
- **Wer wartet (harte Abhängigkeit):** `documents.send`, `documents.booking_notice`. **Wer nicht:** Belegung und Kalendersperren (`binding.portal`, `channels.block`), Datenbeschaffung, Zahlungsüberwachung, Aufenthalt, interne Aufgaben.
- **Wiederaufnahme:** nach Verarbeitung einer Portalmail für diesen Vorgang (Auslöser `portal.mail`) und durch einen Zeitgeber für wartende Vorgänge (`bookings:advance-waiting`, alle 5 Minuten).
- **Ausbleiben:** nach Ablauf der Frist wird der Schritt zum Problem, es entsteht **eine** Aufgabe „Portalbestätigung fehlt“; die Folgeschritte bleiben angehalten, bis der Vermieter bestätigt oder von Hand sendet. Nichts wird automatisch gesendet oder aufgehoben.
- Ist der Vorgang selbst durch diese Mail entstanden, ist der Nachweis sofort erbracht.
## 6. Kommunikation: Medium × Absicht
`IncomingMessage` (Medium, Absender, Text, Zeit, externe Kennung, überprüfter Antwortbezug) → `MessageIntake` → `MessageDecision`.
- **Absicht** bestimmt der Prozesskern regelbasiert (`IntentClassifier`, später KI über dieselbe Schnittstelle, E-035). Der Adapter liefert nur Rohdaten und einen **vom Adapter überprüften** Antwortbezug (signiertes Kennzeichen); eine Behauptung des Absenders zählt nicht.
- **Regeln** (`config/communication.php`, Vermieter dürfen nur einschränken, nie erweitern): je Medium aktiv/inaktiv, Einwilligung nötig, je Absicht erlaubte Wirkungen:
| Wirkung | Bedeutung | Voraussetzung |
|---|---|---|
| `answer_information` | allgemeine Auskunft beantworten, kein Vorgang | – |
| `contribute_facts` | Angaben an einen **zugeordneten** Vorgang über `ContributeCaseFacts` | verifizierter Antwortbezug |
| `report_to_case` | Aufgabe am zugeordneten Vorgang | verifizierter Antwortbezug |
| `handoff_inquiry` | Verweis auf den Anfrageprozess (Formular); kein Vorgang | – |
| `review` | manuelle Klärung im Posteingang | – |
- **Zuordnung:** nur deterministisch (verifizierter Antwortbezug, bestehender `MessageMatcher` bei E-Mail). Gleiche Absenderadresse, Rufnummer, Name oder Zeitraum genügen **nicht**. Unklar ⇒ `review`.
- **Widerspruch/Mehrdeutigkeit** ⇒ `review`, keine Übernahme.
- **Antwort:** die Entscheidung nennt die zulässigen Antwortmedien; ein Versand durch Messenger/Chat-Adapter ist nicht Teil von V2.1.
- WhatsApp und Chat sind **Testfälle der Architektur**: Regeln, Eingang und Tester vorhanden, kein Provideranschluss. Der bestehende E-Mail-Weg (`ReceiveInboundMessage`) bleibt unverändert.
## 7. Darstellung des nichtlinearen Ablaufs
Die Prozessansicht entsteht aus **derselben** Moduldefinition wie die Ausführung (`requires`, `waits`, `triggers`, `applies`, `executions`); es gibt keine zweite Pflege. Je Phase (P01–P05) eine Spur; je Schritt:
- „braucht zuerst: …“ (harte Abhängigkeit, nur wenn im Plan)
- „soll nach: …“ (weiche Abhängigkeit)
- „läuft unabhängig“ (keine harte Abhängigkeit im Plan)
- „wartet auf: Gast / Portal / Frist / Vermieter“
- „nur wenn: …“ (bedingt; Beschreibungstext der Definition, **keine** Logik)
- „löst aus / endet durch: …“ (Auslöser)
- Ausführung: Wer und wie (automatisch · Freigabe · von Hand · extern/Portal), abgeschaltet.
Die Nummerierung 1–n entfällt.
## 8. Prozess-Tester und Nachweisfälle
Die Szenarien laufen weiter im isolierten Prozess. Neu: Portalbestätigung (sofort/verspätet/ausbleibend), Dokumentvarianten (über den Entwurf), Nachrichten über andere Medien, Auskunft ohne Vorgang, Stammdaten-Abgleich, eingefrorene Konfiguration, unabhängige Aktivitäten. Fälle A–H: Abschnitt 2 der Abnahme `ABNAHME_V2_1.md`.
## 9. Grenzen (bewusst)
Keine Skripte oder Bedingungen im Konfigurator · keine Umordnung sicherheitsrelevanter Schritte · keine Umgehung von Verbindlichkeits-, Verfügbarkeits-, Preis- oder Datenschutzprüfungen · keine zweite Engine · keine zweite Wahrheitsquelle · kein Provideranschluss für Messenger/Chat · Storno/Erstattung je Modell nicht einstellbar (offen, DS-06/FW-05).