Files
fewo-stommer/docs/Prozessarchitektur/UMSETZUNGSERGEBNIS_P3.md
T
LarsandClaude Opus 5.5 cf11c8a474
Deploy FeWo mit PipelineManager / deploy (push) Successful in 3m59s
Dokumentenzusammenstellung und Vorlagensteuerung (Paket 3, Prozessarchitektur v0.10)
Eine Zusammenstellung vor jedem Dokument (Angebot, Bestaetigung, Buchungsunterlagen
extern), Dokumentart je Vorgangsart, Freigaben fuer Vorlagen und Dokumentarten,
Schutz vor unvereinbarten Bedingungen bei Portalbuchungen (E-004), kein doppelter
Versand, Absicherung Hold 0 bis Paket 7, A6-Aufenthaltsbestaetigung vorbereitet.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 19:44:52 +01:00

18 KiB
Raw Blame History

Umsetzungsergebnis Paket 3: Dokumentenzusammenstellung und Vorlagensteuerung

Stand: 02.11.2026 · Branch feature/vorgang · Grundlage: UMSETZUNGSPLAN_v0.10 §4.5, §5.4, Abnahmekriterien 3.1–3.3; UMSETZUNGSERGEBNIS_P1_P2. Die normative Prozessarchitektur v0.10 wurde nicht verändert.


1. Implementierungsstand

Paket 3 ist umgesetzt. Alle drei Abnahmekriterien sind durch Tests belegt, die Oberflächen wurden im Browser geprüft.

Bereich Stand
Gemeinsame Zusammenstellung für Angebot, Buchungsbestätigung und Buchungsunterlagen extern umgesetzt
Dokumentart je Vorgang automatisch (A1/A2 Angebot bzw. Bestätigung, A3/A4 Buchungsunterlagen, A5 Portal) umgesetzt
Vorlagenwahl über die Einstellungsebenen, Herkunft sichtbar umgesetzt
Freigabe von Vorlagen und Dokumentarten, Bestätigung der Portalbedingungen umgesetzt
Schutz vor unvereinbarten Bedingungen (E-004) mit bewusster Bestätigung umgesetzt
Kein doppelter Versand (Angebot und Unterlagen) umgesetzt
Absicherung Hold = 0 bis Paket 7 umgesetzt
Auskunft unter Vorbehalt (Paket 7) und A6-Aufenthaltsbestätigung (Paket 6) als Dokumentart und Arbeitsfassung vorbereitet, nicht versendbar
Storno- und Änderungsbestätigung (Paket 5) nicht Teil dieses Pakets

Tests: 648 grün (vorher 634; 13 neue in DocumentCompositionTest, ein neuer in PortalBookingTest), Pint sauber.


2. Tatsächlich umgesetzte Geschäftsfunktionen

Ein Prüfbild vor jedem Dokument. Vor dem Versand sieht die Vermieterin immer dieselbe Zusammenstellung:

  • Dokumentart, Empfänger mit E-Mail-Adresse, Eingang (z. B. „Gebucht über FeWo-direkt · Buchungsnummer HA-…“)
  • Wohnung, Zeitraum, Nächte, Personen (oder „noch nicht bekannt“)
  • Preis mit Positionen und Herkunft („aus Ihren Preisen berechnet“, „laut FeWo-direkt übernommen, nicht neu berechnet“, „wie im angenommenen Angebot“)
  • Zusatzleistungen, Stornoregel, Vorlage mit Herkunft der Einstellung, Anlagen, Annahmelink ja/nein
  • Hinweise in drei Stufen: Fehlt noch (rot, kein Versand), Bitte prüfen (gelb, nur nach Bestätigung), Information (blau)
  • aufklappbar: Vorschau der E-Mail und des Dokuments, dazu „Als PDF öffnen“

„Anpassen“ ist zugeklappt (Zeitraum, Preis/Nachlass, Vorlage, Anlagen, Gültigkeit, Gast). Jede Änderung rechnet die Zusammenstellung sofort neu. In der Expertenansicht zeigt sie zusätzlich Freigabestand und Portalbestätigung der Vorlage.

Wo sie erscheint:

  • „Angebot prüfen und senden“ (ersetzt den bisherigen Angebotsdialog)
  • „Bestätigung prüfen und senden“ bzw. „Buchungsunterlagen prüfen und senden“ (neu, ersetzt den ersten Versand über „Unterlagen an den Gast senden“)
  • „Direkt verbindlich bestätigen“ mit Schalter „Unterlagen an den Gast senden“

„Unterlagen erneut senden“ bleibt für bereits erstellte Unterlagen und schickt unverändert dieselben.

Buchungsunterlagen für beim Portal gebuchte Vorgänge (A3/A4). Eigene Mail „Ihre Buchungsunterlagen“ und PDF „Buchungsunterlagen“:

  • Hinweis, dass die Buchung beim Portal verbindlich zustande gekommen ist
  • kein Annahmelink, kein eigener Stornolink
  • Zahlungsanweisung nur, wenn wir laut Profil zuständig sind, sonst „Die Zahlung läuft über FeWo-direkt“

Eigene Buchungen erhalten weiterhin die Buchungsbestätigung mit Mietvertrag.

Freigaben.

  • Vorlagen (Vorlagen › Bearbeiten › Freigabe): „Für den Versand an Gäste freigegeben“ und „Gibt nur wieder, was Gäste bei der Buchung über das Portal akzeptieren“. Beide Erklärungen gelten für genau diesen Text: Sie entfallen bei einer Textänderung und fehlen bei einer neuen Version. Die Liste zeigt beide Zustände.
  • Dokumentarten (So arbeite ich › Dokumente): Die Buchungsunterlagen extern sind eine Arbeitsfassung, bis die Vermieterin sie freigibt; Datum und Person werden festgehalten. Angebot und Bestätigung sind seit jeher in Verwendung und bleiben freigegeben. Auskunft und Aufenthaltsbestätigung sind als „Arbeitsfassung vorbereitet, noch nicht nutzbar“ aufgeführt.

Verlauf.

  • Jedes erstellte Dokument steht im Verlauf: Art, Vorlage mit Version, Anlagen, Prüfsumme des PDF, beim Angebot auch die Angebotsprüfsumme.
  • Bestätigte Hinweise werden mit Person und Wortlaut gespeichert.
  • Der Kasten „Dokumente“ der Vorgangsseite liest daraus.

3. Nachweise zu den Abnahmekriterien

ID Kriterium Nachweis Ergebnis
3.1 Dasselbe Prüfbild vor jedem Versand; eine Anpassung aktualisiert sofort DocumentCompositionTest::test_the_offer_composition_shows_everything_and_an_adjustment_updates_it prüft Gast, Preis mit Herkunft, Stornoregel, Vorlage, Anlagen, Annahme sowie den neuen Gesamtpreis nach −50 € Nachlass; danach Versand über den Dialog. Browser: Angebots- und Unterlagenzusammenstellung, Neuberechnung nach Nachlass (368,00 € → 318,00 €), E-Mail- und PDF-Vorschau. erfüllt
3.2 Website-Anfrage → bindendes Angebot mit Annahmelink; verbindliche FeWo-direkt-Buchung → Buchungsunterlagen ohne Annahmelink mit der Vorlage für dieses Portal und diese Eingangsart, ohne manuelle Vorlagenwahl test_each_case_gets_its_document_without_choosing_a_template: Angebot mit Standardvorlage und Link /angebot/…. Portalbuchung mit Vorlage „eingestellt für FeWo-direkt (Verbindliche Buchung)“, Datei Buchungsunterlagen-….pdf, Mail ohne Annahmelink und ohne Überweisungsaufforderung. erfüllt
3.3 Nicht nachgewiesene Gebühr in der Vorlage einer extern verbindlichen Buchung → Hinweis und bewusste Bestätigung test_an_unconfirmed_fee_in_a_portal_template_needs_a_conscious_confirmation: Ersatzmieter-Gebühr 35,00 €, Staffel und „60,00 € (im Text)“ werden genannt. Automatik sendet nicht, die Aufgabe nennt den Grund. Versand von Hand wird ohne Haken abgelehnt; mit Haken wird gesendet und die Bestätigung samt Person protokolliert. Dazu test_without_any_template_a_portal_booking_does_not_get_our_website_terms_unchecked. erfüllt

Weitere Tests:

  • Versand der Unterlagen nur einmal bei Wiederholung (Automatik zweimal, dann Handversand)
  • Angebot nicht doppelt bei erneuter Freigabe oder Automatiklauf
  • Hold = 0 nur mit ausdrücklicher Entscheidung; die Automatik sendet nie
  • fehlende Vertragsdaten stoppen das automatische Angebot
  • bereits gesendete Dokumente bleiben unverändert, auch nach Vorlagen- und Einstellungsänderung
  • Freigaben entfallen bei Textänderung
  • Freigabe auf der Einstellungsseite
  • A6-Aufenthaltsbestätigung ohne Mietvertrag
  • PDF-Vorschau speichert nichts

4. Änderungen an Dokumentenverarbeitung und Vorlagensteuerung

Baustein Änderung
App\Enums\DocumentKind (neu) Dokumentarten Angebot, Auskunft, Bestätigung, Buchungsunterlagen extern, Aufenthaltsbestätigung, intern. forCase() leitet die Art aus Vorgangsart und Profil ab, nie aus einer Auswahl. Dazu: Annahmelink, Vertrag ja/nein, versendbar, standardmäßig freigegeben, Dateiname.
App\Documents\DocumentComposer / DocumentComposition / DocumentFinding (neu) Baut die Zusammenstellung auf einer ungespeicherten Kopie des Vorgangs und ermittelt die Hinweise. Für Angebote rechnet er den Preis genau wie SendOffer (SendOffer::quoteFor, jetzt öffentlich). Prüfkriterien sind ausschließlich objektiv: fehlende oder widersprüchliche Daten, Freigaben, Nachweis der Bedingungen.
App\Documents\DocumentReleases (neu) Freigabe je Dokumentart am Mandanten (tenants.document_releases)
App\Actions\SendBookingDocuments (neu) Einziger Weg für Bestätigung bzw. Buchungsunterlagen eines verbindlichen Vorgangs: automatically() oder handle() nach Bestätigung. Hat er Erfolg, ist mit dem Versand die Aktivität „Unterlagen“ erledigt.
SendOffer Prüft die Zusammenstellung (Bestätigungspunkte nur mit acknowledged), expected_version gegen Doppelversand, Verlaufseintrag „Dokument“
AutoOffer Zusätzliche Blocker aus der Zusammenstellung (unfreigegebene Vorlage, fehlende Vertragsdaten); ruft SendOffer mit expected_version: 0 auf
ConfirmBooking::deliver Kennt die Dokumentart: richtige Mail (BookingConfirmed oder BookingDocumentation) und richtiges PDF; Verlaufseintrag beim Erstellen
RentalContract Je Dokumentart Ansicht und Dateiname; render() und view() für Vorschauen ohne Speichern
CaseAutomation, ProvideGuestContact, CreateBooking (sofort bestätigen) Senden Unterlagen nur noch über SendBookingDocuments. Damit gehen keine Unterlagen mehr ungeprüft an der Zusammenstellung vorbei; vorher sendeten diese Wege direkt.
CaseActivities Aktivität „Buchungsunterlagen prüfen und senden“ bzw. „Buchungsbestätigung mit Vertrag prüfen und senden“, Aktion sendDocuments, Detail „vor dem Versand zu prüfen: …“
ContractTemplate released_at/by, portal_terms_confirmed_at/by, applyStatements(); Erklärungen entfallen bei Textänderung
Oberfläche filament/document-composition.blade.php, App\Filament\Forms\DocumentCompositionFields, Route filament.admin.document-preview (PDF-Vorschau, nur angemeldet und mandantengebunden), neue Aktionen auf der Vorgangsseite, Freigabe-Schalter für Vorlagen und Dokumentarten
Neue Ansichten mail/booking-documentation, pdf/stay-confirmation (Arbeitsfassungen); pdf/contract* mit Überschrift „Buchungsunterlagen“ für A3/A4

Vorlagenwahl: Unverändert über die Einstellungsebenen (Vermieterstandard → Wohnung → Portal je Eingangsart → Vorgang). Über die Eingangsart ist das zugleich die Wahl je Dokumentart: Anfrage → Angebot/Bestätigung, verbindliche Buchung → Buchungsunterlagen. Eine Vorlagenwahl im Vorgang gilt nur für diesen Vorgang und erscheint als „für diesen Vorgang gewählt“.


5. Automatischer Versand und vertragliche Verbindlichkeit

Automatik: Gesendet wird nur, wenn die Zusammenstellung weder „fehlt noch“ noch „bitte prüfen“ enthält. Sonst entsteht die Aufgabe im Vorgang und unter „Zu erledigen“, mit den Gründen im Klartext. Nach dem Erledigen gelten die Fortsetzungsregeln aus Paket 2.

Von Hand: Dieselbe Zusammenstellung. Bei Prüfpunkten ist der Haken „Ich habe die Hinweise geprüft und möchte das Dokument so senden“ Pflicht. Die bestätigten Hinweise werden mit Person gespeichert.

Extern verbindliche Buchungen (E-004):

  • kein Annahmelink, keine zweite Annahme
  • der Portalpreis wird nicht neu berechnet
  • Prüfpunkte:
    • Vorlage nicht als Wiedergabe der Portalbedingungen bestätigt
    • in der Vorlage genannte Gebühren: Ersatzmieter-Gebühr und Staffel der Stornoregel sowie Eurobeträge im Text
    • Zahlungsplatzhalter, obwohl das Portal kassiert
    • keine eigene Vorlage (dann stünden die Mietbedingungen der Webseite im Dokument)

Die Bestätigung erklärt nicht, dass etwas vereinbart ist. Sie hält fest, dass die Vermieterin bewusst so sendet; der Hinweistext sagt ausdrücklich: „Zusätzliche Pflichten gelten nur, wenn der Gast ihnen dort zugestimmt hat.“ Eine manuelle Freigabe ersetzt also keine Vereinbarung mit dem Gast.

Wirkung auf den Automatikweg aus Paket 2: Seit Paket 2 konnten Portalbuchungen im Modus „automatisch“ ihre Unterlagen sofort erhalten, sobald E-Mail-Adresse und Preis da waren. Das ist jetzt abgesichert und läuft erst, wenn zwei Freigaben vorliegen:

  • die Vermieterin hat die Buchungsunterlagen freigegeben;
  • die Vorlage dieses Portals ist freigegeben und als Wiedergabe der Portalbedingungen bestätigt.

Bis dahin wartet der Vorgang mit Aufgabe.

Kein doppelter Versand:

  • Unterlagen: Sperre je Vorgang (Cache-Lock), danach eine frische Prüfung von confirmation_sent_at.
  • Angebot: expected_version wird unter der Zeilensperre geprüft. Der Dialog übergibt die beim Öffnen gültige Version, die Automatik die Version 0.

Hold = 0 bis Paket 7:

  • Wenn Anfragen laut Profil nichts reservieren, kann ein Angebot mit Annahmelink nur nach ausdrücklicher Bestätigung entstehen, mit klarer Erklärung der Folge.
  • Die Automatik sendet in diesem Fall nie.
  • Die Auskunft unter Vorbehalt selbst kommt mit Paket 7.

Eingefrorene Inhalte:

  • Angebote frieren ihre Bedingungen wie bisher ein (offer_terms, offer_hash).
  • Unterlagen frieren beim ersten Erstellen ein: Bis dahin werden Vorlage und Anlagen aus der Zusammenstellung übernommen; danach bleiben PDF, Prüfsumme und Bedingungen unverändert, auch beim erneuten Senden.
  • Angenommene Angebote werden nie neu erfasst.

6. Ergebnisse der Tests und der visuellen Prüfung

  • Tests: 648 Tests, 3523 Zusicherungen, alle grün. Pint sauber.
  • Browser (Chromium über Playwright, lokaler Server, Kopie der lokalen Datenbank im Scratchpad, Anmeldung mit Zwei-Faktor-Code):
    • Vorgangsseite einer Website-Anfrage
    • Angebotszusammenstellung, Neuberechnung nach Nachlass, E-Mail-Vorschau
    • Vorgangsseite einer FeWo-direkt-Buchung mit Unterlagenzusammenstellung: drei Prüfpunkte, darunter Ersatzmieter-Gebühr und 60,00 € im Text; Information „Kein Annahmelink“; Preisherkunft „laut FeWo-direkt übernommen“
    • PDF-Vorschau (HTTP 200, application/pdf)
    • „So arbeite ich“ mit Bereich „Dokumente“
    • Keine Konsolenfehler. Zwei kleine Darstellungsmängel (Aufzählungspunkte, Vorlagenangabe „festgeschrieben“ vor dem Versand) wurden behoben.
  • Die lokale Arbeitsdatenbank blieb unberührt.
  • Nicht geprüft: Darstellung auf Tablet oder Smartphone; echte Mailprogramme; Migration auf MariaDB des Testsystems.

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

Kompatibilität:

  • Die Migration 2026_11_02_090000_add_document_releases ist rein additiv.
  • Bestehende Vorlagen gelten als freigegeben (released_by = „Übernahme (bisher schon verwendet)“), damit laufende Angebote und Bestätigungen weiter funktionieren. Keine Vorlage ist als Portalbedingung bestätigt.
  • Bestehende Angebote, Annahmelinks, Prüfsummen und Vertrags-PDFs werden nicht verändert.
  • Dateinamen von Mietverträgen bleiben gleich; neu sind nur Buchungsunterlagen-… und Aufenthaltsbestaetigung-….

Verhaltensänderungen, die man kennen sollte:

  1. Portalbuchungen (A3/A4) erhalten künftig „Buchungsunterlagen“ statt „Buchungsbestätigung/Mietvertrag“, mit eigenem Mailtext (Arbeitsfassung).
  2. Automatische Angebote halten an, wenn die Vorlage nicht freigegeben ist oder Platzhalter im Vertragstext unbelegt bleiben.
  3. „Sofort bestätigen“ beim Anlegen sendet die Unterlagen nur noch, wenn nichts zu prüfen ist; sonst erscheint „Gebucht – Unterlagen noch nicht gesendet“ mit Grund.
  4. Wird eine Vorlage bearbeitet, entfällt ihre Freigabe, außer sie wird beim Speichern erneut angehakt.

Risiken:

  • Die Gebührenerkennung im Freitext ist eine Heuristik (Eurobeträge). Sie meldet lieber zu viel als zu wenig; Gebühren ohne Betrag im Text erkennt sie nicht. Der Hauptschutz ist die fehlende Portalbestätigung der Vorlage, nicht die Heuristik.
  • Die Vorschau zeigt E-Mail und Dokument als HTML. Logos, die als Datei eingebettet sind, fehlen dort; im PDF sind sie enthalten.
  • Die Zusammenstellung wird für offene verbindliche Vorgänge auch in „Zu erledigen“ berechnet. Bei sehr vielen offenen Vorgängen könnte das die Startseite verlangsamen; bei 1–3 Wohnungen ist das unkritisch.
  • Ältere Portalbuchungen aus „Akte anlegen“ (siehe P1/P2) tragen noch den angenommenen Preis. Werden für sie jetzt Unterlagen gesendet, zeigt die Zusammenstellung diesen Preis als „aus Ihren Preisen berechnet“. Vorher sichten.

8. Offene Vorlagenfreigaben und erforderliche Entscheidungen

Was Wer Wirkung bis dahin
Text der Mail und des PDF „Buchungsunterlagen (beim Portal gebucht)“ prüfen und unter So arbeite ich › Dokumente freigeben Betreiber/Vermieterin (Zulieferung §8.4, ggf. rechtliche Prüfung) Kein automatischer Versand; von Hand nur mit Bestätigung
FeWo-direkt-Vorlage („FeWo-direkt Direktbuchung“): Stimmen § 13 (Staffel, Ersatzmieter-Gebühr 35 €), die Endreinigung und die ergänzende Vereinbarung mit dem überein, was Gäste bei FeWo-direkt akzeptieren? (Offene Frage FW-01) Betreiber Jeder Versand verlangt die Bestätigung der Prüfpunkte
Vorlage für Destination Solutions (A3, DS-01/02) Betreiber Ohne Vorlage meldet die Zusammenstellung „keine eigene Vorlage“
Text der Auskunft unter Vorbehalt Paket 7, Betreiber Nicht versendbar
Text der A6-Aufenthaltsbestätigung Paket 6, Betreiber Arbeitsfassung vorhanden, nicht versendbar
Prüfung der übernommenen Freigabe bestehender Vorlagen Betreiber Sie gelten als freigegeben, weil sie schon verwendet wurden

Grundsatzentscheidungen mit Wirkung auf das Geschäftsmodell wurden nicht getroffen. B1, B3, B4 und B5 bleiben offen.


9. Empfehlung für Paket 4

Paket 4 („Ein Eingang für alle Kanäle“) kann direkt auf diesem Stand aufsetzen:

  1. Automatisch übernommene Portalbuchungen (Portalmail, sicher erkannte iCal-Reservierung) rufen nach TakeOverExternalBooking nur CaseAutomation::advance auf. Die Unterlagen laufen dann ohne weiteren Code durch die Zusammenstellung und warten, solange Freigaben fehlen.
  2. Vor dem Einschalten der Automatik je Portal die Freigaben aus §8 erledigen; sonst entstehen viele Prüfaufgaben.
  3. Portalstorno als Ereignis (Aufgabe „FeWo-direkt meldet Stornierung – prüfen“) gehört zu Paket 4; die Stornobestätigung als Dokumentart folgt in Paket 5 und kann DocumentKind und die Zusammenstellung wiederverwenden.
  4. Beobachtungsmodus für Portalmails (Annahme §8.5) zuerst auf dem Testsystem, bevor Vorgänge ohne Klick entstehen.

Vor Paket 4 sollte der Stand von Paketen 1–3 auf dem Testsystem abgenommen werden. Dazu gehören die Migration auf MariaDB und die Bedienprobe mit der Vermieterin.