Files
fewo-stommer/docs/architecture/ical-synchronisation-pruefung-2026-10-27.md
Lars 783068501c
Deploy FeWo mit PipelineManager / deploy (push) Successful in 2m33s
Generische iCal-Kanäle mit Bestandsklärung und sicheren Exporten bereitstellen
2026-10-27 17:14:45 +01:00

17 KiB
Raw Permalink Blame History

Der direkte FeWo-direkt-Fall ist korrekt abgesichert: Eine als Sperrzeit mit FeWo-direkt als Herkunftskanal importierte Sofortbuchung wird im Feed für genau diesen Kanal ausgeschlossen. Auch eine manuelle Sperraufgabe wird nicht an den Herkunftskanal zurückgegeben.

Eine umfassende Rückkopplungs- und Dublettensicherheit besteht dennoch nicht. Risiken liegen besonders bei veränderter Herkunft, der Mail/iCal-Zusammenführung, unvollständigen Kalenderantworten und den Sperraufgaben bei Terminänderungen.

Prüfstand: lokaler Commit 6fe5bbc, 27.10.2026. Keine Dateien, Anwendungsdaten, Konfigurationen oder Kalender verändert. Keine Portal-, Postfach- oder Datenbankzugriffe ausgeführt.

Dokumentation, Implementierung und Verifikation

Ebene Feststellung
Dokumentiert Kanalspezifische Feeds ohne eigene Portalbelegungen; Kalenderabgleich alle fünf Minuten; Mail-Schnellweg mit späterer Kalenderbestätigung. Siehe PORTALE.md:100.
Implementiert Herkunftskanal, Exportausschluss und zusätzlicher UID-Echofilter sind vorhanden. Änderungen und Löschungen werden anhand der UID verarbeitet.
Vorhandene Testnachweise Feature-Tests mit synthetischen Kalendern und simuliertem HTTP/Mailversand. Laut Projektstand war die Gesamtsuite erfolgreich; in dieser Prüfung nicht erneut ausgeführt.
Hier praktisch geprüft Ausschließlich speicherbasierte Parserproben und eine isolierte Probe des installierten Laravel-After-Commit-Verhaltens.
Nicht praktisch verifiziert Tatsächliche Portalzuordnungen, eingetragene Exportadressen, echte FeWo-direkt-Ereignisse, UID-Erhaltung durch andere Portale und deren Löschverhalten. Laut Betriebsdokumentation sind Postfachabruf und regelmäßiger Hintergrundbetrieb noch nicht vollständig eingerichtet.

1. Import, Herkunft und Export je Kanal

Es existiert ein generischer iCal-Connector, keine besondere FeWo-direkt-Importlogik. Importadresse und Exporttoken gehören zum jeweiligen Kanaldatensatz. Der reguläre Import berücksichtigt aktive, freigeschaltete Kanäle mit Importadresse: SyncChannels.php:29.

Die Herkunft wird folgendermaßen geführt:

Eingang Kennzeichnung
iCal channel_id des abrufenden Kanals, source = channel, ursprüngliche external_uid
Portal-Mail channel_id des erkannten Kanals, source = email, zunächst external_uid = email:<Referenz>
Manuelle Sperre source = manual; ohne Kanalzuordnung gilt sie als eigene Sperre

Beim iCal-Import entstehen Sperrzeiten, keine vollständigen Buchungen. Der Portalname wird als Grund gespeichert; der möglicherweise personenbezogene SUMMARY wird nicht übernommen. Siehe SyncChannel.php:64 und ProcessPortalMail.php:136.

Für eine FeWo-direkt-Sofortbuchung mit Herkunftskanal A ergibt sich:

Ziel Verhalten im Code
Eigene Verfügbarkeitsprüfung Zeitraum ist gesperrt
Exportfeed für A Sperre ausgeschlossen
Exportfeed für anderen Kanal B Sperre enthalten
Manuelle Sperraufgabe für A ausgeschlossen
Manuelle Sperraufgabe für B entsteht, sofern B entsprechend eingerichtet ist

Der Export filtert ausdrücklich nach channel_id, unabhängig davon, ob die Sperre aus Mail oder iCal stammt: ICalFeed.php:31. Der Observer übergibt dieselbe Herkunft als Ausschluss an die Aufgabenanlage: BlockedPeriodObserver.php:43, CreateChannelTasks.php:33.

Der Kalender wird zum Abruf bereitgestellt; ein Abruf durch FeWo-direkt ist dadurch noch nicht nachgewiesen.

2. Grenzen des Rückkopplungsschutzes

Zusätzlich erzeugt der Export UIDs wie block-123@fewo-stommer. Beim Import werden Ereignisse mit diesem Suffix verworfen: ICalFeed.php:37, SyncChannel.php:43.

Dieser zweite Schutz funktioniert nur bei erhaltenem Suffix:

  • A-Belegung wird intern importiert und an B exportiert.
  • B liefert dieselbe Belegung mit neu erzeugter UID ohne Suffix zurück.
  • Sie wird als neue B-Sperre importiert.
  • Diese B-Sperre erscheint anschließend im Feed für A.

Eine ursprüngliche Herkunft über mehrere Portale hinweg wird nicht gespeichert. Ob ein tatsächlich genutztes Portal UIDs verändert, ist nicht praktisch geprüft.

Außerdem gilt der Ausschluss für die konkrete Kanal-ID, nicht für den Namen „FeWo-direkt“. Ein zweiter Kanaldatensatz desselben Portals oder eine im Portal vertauschte Feedadresse kann den Schutz umgehen.

Eine weitere Grenze: Wird ein Portalaufenthalt zusätzlich als normale Booking erfasst, exportiert der Feed diese Buchung ohne kanalbezogenen Herkunftsausschluss: ICalFeed.php:26. Auch der Buchungsobserver reicht keinen Herkunftskanal zum Ausschluss weiter: BookingObserver.php:56.

3. Änderungen und Stornierungen

Für vorhandene iCal-Sperren gilt:

  • Gleiche Kanal-ID und UID, unveränderte Daten: keine Änderung.
  • Gleiche UID, andere Daten: vorhandene Sperre aktualisieren.
  • Zukünftige Sperre fehlt im nächsten erfolgreich verarbeiteten Feed: löschen.
  • STATUS:CANCELLED: Parser überspringt das Ereignis; dadurch wird eine zuvor importierte zukünftige Sperre anschließend als fehlend entfernt.
  • Vergangene Sperren werden bei dieser Bereinigung behalten.

Code: SyncChannel.php:52, SyncChannel.php:100, ICalParser.php:63.

HTTP-Fehler oder eine Antwort ohne Kalenderkennung führen zum Fehlerpfad, bevor Sperren abgeglichen werden.

Hohes Risiko: unvollständige Kalender werden dagegen als gültiger Bestand behandelt. Praktisch beobachtet:

Parserprobe Ergebnis
Gültiger Kalender mit einem Ereignis ein Zeitraum
Nur BEGIN:VCALENDAR null Zeiträume, keine Ausnahme
Ein vollständiges und ein abgeschnittenes Ereignis nur das vollständige Ereignis, keine Ausnahme
HTML statt Kalender Ausnahme

Der Parser verlangt keine vollständige Kalenderstruktur: ICalParser.php:22. Zusammen mit der Löschung fehlender Ereignisse bedeutet das: Eine unvollständige erfolgreiche HTTP-Antwort kann bestehende Sperren entfernen und anschließend als erfolgreicher Abgleich protokolliert werden. Diese Löschfolge ist aus dem Code abgeleitet, nicht an einer Datenbank ausgeführt.

4. Zusammenführung von Mail-Sperren und iCal

Die implementierte Logik ist eingeschränkter als die allgemeine Dokumentationsaussage „abweichende Daten ersetzen die Mail-Sperre“:

Fall Tatsächliches Verhalten
Gleicher Kanal und exakt gleiche Termine Mail-Sperre wird auf source = channel und iCal-UID umgestellt; dieselbe Sperr-ID bleibt erhalten
Abweichende, überlappende Termine iCal-Sperre wird angelegt/aktualisiert; überlappende Mail-Sperren desselben Kanals werden gelöscht
Vollständig verschobener, nicht überlappender Termin Keine Zusammenführung; alte Mail-Sperre bleibt zusätzlich bestehen
Kalender kennt die Mail-Buchung noch nicht Mail-Sperre bleibt absichtlich bestehen

Code: SyncChannel.php:73, SyncChannel.php:92.

Risiko: Beim Ersetzen wird keine Buchungsreferenz mit der iCal-UID abgeglichen. Überschneidung allein gilt als Zuordnung. Dadurch können andere Mail-Sperren fälschlich entfernt werden; vollständig verschobene Buchungen können dagegen doppelt gesperrt bleiben.

Die Mail-Stornierung löscht ausschließlich source = email. Nach erfolgreicher iCal-Übernahme kann sie die Sperre nicht mehr unmittelbar aufheben; sie meldet Prüfbedarf und wartet auf den Kalenderabgleich: ProcessPortalMail.php:155.

Umgekehrt verschwinden nie bestätigte Mail-Sperren nicht durch bloßes Fehlen im Kalender. Ohne passende Stornomail oder weitere Bearbeitung können sie bestehen bleiben.

5. Doppelsperren und manuelle Portalpflege

Hier bestehen zusätzliche Risiken:

  • Doppelte UID im selben Feed: Der Parser liefert beide Ereignisse zurück – praktisch bestätigt. Der Import verwendet einen einmalig eingelesenen Bestand und ergänzt diesen während der Schleife nicht. Neue doppelte UIDs können deshalb mehrfach angelegt werden. Ein Unique-Constraint verhindert das nicht; vorhanden ist nur ein Index: Migration:16.
  • Parallele Läufe: Keine kanalbezogene Sperre innerhalb von SyncChannel. Der Scheduler besitzt Überlappungsschutz; manuelle Aufrufe können daneben stattfinden.
  • Gleichkanalige Überschneidungen: Die Konflikterkennung ignoriert sie ausdrücklich. Damit meldet sie auch entsprechende Dubletten nicht: ConflictDetector.php:26.
  • Belegung versus Export: Die Verfügbarkeitsprüfung behandelt Nächte als Menge; doppelte Datensätze verdoppeln dort keine Nächte. Der Export erzeugt hingegen ein Ereignis pro Sperrdatensatz: AvailabilityChecker.php:39.

Hohes Risiko bei Terminänderungen: Der Sperrzeit-Observer läuft nach Commit und liest die alten Termine mit getOriginal(): BlockedPeriodObserver.php:24.

Das installierte Laravel reicht dasselbe Modellobjekt verzögert weiter und synchronisiert zuvor dessen Originalwerte: Dispatcher.php:620, Model.php:1510.

Die speicherbasierte Probe ergab:

Vor verzögertem Aufruf: original = 2026-11-07
Im After-Commit-Listener:
  wasChanged = true
  original   = 2026-11-14
  current    = 2026-11-14

Damit kann die Entsperraufgabe den neuen statt des alten Zeitraums betreffen. Der vollständige Anwendungspfad wurde nicht ausgeführt.

Beim Ersetzen einer überlappenden Mail-Sperre besteht außerdem die Aufgabenfolge „neuen Zeitraum sperren, alten Zeitraum entsperren“. Eine Prüfung, welche Nächte weiterhin durch andere Sperren belegt sind, erfolgt in der Aufgabenanlage nicht. Eine nachgelagerte Automatisierung könnte dadurch weiterhin belegte Nächte freigeben.

6. Herkunftszuordnung über E-Mail

Die Kanalauswahl nimmt den ersten aktiven Kanal mit passendem Absenderfragment. Inserats- oder Wohnungskennung werden dabei nicht ausgewertet: ProcessPortalMail.php:92.

Bei mehreren Wohnungen desselben Mandanten mit FeWo-direkt-Kanälen und identischen Absenderregeln kann eine Mail deshalb der falschen Wohnung zugeordnet werden. Der iCal-Import hat dieses spezielle Problem nicht, weil er bereits einen bestimmten Kanal abruft.

Vorhandene Tests und ihre Grenzen

Abdeckung Codeverweis
Datumswerte, Uhrzeiten, gefaltete Zeilen, stornierte Ereignisse ChannelSyncTest.php:60
Hinzufügen, Ändern, Entfernen und eigenes UID-Suffix ignorieren ChannelSyncTest.php:88
Eigene Portalbelegung im Export ausschließen ChannelSyncTest.php:137
Herkunftskanal von manuellen Aufgaben ausschließen ChannelSyncTest.php:156
Mail sofort sperren; wiederholte Nachricht erkennen PortalMailTest.php:90
Exakte Mail/iCal-Zusammenführung ohne zusätzliche Aufgaben PortalMailTest.php:116
Überlappend geänderte Termine ersetzen Mail-Sperre PortalMailTest.php:130
Mail-Sperre überlebt leeren Feed; Mail-Storno gibt sie frei PortalMailTest.php:140
Mandantentrennung und Dienstsperre für Feeds TenantScheduleTest.php:123, TenantServiceGateTest.php:27

Der Exporttest legt Sperren direkt an. Er prüft nicht die komplette Kette FeWo-Sofortbuchungsmail → iCal-Übernahme → beide Exportfeeds → Storno. Die Änderungstests prüfen außerdem nicht die korrekten alten/neuen Zeiträume aller manuellen Aufgaben.

Weitere Parsergrenzen aus den Speicherproben: Wiederholungsregeln werden nicht expandiert; 20261131 wird zu 2026-12-01 normalisiert statt zurückgewiesen.

Reproduzierbarer Testplan – nicht ausgeführt

Für die zustandsändernden Fälle ausschließlich eine separate Wegwerf-Testumgebung verwenden: leere In-Memory-Datenbank, simuliertes HTTP/Mail, keine externen Netzwerkzugriffe oder echten Tokens. Keine Kopie produktiver Daten erforderlich.

Ausgangslage je Fall neu herstellen: Zeit 01.11.2026, eine Wohnung, Kanäle A = FeWo-direkt und B = anderes Portal, beide mit manueller Sperrpflege. Kalenderereignis U1 = 07.–10.11.2026.

Fall Schritte und zu prüfendes Ergebnis
T1 – Zentraler FeWo-Fall U1 über A importieren. Genau eine A-Sperre; im A-Feed nicht enthalten, im B-Feed enthalten; keine A-Sperraufgabe.
T2 – Wiederholung Identischen A-Feed zweimal importieren. Sperr-ID und Anzahl unverändert; keine zusätzlichen Aufgaben.
T3 – Unverändertes Echo B liefert die exportierte UID mit @fewo-stommer zurück. Keine neue B-Sperre und kein Rückexport an A.
T4 – Veränderte Echo-UID B liefert denselben Zeitraum mit neuer UID ohne Suffix. Prüfen, dass aktuell eine B-Sperre und damit ein Rückexport an A entsteht.
T5 – Mail vor Kalender A-Mail mit Referenz HA-TEST01 für U1 verarbeiten, danach U1 importieren. Dieselbe Sperr-ID, Quelle channel, keine zusätzlichen Aufgaben; beide Feeds prüfen.
T6 – Terminänderungen U1 bei gleicher UID zunächst verlängern, dann vollständig auf 14.–17.11. verschieben. Datenbestand sowie Entsperrung des alten und Sperrung des neuen Zeitraums prüfen. Mail-Vorlauf gesondert wiederholen.
T7 – Unsichere Zusammenführung Zwei unterschiedliche Mail-Sperren anlegen; ein iCal-Ereignis über beide hinweg liefern. Prüfen, welche Mail-Sperren ohne Referenznachweis gelöscht werden.
T8 – Storno Getrennt testen: Mail-Storno vor Übernahme; Mail-Storno nach Übernahme; U1 fehlt; U1 trägt STATUS:CANCELLED. Belegung, Feed und Aufgaben jeweils prüfen.
T9 – Fehlerantworten Nach bestehendem U1 HTTP 500, HTML, nur BEGIN:VCALENDAR und abgeschnittenen Kalender liefern. Sperrerhalt und Erfolgsmeldung vergleichen.
T10 – Dubletten U1 zweimal im selben Feed liefern; anschließend erneut synchronisieren. Anzahl, UIDs, Konfliktmeldungen und Exportereignisse prüfen. Parallelaufrufe separat testen.
T11 – Überlappende Sperraufgaben Mail U1, danach iCal 07.–11.11. Aufgaben für B in Ausführungsreihenfolge auswerten: Bleiben 07.–10.11. trotz nachfolgender Entsperraufgabe geschlossen?
T12 – Mehrere Wohnungen Zweite Wohnung mit eigenem A-Kanal und gleichen Mailabsendern anlegen. Nachweisen, welcher Wohnung eine Mail tatsächlich zugeordnet wird.

Vorhandene Tests lassen sich später dort ohne PHPUnit-Ergebnisdatei ausführen:

php vendor/bin/phpunit --do-not-cache-result --filter='ChannelSyncTest|PortalMailTest|TenantScheduleTest|TenantServiceGateTest'

Bewertung: Der direkte Herkunftsausschluss für FeWo-direkt ist nachvollziehbar implementiert und durch Teiltests abgedeckt. Eine praktische Freigabe der gesamten Synchronisationskette lässt sich daraus noch nicht ableiten. Vorrangige Prüfpunkte sind der Umgang mit unvollständigen Feeds, die Terminänderungsaufgaben und die nur heuristische Zuordnung zwischen Mail und iCal.