460 lines
12 KiB
Markdown
460 lines
12 KiB
Markdown
# 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*
|