refactoring Single Source of Truth
This commit is contained in:
@@ -20,162 +20,79 @@ Unsere Architektur basiert auf **vier Säulen**:
|
||||
|
||||
---
|
||||
|
||||
## 2. Coding Conventions & Code-Qualität
|
||||
## 2. Coding Standards & Code-Qualität
|
||||
|
||||
### 2.1. Sprach- und Stilstandards
|
||||
Detaillierte Coding-Standards und Qualitätsrichtlinien finden Sie in:
|
||||
**→ [Coding Standards](./project-standards/coding-standards.md)**
|
||||
|
||||
* **Primärsprache:** Kotlin (JVM/Multiplatform)
|
||||
* **Java-Kompatibilität:** Ziel ist Java 21+
|
||||
* **Code-Stil:** Offizielle Kotlin Coding Conventions, durch `Detekt` geprüft.
|
||||
|
||||
### 2.2. Namenskonventionen
|
||||
|
||||
* **Klassen & Interfaces:** `PascalCase` (z.B. `MemberService`, `EventRepository`)
|
||||
* **Funktionen & Variablen:** `camelCase` (z.B. `authenticateUser`, `memberRepository`)
|
||||
* **Testmethoden:** Beschreibend mit Backticks (z.B. `` `should return Success for valid credentials` ``)
|
||||
* **Konstanten:** `SCREAMING_SNAKE_CASE` (z.B. `MAX_RETRY_ATTEMPTS`)
|
||||
* **Enums:** `PascalCase` für Werte (z.B. `MemberStatus.ACTIVE`)
|
||||
|
||||
### 2.3. Value Classes für Typsicherheit
|
||||
|
||||
Primitive Typen (UUID, String, Long) für IDs oder spezifische Werte müssen in typsichere `value class`-Wrapper gekapselt
|
||||
werden.
|
||||
|
||||
```kotlin
|
||||
@JvmInline
|
||||
value class MemberId(val value: UUID) {
|
||||
companion object {
|
||||
fun of(value: String): Result<MemberId, ValidationError> =
|
||||
runCatching { UUID.fromString(value) }
|
||||
.map { MemberId(it) }
|
||||
.mapError { ValidationError.INVALID_UUID }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2.4. Error-Handling & Logging
|
||||
|
||||
* **`Result`-Pattern:** Für erwartbare Geschäftsfehler ist das `Result`-Pattern zu verwenden. Exceptions sind für
|
||||
unerwartete, technische Fehler reserviert.
|
||||
|
||||
* **Fehler-Hierarchie:** Wir verwenden eine `sealed class`-Hierarchie, um Fehlerarten klar zu kategorisieren (
|
||||
`DomainError`, `ValidationError`, `BusinessError`, `TechnicalError`).
|
||||
|
||||
* **Structured Logging:** Logs müssen strukturiert sein und eine Korrelations-ID enthalten, um Anfragen über
|
||||
Service-Grenzen hinweg zu verfolgen.
|
||||
|
||||
```kotlin
|
||||
logger.info {
|
||||
"Creating member" with mapOf(
|
||||
"memberId" to command.memberId.value,
|
||||
"correlationId" to MDC.get("correlationId")
|
||||
)
|
||||
}
|
||||
```
|
||||
Kernpunkte:
|
||||
- **Primärsprache:** Kotlin (JVM/Multiplatform) mit Java 21+ Kompatibilität
|
||||
- **Namenskonventionen:** PascalCase für Klassen, camelCase für Funktionen
|
||||
- **Value Classes:** Typsichere Wrapper für primitive Typen
|
||||
- **Result-Pattern:** Für erwartbare Geschäftsfehler
|
||||
- **Structured Logging:** Mit Korrelations-IDs
|
||||
|
||||
---
|
||||
|
||||
## 3. Backend-Entwicklungsrichtlinien
|
||||
## 3. Architecture Principles & Backend-Entwicklung
|
||||
|
||||
### 3.1. Microservice-Struktur (Clean Architecture)
|
||||
Detaillierte Architektur-Prinzipien und Backend-Entwicklungsrichtlinien finden Sie in:
|
||||
**→ [Architecture Principles](./project-standards/architecture-principles.md)**
|
||||
|
||||
Jeder fachliche Microservice folgt der 4-Layer-Struktur (`api`, `application`, `domain`, `infrastructure`).
|
||||
|
||||
### 3.2. Repository-Pattern
|
||||
|
||||
Jede Repository-Methode muss das `Result`-Pattern verwenden.
|
||||
|
||||
```kotlin
|
||||
interface MemberRepository {
|
||||
suspend fun findById(id: MemberId): Result<Member?, RepositoryError>
|
||||
suspend fun save(member: Member): Result<Unit, RepositoryError>
|
||||
}
|
||||
```
|
||||
|
||||
### 3.3. Messaging & Event-Naming
|
||||
|
||||
* **Event-Naming Convention:** Domänen-Events folgen dem Muster `{Domain}{Entity}{Action}Event`.
|
||||
|
||||
```kotlin
|
||||
data class MemberPersonalDataUpdatedEvent(...) : DomainEvent(...)
|
||||
```
|
||||
Kernpunkte:
|
||||
- **Clean Architecture:** 4-Layer-Struktur (api, application, domain, infrastructure)
|
||||
- **DDD:** Domain-Driven Design mit Bounded Contexts
|
||||
- **EDA:** Event-Driven Architecture mit Kafka
|
||||
- **Repository-Pattern:** Alle Methoden verwenden Result-Pattern
|
||||
|
||||
---
|
||||
|
||||
## 4. Frontend-Entwicklungsrichtlinien
|
||||
## 4. Frontend-Entwicklung & Multiplatform
|
||||
|
||||
Das Frontend folgt konsequent dem **Model-View-ViewModel (MVVM)**-Muster und der **Kotlin Multiplatform (KMP)**
|
||||
-Strategie. Der UI-Code wird nach **fachlichen Features** (vertikale Schnitte) strukturiert.
|
||||
Detaillierte Frontend-Entwicklungsrichtlinien finden Sie in:
|
||||
**→ [Web App Guideline](./technology-guides/web-app-guideline.md)**
|
||||
|
||||
Kernpunkte:
|
||||
- **MVVM-Pattern:** Model-View-ViewModel für UI-Struktur
|
||||
- **Kotlin Multiplatform:** Code-Sharing zwischen Desktop und Web
|
||||
- **Compose Multiplatform:** Deklarative UI mit @Composable-Funktionen
|
||||
- **Feature-basierte Struktur:** Vertikale Schnitte nach Fachlichkeit
|
||||
|
||||
---
|
||||
|
||||
## 5. Testing
|
||||
## 5. Testing Standards
|
||||
|
||||
Tests sind ein integraler Bestandteil jedes Features und müssen einen hohen Standard erfüllen.
|
||||
Detaillierte Testing-Standards finden Sie in:
|
||||
**→ [Testing Standards](./project-standards/testing-standards.md)**
|
||||
|
||||
### 5.1. Test-Pyramide & Werkzeuge
|
||||
|
||||
* **Unit-Tests (80 %+ Abdeckung):** Für Domänen- und Anwendungslogik (JUnit 5, MockK).
|
||||
|
||||
* **Integrationstests:** Decken alle Repository-Implementierungen und externen Integrationen ab.
|
||||
|
||||
* **Testcontainers als Goldstandard:** Jede Interaktion mit externer Infrastruktur (DB, Cache, Broker) **muss** mit
|
||||
**Testcontainers** getestet werden.
|
||||
|
||||
### 5.2. Debugging
|
||||
|
||||
Debug-Ausgaben im Test-Code müssen mit `[DEBUG_LOG]` beginnen, um sie leicht identifizieren und filtern zu können.
|
||||
Kernpunkte:
|
||||
- **Test-Pyramide:** 80%+ Unit-Tests, Integrationstests für externe Systeme
|
||||
- **Testcontainers:** Goldstandard für Infrastruktur-Tests
|
||||
- **Result-Pattern:** Tests für Success- und Failure-Cases
|
||||
- **Debug-Logs:** `[DEBUG_LOG]`-Präfix für Test-Ausgaben
|
||||
|
||||
---
|
||||
|
||||
## 6. Infrastruktur- & Betriebs-Spezifikationen
|
||||
## 6. Docker & Infrastructure
|
||||
|
||||
### 6.1. Kafka-Konfiguration
|
||||
Detaillierte Docker- und Infrastruktur-Richtlinien finden Sie in:
|
||||
**→ [Docker Guidelines](./technology-guides/docker/)**
|
||||
|
||||
Die Konfiguration muss auf maximale Zuverlässigkeit ausgelegt sein:
|
||||
|
||||
```yaml
|
||||
# in application.yml
|
||||
kafka:
|
||||
producer:
|
||||
acks: all
|
||||
enable-idempotence: true
|
||||
max-in-flight-requests-per-connection: 1
|
||||
consumer:
|
||||
group-id-prefix: "meldestelle-${spring.application.name}"
|
||||
auto-offset-reset: earliest
|
||||
enable-auto-commit: false
|
||||
```
|
||||
|
||||
### 6.2. Datenbank-Migrationen (Flyway)
|
||||
|
||||
Migrations-Skripte müssen einer klaren Namenskonvention folgen.
|
||||
|
||||
* **Pattern:** `V{version}__{description}.sql` (z.B., `V001__Create_member_tables.sql`)
|
||||
|
||||
* **Repeatable:** `R__{description}.sql` (z.B., `R__Update_member_view.sql`)
|
||||
|
||||
### 6.3. API-Dokumentation (OpenAPI)
|
||||
|
||||
Alle öffentlichen REST-Endpunkte müssen mit OpenAPI-Annotationen (`@Operation`, `@ApiResponse`) dokumentiert werden, um
|
||||
eine klare und interaktive API-Dokumentation zu generieren.
|
||||
Kernpunkte:
|
||||
- **Docker-Architektur:** Microservices mit Service Discovery
|
||||
- **Zentrale Versionsverwaltung:** Single Source of Truth
|
||||
- **Monitoring:** Prometheus & Grafana
|
||||
- **Security:** Non-Root-Container, SSL/TLS everywhere
|
||||
|
||||
---
|
||||
|
||||
## 7. Dokumentationsstandards
|
||||
## 7. Documentation Standards
|
||||
|
||||
### 7.1. Sprache für Dokumentation
|
||||
Detaillierte Dokumentationsstandards finden Sie in:
|
||||
**→ [Documentation Standards](./project-standards/documentation-standards.md)**
|
||||
|
||||
* **README-Dateien:** Alle README-Dokumentationen im Projekt müssen in **deutscher Sprache** verfasst werden.
|
||||
Dies gewährleistet Konsistenz und Zugänglichkeit für das deutsche Entwicklungsteam.
|
||||
|
||||
* **Code-Kommentare:** Komplexe Geschäftslogik und fachliche Zusammenhänge sollen in deutscher Sprache kommentiert werden.
|
||||
|
||||
* **API-Dokumentation:** OpenAPI-Beschreibungen und -Beispiele sind bevorzugt in deutscher Sprache zu verfassen,
|
||||
sofern keine internationalen Anforderungen bestehen.
|
||||
|
||||
### 7.2. Dokumentationsstruktur
|
||||
|
||||
* README-Dateien sollen eine einheitliche Struktur befolgen: Überblick, Architektur, Entwicklung, Tests, Deployment.
|
||||
|
||||
* Technische Begriffe dürfen in englischer Originalform verwendet werden, wenn keine etablierte deutsche Übersetzung existiert.
|
||||
Kernpunkte:
|
||||
- **Sprache:** README-Dateien auf Deutsch, Code-Kommentare je nach Kontext
|
||||
- **Struktur:** Einheitliche README-Template
|
||||
- **API-Docs:** OpenAPI-Annotationen mit deutschen Beschreibungen
|
||||
- **Versionierung:** Dokumentation wird mit Code versioniert
|
||||
|
||||
Reference in New Issue
Block a user