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>

backend/services/masterdata/docs/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog: Masterdata-SCS (Stammdaten)
+
+Alle wesentlichen Änderungen am Masterdata-SCS (Stammdaten) werden in dieser Datei dokumentiert.
+
+## [1.0.0-SNAPSHOT] - 2026-03-30
+
+### Hinzugefügt
+
+- **ADRs:**
+  - `ADR-0017`: Importer-Einbettung als Worker im Masterdata-SCS.
+  - `ADR-0018`: Rule-Versionierung (Regulation-as-Data) für ÖTO-Konformität.
+  - `ADR-0019`: API-Schichten-Trennung (REST vs. Ingestion).
+- **Datenbank:**
+  - Exposed-Tabellen für Reiter, Pferde, Vereine, Funktionäre, Turnierklassen, Lizenzen, Richtverfahren, Gebühren und
+    Regel-Konfigurationen.
+  - Flyway-Migrationen (V005-V007) zur Schema-Erstellung und -Bereinigung.
+- **Domänenlogik:**
+  - Rule-Engine zur Berechnung von Altersklassen, Lizenz-Prüfungen und Abteilungsregeln (§ 39 ÖTO).
+  - Use-Cases für Stammdaten-Management.
+- **API:**
+  - Ktor-REST-Endpunkte für `/rules/turnierklassen`, `/rules/lizenzen` etc.
+  - OpenAPI 3 Spezifikation (`documentation.yaml`).
+- **Observability:**
+  - Micrometer/Prometheus Integration für API-Metriken.
+  - Spring Boot Actuator für Health-Checks und Monitoring.
+  - Strukturiertes Logging mit Logback.
+- **Operations:**
+  - Operatives Runbook (`masterdata-ops.md`) für Backup, Restore und Import.
+
+### Geändert
+
+- **Architektur:** Migration zu einer hexagonalen Architektur mit strikter Trennung zwischen Domäne, Infrastruktur und
+  API.
+- **Schema:** Harmonisierung der Tabellennamen zwischen SQL und Exposed.
+
+### Behoben
+
+- Namenskonflikte in `HorseRepositoryImpl` (Spalte `name`).
+- Typ-Inkompatibilitäten bei Datums-Werten (Kotlin 2.1.20 `Instant`).
+- YAML-Syntaxfehler in der OpenAPI-Dokumentation.
+- Idempotency-Plugin Pipeline-Issues im Ktor-Context.

backend/services/masterdata/docs/ROADMAP.md

@@ -23,7 +23,7 @@
   aktivieren.
 - Deliverables:
   - [x] ADR-Set im Repo (Rules, DB, Import, API) → ADR-0017, ADR-0018, ADR-0019
-  - Operative Runbooks (Backup/Restore, Re-Import, Rollback)
+  - [x] Operative Runbooks (Backup/Restore, Re-Import, Rollback) -> `masterdata-ops.md`
 
 ### 2) Datenmodell & Persistenz (WK 2–4)
 
@@ -137,4 +137,4 @@
 4. [ ] ZNS‑Importer an Repositories anbinden, Idempotenz-Checks ergänzen, Mini‑ZNS Testlauf (👷🧐) *
 5. [x] API v1 Endpunkte + OpenAPI, Contract‑Tests (👷🧐)
 6. [x] Observability-Grundlagen (Metriken + Dashboards) (🐧)
-7. Curator: Docs aktualisieren, Runbooks und Changelogs pflegen (🧹)
+7. [x] Curator: Docs aktualisieren, Runbooks und Changelogs pflegen (🧹)

backend/services/masterdata/docs/runbooks/masterdata-ops.md

@@ -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
+```