Files
fewo-stommer/docs/Prozessarchitektur/MODUL_KONFIGURATIONSMATRIX.md
T
LarsandClaude Sonnet 5.5 381720763c
Deploy FeWo mit PipelineManager / deploy (push) Successful in 6m16s
Modul-Konfigurationsmatrix und Auswirkungs-Abgleich im Kanalkonfigurator
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-05 09:51:33 +01:00

175 lines
17 KiB
Markdown
Raw 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.
# Modul-Konfigurationsmatrix
Stand: 05.11.2026 (nach V2.1). **Die** verbindliche Übersicht, was an jedem registrierten Fachmodul tatsächlich einstellbar ist – und was nicht. Quelle: `config/process.php` (28 Module), `ModuleDefinition` der Module, `ChannelProcessConfiguration::STEP_CONTROLS`, `ProcessSetting`, die Modelle A1–A6 und der Code der Aktionen. Die technische Modul-/Modell-Tabelle (`Architektur/MODULMATRIX.md`) wird von `process:check --matrix` erzeugt; dieses Dokument ergänzt die **fachliche** Sicht und wird von Hand gepflegt.
Ein Modul gilt erst dann als konfigurierbar, wenn seine Varianten **auswählbar, speicherbar, wirksam und testbar** sind. Spalte „Zustand“ benennt das je Modul ehrlich.
## 1. Einordnung der Einschränkungen
| Kürzel | Bedeutung |
|---|---|
| **V** | Technisch vorhanden, im Konfigurator nicht (mehr) sichtbar |
| **R** | Unnötig restriktive Validierung oder historische Implementierungsentscheidung |
| **P** | Zulässige Option, aber der Konfigurationsparameter fehlt |
| **F** | Fachliche Fähigkeit fehlt (Implementierungsumfang angegeben) |
| **S** | Unveränderliche Sicherheitsregel (nicht Gegenstand der Konfiguration) |
| **O** | Fachliche Festlegung offen (blockiert die Umsetzung nicht) |
Grundregeln, die für **alle** Module gelten (S): Pflichtschritte sind nicht abschaltbar; Verbindlichkeit beim Portal wird nie von uns aufgehoben (E-036); Verfügbarkeit wird immer geprüft (E-027); Preise kommen nur aus `PriceCalculator` bzw. dem Portal; kein Versand an Gäste außerhalb des Mail-Tores (`EnforceMailTestMode`); laufende Vorgänge behalten ihren eingefrorenen Plan (E3); Nachrichten werden nur über einen verifizierten Bezug einem Vorgang zugeordnet (CH-07).
Wirkungsweise einer Einstellung: Landlord → Wohnung → Kanal je Eingangsart (`ProcessSettings`); das Modell kann Werte festlegen (`fixes()`), bestätigte Altwerte, die das Modell überstimmt, werden nach ausdrücklicher Bestätigung entfernt (`ConfigureChannelProcess`, Konflikte). Neue Vorgänge folgen der neuen Konfiguration, laufende nicht.
## 2. Übersicht
| Modul | Ablauf | Abschaltbar | Einstellbar im Konfigurator | Zustand |
|---|---|---|---|---|
| `intake.record` | alle | nein (S) | – | vollständig, nichts einzustellen |
| `guest.details` | A1–A5 | nein (S) | Anschrift im Formular Pflicht | vollständig |
| `guest.data_request` | A1–A5 | ja | Modus, Erinnerungen, Folgefragen, Abstand, Linkdauer | vollständig |
| `hold` | A1/A2 | bedingt | Vorreservierung, Frist, Klärungsfrist | vollständig |
| `availability.check` | A1/A2 | nein (S) | – | vollständig |
| `binding.portal` | A3–A5 | nein (S) | – | vollständig |
| `channels.block` | alle | nein (S) | – | Aufgabenweg je Portal über Kanaldaten |
| `portal.confirmation` | A3–A5 | bedingt | Warten ja/nein, Wartefrist | Nachweis-Mindestumfang **O** |
| `offer.information` | A1/A2 | nein | Modus, Linkdauer | vollständig |
| `offer.binding` | A1/A2 | nein | Modus, Haltefrist, Vorlage | vollständig |
| `offer.acceptance` | A1/A2 | nein (S) | – | vollständig |
| `documents.send` | A1–A5 | nein | Modus, Zustellung, Vorlage | Zustellwege vollständig, Varianten siehe 3.12 |
| `documents.booking_notice` | A3–A5 | bedingt | Buchungsinformation: Art | vollständig |
| `documents.stay_confirmation` | A6 | ja | – | nur manuell (P) |
| `case.tasks` | alle | – | – | ereignisgesteuert |
| `change.proposal` | A1–A5 | – | – | ereignisgesteuert |
| `case.closure` | alle | nein (S) | – | – |
| `case.settlement` | alle | nein (S) | – | – |
| `payments.monitor` | A1–A5 | nein | Zahler (durch Modell) | **Zahlungsanforderung, Erinnerung, Mahnung nicht konfigurierbar (F/P)** |
| `portal.payout` | A1–A5 | nein | – | Nachweis-Mindestumfang **O** |
| `payments.internal` | A6 | bedingt | – | – |
| `arrival.details` | A1–A5 | ja | nur Schalter | Parameter fehlen (P) |
| `arrival.info` | A1–A5 | nein | Absender, Tage vor Anreise | Zustellweg Dienstleister nicht ausgeführt (F) |
| `stay` | alle | nein (S) | – | – |
| `review.request` | A1–A5 | ja | Absender (über Gastkommunikation) | Zeitpunkt nur mandantenweit (P) |
| `guest.address_check` | Tester | ja | – | nur Prozess-Tester (Erweiterungsnachweis) |
| `guest.loyalty_status` | Tester | ja | Mindestbesuche, Rückblick | nur Prozess-Tester (E7) |
| `pricing.loyalty_discount` | Tester | ja | Prozent, Höchstbetrag | nur Prozess-Tester (E7) |
## 3. Module im Einzelnen
Die zwölf Punkte je Modul sind in der Kurzform: **Ergebnis/Invarianten · Aktivierung · Varianten · Auslöser · Voraussetzungen · Parameter · Kommunikation/Nachweis · Alternativen · Wirkung auf andere · Fehler/Warten/Eskalation · Ist (Code/UI) · Fehlt**. Was nicht aufgeführt ist, gibt es für das Modul nicht und wird nicht gebraucht.
### 3.1 `intake.record` – Eingang
Ergebnis: Vorgang mit eingefrorenem Plan, Belegung gesetzt. Invarianten (S): immer; friert Modell und Version ein. Auslöser: `intake`. Alle anderen Module hängen hart daran. Keine Parameter. Ist: vollständig. Fehlt: nichts.
### 3.2 `guest.details` – Angaben des Gastes
Ergebnis: Gast identifiziert, Angaben aus allen Quellen zusammengeführt, Vollständigkeit geprüft (G2a). Pflicht, wenn wir selbst schreiben. Varianten (Ausführung): automatisch, von Hand. Auslöser: `facts.applied`. Parameter: `form_requires_address` (Anschrift im Formular Pflicht; nur Anfragen). Beschaffung der fehlenden Angaben ist **unabhängig** vom Modul `guest.data_request`; beim Wegfall der Anfrage bleiben die Pflichtangaben erforderlich, die Alternative ist die manuelle Erfassung/Aufgabe. Ist: vollständig. Fehlt: Pflichtfeldliste je Kanal (P, später).
### 3.3 `guest.data_request` – Fehlende Angaben anfragen
Ergebnis: fehlende Pflichtangaben kommen per Link vom Gast. Optional (V2.1 unabhängig). Varianten: automatisch, nach Freigabe, von Hand, nicht erforderlich. Auslöser: `request.created`, `booking.taken_over`, Wunsch. Parameter (alle einstellbar): `data_request_mode`, `data_request_reminders_max`, `data_request_followups_max`, `data_request_reminder_hours`, `guest_link_valid_days` (nur Landlord-/Wohnungsebene, nicht je Kanal). Kommunikation: Mail mit signiertem Link; Nachweis: Antwort-Fakten (Provenienz). Warten: Gast, Zeit, danach Übergabe an Sie. Wirkung: bei „nicht erforderlich“ bleiben `guest.details` und alles, was es voraussetzt, bestehen – der Konfigurator zeigt die Ersatzwege (siehe Abschnitt 5). Ist: vollständig. Fehlt: Medium je Anfrage (WhatsApp usw.) – F, hängt an F4/F5.
### 3.4 `hold` – Reservierung
Ergebnis: Zeitraum frei halten, nach Ablauf freigeben (`Booking::occupying()` ignoriert abgelaufene Haltefristen). Varianten: nur Anfragen mit Vorreservierung. Parameter: `pre_reservation`, `hold_hours`, `clarification_hold_auto_minutes`, `clarification_hold_manual_minutes`. Zustand: vollständig. Fehlt: nichts.
### 3.5 `availability.check` – Verfügbarkeit
Pflicht (S, E-027). Keine Parameter. Fehlt nichts.
### 3.6 `binding.portal` – Verbindlichkeit beim Portal
Ergebnis: Buchung verbindlich beim Portal (E-036), Gesamtpreis laut Portal übernommen. Pflicht (S). Ausführung: Portal, von Hand. Auslöser: `intake`, `portal.amounts`. Fehlt nichts.
### 3.7 `channels.block` – Andere Kanäle sperren
Ergebnis: Belegung in Portalen nachgezogen, Nachweis je Portal. Pflicht (S). Ausführung: automatisch (iCal/Connector) oder von Hand (`ChannelTask`). Parameter je Portal in den Kanaldaten (`requires_manual_blocking`, iCal-URL); Erinnerung `task_reminder_after_minutes` (Betrieb). Eskalation: Aufgabe, Erinnerung, Postfach. Fehlt: nichts im Ablauf.
### 3.8 `portal.confirmation` – Bestätigung des Portals abwarten
Ergebnis: Nachweis der Portalbestätigung (PortalEmail-Buchung deterministisch verknüpft oder Ereignis des Vermieters). Bedingt: nur bei extern verbindlicher Buchung. Varianten: automatisch, von Hand, nicht erforderlich. Parameter: `await_portal_confirmation`, `portal_confirmation_wait_hours` (Vorschlag 48). Wirkung: **nur** `documents.send` und `documents.booking_notice` warten; Belegung, Datenbeschaffung, Zahlungsüberwachung nicht. Fristablauf: genau eine Aufgabe `PortalConfirmationMissing`, kein automatisches Aufheben. Fortsetzung: `portal.mail`, `schedule:waiting`. **O**: Mindestnachweis (D3) und akzeptierte Angaben (D4) = F2; Wartefrist = F3 (Vorschlag steht). Ist: vollständig im Rahmen der Vorschläge.
### 3.9 `offer.information` / `offer.binding` / `offer.acceptance`
Ergebnis: Auskunft (A1/A2 ohne Reservierung) bzw. verbindliches Angebot mit Vertragsentwurf (Version, signierter Link) und Annahme durch den Gast. Annahme ist Pflicht (S, E-003). Parameter: `processing` (automatisch/Freigabe/von Hand), `hold_hours`, `contract_template_id`, `guest_link_valid_days`. Preisänderungen nur als `Adjustment`-Zeile. Fehlt: nichts; ein Zahlungsplan im Angebot (Anzahlungsanteil/Termine) ist nicht je Kanal einstellbar (siehe 3.17).
### 3.10 `documents.send` – Buchungsunterlagen (Vertragsdokumentation)
Ergebnis: die Vertragsdokumentation erreicht den Gast – von uns oder vom Portal (O1). Pflicht (S). Varianten (`Execution`): automatisch, nach Freigabe, von Hand, durch das Portal (A5). Parameter: `documents` (Verantwortung; durch das Modell festgelegt), `processing`, `contract_delivery` (folgt dem Modus / automatisch / von Hand / intern), `contract_template_id`. Auslöser: `automation`, `booking.taken_over`, `portal.mail`, `schedule:waiting`. Voraussetzungen hart: `guest.details`, `portal.confirmation` (sofern im Plan). Fehlt: Auswahl mehrerer Dokumentenarten (z. B. nur Buchungsbestätigung ohne Vertrag) – der Weg dafür ist `documents.booking_notice`; Dokumentenarten selbst sind **F** (mittel).
### 3.11 `documents.booking_notice` – Buchungsinformation
Ergebnis: kurze Information ohne Vertrag, unabhängig von den Vertragsunterlagen. Parameter: `booking_notice` (aus/automatisch/von Hand/Portal). Wartet auf `portal.confirmation`, falls im Plan. Vollständig.
### 3.12 `documents.stay_confirmation` (A6)
Nur manuell oder nicht erforderlich. Kein Parameter nötig. Fehlt nichts.
### 3.13 `case.tasks`, `change.proposal` (ereignisgesteuert)
Zeigen Aufgaben bzw. Änderungsvorschläge. Keine Einstellung; Eskalation über Postfach/Digest (`reminder_interval_days`, Betrieb).
### 3.14 `case.closure`, `case.settlement`, `stay`
Pflicht (S). Abschluss erst, wenn nichts mehr offen ist (E-010); kaufmännischer Abschluss braucht tatsächliche Nachweise (O5), eine Portalmeldung ersetzt sie nicht. Keine Parameter. Fehlt: Storno-/Erstattungsregeln je Modell (F, **O**: DS-06/FW-05).
### 3.15 `payments.monitor` – Zahlungen des Gastes
Ergebnis: Anzahlung/Restzahlung überwacht (wir) oder „laut Portal“ (Portal zieht ein). Wer kassiert, legt das **Modell** fest (A3 wir, A4/A5 Portal); bei A1–A3 sind die Fristen:
| Teil | Ist | Zustand |
|---|---|---|
| Frist Anzahlung | `deposit_due_days` (Betrieb, mandantenweit; im Angebot eingefroren) | **P**: nicht je Kanal/Eingang |
| Zahlungsanforderung (Restzahlung) | Aufgabe 7 Tage vor Fälligkeit (`SendBookingReminders::BALANCE_REQUEST_DAYS_BEFORE`, Konstante) | **P**: Konstante, einstellbar machen |
| Zahlungserinnerung | Aufgabe für den Vermieter, Versand per Klick (`SendPaymentReminder`) | vorhanden, **nicht automatisch** (bewusst, S); Modus automatisch/Freigabe = **F** (klein) |
| Mahnung (mehrstufig) | gibt es nicht | **F** (mittel): Stufen, Fristen, Texte, Gebühren-Regel; rechtlich zu prüfen **O** |
| Zahlungseingang | Vermieter erfasst (`RecordPayment`); Bank-Abgleich nicht vorhanden | **F** (groß, später) |
Fehlt (Referenzfall A3): konfigurierbare Zahlungsanforderungen/-erinnerungen/Mahnungen. Priorisiert in Abschnitt 6.
### 3.16 `portal.payout`
Nachweis des tatsächlichen Eingangs der Auszahlung (O5). Nur wo das Portal einzieht (A4/A5). Manuell. **O**: DS-Inkasso F7.
### 3.17 `arrival.details`, `arrival.info`
`arrival.details` (optional): Telefon, Anreisezeit; keine Parameter (P: Pflichtfelder, Erinnerungsabstand). `arrival.info`: Absender (wir/Portal/Dienstleister/nicht erforderlich) über `guest_messages` (nach Modell erlaubt), Zeitpunkt `arrival_info_days_before` (≤ 14, Konstante). Zurückgehalten bei offener Portalmeldung (O4). **F**: Zustellung durch Dienstleister (Ausführung „service_provider“ ohne Anbindung – klein, nur Aufgabe).
### 3.18 `review.request`
Optional. Absender wie `arrival.info` (Portal schreibt dem Gast → Schritt entfällt). Zeitpunkt `review_request_after_days` nur mandantenweit (**P**). Vollständig sonst.
### 3.19 `payments.internal` (A6)
Zahlung ohne Erinnerungen, manuell. Fehlt nichts.
### 3.20 Tester-Module
`guest.address_check`, `guest.loyalty_status`, `pricing.loyalty_discount`: Erweiterungsnachweis (E7); nur im Prozess-Tester, nie im Plan eines echten Vorgangs (S). Parameter dort sichtbar. Bleiben so, solange nicht ausdrücklich freigegeben.
## 4. Technisch vorhanden, im Konfigurator nicht sichtbar (V) – Ergebnis der Prüfung
Geprüft wurde jede der 20 Einstellungen aus `ProcessSetting` gegen `STEP_CONTROLS`: **17 sitzen an einem Schritt; die übrigen drei (`pre_reservation`, `documents`, `payments`) werden durch die Wahl des Modells entschieden** (A1/A2 Angebot oder Auskunft, A3–A5 Verantwortung für Unterlagen und Inkasso) und sind deshalb bewusst kein Schrittparameter. Es gibt keine versteckte, bereits implementierte Variante, die nur freizulegen wäre. Gefunden wurden stattdessen:
| Befund | Art | Maßnahme |
|---|---|---|
| Veralteter Altwert (`payments`/`guest_messages = portal`) blockierte den Wechsel zu A3 trotz Bestätigung | Implementierungsdefekt | **behoben** (`a3ab1b6`): Konflikte umfassen auch nicht mehr erlaubte variable Verantwortlichkeiten; bestätigte Altwerte werden nicht mehr gegen das neue Modell geprüft |
| Balance-Anforderung 7 Tage, Anreise-Info Obergrenze 14 Tage, Bewertungsbitte-Tage, Anzahlungsfrist | **P** | als Einstellung einführen (Abschnitt 6, Prio 2) |
| Linkdauer/Erinnerungsparameter der Datenanfrage nur auf Landlord-/Wohnungsebene | **R** (historisch) | je Kanal ermöglichen, wenn gewünscht (klein) |
| Auswahl der Ersatzstrategie bei Wegfall eines Moduls | fehlte als Hilfe | **neu**: Auswirkungs-Abgleich (Abschnitt 5) |
## 5. Auswirkungs-Abgleich (Auftrag 4)
`App\Process\ConfigurationImpact` wertet die Moduldefinitionen aus (`requires` hart/weich, `executions`, `why`, Plan des Modells) für den **Entwurf** des Konfigurators und liefert je Änderung: betroffene abhängige Schritte, weiterhin erforderliche fachliche Ergebnisse, zulässige Ersatzwege und einen Vorschlag. Er ändert nie selbst etwas. Das Beispiel „automatische Datenanfrage aus“ ergibt: Pflichtangaben bleiben erforderlich (`guest.details`), Ersatz: „nach Freigabe“, „von Hand“ (Aufgabe).
## 6. Fehlende Fähigkeiten, priorisiert
| Prio | Fähigkeit | Umfang | Abhängigkeit |
|---|---|---|---|
| 1 | Zahlungsplan je Kanal/Eingang: Anzahlungsanteil, Fristen (Tage), Anforderung X Tage vor Fälligkeit als `ProcessSetting` | klein–mittel: Enum-Fall(e), ConfirmBooking/TakeOver, `SendBookingReminders`, Konfigurator, Tests | F7 (wer kassiert) |
| 1 | Zahlungserinnerung automatisch/mit Freigabe statt nur Aufgabe | klein, aber Tor `EnforceMailTestMode` und Gastkommunikation beachten | Prio 1 oben |
| 2 | Mahnstufen (Fristen, Texte, Stufen) | mittel; rechtliche Prüfung nötig **O** | Zahlungsplan |
| 2 | Einstellbare Zeitpunkte: Anreise-Info Obergrenze, Bewertungsbitte je Kanal | klein | – |
| 3 | Nachweis-Mindestumfang Portalbestätigung (D3/D4) | klein, nach Beschluss F2 | **O** F2 |
| 3 | Dienstleister-Zustellung Anreise-Info | klein (Aufgabe) bis mittel (Anbindung) | – |
| 4 | Dokumentenarten je Kanal wählbar | mittel | – |
| 4 | Kommunikationskanal je Anfrage (WhatsApp usw.) | groß, Anbindung ausgeschlossen | F4/F5 |
| 4 | Bank-Abgleich Zahlungseingang | groß | – |
## 7. Offene Festlegungen (blockieren nichts)
F2 Mindestnachweis, F3 Wartefrist (Vorschlag 48 h), F4/F5 Messenger, F6 DS-01…06/FW-01…07 Prüfpunkte, F7 Inkasso Destination Solutions, Storno/Erstattung je Modell (DS-06/FW-05), rechtliche Ausgestaltung der Mahnung. Siehe `V2.1/01_KONFIGURATIONSLUECKEN.md`.
## 8. Referenzfall Destination Solutions A3 – was heute **ohne Quellcodeänderung** einstellbar ist
| Anforderung | Einstellbar? |
|---|---|
| Extern verbindliche Buchung | ja (Modell A3, `binding.portal`) |
| Eigene Zahlungsabwicklung | ja (A3, Inkasso beim Vermieter; Wechsel A4↔A3 inkl. Bestätigung getestet) |
| Dokumentenerstellung/-übermittlung | ja: `processing`, `contract_delivery`, Vorlage, Buchungsinformation |
| Zahlungsanforderung, Fristen | **teilweise**: Anzahlungsfrist mandantenweit; Rest-Anforderung fest 7 Tage (P) |
| Zahlungserinnerung | **teilweise**: Aufgabe + Versand per Klick |
| Mahnung | **nein** (F) |
| Warten auf Portalbestätigung für Folgeaktionen | ja (Schalter + Frist) |
| Unabhängige Datenbeschaffung | ja (`guest.data_request`, eigene Modi) |
| Fristen, Nachweise, Eskalationen | ja (Aufgaben, Postfach, Digest); Zahlungs-Eskalation siehe oben |