notify-gateway/PROJECT_PLAN.md

Projektplan – Notification Gateway für Divera247

Aktualisierte Prioritäten (2026-09-15)

Der konkrete Ausbau zum Gateway mit mehreren Ausgangsprovidern ist in PROVIDER_PLAN.md beschrieben. Ausgangsmodell, Discord und HTTP-Webhooks waren der erste Schritt. Outbox/Deduplizierung, SMTP-Ausgang, IMAP-Eingang, ntfy/Gotify-Ausgänge, Discord-Interactions und Betriebsoberflächen sind inzwischen implementiert. Einrichtung: OPERATIONS.md. Die folgende Divera247-Roadmap bleibt als Bestandsinventar erhalten; Vollständigkeit der Divera247-API ist gegenüber diesen Schritten nachrangig.

Zielbild

Ein eigenständig betreibbares Go-Gateway nimmt Benachrichtigungen aus ntfy-kompatiblen Publishern, Gotify-kompatiblen Publishern und frei definierbaren Webhooks entgegen. Es authentifiziert Eingänge, normalisiert Nachrichten, wendet konfigurierbare Regeln an und führt die gewünschte Aktion in Divera247 aus. Zuordnungen sollen sowohl Inhaltsfelder (Meldung, Titel/Stichwort, Adresse usw.) als auch Divera247-Empfänger (Einheit/Standort, Gruppe, Person, Fahrzeug) steuern können. Konfiguration und Betriebszustand werden persistent gespeichert und über eine WebUI verwaltet.

Architektur

Datenfluss:

Ingress -> Auth -> Normalisierung -> Mapping/Regeln -> Divera247 Adapter -> Ergebnis/Audit

Komponenten:

1. Ingress Adapter: ntfy, Gotify, generischer Webhook. Später optional dedizierte Profile/Plugins.
2. Auth: pro Quelle/Kanal Tokens; Admin-Session für WebUI; später Rollen/API-Keys/OIDC.
3. Canonical Message: ein internes Modell für Quelle, Kanal, Titel, Meldung, Adresse, Priorität, Tags und Raw-Payload.
4. Mapping Engine: Regex/Prädikate, Templates, Priorität, Empfänger und erweiterte Divera247-Felder.
5. Divera247 Client: vollständige Abbildung der offiziellen v2/v3 OpenAPI-Funktionen; generischer Request als Escape Hatch.
6. Persistence: aktuell atomare JSON-Datei; Ziel SQLite mit Migrationen, Audit-Log und Transaktionssicherheit.
7. WebUI: formularbasierte Administration mit Divera247-Stammdaten-Auswahl, Regel-Editor und Payload-Vorschau.
8. Operations: strukturierte Logs, Metriken, Health/Readiness, Retry/Queue, Idempotenz, Backups.

Meilensteine

M0 – API-Abgleich und Architektur – erledigt

• Offizielle ntfy-Publish-Varianten geprüft: POST/PUT Text, JSON-Publish, GET-Trigger und Basic/Bearer-Authentifizierung.
• Gotify Message-Endpunkt und Token-Modell geprüft.
• Divera247 v2 für Alarmierungen, Mitteilungen, Termine und Pull geprüft.
• Divera247 v3 Benutzersynchronisation/Stammdaten berücksichtigt; v3 ist laut offizieller Dokumentation aktuell Beta.

M1 – Lauffähiges Gateway-Grundgerüst – aktueller Snapshot

• Go-Projektstruktur
• Persistente JSON-Konfiguration mit atomarem Schreiben
• Admin-Login und formularbasierte WebUI-Konfiguration
• ntfy Text/JSON/Trigger-Ingress
• Gotify POST /message
• generischer Webhook
• Ingress-Tokenprüfung
• Canonical Message
• Mapping-Regeln und Templates
• Divera247 Alarm/News/Event Create aus Mapping
• Divera247 v2 Client-Grundfunktionen und Pull
• Dry-Run
• Docker/Compose
• Unit- und Smoke-Tests

M2 – Vollständige Ingress-Kompatibilität

• ntfy Header/JSON-Feldmatrix vollständig abbilden (Tags, Click, Actions, Attachments, Delay usw.; nur relevante Felder an Divera247 weitergeben)
• ntfy Topic-Pfad-/Alias-Verhalten mit Konformance-Tests absichern
• Gotify Request/Response exakt gegen API-Schema testen, Extras übernehmen
• Webhook-Profile: JSONPath-/Form-/Header-Mapping statt nur Konventionen
• Größenlimits, Content-Type-Policy, optionale IP-Allowlist
• Idempotency-Key/Deduplizierung

M3 – Divera247 API vollständig

• generischer API-Request unterstützt beliebige dokumentierte Pfade schon jetzt
• v2 Alarm CRUD + List + Archiv + Read + Confirm + Close + Reach + Download + Reset Responses + Attachment
• v2 News CRUD + Archiv + Read + Confirm + Reach + Download + Reset Responses + Attachment
• v2 Events CRUD + Archiv + Read + Confirm + Reach + Download + ICS + Reset Responses + Attachment
• v2 Pull All + Vehicle Status
• alle weiteren offiziellen v2-Spezifikationen inventarisieren und typisierte Methoden ergänzen
• v3 Clusters, Qualifications, Access Groups, User Groups, RICs, Account, User-Cluster-Relations, Pager, Telefonnummern, Vehicle Types und Vehicles vollständig typisieren
• automatisierter OpenAPI-Abgleich im CI: neue/entfernte Endpunkte erkennen
• Divera247 Fehlercodes, 2FA-/Berechtigungsfälle und Rate Limits sauber modellieren

M4 – Stammdaten-Synchronisation und komfortable Zuordnung

• pull/all-Abgleich auf Knopfdruck
• Personen/UCR-IDs primär über v2 pull/all (data.cluster.consumer) je erreichbarer data.ucr laden; v3 nur als Fallback
• Cache/DB für Einheiten, Gruppen, Personen, Fahrzeuge, Status und Alarmvorlagen
• WebUI-Auswahllisten für Einheiten, Gruppen, Personen und Fahrzeuge; manuelle IDs bleiben als Fallback
• Regeln wie „Kanal X -> Stichwort Y -> Gruppe Z“ formularbasiert bearbeiten
• Testmodus pro Regel mit Vorschau des erzeugten Divera247-Payloads
• Regelreihenfolge, Stop/Continue, Fallback und Default-Regel

M5 – Persistence, Queue und Zuverlässigkeit

• SQLite für Queue, Checkpoints und Zustellhistorie; Konfiguration bleibt JSON
• Schema-Version für SQLite
• persistente Outbox/Retry mit exponentiellem Backoff
• Dead-Letter-Queue und manuelles Wiederholen
• Zustellprotokoll ohne Provider-Response-Bodies/Secrets
• Graceful Shutdown und in-flight Delivery Handling

M6 – Security-Härtung

• bcrypt für Admin-Passwort mit Legacy-Migration
• CSRF-Tokens und Security Header/CSP
• Secret-Verschlüsselung at rest oder externer Secret Store
• optional OIDC/Reverse-Proxy-Auth und Rollen
• TLS-Konfiguration bzw. dokumentierter Reverse-Proxy-Betrieb
• Login-Rate-Limiting und Brute-Force-Schutz
• Security-Tests/Fuzzing

M7 – Observability und Release

• Prometheus-Zustandsmetriken
• strukturierte JSON-Logs und Correlation IDs
• /readyz mit DB-Zustand (Provider-Erreichbarkeit separat)
• OpenTelemetry optional
• CI für Go-Test, Race, Vet, Staticcheck, Container-Scan
• Multi-Arch Container und signierte Releases
• Backup/Restore-Dokumentation

Abnahmekriterien für 1.0

1. ntfy, Gotify und generische Webhooks sind mit dokumentierten Konformancefällen getestet.
2. Sämtliche in den offiziellen Divera247 OpenAPI-Spezifikationen enthaltenen Endpunkte sind entweder typisiert oder ausdrücklich als nicht sinnvoll für das Gateway begründet; ein CI-Abgleich verhindert stilles Hinterherlaufen.
3. Divera247-Stammdaten können in der WebUI synchronisiert und für Einheiten/Gruppen/Personen/Fahrzeuge ausgewählt werden.
4. Keine Klartext-Passwörter; Secrets werden angemessen geschützt.
5. Zustellungen sind bei temporären Fehlern persistent retry-fähig und deduplizierbar.
6. Audit, Health, Readiness, Metriken und Backup/Restore sind vorhanden.
7. Automatisierte Tests decken Mapping, Auth, Ingress, Divera247-Adapter und Migrationen ab.