docs(phase-2): Phase 2 in acht Meilensteine schneiden (#56)

2026-10-04 16:20:42 +00:00
parent 7c9fc4eb21
commit b688e2ebc8
10 changed files with 494 additions and 13 deletions
@@ -0,0 +1,57 @@
+# #034 M21 – Benachrichtigungen per Mail und Webhook
+
+**Status:** offen
+**Im Tracker:** [#54](https://git.wilde-server.de/florian.wilde/Laufzettel/issues/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