mocode-software/meldestelle
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
689e3bf8e7
meldestelle/core/README-CORE.md
stefan 1db41a5c62 refactor(core): Stabilize and Refactor Shared Kernel 
This commit introduces a comprehensive refactoring and stabilization of the core module, establishing a robust and well-tested foundation (Shared Kernel) for all other services.

The module has been thoroughly analyzed, cleaned up, and equipped with a professional-grade test suite.

Architectural Refinements:
- Slimmed down `core-domain` to be a true, minimal Shared Kernel by removing all domain-specific enums (`PferdeGeschlechtE`, `SparteE`, etc.). This enforces loose coupling between feature modules.
- The only remaining enum is `DatenQuelleE`, which is a cross-cutting concern.

Code Refactoring & Improvements:
- Refactored the configuration loading by introducing a `ConfigLoader` class. This decouples the `AppConfig` data classes from the loading mechanism, significantly improving the testability of components that rely on configuration.
- Unified the previously duplicated `ValidationResult` and `ValidationError` classes into a single, serializable source of truth, ensuring consistent error reporting across all APIs.

Testing Enhancements:
- Introduced a comprehensive test suite for the core module, bringing it to a production-ready quality standard.
- Implemented the "gold standard" for database testing by replacing the previous H2 approach with **Testcontainers**. The `DatabaseFactory` is now tested against a real, ephemeral PostgreSQL container, guaranteeing 100% production parity.
- Added robust unit and integration tests for critical components, including the new `ConfigLoader`, all custom `Serializers`, and the `ApiResponse` logic.
- Fixed all compilation and runtime errors in the test suite, resulting in a successful `./gradlew clean build`.
2025-08-05 18:25:21 +02:00

3.5 KiB
Raw Blame History

Core Module

Überblick

Das Core-Modul bildet das Fundament des gesamten Meldestelle-Systems und implementiert den Shared Kernel nach Domain-Driven Design Prinzipien. Es stellt gemeinsame, domänen-agnostische Konzepte, Utilities und Infrastrukturkomponenten bereit, die von allen anderen Modulen verwendet werden.

Architektur

Das Modul ist nach den Prinzipien der Clean Architecture in zwei Hauptkomponenten unterteilt:

  • :core-domain: Der "reine" Teil des Kernels. Enthält nur Datenstrukturen und Interfaces ohne externe Abhängigkeiten.
  • :core-utils: Stellt technische Hilfsfunktionen und konkrete Implementierungen bereit, die auf dem core-domain aufbauen.

Core-Domain Komponenten

Dieses Modul hat eine minimale Oberfläche, um eine maximale Entkopplung der Fach-Services zu gewährleisten.

  • BaseDto.kt: Definiert standardisierte DTOs (Data Transfer Objects) wie ApiResponse<T> und PagedResponse<T>, um eine konsistente API-Struktur im gesamten System sicherzustellen.
  • DomainEvent.kt: Stellt die Basis-Infrastruktur für Domänen-Events (DomainEvent, BaseDomainEvent) bereit, die für eine asynchrone, ereignisgesteuerte Kommunikation unerlässlich ist.
  • Enums.kt: Enthält ausschließlich fundamental querschnittliche Enums. Nach einem Refactoring verbleibt hier nur noch DatenQuelleE, da es die Herkunft von Daten beschreibt – ein Konzept, das für alle Domänen relevant ist. Domänenspezifische Enums (z.B. für Pferderassen oder Disziplinen) wurden bewusst entfernt.
  • Serializers.kt: Bietet benutzerdefinierte Serializer für kotlinx.serialization, um Typen wie Uuid und Instant systemweit konsistent in JSON umzuwandeln.

Core-Utils Komponenten

  • Konfiguration (config/):
    • ConfigLoader.kt: Implementiert ein sauberes Muster zur Entkopplung der Konfigurations-Ladelogik. Er liest .properties-Dateien und Umgebungsvariablen.
    • AppConfig.kt: Dient als reine, unveränderliche Datenklasse, die die vom ConfigLoader geladenen Werte enthält. Dieses Muster verbessert die Testbarkeit erheblich.
  • Datenbank (database/):
    • DatabaseFactory.kt: Eine robuste Factory zur Verwaltung von Datenbankverbindungen mit einem hoch-performanten Connection Pool (HikariCP) und automatischer Datenbank-Migration durch den Industriestandard Flyway.
  • Fehlerbehandlung (error/):
    • Result.kt: Eine typsichere, versiegelte Klasse (sealed class) für funktionales Error-Handling, die den übermäßigen Einsatz von Exceptions für erwartete Geschäftsfehler vermeidet.
  • Validierung (validation/):
    • ValidationResult.kt: Eine vereinheitlichte, serialisierbare Datenstruktur (ValidationResult, ValidationError) zur systemweiten, konsistenten Kommunikation von Validierungsfehlschlägen über API-Grenzen hinweg.

Testing-Strategie

Das core-Modul ist durch eine umfassende Suite von Unit- und Integrationstests abgesichert, die einen hohen Qualitätsstandard setzen.

  • Unit-Tests: Kritische Komponenten wie der ConfigLoader, die Serializer und die ApiResponse-Logik sind durch Unit-Tests abgedeckt.
  • Datenbank-Tests (Goldstandard): Die Datenbanklogik wird nicht gegen eine ungenaue In-Memory-Datenbank (wie H2) getestet. Stattdessen wird Testcontainers verwendet, um für jeden Testlauf eine echte PostgreSQL-Datenbank in einem Docker-Container zu starten. Dies garantiert 100%ige Kompatibilität zwischen Test- und Produktionsumgebung.