diff --git a/backend/services/masterdata/docs/CHANGELOG.md b/backend/services/masterdata/docs/CHANGELOG.md new file mode 100644 index 00000000..c0424cef --- /dev/null +++ b/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. diff --git a/backend/services/masterdata/docs/ROADMAP.md b/backend/services/masterdata/docs/ROADMAP.md index aeaa11dd..60e7bea2 100644 --- a/backend/services/masterdata/docs/ROADMAP.md +++ b/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 (🧹) diff --git a/backend/services/masterdata/docs/runbooks/masterdata-ops.md b/backend/services/masterdata/docs/runbooks/masterdata-ops.md new file mode 100644 index 00000000..cfce5c7b --- /dev/null +++ b/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 +``` diff --git a/docs/01_Architecture/MASTER_ROADMAP.md b/docs/01_Architecture/MASTER_ROADMAP.md index 1d98669c..371b8b4a 100644 --- a/docs/01_Architecture/MASTER_ROADMAP.md +++ b/docs/01_Architecture/MASTER_ROADMAP.md @@ -206,6 +206,7 @@ und über definierte Schnittstellen kommunizieren. | 11 | Masterdata: Importer-Einbettung als Worker | ✅ | ADR-0017 | | 12 | Masterdata: Rule-Versionierung (Regulation-as-Data) | ✅ | ADR-0018 | | 13 | Masterdata: API-Schichten (REST vs. Ingestion) | ✅ | ADR-0019 | +| 14 | Masterdata: Observability & Operations | ✅ | masterdata-ops.md, CHANGELOG | --- @@ -224,3 +225,6 @@ und über definierte Schnittstellen kommunizieren. | Agent Playbooks | `docs/04_Agents/Playbooks/` | | ADR-Verzeichnis | `docs/01_Architecture/adr/` | | ZNS-Importer Roadmap | `docs/01_Architecture/Roadmap_ZNS_Importer.md` | +| Masterdata Roadmap | `backend/services/masterdata/docs/ROADMAP.md` | +| Masterdata Changelog | `backend/services/masterdata/docs/CHANGELOG.md` | +| Masterdata Operations | `backend/services/masterdata/docs/runbooks/masterdata-ops.md` |