# 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](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](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 - [x] Go-Projektstruktur - [x] Persistente JSON-Konfiguration mit atomarem Schreiben - [x] Admin-Login und formularbasierte WebUI-Konfiguration - [x] ntfy Text/JSON/Trigger-Ingress - [x] Gotify `POST /message` - [x] generischer Webhook - [x] Ingress-Tokenprüfung - [x] Canonical Message - [x] Mapping-Regeln und Templates - [x] Divera247 Alarm/News/Event Create aus Mapping - [x] Divera247 v2 Client-Grundfunktionen und Pull - [x] Dry-Run - [x] Docker/Compose - [x] 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 - [x] Idempotency-Key/Deduplizierung ### M3 – Divera247 API vollständig - [x] generischer API-Request unterstützt beliebige dokumentierte Pfade schon jetzt - [x] v2 Alarm CRUD + List + Archiv + Read + Confirm + Close + Reach + Download + Reset Responses + Attachment - [x] v2 News CRUD + Archiv + Read + Confirm + Reach + Download + Reset Responses + Attachment - [x] v2 Events CRUD + Archiv + Read + Confirm + Reach + Download + ICS + Reset Responses + Attachment - [x] 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 - [x] `pull/all`-Abgleich auf Knopfdruck - [x] 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 - [x] WebUI-Auswahllisten für Einheiten, Gruppen, Personen und Fahrzeuge; manuelle IDs bleiben als Fallback - [x] Regeln wie „Kanal X -> Stichwort Y -> Gruppe Z“ formularbasiert bearbeiten - [x] Testmodus pro Regel mit Vorschau des erzeugten Divera247-Payloads - [ ] Regelreihenfolge, Stop/Continue, Fallback und Default-Regel ### M5 – Persistence, Queue und Zuverlässigkeit - [x] SQLite für Queue, Checkpoints und Zustellhistorie; Konfiguration bleibt JSON - [x] Schema-Version für SQLite - [x] persistente Outbox/Retry mit exponentiellem Backoff - [x] Dead-Letter-Queue und manuelles Wiederholen - [x] Zustellprotokoll ohne Provider-Response-Bodies/Secrets - [x] Graceful Shutdown und in-flight Delivery Handling ### M6 – Security-Härtung - [x] bcrypt für Admin-Passwort mit Legacy-Migration - [x] 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 - [x] Login-Rate-Limiting und Brute-Force-Schutz - [ ] Security-Tests/Fuzzing ### M7 – Observability und Release - [x] Prometheus-Zustandsmetriken - [ ] strukturierte JSON-Logs und Correlation IDs - [x] `/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.