meldestelle/Schlachtplan.md at b5b87292fe516941f554723063df31b8d0ab2b9e

mocode-software/meldestelle

Fork 0

StefanMo b35c4087a2

Fix: Test-Commit für VCS-Integration (MP-8) (#15 )

* MP-8 OTHER Implementiere JWT-Authentifizierungs-Filter im Gateway

* Fix(ci): Update upload-artifact action to v4

* Fix(ci): Add start command for Keycloak and failure logs

* Fix(ci): Remove invalid 'command' property from Keycloak service

* Fix(ci): Use KC_DEV_MODE env var to start Keycloak

* Fix(ci): Keycloak service was removed from GitHub Actions services and replaced with a manual docker run step that starts Keycloak with the start-dev command.

* dev(ci): vereinheitliche Keycloak auf 26.4.2; aktiviere Health im CI (MP-8)

* Fix(ci): Stabilize Keycloak startup in integration tests via matrix

- Add `dev-file` Keycloak variant to matrix for stability fallback.
- Improve wait logic and health checks for Keycloak and Postgres.
- Unify Keycloak version to 26.4.2 across codebase.
- Add log dumps on failure.

* Fix(ci): Die betroffene Datei docs/Visionen-Ideen/Infrastruktur-Strategie_DSGVO-Konformität.md endet aktuell mit genau einer leeren Zeile (Zeile 87). Das entspricht der Regel MD047 („Files should end with a single newline character“). Damit ist deine Korrektur korrekt.

* Fix(ci): Repository-wide auto-fix for Markdown files was implemented with a GitHub Actions workflow and a local helper script. EditorConfig and markdownlint ignore files were added to ensure consistent formatting. Instructions for using the auto-fix both via GitHub Actions and locally were provided.

* fix(gradle): build.gradle.kts jsBrowser testTask disabled

* Fix(ci): Stabilize integration tests with Keycloak matrix build (MP-8)

Introduces a matrix strategy (`keycloak_db: [postgres, dev-file]`)
in the integration-tests workflow to mitigate flaky Keycloak starts
when using the Postgres service container.

- Adds a `dev-file` Keycloak variant for stability fallback.
- Improves wait logic and health checks for Keycloak/Postgres.
- Unifies Keycloak version to 26.4.2 across codebase (Dockerfile, Compose,
ADR, README, tests).
- Adds log dumps on failure in CI.
- Ensures `KC_HEALTH_ENABLED=true` is set.
- Updates related documentation (README, Schlachtplan).
- Includes broader Docker SSoT cleanup (versions.toml as source,
script updates, env file cleanup, validator hardening).

This resolves recurring CI failures related to Keycloak startup and
ensures required checks for PRs (#15) are reliable, while also
improving overall Docker build consistency.

* feat(docs, ci): Implement YouTrack SSoT strategy with Dokka sync (MP-8)

- Add Dokka multi-module Gradle configuration and KDoc style guide.
- Add GitHub Actions workflow (docs-kdoc-sync.yml) and Python script
(youtrack-sync-kb.py) to sync Dokka GFM output to YouTrack KB.
- Extend front-matter schema (bc, doc_type) and update relevant pages/stubs.
- Adapt CI scripts (validate-frontmatter, check-docs-drift, ci-docs link ignore).
- Update README.md to reference YouTrack KB.

* feat(docs, ci): Implement YouTrack SSoT strategy with Dokka sync (MP-8)

* Fix(ci): Replace OpenAPI validator with Spectral

Replaces the deprecated 'char0n/swagger-editor-validate' action,
which failed due to sandbox issues in GitHub Actions, with the
modern '@stoplight/spectral-cli'.

This ensures robust OpenAPI specification validation without
requiring a headless browser environment. The 'generate-api-docs'
job now depends on the successful completion of the Spectral validation.

Part of resolving CI failures for PR #15 (MP-8).

* Fix(ci): Specify spectral:oas ruleset for OpenAPI validation (MP-8)

* Fix(ci): Remove explicit ruleset argument for Spectral validation (MP-8)

* Fix(ci): Added a .spectral.yaml file to fix Spectral linting errors. Corrected markdown lint issues in two documentation files. Updated README.md with a new guidelines section to fix link validation errors.

* Fix(ci): Markdownlint errors were fixed by adding required blank lines. The Guidelines Validation error was resolved by updating the README.md link. The API Documentation Generator workflow was stabilized by updating paths, tasks, and validation steps.

* Fix(ci): Alle vier fehlerhaften GitHub-Action-Prüfungen wurden behoben. Fehler in der OpenAPI-Spezifikation, Probleme mit der Markdown-Linting-Analyse und Validierungsfehler bei Querverweisen wurden korrigiert. Die README.md enthält nun alle erforderlichen Links zu den Richtlinien.

* Fix(ci): Markdown linting errors in docs/api/README.md were fixed by specifying languages in fenced code blocks. OpenAPI specification errors in documentation.yaml were resolved by correcting example property types to strings. Cross-reference validation errors in README.md were fixed by adding the missing link to project-standards/coding-standards.md.

* Fix(ci): Duplicate heading errors in docs/api/members-api.md were fixed. Cross-reference validation errors for docker-architecture.md were resolved. All originally reported issues passed validation successfully.

* Fix(ci): The markdown heading levels in docs/api/members-api.md were corrected from h5 to h4 to fix linting errors. The missing cross-reference link from technology-guides/docker/docker-development.md to docker-overview.md was added. These fixes resolved the original validation and linting errors causing the process to fail.

* Fix(ci): Duplicate heading warnings in docs/api/members-api.md were resolved. Cross-reference validation for docker-development.md to docker-architecture.md was fixed. A new unrelated warning about docker-production.md was identified but not addressed.

* refactor(ci,docs): Simplify CI pipeline and migrate docs to YouTrack SSoT

BREAKING CHANGE: Documentation structure radically simplified

- Consolidate 9 GitHub Actions workflows into 1 main pipeline (ci-main.yml)
- Remove redundant workflows: ci-docs, markdownlint-autofix, guidelines-validation, api-docs
- Delete documentation migrated to YouTrack: api/, BCs/, Visionen-Ideen/, reference/, now/, overview/
- Keep only ADRs, C4 diagrams, and essential dev guides in repo
- Update README.md with YouTrack KB links
- Create new docs/README.md as documentation gateway
- Relax markdown-lint config for pragmatic developer experience

Kept workflows:
- ssot-guard.yml (Docker SSoT validation)
- docs-kdoc-sync.yml (KDoc → YouTrack sync)
- integration-tests.yml (Integration tests)
- deploy-proxmox.yml (Deployment)
- youtrack-sync.yml (YouTrack integration)

Related: MP-DOCS-001

* refactor(ci,docs): Simplify CI pipeline and migrate docs to YouTrack SSoT

BREAKING CHANGE: Documentation structure radically simplified

Related: MP-DOCS-001

* refactor(ci,docs): README.md und einige andere Dokumentationen überarbeitet.
ports-and-urls.md hinzugefügt.
Related: MP-DOCS-001

* refactor(ci,docs): Die Markdownlint-Fehler in README.md und docs/README.md wurden behoben, indem die Überschriftenebenen angepasst, überflüssige Satzzeichen am Ende entfernt und die notwendigen Leerzeilen um Überschriften, Listen, Tabellen und Codeblöcke eingefügt wurden. Das problematische Leerzeichen am Ende in docs/README.md wurde ebenfalls entfernt. Die Dateien entsprechen nun den vorgegebenen Markdownlint-Regeln und sollten die CI-Validierung bestehen.
Related: MP-DOCS-001

* refactor(ci,docs): Docker guideline cross-references were fixed and normalized to lowercase labels. Validation scripts confirmed zero cross-reference warnings and consistent metadata. Documentation was updated with a changelog and enhanced README navigation.
Related: MP-DOCS-001

* refactor(ci,docs): Dead links in docs/architecture/adr were fixed by updating URLs to stable sources and adding an ignore pattern for a placeholder link. Specific ADR files had their broken links replaced with valid ones. The markdown-link-check GitHub Action is expected to pass with zero dead links now.
Related: MP-DOCS-001

* refactor(ci,docs): Links in ADR checked
Related: MP-DOCS-001

* refactor(ci,docs): Markdown Regeln ausgebessert
Related: MP-DOCS-001

* Chore: Rerun CI checks with updated branch protection rules

2025-11-07 12:26:33 +01:00

12 KiB

Raw Blame History

Schlachtplan für das 'infrastructure'-Modul

Basierend auf der Analyse des aktuellen Zustands (Stand: 11. Oktober 2025) habe ich einen strukturierten Aktionsplan erstellt. Die letzte größere Aktualisierung war im Juli 2025, seitdem gab es signifikante Änderungen am Gateway-Modul.

🔴 Phase 1: SOFORT (Diese Woche)

1.1 Gateway-Tests reparieren (Höchste Priorität)

Problem: Tests sind komplett defekt - nur ~47% funktionieren noch (25/53 Tests).

Aktionen:

❌ Löschen: JwtAuthenticationTests.kt - testet nicht-existierende Custom-Filter
✅ Behalten: FallbackControllerTests.kt, GatewayApplicationTests.kt
✏️ Überarbeiten: GatewayRoutingTests.kt, GatewaySecurityTests.kt, GatewayFiltersTests.kt
- Option A: Tests mit MockJWT-Tokens ausstatten (siehe TestSecurityConfig.kt)
- Option B: Tests auf Public Paths verlegen (/actuator/**, /fallback/**)
- Option C: Security in Tests deaktivieren

Warum jetzt: Tests geben keine Sicherheit mehr – blockiert Entwicklung.

Zeitaufwand: 4–6 Stunden

1.2 Gateway-Build-Datei bereinigen

Problem: Duplizierte Dependency in gateway/build.gradle.kts (Zeile 33-34).

Aktion:

// ENTFERNEN: Zeile 34
implementation(project(":infrastructure:event-store:redis-event-store"))  // ← Duplikat!

Zeitaufwand: 5 Minuten

🟡 Phase 2: KURZFRISTIG (Nächste 2 Wochen)

2.1 Dependency-Versionen aktualisieren

Problem: Versionen von Juli 2025 – teilweise veraltet.

Zu prüfen und aktualisieren:

Dependency	Aktuell	Latest (Okt 2025)	Priorität
Spring Boot	3.5.5	3.5.x	Mittel
Spring Cloud	2025.0.0	2025.0.x	Mittel
Kotlin	2.2.20	2.2.x	Niedrig
Keycloak	26.0.7	26.x.x	Hoch
Testcontainers	1.21.3	1.21.x	Niedrig
PostgresQL Driver	42.7.7	42.7.x	Niedrig

Aktion:

gradle/libs.versions.toml aktualisieren
Tests nach jedem Update ausführen
Breaking Changes dokumentieren

Zeitaufwand: 1–2 Tage (mit Testing)

2.2 Docker-Images aktualisieren

Problem: Einige Docker-Images sind möglicherweise veraltet.

Zu prüfen:

# docker-compose.yml
postgres: 16-alpine           # ✅ Aktuell (neueste: 16.x)
redis: 7-alpine               # ✅ Aktuell
keycloak: 26.4.0              # ⚠️ Prüfen auf 26.x updates
consul: 1.15                  # ⚠️ Prüfen (neueste: 1.20+)
kafka: 7.4.0                  # ⚠️ Prüfen (neueste: 7.8+)
prometheus: v2.54.1           # ⚠️ Prüfen
grafana: 11.3.0               # ✅ Wahrscheinlich aktuell

Aktion:

Versions-Check durchführen
Schrittweise aktualisieren (einzeln testen!)
.env-Datei mit Versions-Variablen anlegen

Zeitaufwand: 3–4 Stunden

2.3 Monitoring-Modul vervollständigen

Problem: Nur 3 Kotlin-Files – deutlich unter implementiert im Vergleich zur Dokumentation.

Dokumentiert, aber fehlt:

Distributed Tracing (Zipkin) - Docker-Container fehlt!
Custom Metrics Implementation
Health Check Aggregation
Alerting Rules Implementation

Aktion:

Zipkin zu docker-compose.yml hinzufügen
Tracing-Integration in Gateway testen
Custom Metrics-Library erstellen
Prometheus Alerting Rules konfigurieren

Zeitaufwand: 2–3 Tage

🟢 Phase 3: MITTELFRISTIG (Nächste 4–6 Wochen)

3.1 Dokumentation aktualisieren

Problem: README von Juli 2025 – nicht mehr aktuell.

Zu aktualisieren:

README-INFRASTRUCTURE.md:

Zeile 552: "Letzte Aktualisierung: 25. Juli 2025" → Oktober 2025
Security-Sektion: OAuth2 Resource Server statt Custom JWT Filter
Keycloak Version: 23.0 → 26.4.0
Kafka Version: 7.5.0 → 7.4.0 (Downgrade dokumentieren!)
Monitoring: Zipkin-Konfiguration ergänzen

Neue Sections hinzufügen:

Bekannte Limitierungen
Migration Notes (Juli → Oktober 2025)
Troubleshooting erweitern

Zeitaufwand: 1 Tag

3.2 Auth-Module überarbeiten

Problem: Vermutlich veraltet - Custom JWT vs. OAuth2 Resource Server Diskrepanz.

Zu klären:

Werden auth-client und auth-server noch verwendet?
Redundanz mit Gateway's OAuth2 Resource Server?
Keycloak-Integration vereinheitlichen

Aktion:

Abhängigkeiten zu auth-Modulen analysieren
Entscheiden: Refactoring oder Deprecation
Wenn deprecated: Migration Path dokumentieren

Zeitaufwand: 3–5 Tage

3.3 Cache-Module modernisieren

Problem: Redis 7 ist aktuell, aber Implementation-Patterns könnten veraltet sein.

Zu prüfen:

Multi-Level Caching tatsächlich implementiert?
Cache Statistics vorhanden?
TTL Management korrekt?
Integration mit Spring Cache Abstraction?

Aktion:

Cache-Tests erweitern
Performance-Metriken hinzufügen
Cache-Warming Strategy implementieren

Zeitaufwand: 2–3 Tage

3.4 Event-Store Performance-Optimierung

Problem: Redis-basiert - für Production ggf. nicht optimal.

Zu evaluieren:

Ist Redis der richtige Event Store für Production?
Alternative: PostgresQL mit Event Store Pattern?
Snapshot-Strategie tatsächlich implementiert?

Aktion:

Performance-Tests durchführen
Event Store Benchmark (Redis vs. PostgresQL)
Dokumentation aktualisieren mit Pros/Cons

Zeitaufwand: 1 Woche

🔵 Phase 4: LANGFRISTIG (Nächste 2–3 Monate)

4.1 Service Mesh evaluieren

Dokumentiert in "Zukünftige Erweiterungen" – noch nicht implementiert.

Optionen:

Istio (komplex, feature-reich)
Linkerd (leichtgewichtig)
Consul Connect (bereits Consul vorhanden!)

Empfehlung: Start mit Consul Connect - minimaler Overhead.

Zeitaufwand: 2–3 Wochen

4.2 OpenTelemetry statt Zipkin

Problem: Zipkin ist veraltet – OpenTelemetry ist der moderne Standard.

Migration Path:

OpenTelemetry Collector aufsetzen
Spring Boot Auto-Instrumentation aktivieren
Zipkin als Backend behalten (kompatibel!)
Schrittweise migrieren

Zeitaufwand: 1–2 Wochen

4.3 Security Hardening

Aktuelle Gaps:

JWT Token Rotation nicht implementiert
Rate Limiting nur dokumentiert, nicht konfiguriert
Audit Logging fehlt
HTTPS/TLS noch nicht erzwungen

Aktion:

Rate Limiting im Gateway aktivieren
Audit Log Framework implementieren
TLS für Service-zu-Service-Kommunikation
Security Scan mit OWASP Dependency Check

Zeitaufwand: 2–3 Wochen

4.4 Infrastructure as Code (IaC)

Problem: Nur Docker Compose – für Production nicht ausreichend.

Zu erstellen:

Kubernetes Manifests (aktualisieren - Zeile 393+)
Helm Charts (aktualisieren – Zeile 420+)
Terraform für Cloud-Ressourcen
CI/CD Pipelines

Zeitaufwand: 4–6 Wochen

📊 Priorisierung-Matrix

Phase	Aufgabe	Dringlichkeit	Aufwand	Impact
1	Gateway-Tests	🔴 Sehr hoch	4-6h	Hoch
1	Build-Datei	🔴 Sehr hoch	5min	Niedrig
2	Dependencies	🟡 Hoch	1-2d	Mittel
2	Docker-Images	🟡 Hoch	3-4h	Mittel
2	Monitoring	🟡 Mittel	2-3d	Hoch
3	Dokumentation	🟢 Mittel	1d	Mittel
3	Auth-Module	🟢 Mittel	3-5d	Hoch
3	Cache	🟢 Niedrig	2-3d	Mittel
3	Event-Store	🟢 Niedrig	1w	Mittel
4	Service Mesh	🔵 Niedrig	2-3w	Hoch
4	OpenTelemetry	🔵 Niedrig	1-2w	Mittel
4	Security	🔵 Mittel	2-3w	Hoch
4	IaC	🔵 Niedrig	4-6w	Hoch

🎯 Empfohlene Reihenfolge

Woche 1-2

Gateway-Tests reparieren
Build-Datei bereinigen
Dependencies aktualisieren

Woche 3-4

Docker-Images aktualisieren
Monitoring vervollständigen
Dokumentation aktualisieren

Woche 5-8

Auth-Module evaluieren/refactored
Cache-Module modernisieren
Event-Store Performance-Tests

Monat 3-4

Security Hardening
OpenTelemetry Migration
Service Mesh Evaluation

Monat 5-6

Infrastructure as Code
Production Readiness Assessment

🛠️ Tooling-Empfehlungen

Für Dependency-Management:

Renovate Bot oder Dependabot für automatische Updates
./gradlew dependencyUpdates Plugin verwenden

Für Security:

OWASP Dependency Check
Trivy für Container-Scanning
SonarQube für Code-Qualität

Für Monitoring:

Grafana Dashboards aus Community importieren
Prometheus Alertmanager konfigurieren

📝 Nächste Schritte

Jetzt sofort: Gateway-Tests fixen (blockiert alles andere)
Diese Woche: Dependencies updaten und testen
Nächste Woche: Sprint Planning für Phase 2
Monatlich: Review des Fortschritts und Repriorisierung

⚠️ Risiken & Abhängigkeiten

Kritische Pfade:

Gateway-Tests müssen ZUERST behoben werden
Dependency-Updates können Breaking Changes haben
Auth-Refactoring könnte alle Services betreffen

Externe Abhängigkeiten:

Keycloak Breaking Changes bei Major Updates
Spring Boot/Cloud Release Schedule beachten
Kubernetes Cluster für IaC-Phase benötigt

Geschätzter Gesamtaufwand: 6–8 Wochen (bei 1 Vollzeit-Entwickler)

Empfohlener Start: Sofort mit Phase 1, dann iterativ durch die Phasen

Documentations-Sprachbereinigung (2025-10-22)

Im Zuge der Vereinheitlichung auf ausschließlich deutschsprachige Dokumentation wurden folgende Dateien entfernt:

Gelöschte ADRs (englische Varianten):

docs/architecture/adr/0000-adr-template.md
docs/architecture/adr/0001-modular-architecture.md
docs/architecture/adr/0002-domain-driven-design.md
docs/architecture/adr/0003-microservices-architecture.md
docs/architecture/adr/0004-event-driven-communication.md
docs/architecture/adr/0005-polyglot-persistence.md
docs/architecture/adr/0006-authentication-authorization-keycloak.md
docs/architecture/adr/0007-api-gateway-pattern.md
docs/architecture/adr/0008-multiplatform-client-applications.md

Gelöschte C4-Diagramme (englische Varianten):

docs/architecture/c4/01-context.puml
docs/architecture/c4/02-container.puml
docs/architecture/c4/03-component-events-service.puml

Hinweis:

Alle verbleibenden ADRs und C4-Diagramme sind in deutscher Sprache vorhanden (Suffix-de) und verlinkt.
Weitere Doku-Dateien in docs/ sind deutsch (Front-Matter/Sprachindizien geprüft).

CI‑Stabilisierung Keycloak (2025‑10‑25)

Hintergrund: In GitHub Actions startete Keycloak zeitweise nicht zuverlässig. Ziel: Integrationstests stabilisieren, ohne produktive Architektur zu ändern.

Änderungen:

Integration‑Workflow (.github/workflows/integration-tests.yml) auf Matrixbetrieb umgestellt:
- keycloak_db=postgres (produktnäher, mit externer Postgres‑DB)
- keycloak_db=dev-file (Dateibackend, ohne Postgres; stabiler im CI)
Robuste Startlogik:
- Aktives Warten auf Postgres (nur in postgres‑Variante)
- Keycloak‑Start per docker run … start-dev (26.4.2) mit KC_HEALTH_ENABLED=true
- Health‑Checks gegen /, /health, /q/health, /health/ready, Admin‑Konsole
- Ausführliche Log‑Ausgabe bei Fehlern (Keycloak & Postgres)
Fail‑fast deaktiviert; beide Matrix‑Jobs laufen unabhängig.

Nutzung/Operative Hinweise:

In PRs beide Matrix‑Runs beachten; bei Flakes in postgres sichert dev-file die Tests ab.
Logs bei Fehlschlag: Step „Dump service logs (Keycloak, Postgres)“ am Jobende öffnen.
Produktiv bleibt Postgres maßgeblich (siehe docker-compose.yml).

ADR‑Konsistenz:

ADR‑0006 (Keycloak) bleibt gültig und unverändert; die dev-file‑Variante betrifft ausschließlich CI‑Tests.

Next Steps (optional):

Falls postgres im CI dauerhaft flakey: Required Checks vorübergehend auf dev-file begrenzen.
Langfristig: Ursachenanalyse für Postgres‑Variante (Runner‑Leistung/Timeouts/Schema‑Setup) und Re‑Enable als Required Check nach Stabilisierung.

12 KiB Raw Blame History Unescape Escape

Schlachtplan für das 'infrastructure'-Modul

🔴 Phase 1: SOFORT (Diese Woche)

1.1 Gateway-Tests reparieren (Höchste Priorität)

1.2 Gateway-Build-Datei bereinigen

🟡 Phase 2: KURZFRISTIG (Nächste 2 Wochen)

2.1 Dependency-Versionen aktualisieren

2.2 Docker-Images aktualisieren

2.3 Monitoring-Modul vervollständigen

🟢 Phase 3: MITTELFRISTIG (Nächste 4–6 Wochen)

3.1 Dokumentation aktualisieren

Bekannte Limitierungen

Migration Notes (Juli → Oktober 2025)

Troubleshooting erweitern

3.2 Auth-Module überarbeiten

3.3 Cache-Module modernisieren

3.4 Event-Store Performance-Optimierung

🔵 Phase 4: LANGFRISTIG (Nächste 2–3 Monate)

4.1 Service Mesh evaluieren

4.2 OpenTelemetry statt Zipkin

4.3 Security Hardening

4.4 Infrastructure as Code (IaC)

📊 Priorisierung-Matrix

🎯 Empfohlene Reihenfolge

Woche 1-2

Woche 3-4

Woche 5-8

Monat 3-4

Monat 5-6

🛠️ Tooling-Empfehlungen

📝 Nächste Schritte

⚠️ Risiken & Abhängigkeiten

Documentations-Sprachbereinigung (2025-10-22)

CI‑Stabilisierung Keycloak (2025‑10‑25)

12 KiB

Raw Blame History