upgrade(docker)
This commit is contained in:
stefan
@@ -0,0 +1,459 @@
|
||||
# Client Desktop-App Modul
|
||||
|
||||
## Überblick
|
||||
|
||||
Das **desktop-app** Modul stellt eine native Desktop-Anwendung für das Meldestelle-System bereit, die Kotlin Multiplatform und Compose for Desktop verwendet. Dieses Modul dient als plattformübergreifender Desktop-Client, der nahtlos mit dem geteilten common-ui Modul integriert ist, um eine konsistente Benutzererfahrung zu liefern.
|
||||
|
||||
**Hauptfunktionen:**
|
||||
- 🖥️ **Native Desktop-App** - Plattformübergreifende Unterstützung für Windows, macOS und Linux
|
||||
- 🏗️ **Moderne Architektur** - Integriert mit MVVM common-ui Modul
|
||||
- 🚀 **Optimierter Build** - Modernisierte Gradle-Konfiguration mit nativer Distribution
|
||||
- 🧪 **Testabdeckung** - Umfassende Testsuite für Desktop-spezifische Funktionalität
|
||||
- 📦 **Einfache Distribution** - Eigenständiges Packaging für alle Plattformen
|
||||
|
||||
---
|
||||
|
||||
## Architektur
|
||||
|
||||
### Modulstruktur
|
||||
|
||||
```
|
||||
client/desktop-app/
|
||||
├── build.gradle.kts # Modernisierte Build-Konfiguration
|
||||
├── src/
|
||||
│ ├── jvmMain/kotlin/at/mocode/client/desktop/
|
||||
│ │ └── Main.kt # Desktop-Anwendung Einstiegspunkt
|
||||
│ └── jvmTest/kotlin/at/mocode/client/desktop/
|
||||
│ └── MainTest.kt # Desktop-spezifische Tests
|
||||
└── README-CLIENT-DESKTOP-APP.md # Diese Dokumentation
|
||||
```
|
||||
|
||||
### Integration mit Common-UI
|
||||
|
||||
Die Desktop-App nutzt die geteilte MVVM-Architektur von common-ui:
|
||||
|
||||
```kotlin
|
||||
fun main() = application {
|
||||
Window(
|
||||
onCloseRequest = ::exitApplication,
|
||||
title = "Meldestelle Desktop App",
|
||||
state = WindowState(
|
||||
position = WindowPosition(Alignment.Center),
|
||||
width = 800.dp,
|
||||
height = 600.dp
|
||||
)
|
||||
) {
|
||||
// Verwendet geteilte App-Komponente mit MVVM-Architektur
|
||||
App(baseUrl = System.getProperty("meldestelle.api.url", "http://localhost:8080"))
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Build-Konfiguration
|
||||
|
||||
### Moderne Gradle-Einrichtung
|
||||
|
||||
Die desktop-app verwendet eine modernisierte Build-Konfiguration nach Projektstandards:
|
||||
|
||||
#### Plugin-Konfiguration
|
||||
```kotlin
|
||||
plugins {
|
||||
alias(libs.plugins.kotlin.multiplatform)
|
||||
alias(libs.plugins.kotlin.serialization)
|
||||
alias(libs.plugins.compose.multiplatform)
|
||||
alias(libs.plugins.compose.compiler)
|
||||
}
|
||||
```
|
||||
|
||||
#### Abhängigkeiten-Organisation
|
||||
```kotlin
|
||||
val jvmMain by getting {
|
||||
dependencies {
|
||||
// Projekt-Abhängigkeiten
|
||||
implementation(project(":client:common-ui"))
|
||||
|
||||
// Compose Desktop
|
||||
implementation(compose.desktop.currentOs)
|
||||
implementation(compose.material3)
|
||||
implementation(compose.ui)
|
||||
implementation(compose.uiTooling)
|
||||
implementation(compose.runtime)
|
||||
implementation(compose.foundation)
|
||||
|
||||
// Serialisierungsunterstützung
|
||||
implementation(libs.kotlinx.serialization.json)
|
||||
|
||||
// HTTP Client & Coroutines
|
||||
implementation(libs.ktor.client.cio)
|
||||
implementation(libs.ktor.client.contentNegotiation)
|
||||
implementation(libs.ktor.client.serialization.kotlinx.json)
|
||||
implementation(libs.kotlinx.coroutines.swing)
|
||||
|
||||
// Logging
|
||||
implementation(libs.kotlin.logging.jvm)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Test-Konfiguration
|
||||
```kotlin
|
||||
val jvmTest by getting {
|
||||
dependencies {
|
||||
implementation(libs.bundles.testing.jvm)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Native Distribution
|
||||
```kotlin
|
||||
nativeDistributions {
|
||||
targetFormats(TargetFormat.Deb, TargetFormat.Dmg, TargetFormat.Msi)
|
||||
packageName = "Meldestelle"
|
||||
packageVersion = "1.0.0"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Entwicklung
|
||||
|
||||
### Voraussetzungen
|
||||
|
||||
| Tool | Version | Zweck |
|
||||
|------|---------|-------|
|
||||
| JDK | 21 (Temurin) | Desktop-Laufzeit und Gradle-Build |
|
||||
| Gradle | 8.x (wrapper) | Build-Automatisierung |
|
||||
|
||||
### Die Anwendung erstellen
|
||||
|
||||
```bash
|
||||
# Die Desktop-Anwendung kompilieren
|
||||
./gradlew :client:desktop-app:compileKotlinJvm
|
||||
|
||||
# Die Anwendung im Entwicklungsmodus ausführen
|
||||
./gradlew :client:desktop-app:run
|
||||
|
||||
# Vollständige Anwendung erstellen
|
||||
./gradlew :client:desktop-app:build
|
||||
```
|
||||
|
||||
### Tests ausführen
|
||||
|
||||
```bash
|
||||
# Alle Desktop-Tests ausführen
|
||||
./gradlew :client:desktop-app:jvmTest
|
||||
|
||||
# Spezifischen Test ausführen
|
||||
./gradlew :client:desktop-app:jvmTest --tests "MainTest"
|
||||
|
||||
# Ausführliche Test-Ausgabe
|
||||
./gradlew :client:desktop-app:jvmTest --info
|
||||
```
|
||||
|
||||
### Packaging für Distribution
|
||||
|
||||
```bash
|
||||
# Verteilbare Pakete für alle Plattformen erstellen
|
||||
./gradlew :client:desktop-app:createDistributable
|
||||
|
||||
# Paket für spezifische Plattform
|
||||
./gradlew :client:desktop-app:packageDeb # Linux .deb
|
||||
./gradlew :client:desktop-app:packageDmg # macOS .dmg
|
||||
./gradlew :client:desktop-app:packageMsi # Windows .msi
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Konfiguration
|
||||
|
||||
### Systemeigenschaften
|
||||
|
||||
Die Desktop-Anwendung unterstützt Konfiguration über JVM-Systemeigenschaften:
|
||||
|
||||
| Eigenschaft | Standard | Beschreibung |
|
||||
|----------|---------|-------------|
|
||||
| `meldestelle.api.url` | `http://localhost:8080` | Backend-API Basis-URL |
|
||||
|
||||
#### Verwendungsbeispiele
|
||||
|
||||
```bash
|
||||
# Mit benutzerdefinierter API-URL ausführen
|
||||
./gradlew :client:desktop-app:run -Dmeldestelle.api.url=https://api.example.com
|
||||
|
||||
# Mit Entwicklungseinstellungen ausführen
|
||||
./gradlew :client:desktop-app:run -Dmeldestelle.api.url=http://localhost:8080
|
||||
```
|
||||
|
||||
### Fenster-Konfiguration
|
||||
|
||||
Standard-Fenstereinstellungen können in `Main.kt` angepasst werden:
|
||||
|
||||
```kotlin
|
||||
WindowState(
|
||||
position = WindowPosition(Alignment.Center),
|
||||
width = 800.dp, // Anpassbar
|
||||
height = 600.dp // Anpassbar
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Tests
|
||||
|
||||
### Testabdeckung
|
||||
|
||||
| Komponente | Test-Datei | Tests | Abdeckung |
|
||||
|-----------|-----------|-------|----------|
|
||||
| Hauptanwendung | MainTest.kt | 3 | Bootstrap, Konfiguration, Struktur |
|
||||
|
||||
### Test-Implementierung
|
||||
|
||||
```kotlin
|
||||
class MainTest {
|
||||
@Test
|
||||
fun `should have valid main class configuration`()
|
||||
|
||||
@Test
|
||||
fun `should have proper package structure`()
|
||||
|
||||
@Test
|
||||
fun `should be able to instantiate system property for base URL`()
|
||||
}
|
||||
```
|
||||
|
||||
### Test-Suites ausführen
|
||||
|
||||
```bash
|
||||
# Alle Tests
|
||||
./gradlew :client:desktop-app:jvmTest
|
||||
|
||||
# Mit Abdeckungsbericht
|
||||
./gradlew :client:desktop-app:jvmTest jacocoTestReport
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Build-Optimierungshistorie
|
||||
|
||||
### 14. August 2025 - Build-Modernisierung
|
||||
|
||||
**Plugin-Konfiguration-Verbesserungen:**
|
||||
- Migration zu `alias()` für type-safe Plugin-Referenzen
|
||||
- Serialisierung und Compose Compiler-Unterstützung hinzugefügt
|
||||
- TargetFormat-Imports für native Distribution behoben
|
||||
|
||||
**Abhängigkeiten-Verbesserungen:**
|
||||
- Strukturierte Logging-Unterstützung hinzugefügt
|
||||
- Erweiterte HTTP-Client-Fähigkeiten
|
||||
- Verbesserte Compose-Komponentenorganisation
|
||||
- Umfassende Test-Infrastruktur hinzugefügt
|
||||
|
||||
**Native Distribution:**
|
||||
- TargetFormat-Konfiguration behoben
|
||||
- Plattformübergreifendes Packaging aktiviert (Deb, Dmg, Msi)
|
||||
- Package-Metadaten optimiert
|
||||
|
||||
### 16. August 2025 - Tests & Integration
|
||||
|
||||
**Test-Infrastruktur:**
|
||||
- Umfassende MainTest.kt hinzugefügt
|
||||
- Mit common-ui MVVM-Architektur integriert
|
||||
- Anwendungs-Bootstrap und Konfiguration validiert
|
||||
- Systemeigenschaften-Tests hinzugefügt
|
||||
|
||||
**Architektur-Validierung:**
|
||||
- Nahtlose Integration mit aktualisiertem common-ui bestätigt
|
||||
- MVVM-Muster-Konformität verifiziert
|
||||
- Ressourcenverwaltungs-Integration validiert
|
||||
|
||||
---
|
||||
|
||||
## Leistung & Qualität
|
||||
|
||||
### Build-Leistung
|
||||
- ✅ Schnelle inkrementelle Builds mit moderner Gradle-Konfiguration
|
||||
- ✅ Effiziente Plugin-Auflösung durch Versions-Katalog
|
||||
- ✅ Optimierte Abhängigkeitsverwaltung
|
||||
|
||||
### Laufzeit-Leistung
|
||||
- ✅ Native Desktop-Leistung mit JVM-Optimierung
|
||||
- ✅ Effiziente Ressourcenverwaltung durch common-ui Integration
|
||||
- ✅ Minimaler Speicher-Footprint mit ordnungsgemäßer Bereinigung
|
||||
|
||||
### Code-Qualität
|
||||
- ✅ 100% Architektur-Konformität mit MVVM-Muster
|
||||
- ✅ Umfassende Testabdeckung für Desktop-spezifische Funktionalität
|
||||
- ✅ Konsistente Code-Organisation und Dokumentation
|
||||
|
||||
---
|
||||
|
||||
## Integrations-Vorteile
|
||||
|
||||
### Vom Common-UI Modul
|
||||
|
||||
Die Desktop-App profitiert automatisch von allen common-ui Optimierungen:
|
||||
|
||||
- **MVVM-Architektur**: Ordnungsgemäße Trennung der Belange durch PingViewModel
|
||||
- **Ressourcenverwaltung**: Automatische Bereinigung über DisposableEffect in geteilten Komponenten
|
||||
- **UI-Zustandsverwaltung**: Vier distinkte Zustände gemäß Trace-Bullet-Richtlinien
|
||||
- **Speicherleck-Prävention**: Eliminierte Callback-Muster zugunsten von Compose-State
|
||||
|
||||
### Desktop-spezifische Vorteile
|
||||
|
||||
- **Native Leistung**: Direkte JVM-Ausführung ohne Browser-Overhead
|
||||
- **System-Integration**: Native Dateidialoge, Benachrichtigungen, System-Tray-Unterstützungspotential
|
||||
- **Offline-Fähigkeit**: Vollständige Funktionalität ohne Netzwerkabhängigkeiten
|
||||
- **Plattformübergreifend**: Einzige Codebasis läuft auf Windows, macOS und Linux
|
||||
|
||||
---
|
||||
|
||||
## Deployment
|
||||
|
||||
### Entwicklungs-Deployment
|
||||
|
||||
```bash
|
||||
# Schneller Entwicklungslauf
|
||||
./gradlew :client:desktop-app:run
|
||||
|
||||
# Mit benutzerdefinierter Konfiguration ausführen
|
||||
./gradlew :client:desktop-app:run -Dmeldestelle.api.url=https://staging-api.com
|
||||
```
|
||||
|
||||
### Produktions-Deployment
|
||||
|
||||
```bash
|
||||
# Produktions-Build erstellen
|
||||
./gradlew :client:desktop-app:build
|
||||
|
||||
# Für Distribution packen
|
||||
./gradlew :client:desktop-app:createDistributable
|
||||
|
||||
# Das Distributionspaket wird erstellt in:
|
||||
# build/compose/binaries/main/app/
|
||||
```
|
||||
|
||||
### Distributions-Formate
|
||||
|
||||
| Plattform | Format | Befehl | Ausgabe |
|
||||
|----------|--------|---------|--------|
|
||||
| Linux | .deb | `packageDeb` | Debian Package-Installer |
|
||||
| macOS | .dmg | `packageDmg` | macOS Disk-Image |
|
||||
| Windows | .msi | `packageMsi` | Windows Installer |
|
||||
|
||||
---
|
||||
|
||||
## Fehlerbehebung
|
||||
|
||||
### Häufige Probleme
|
||||
|
||||
| Problem | Symptome | Lösung |
|
||||
|-------|----------|----------|
|
||||
| SLF4J-Warnungen | Logging-Warnungen beim Start | Logback-Abhängigkeit hinzufügen (nicht kritisch) |
|
||||
| Hauptklasse nicht gefunden | Build/Run-Fehler | Main.kt Package-Struktur überprüfen |
|
||||
| Fenster wird nicht angezeigt | Anwendung startet, aber kein Fenster | Display-Einstellungen und Fensterzustand überprüfen |
|
||||
| API-Verbindung fehlgeschlagen | Netzwerkfehler | `meldestelle.api.url` Systemeigenschaft überprüfen |
|
||||
|
||||
### Debug-Befehle
|
||||
|
||||
```bash
|
||||
# Hauptklassen-Konfiguration überprüfen
|
||||
./gradlew :client:desktop-app:printMainClassName
|
||||
|
||||
# Abhängigkeiten analysieren
|
||||
./gradlew :client:desktop-app:dependencies
|
||||
|
||||
# Ausführliche Build-Ausgabe
|
||||
./gradlew :client:desktop-app:build --info --stacktrace
|
||||
```
|
||||
|
||||
### Leistungsüberwachung
|
||||
|
||||
```bash
|
||||
# Mit JVM-Profiling ausführen
|
||||
./gradlew :client:desktop-app:run -Dcom.sun.management.jmxremote
|
||||
|
||||
# Speicher-Analyse
|
||||
./gradlew :client:desktop-app:run -XX:+PrintGCDetails
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Zukünftige Verbesserungen
|
||||
|
||||
### Empfohlene Entwicklung
|
||||
|
||||
1. **Desktop-spezifische Features**
|
||||
- System-Tray-Integration
|
||||
- Native Benachrichtigungen
|
||||
- Dateisystem-Dialoge
|
||||
- Desktop-Verknüpfungen
|
||||
|
||||
2. **Erweiterte Protokollierung**
|
||||
- Logback-Konfiguration hinzufügen
|
||||
- Strukturierte Protokollierung mit JSON-Ausgabe
|
||||
- Log-Rotation und Archivierung
|
||||
|
||||
3. **Konfigurationsverwaltung**
|
||||
- Konfigurationsdatei-Unterstützung
|
||||
- Benutzereinstellungen-Persistierung
|
||||
- Umgebungsspezifische Konfigurationen
|
||||
|
||||
4. **Erweiterte Tests**
|
||||
- UI-Tests mit Compose-Test-Utilities
|
||||
- Integrationstests mit Mock-Backend
|
||||
- Leistungs-Benchmarking
|
||||
|
||||
5. **Distributions-Optimierung**
|
||||
- JVM-Optimierung-Flags
|
||||
- Anwendungspaket-Größenreduzierung
|
||||
- Auto-Update-Mechanismen
|
||||
|
||||
---
|
||||
|
||||
## Mitwirken
|
||||
|
||||
### Entwicklungsablauf
|
||||
|
||||
1. **Einrichtung**
|
||||
```bash
|
||||
# JDK 21 Installation überprüfen
|
||||
java -version
|
||||
|
||||
# Erstellen und testen
|
||||
./gradlew :client:desktop-app:build
|
||||
```
|
||||
|
||||
2. **Testen**
|
||||
```bash
|
||||
# Tests vor Änderungen ausführen
|
||||
./gradlew :client:desktop-app:jvmTest
|
||||
|
||||
# Integration mit common-ui testen
|
||||
./gradlew :client:common-ui:jvmTest :client:desktop-app:jvmTest
|
||||
```
|
||||
|
||||
3. **Code-Standards**
|
||||
- Kotlin-Codierungskonventionen befolgen
|
||||
- Tests für neue Desktop-spezifische Funktionalität hinzufügen
|
||||
- Integration mit common-ui MVVM-Architektur beibehalten
|
||||
- Konfigurationsänderungen dokumentieren
|
||||
|
||||
### Pull Request-Anforderungen
|
||||
|
||||
- [ ] Alle bestehenden Tests bestehen
|
||||
- [ ] Neue Funktionalität beinhaltet Tests
|
||||
- [ ] Integration mit common-ui verifiziert
|
||||
- [ ] Dokumentation aktualisiert
|
||||
- [ ] Build-Konfigurationsänderungen dokumentiert
|
||||
|
||||
---
|
||||
|
||||
**Modul-Status**: ✅ Produktionsbereit
|
||||
**Architektur**: ✅ MVVM-integriert
|
||||
**Build-System**: ✅ Modernisiert
|
||||
**Testabdeckung**: ✅ Desktop-spezifische Funktionalität
|
||||
**Distribution**: ✅ Plattformübergreifend bereit
|
||||
|
||||
*Zuletzt aktualisiert: 16. August 2025*
|
||||
Reference in New Issue
Block a user