Files
fewo-stommer/docs/Prozessarchitektur/UMSETZUNGSERGEBNIS_P4.md
T
LarsandClaude Opus 5.5 ac9d20b812 Ein Eingang fuer alle Kanaele (Paket 4, Prozessarchitektur v0.10)
Portalbuchungen und -anfragen aus Kalender und Mail werden ueber PortalIntake
zum Vorgang (nur bei sicherer Erkennung), Dubletten ueber Buchungsnummer,
gleiches Portal mit gleichen Naechten und Spiegelung; Unsicheres wird geklaert.
Portalstorno und -aenderung als Aufgabe am Vorgang ohne stille Stornierung.
Schalter je Kanal (Aus als Standard, Beobachten, Anlegen, Anlegen + weiter),
Eingangsprotokoll, Bestandsuebernahme mit Vorschau/Bericht/Ruecknahme,
Sperrnachweis in drei Stufen.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 20:53:35 +01:00

18 KiB
Raw Blame History

Umsetzungsergebnis Paket 4: Ein Eingang für alle Kanäle

Stand: 03.11.2026 · Branch feature/eingang (aufbauend auf cf11c8a, Pakete 1–3) · Grundlage: UMSETZUNGSPLAN_v0.10 §4.3, §5.5, Abnahmekriterien 4.1–4.7. Die normative Prozessarchitektur v0.10 wurde nicht verändert.

Hinweis: Der Auftrag kam abgeschnitten an (Abschnitt 11 endet mitten im Satz). Umgesetzt wurde alles bis dahin. Dokumentation und Bericht folgen dem Muster der Pakete 1–3.


1. Implementierungsstand

Paket 4 ist umgesetzt. Alle Abnahmekriterien 4.1–4.7 sind durch Tests belegt, die Oberflächen wurden im Browser geprüft. Kein Portal ist automatisch aktiviert: Jeder Kanal steht auf „Aus“, auch nach der Migration. Die Aktivierung auf Produktion ist nicht Teil des Auftrags.

Bereich Stand
Ein Eingang für Kalender, Buchungs-, Anfrage- und Stornomails (App\Channels\Intake\PortalIntake) umgesetzt
Automatische Vorgänge nur bei sicherer Erkennung; unsichere Fälle werden geklärt umgesetzt
Dublettenregel: Referenz → gleiches Portal mit gleichen Nächten → Spiegelung; keine Zusammenführung nach Überschneidung umgesetzt
Schalter je Kanal: Aus / Beobachten / Anlegen / Anlegen und weiterbearbeiten umgesetzt
Eingangsprotokoll (Expertenansicht und Befehl) umgesetzt
Portalstorno und -änderung als Aufgabe am Vorgang, nie stille Stornierung umgesetzt
Sperrnachweis in drei Stufen umgesetzt
Bestandsübernahme mit Vorschau, Bericht, Wiederholbarkeit, Rücknahme umgesetzt
A2-Portalanfrage aus der Anfrage-Mail umgesetzt
Rückbau von „Ungeklärte Belegungen“ und AssignOccupationGuest teilweise (siehe §7)

Tests: 662 grün (vorher 648; 14 neue in CaseIntakeTest), Pint sauber.


2. Umgesetzte Geschäftsfunktionen

Sicher erkannte Buchung → Vorgang ohne Klick.

  • Quellen: eine Buchungsmail des Portals mit Zeitraum und Buchungsnummer, oder ein Kalendereintrag, den die Regeln des Kanals als Reservierung dieses Portals erkennen bzw. den die Vermieterin so eingeordnet hat.
  • Ergebnis: ein Vorgang „Gebucht über FeWo-direkt“ mit Ursprungskanal, Buchungsnummer und Abwicklungsprofil; die Vorgangsart ergibt sich aus dem Profil (A3/A4/A5).
  • Was nicht entsteht: kein Angebot, keine Annahme, kein eigener Preis. Gast, Personen und Preis bleiben „noch nicht bekannt“; ein Name aus dem Kalender steht nur als Hinweis in der Notiz.
  • Nächste Schritte: Die Aktivitäten aus Paket 2 übernehmen, z. B. „Kontaktdaten eintragen“, „Gesamtpreis laut Portal eintragen“, „Buchungsunterlagen prüfen und senden“.

Derselbe Fall auf mehreren Wegen bleibt ein Vorgang.

  • Kommt die Buchung zuerst per Mail und dann im Kalender, wird der Kalendereintrag dem Vorgang zugeordnet. Ebenso die Spiegelung bei einem anderen Portal.
  • Wiederholte Abgleiche und Mails erzeugen nichts doppelt.
  • Unterschiedliche Buchungsnummern oder nur überlappende Termine werden nie zusammengeführt, sondern geklärt.

Unklare Belegung.

  • Unter „Zu erledigen“ steht: „Belegung von FeWo-direkt klären – Für den Zeitraum 26.11.–29.11.2026 wurde eine Belegung von FeWo-direkt gemeldet. Bitte klären Sie, um welche Art von Belegung es sich handelt.“
  • Der Knopf „Klären: Was ist das?“ bietet drei Antworten:
    • Buchung über das Portal: Der Vorgang entsteht.
    • Gehört zu einem vorhandenen Vorgang: nur Vorgänge mit genau diesen Nächten.
    • Keine Buchung: Sperre, eigene Nutzung oder Spiegelung.
  • Die bisherigen Detailwerkzeuge liegen unter „Weitere Möglichkeiten“.

Portalanfrage (A2). Eine Anfrage-Mail des Portals wird zum Vorgang „Anfrage über FeWo-direkt“ mit Zeitraum und Anfragenummer. Gast und Personen bleiben unbekannt, der Vorgang fragt sie gezielt ab und läuft danach wie A1. Ob der Zeitraum reserviert wird, folgt der Einstellung für Anfragen dieses Portals.

Portalstorno und -änderung.

  • Auslöser:
    • Stornomail mit Buchungsnummer eines gebuchten Vorgangs;
    • Kalendereintrag eines gebuchten Vorgangs, der verschwunden ist (erst nach zwei bestätigenden Abgleichen);
    • abweichende Termine im Kalender.
  • Folgen am Vorgang:
    • Aufgabe „Das Portal meldet eine Stornierung – bitte prüfen“ bzw. „… eine Änderung …“;
    • Eintrag im Verlauf mit dem Portal als Quelle;
    • die Aufgabe wird zum nächsten Schritt des Vorgangs.
  • Was nicht passiert: Der Vorgang bleibt gebucht und der Zeitraum belegt. Ein mit dem Vorgang verbundener Mail-Eintrag wird nicht mehr freigegeben. Über „Stornieren …“ (Paket 2) gelangt die Vermieterin in den Stornoweg.
  • Jede Meldung zählt einmal. Zwei verschiedene Mails sind zwei Meldungen; derselbe verschwundene Eintrag bleibt eine.

Sperrnachweis.

  • „Erledigt“ bei einer Portalaufgabe fragt, was die Person sagen kann:
    • „Ich habe den Zeitraum im Portal gesperrt“ (veranlasst);
    • „… und im Kalender des Portals gesehen“ (im Portal gesehen);
    • „Das Portal hat es bestätigt“ (Wirksamkeit bestätigt);
    • optional mit Notiz.
  • „Nachweis ergänzen“ hebt die Stufe später an, senkt sie aber nie.
  • Die Vorgangsseite zeigt die Stufe, z. B. „In Ostseeklar sperren · 07.12.–14.12.2026 · im Portal gesehen (im Kalender rot)“.
  • Eine erledigte Automatisierung gilt nur als veranlasst.

3. Nachweise zu den Abnahmekriterien

ID Kriterium Nachweis (tests/Feature/CaseIntakeTest.php) Ergebnis
4.1 A3 Destination Solutions manuell; gebucht ohne Angebot/Annahme; Sperraufgaben, Unterlagen, Zahlung durch uns, Portalpreis test_a_destination_solutions_booking_is_entered_by_hand_and_handled_by_us: A3, bestätigt, Angebotsversion 0, Preis 840,00 €, Zahlungsaufgaben aktiv, „In Ostseeklar sperren“, „Buchungsunterlagen prüfen und senden“ erfüllt
4.2 FeWo-direkt-Mail → Vorgang ohne Klick; späterer iCal-Eintrag → kein zweiter; Zahlung „über das Portal“, keine eigenen Mahnungen test_a_booking_mail_becomes_a_case_and_the_later_calendar_entry_joins_it erfüllt. Fehlende Postanschrift erzeugt keine Aufgabe; die E-Mail-Adresse wird nur verlangt, weil eigene Unterlagen sie brauchen.
4.3 iCal-Eintrag ohne Erkennung → kein Vorgang, Aufgabe „Was ist das?“, Antwort „Buchung“ legt ihn an test_an_unrecognised_calendar_entry_is_clarified_and_the_answer_booking_creates_the_case erfüllt
4.4 Stornomail oder verschwundener iCal-Eintrag → „Stornierung prüfen“, Vorgang bleibt gebucht test_a_cancellation_mail_reaches_the_case_as_a_task_and_cancels_nothing, test_a_disappeared_or_changed_calendar_entry_is_reported_once_and_nothing_is_released erfüllt
4.5 „In Portal X sperren“, Erledigen mit Stufe und Notiz, Vorgangsseite zeigt Nachweisgrad test_portal_blocks_state_how_far_they_are_proven erfüllt
4.6 Beobachtungsmodus: keine Vorgänge, Bericht über das, was entstanden wäre test_observing_creates_nothing_and_reports_what_would_have_been_created (channels:intake-report) erfüllt
4.7 A2-Portalanfrage mit unvollständigen Daten → Anfrage, fordert fehlende Daten test_a_portal_request_becomes_a_request_that_asks_for_the_missing_data erfüllt

Weitere Tests:

  • Kalender mehrfach gelesen ergibt genau einen Vorgang und einen Protokolleintrag.
  • Gleiches Portal mit gleichen Nächten wird dem vorhandenen Vorgang zugeordnet.
  • Fremdportal-Reservierung und überlappende Reservierung werden nie zum Vorgang.
  • Ein nicht eingeschalteter Kanal verhält sich wie bisher; neue Kanäle starten auf „Aus“.
  • „Anlegen und weiterbearbeiten“ versendet trotzdem keine unfreigegebenen Unterlagen.
  • Bestandsübernahme: Vorschau, Anwendung, Wiederholung ohne Dublette, Rücknahme.

4. Technische Umsetzung

Baustein Inhalt
App\Channels\Intake\PortalIntake (neu) evaluate() bewertet ohne Änderung; process() handelt nach Kanalschalter; afterSync() nach jedem Kalenderabgleich; cancellationMail(), inquiryMail(); adopt() für die Bestandsübernahme. Ergebnisse als IntakeDecision mit Begründung und fehlenden Angaben.
App\Enums\CaseIntakeMode, IntakeOutcome, ChannelTaskProof (neu) Schalter je Kanal, Ergebnis eines Eingangs, Nachweisstufe
App\Models\IntakeObservation (neu) Eingangsprotokoll; ein Eintrag je Ereignis und Ergebnis (Fingerabdruck, eindeutig je Mandant)
App\Actions\TakeOverPortalInquiry (neu) A2-Anfrage mit unbekannten Angaben, Reservierung nach Kanalprofil
TakeOverExternalBooking Neues Feld processing_mode. Automatisch angelegte Vorgänge laufen bei „Anlegen“ mit Freigabe, bei „Anlegen und weiterbearbeiten“ nach Profil.
SyncChannel Ruft nach erfolgreichem Abgleich afterSync() auf, gekapselt mit rescue(). Ein Fehler im Eingang lässt den 5-Minuten-Abgleich nie scheitern.
ProcessPortalMail Leitet Buchung, Anfrage und Storno an den Eingang. Ein mit einem Vorgang verbundener Mail-Eintrag wird durch eine Stornomail nicht mehr freigegeben (Status „Bitte prüfen“).
BookingTaskKind PortalCancellationReported, PortalChangeReported. Je Vorgang und Art eine Aufgabe; eine neue Meldung öffnet sie wieder.
ChannelTask proof, proof_note, proof_at, proof_by; complete() mit Stufe; prove() hebt nur an; proofLabel()
CaseActivities Portalmeldungen haben Vorrang als nächster Schritt; Sperraufgaben zeigen ihren Nachweis.
Oberfläche Kanalformular „Erkannte Buchungen automatisch als Vorgang übernehmen?“; Klärdialog an der Portalbelegung; Dialoge „Erledigt“ und „Nachweis ergänzen“ bei Portalaufgaben; Eingangsprotokoll unter System (Expertenansicht); Vorgangsseite, technischer Abschnitt „Quellen und Kalenderdarstellungen“
Befehle channels:intake-report {--days}; channels:adopt-occupations {--channel=*} {--apply} {--revert=}
Migration 2026_11_03_090000_create_case_intake, rein additiv: channels.case_intake (Standard off), Tabelle intake_observations, Nachweisspalten an channel_tasks

Wann ein Eintrag als sicher gilt.

  • Mail: Typ „Buchung“ mit Zeitraum und Buchungsnummer. Ohne Nummer wird geklärt, weil sich ein späterer Kalendereintrag sonst nicht sicher zuordnen lässt.
  • Kalender: Die Regel erkennt „Portalreservierung“, „Kandidat für führende Belegung“ und Ursprung „dieses Portal“; oder die Vermieterin hat den Eintrag als Reservierung dieses Portals eingeordnet.

Was immer geklärt wird.

  • Belegt-Meldungen ohne Regel
  • Spiegelungen fremder Portale
  • Überschneidung mit einem Vorgang oder mit weiteren Einträgen desselben Portals
  • Prüfhinweise am Eintrag
  • „Was kommt über dieses Portal?“ = „nur Anfragen“

Was nie ein Vorgang wird. Einträge, die als Sperrzeit oder privat eingeordnet sind, sowie Vergangenes.

Zuordnung nach Terminen. Nur innerhalb desselben Portals, bei genau gleichen Nächten und genau einem passenden Vorgang ohne widersprechende Buchungsnummer. Ein Portal kann dieselben Nächte nicht zweimal vergeben, deshalb ist das keine Datumsheuristik im Sinn des Auftrags.

Mandantentrennung. Alle Abfragen laufen über den Mandantenbereich der Modelle; das Protokoll ist je Mandant eindeutig.


5. Aktivierung, Automatik und externe Kommunikation

Schalter je Kanal (Kanäle › Portal bearbeiten):

Stufe Wirkung
Aus (Standard, auch für alle bestehenden Kanäle) Wie bisher. Erkannte Buchungen erscheinen als Klärungsfall; es wird nichts protokolliert.
Beobachten Es entsteht nichts und es wird nichts geändert. Das Eingangsprotokoll zeigt Ergebnis, Vorgangsart, Zuordnung, fehlende Angaben und Begründung.
Anlegen Vorgänge, Zuordnungen, Klärungen und Meldungsaufgaben entstehen. Neue Vorgänge stehen auf „Sie geben frei“.
Anlegen und weiterbearbeiten Wie „Anlegen“; die neuen Vorgänge folgen der Einstellung unter „So arbeite ich“.

Externe Kommunikation. Kein automatisch angelegter Vorgang versendet etwas, das nicht freigegeben ist. Buchungsunterlagen extern gehen erst raus, wenn beides vorliegt:

  • die Buchungsunterlagen sind freigegeben;
  • die Portalvorlage ist freigegeben und als Wiedergabe der Portalbedingungen bestätigt.

Das ist der Freigabeschutz aus Paket 3. Bei „Anlegen“ gibt die Vermieterin zusätzlich jeden Schritt selbst frei. Zahlungsaufforderungen entstehen nur, wenn wir laut Profil für die Zahlung zuständig sind.

Meldungen zu bekannten Vorgängen (Storno, Änderung) erzeugen Aufgaben nur bei „Anlegen“ oder „Anlegen und weiterbearbeiten“. Bei „Beobachten“ werden sie nur protokolliert. Bei „Aus“ bleibt es wie bisher: Die Portalmail wird als „Bitte prüfen“ gemeldet.

Vermeidung unnötiger Aufgaben.

  • Ein verschwundener Eintrag zählt erst, wenn der Abgleich ihn nach zwei bestätigenden Läufen entfernt.
  • Bei ungewöhnlich vielen fehlenden Einträgen wird nichts entfernt.
  • Unveränderte Wiederholungen erzeugen weder Aufgaben noch Verlaufseinträge.
  • Fehlgeschlagene Abgleiche lösen keine Meldungen aus.

6. Ergebnisse der Tests und der visuellen Prüfung

Tests: 662 Tests, 3636 Zusicherungen, alle grün. Pint sauber. Die bestehenden Kanal-, Mail-, Spiegelungs- und Klärungstests (129) laufen unverändert; nur ein Listentitel unter „Zu erledigen“ wurde angepasst.

Browser: Chromium über Playwright, lokaler Server, Kopie der lokalen Datenbank im Scratchpad, Anmeldung mit Zwei-Faktor-Code, Kanal „FeWo-direkt“ auf „Anlegen“. Geprüft:

  • „Zu erledigen“:
    • „Belegung von FeWo-direkt klären“ mit dem Klartextsatz;
    • „Das Portal meldet eine Stornierung – bitte prüfen“ am automatisch angelegten Vorgang;
    • „In Ostseeklar sperren“;
    • „Buchungsunterlagen prüfen und senden“ mit den Prüfpunkten aus Paket 3.
  • Klärdialog: zwei passende Antworten, die dritte („vorhandener Vorgang“) erscheint nur bei Vorgängen mit gleichen Nächten.
  • Dialog „Erledigt“ mit den drei Nachweisstufen und Notiz.
  • Eingangsprotokoll mit Klärung, Neuer Vorgang und Stornomeldung. Daraufhin habe ich die Begründung unter das Ergebnis verlegt, weil sie in der breiten Tabelle abgeschnitten war.

Keine Konsolenfehler. Die lokale Arbeitsdatenbank blieb unberührt.

Nicht geprüft: echte Portalmails und echte Feeds von FeWo-direkt; Tablet und Smartphone; MariaDB.


7. Rückwärtskompatibilität und verbleibende Risiken

Kompatibilität:

  • Ohne Einschalten ändert sich nichts. Die einzige sichtbare Änderung für alle sind der neue Klärdialog und der Titel unter „Zu erledigen“.
  • Bestehende Vorgänge, Preise, Dokumente und Spiegelungen bleiben unverändert.
  • Die Bestandsübernahme ändert nur mit --apply etwas. Sie legt Vorgänge mit Freigabe an und schreibt einen Bericht nach storage/app/private/intake-adoptions/.
  • --revert=<Bericht> stellt die Einträge wieder her und entfernt die Vorgänge des Laufs, sofern mit ihnen noch nichts geschehen ist (kein Dokument, keine Zahlung). Offene Sperraufgaben des Laufs werden verworfen.
  • Vor --apply auf echten Daten zusätzlich eine Datenbanksicherung ziehen.

Nicht vollständig zurückgebaut:

  • „Gast zuordnen“ an der Portalbelegung (AssignOccupationGuest) und die Liste „Portalbelegungen & Klärung“ bestehen in der Expertenansicht weiter. Die einfache Ansicht braucht sie nicht mehr. Der vollständige Rückbau gehört in einen eigenen Schritt, weil viele bestehende Tests und der Belegungsplan darauf aufbauen.
  • OpenPortalFile bleibt als Baustein der Antwort „Buchung“.

Risiken:

  • Erkennung realer Mails: nur an Testmustern geprüft (Annahme §8.5 des Plans). Deshalb zuerst „Beobachten“ und das Protokoll mit echten Fällen abgleichen.
  • Kalenderregeln: Die Sicherheit der iCal-Übernahme hängt an der Regel des Kanals („Portalreservierung, führend, dieses Portal“). Eine zu weit gefasste Regel würde falsche Vorgänge erzeugen. Auch dafür ist der Beobachtungsmodus da.
  • Buchungsmails ohne Nummer werden geklärt, nicht übernommen. Liefert ein Portal nie Nummern, bleibt dort die Klärung.
  • Last im 5-Minuten-Abgleich: afterSync() läuft je Kanal über dessen offene Einträge. Bei wenigen Wohnungen ist das unkritisch, und ein Fehler bricht den Abgleich nicht ab.
  • Sperraufgaben entstehen wie bisher für jede belegende Sperre, auch für unklare Einträge. Das ist unverändert und gewollt, damit nichts doppelt vermietet wird.
  • Die Migration ist auf MariaDB noch nicht geprüft.

8. Offene Punkte und erforderliche Entscheidungen

Was Wer Wirkung bis dahin
Je Portal entscheiden, wann von „Aus“ auf „Beobachten“ und danach auf „Anlegen“ umgestellt wird Betreiber Alles wie bisher
Kalenderregeln je Portal prüfen: Liefert der Feed Buchungsnummer oder Gastnamen? (§8.3: „Erkennt die iCal-Regel sicher?“) Betreiber, Kanaleinrichtung Ohne Regel nur Klärung
Absenderadressen der Portalmails eintragen, Mail-Eingang einschalten Betreiber Keine Mail-Übernahme
Freigaben aus Paket 3 (Buchungsunterlagen, FeWo-direkt-Vorlage FW-01) Betreiber Unterlagen nur von Hand mit Bestätigung
Bestandsübernahme auf Test, dann Produktion (--apply, mit Sicherung) Betreiber Bestehende Belegungen bleiben Klärungsfälle

Grundsatzentscheidungen wurden nicht getroffen; B1 und B3–B5 bleiben offen.


9. Empfehlung für die nächsten Schritte

  1. Pakete 1–4 auf dem Testsystem ausrollen. Danach FeWo-direkt auf „Beobachten“ stellen, nach einigen echten Buchungen channels:intake-report prüfen und erst dann auf „Anlegen“.
  2. Paket 5 (Änderung, Storno, kontrollierter Abbruch) schließt direkt an: Die Aufgaben „Das Portal meldet eine Stornierung/Änderung“ sind die Einstiege. Paket 5 kann sie um „Stornierung übernehmen“ (Initiator „Gast über Portal“) und die Stornobestätigung als Dokumentart erweitern.
  3. Danach den Rückbau der Expertenwerkzeuge an Portalbelegungen (§7) und die Bedienprobe mit der Vermieterin.