M21 – Benachrichtigungen per Mail und Webhook #54

New Issue

2026-10-04T16:19:18Z

florian.wilde commented

2026-10-04 16:19:18 +00:00

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 M7 – Platzhalter, Namensregeln, Escaping (#12)
Test: ein Benutzer mit abgeschalteter Benachrichtigung bekommt nichts

Quelle im Repo: docs/issues/034-benachrichtigungen.md

## 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 --- Quelle im Repo: `docs/issues/034-benachrichtigungen.md`

florian.wilde added this to the v0.2.0 milestone 2026-10-04 16:19:18 +00:00