129 lines
7.1 KiB
Markdown
129 lines
7.1 KiB
Markdown
# 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.
|