chore(docs): add CHANGELOG and operations runbook for masterdata service

- Introduced `CHANGELOG.md` to document essential changes in the Masterdata-SCS, including ADRs, database schema updates, domain logic additions, API enhancements, and observability improvements. - Added `masterdata-ops.md` runbook detailing operational procedures such as backup, restore, import management, and troubleshooting. - Updated roadmaps to reference the new documentation and mark relevant tasks as complete. Signed-off-by: Stefan Mogeritsch <stefan.mo.co@gmail.com>
2026-03-30 15:40:05 +02:00
parent 2f17778df6
commit 2262826603
4 changed files with 112 additions and 2 deletions
@@ -0,0 +1,65 @@
+# Runbook: Masterdata-SCS Operations
+
+Dieses Runbook beschreibt die betrieblichen Abläufe für das Masterdata-SCS (Stammdaten), einschließlich Backup, Restore
+und Import-Management.
+
+---
+
+## 1. Backup & Restore (Postgres)
+
+Das Masterdata-SCS nutzt eine eigene PostgreSQL-Instanz.
+
+### 1.1 Manuelles Backup erstellen
+
+Um ein Backup der Masterdata-Datenbank zu erstellen:
+
+```bash
+docker exec -t masterdata-db pg_dump -U masterdata masterdata_db > masterdata_backup_$(date +%Y%m%d).sql
+```
+
+### 1.2 Restore durchführen
+
+**Achtung:** Dies überschreibt den aktuellen Stand der Datenbank.
+
+```bash
+cat masterdata_backup_YYYYMMDD.sql | docker exec -i masterdata-db psql -U masterdata -d masterdata_db
+```
+
+---
+
+## 2. ZNS-Import Management
+
+### 2.1 Import manuell triggern
+
+Der Import kann über die REST-API des `masterdata-service` gestartet werden.
+
+```bash
+curl -X POST http://localhost:8091/admin/import/trigger -H "Content-Type: application/json" -d '{"file": "path/to/zns.zip"}'
+```
+
+### 2.2 Import-Status prüfen
+
+```bash
+curl http://localhost:8091/admin/import/status
+```
+
+---
+
+## 3. Fehlerbehebung
+
+### 3.1 Regel-Set-Mismatch
+
+Wenn eine Nennung aufgrund einer veralteten Regel abgelehnt wird:
+
+1. Prüfe die `RegulationConfigTable` in der DB.
+2. Stelle sicher, dass `valid_from` und `valid_to` das aktuelle Datum abdecken.
+3. Ggf. ein neues Regel-Set via Seed-Skript einspielen.
+
+### 3.2 Datenbank-Migrationen (Flyway)
+
+Bei Fehlern während des Hochfahrens (Migration-Checksum-Mismatch):
+
+```bash
+# Nur in Entwicklungsumgebungen!
+./gradlew :backend:services:masterdata:masterdata-service:flywayRepair
+```