init

PROJECT_PLAN.md

@@ -0,0 +1,128 @@
+# 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.