Laufzettel/docs/issues/034-benachrichtigungen.md

#034 M21 – Benachrichtigungen per Mail und Webhook

Status: offen Im Tracker: #54 Meilenstein: v0.2.0 Labels: phase-2, backend, frontend, infra Geschätzt: 10 h Tatsächlich: –

Ziel

Ein zugewiesener Lauf fällt heute nur auf, wenn jemand die Übersicht öffnet. Ein überfälliger überhaupt nicht. Vier Ereignisse sind es wert, gemeldet zu werden: zugewiesen, überfällig, abgeschlossen, Verzeichnisabgleich fehlgeschlagen.

Zu entscheiden

• Nur diese vier Ereignisse, je Empfänger abschaltbar — Empfehlung. Ein allgemeiner Benachrichtigungsbaukasten ist eine Phase für sich; vier Ereignisse decken ab, was im Betrieb wirklich fehlt.
• Mail über SMTP, keine Dienstanbindung. Eine selbst gehostete Anwendung soll an den Mailserver des Hauses können, und das ist SMTP. Zugangsdaten verschlüsselt wie das LDAP-Bind-Passwort.
• Zustellung in einer Warteschlange in der Datenbank, nicht im Anfrage-Pfad. Ein hängender Mailserver darf kein Abhaken blockieren. Dieselbe Sperre wie beim Abgleich (AbgleichSperre) verhindert, dass zwei Instanzen dasselbe zweimal schicken.

Aufgaben

• Modell Zustellung: Ereignis, Empfänger, Weg (MAIL | WEBHOOK), Versuche, letzter Fehler, Zustand; mit Index auf das, was der Zeitplan abholt
• SMTP-Einstellungen unter Admin → Einstellungen: Host, Port, TLS, Benutzer, Passwort (verschlüsselt, nie in einer Antwort), Absender, „Testmail schicken“
• Webhook: Ziel-URL, Geheimnis, HMAC-SHA256 über den Rumpf im Kopf X-Laufzettel-Signatur, dazu ein Zeitstempel gegen Wiedereinspielen
• Wiederholung mit wachsendem Abstand (1, 5, 30, 120 Minuten), dann aufgeben und sichtbar machen. Eine stille Warteschlange ist schlimmer als keine
• Überfälligkeit erkennt der Zeitplan, der schon läuft (node-cron im Prozess) — kein zweiter Dienst
• Je Benutzer abschaltbar; ein Benutzer ohne Mailadresse bekommt keine Mail und keinen Fehler
• Admin: die letzten Zustellungen mit Zustand und Grund
• {{generiertes_passwort}} kommt in keine Nachricht. Eine Mail mit dem Lauf-Inhalt wäre genau die Lücke, die das Projekt an jeder anderen Stelle geschlossen hat. Die Nachricht enthält Titel, Status und einen Link — keine Schrittinhalte
• docs/betrieb/: SMTP einrichten, Webhook prüfen, Signatur nachrechnen
• Anleitung Kapitel 07

Akzeptanzkriterien

• Test gegen einen echten SMTP-Fänger im Container (mailpit): zugewiesen, überfällig, abgeschlossen, Abgleich fehlgeschlagen — vier Mails, richtige Empfänger
• Test gegen einen lokalen Empfänger: die Signatur lässt sich mit dem Geheimnis nachrechnen, mit einem falschen nicht
• Test: eine fehlgeschlagene Zustellung wird wiederholt und ist danach sichtbar
• Test: zwei gleichzeitige Durchgänge schicken nichts zweimal
• Test: in keiner Nachricht steht ein erzeugtes Passwort — über alle Rumpftexte geprüft, wie in #012
• Test: ein Benutzer mit abgeschalteter Benachrichtigung bekommt nichts