From da1f26168442716fb22c7225cb92574dacc55057 Mon Sep 17 00:00:00 2001 From: Philipp Wagner Date: Wed, 18 Nov 2026 20:14:16 +0100 Subject: [PATCH] Remove the executed setup wizard stage 1 plan Stage 1 is implemented and manually checked. What was worth keeping is in the commit messages, the spec and docs/PROJECT_CONTEXT.md. Written-by: Claude Fable 5.2 --- ...026-11-18-einrichtungsassistent-stufe-1.md | 2694 ----------------- 1 file changed, 2694 deletions(-) delete mode 100644 docs/superpowers/plans/2026-11-18-einrichtungsassistent-stufe-1.md diff --git a/docs/superpowers/plans/2026-11-18-einrichtungsassistent-stufe-1.md b/docs/superpowers/plans/2026-11-18-einrichtungsassistent-stufe-1.md deleted file mode 100644 index d351a53f..00000000 --- a/docs/superpowers/plans/2026-11-18-einrichtungsassistent-stufe-1.md +++ /dev/null @@ -1,2694 +0,0 @@ -# Einrichtungsassistent, Ausbaustufe 1 — Implementation Plan - -> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. - -**Goal:** Ein unkonfiguriertes Operatorprofil startet in einem Einrichtungsassistenten, der Persönliches, Anmeldung, Standort und Bänder abfragt und `preferences.xml` schreibt, bevor die Laufzeit gebaut wird. - -**Architecture:** Der Assistent läuft vor dem `ChatController` auf einem eigenen `ChatPreferences`-Objekt und schreibt die Datei; `startRuntime` liest sie danach wie jede gespeicherte Einstellung. Er ändert keine laufende Sitzung und berührt `SettingsDraft` nicht. Aus dem Menü wird die Laufzeit erst abgebaut, dann das selbe Profil mit dem Assistenten neu gestartet. - -**Tech Stack:** Java 21 (`core`), Kotlin 2.2 und Compose Multiplatform 1.8 (`app-desktop`), JUnit 5, Gradle-Wrapper. - -**Spec:** `docs/superpowers/specs/2026-11-18-einrichtungsassistent-design.md` — dieser Plan setzt **nur Ausbaustufe 1** um. Die Stufen 2 (Antenne, Logprogramm, Rotor, AirScout) und 3 („von Profil X übernehmen") bekommen eigene Pläne, sobald Stufe 1 steht; ihre Schritte hängen an den Formen, die hier entstehen. - -## Global Constraints - -- Gradle, nicht Maven. Java 21. Bau und Tests über `./gradlew`. -- Quelltextkommentare und Javadoc ausschließlich Englisch. Kommunikation und Handbuch-Deutsch in neuer Rechtschreibung (`muss`, `dass`). -- `core` erzeugt keinen Anzeigetext und kennt kein Toolkit. Die Erkennung liegt in `core`, alles Sichtbare in `app-desktop`. -- Oberflächentexte stehen in `app-desktop/src/main/i18n/strings_en.properties` (Basis) und `strings_de.properties`. Beide Dateien bekommen jeden neuen Schlüssel. Ein Schlüssel nur in der deutschen Datei bricht den Bau. -- Kein Apostroph in den neuen Texten: parametrisierte Texte laufen durch `MessageFormat`. -- Bandbezeichnungen (`144 MHz`) und Kategorienamen sind Funkerkürzel und werden nicht übersetzt. -- Rufzeichen und Locator werden gespeichert, wie sie getippt wurden, nur ohne Leerraum am Rand. Keine neue Normalisierung. -- Nie blockierend auf dem AWT-Ereignisfaden warten. Das Fenster ist ein modaler `ComposeDialog`, geöffnet über `openOnEventThread`, wie `OperatorProfilePickerWindow`. -- Unverändert bleiben: das Format von `preferences.xml`, das Einstellungsfenster mit seinen zwölf Reitern, `SettingsDraft.apply`, `OperatorProfileManagementService`, `praktiKSTpreferences.xml`. -- Unkonfiguriert heißt: Rufzeichen leer, oder Rufzeichen `DO5AMF` mit Passwort `changeMe`. -- Pflichtangaben für „Fertig" und „Speichern": Anzeigename, Rufzeichen, Passwort, Locator, mindestens ein Band, Chatkategorie. -- Kein Commit, kein Push ohne ausdrücklichen Auftrag des Nutzers (`AGENTS.md`). Die Commit-Schritte unten gelten nur, wenn der Auftrag zur Ausführung das Committen einschließt; sonst bleiben die Änderungen im Arbeitsbaum. -- Ein Testfehler bricht den Bau, PMD und SpotBugs nicht. Ergebnis aus der Test-XML unter `*/build/test-results/` lesen, nicht aus dem Rückgabewert. - -## Review Focus - -1. **Rufzeichen mit Zusatz oder in Kleinschrift** (`DL0TEST/P`, `DO5AMF-2`, `do5amf`): wird angenommen und unverändert gespeichert. Test in Task 2 (`callsignsWithSuffixAndLowerCaseAreAccepted`) und Task 3 (`aCallsignIsStoredAsTyped`). -2. **Gespeicherte Chatkategorie außerhalb 1–3** (etwa 7) bei „unverändert lassen": bleibt 7, der Assistent schlägt nichts darüber. Test in Task 3 (`aKeptCategoryOutsideTheSuggestionsSurvives`). -3. **Die Datei lässt sich nicht schreiben**: der Assistent bleibt offen und meldet es, statt sich mit „gespeichert" zu schließen. Test in Task 3 (`aFailedWriteIsReported`) und Task 5 (`aFailedSaveKeepsTheWizardOpen`). -4. **Die Profildatei ist unlesbar**: der Assistent erscheint nicht und überschreibt nichts; der Start geht weiter wie heute. Test in Task 5 (`anUnreadableFileNeverOpensTheWizard`). -5. **Fenster über das X geschlossen**: zählt als „Später", schreibt nichts. Test in Task 5 (`closingTheWindowCountsAsLater`). - ---- - -## Dateien - -| Datei | Aufgabe | -|---|---| -| `core/src/main/java/kst4contest/controller/LoginConfiguration.java` (neu) | Erkennung „unkonfiguriert" und Vorlagen-Anmeldedaten | -| `core/src/test/java/kst4contest/controller/LoginConfigurationTest.java` (neu) | deren Tests, auch gegen die mitgelieferte Vorlage | -| `app-desktop/src/main/kotlin/kst4contest/view/compose/wizard/SetupWizardState.kt` (neu) | Zustand, Ablauf, Prüfregeln, Schreiben der Antworten | -| `app-desktop/src/main/kotlin/kst4contest/view/compose/wizard/SetupWizardContent.kt` (neu) | die Seiten als Composables | -| `app-desktop/src/main/kotlin/kst4contest/view/compose/wizard/SetupWizardWindow.kt` (neu) | modaler Dialog, Ergebnis, Starter | -| `app-desktop/src/test/kotlin/kst4contest/view/compose/wizard/*Test.kt` (neu) | Tests dazu | -| `app-desktop/src/main/i18n/strings_en.properties`, `strings_de.properties` | neue Texte | -| `app-desktop/src/main/java/kst4contest/view/Kst4ContestApplication.java` | Aufruf im Start, Verbinden danach, Menüaktion | -| `app-desktop/src/main/java/kst4contest/view/ApplicationRuntimeLauncher.java` | Wunsch „Assistent zeigen", Neustart des selben Profils | -| `app-desktop/src/main/java/kst4contest/view/ComposeMenuActions.java`, `.../compose/MainMenuBar.kt`, `.../compose/MainMenuModel.kt` | Menüeintrag | -| `docs/PROJECT_CONTEXT.md`, `github_docs/de-Konfiguration.md`, `github_docs/en-Configuration.md` | Dokumentation | - ---- - -### Task 1: Erkennung eines unkonfigurierten Profils - -**Files:** -- Create: `core/src/main/java/kst4contest/controller/LoginConfiguration.java` -- Test: `core/src/test/java/kst4contest/controller/LoginConfigurationTest.java` - -**Interfaces:** -- Consumes: `ChatPreferences.getStn_loginCallSign()`, `getStn_loginPassword()`, `ChatPreferences.PREFERENCE_RESOURCE`, Konstruktor `ChatPreferences(Path)`. -- Produces: - - `public static final String LoginConfiguration.TEMPLATE_CALLSIGN` (`"DO5AMF"`) - - `public static final String LoginConfiguration.TEMPLATE_PASSWORD` (`"changeMe"`) - - `public static boolean LoginConfiguration.carriesTemplateCredentials(ChatPreferences)` - - `public static boolean LoginConfiguration.isUnconfigured(ChatPreferences)` - -- [ ] **Step 1: Write the failing test** - -```java -package kst4contest.controller; - -import kst4contest.model.ChatPreferences; -import org.junit.jupiter.api.Test; -import org.junit.jupiter.api.io.TempDir; - -import java.io.IOException; -import java.io.InputStream; -import java.nio.file.Files; -import java.nio.file.Path; -import java.nio.file.StandardCopyOption; - -import static org.junit.jupiter.api.Assertions.assertFalse; -import static org.junit.jupiter.api.Assertions.assertNotNull; -import static org.junit.jupiter.api.Assertions.assertTrue; - -/** - * When a profile counts as not set up yet. The setup wizard appears on exactly this - * condition, so a wrong answer either nags a working station or leaves a newcomer alone - * with the template's callsign. - */ -class LoginConfigurationTest { - - @TempDir - Path temporaryDirectory; - - private ChatPreferences preferences(String callsign, String password) { - ChatPreferences preferences = new ChatPreferences(temporaryDirectory.resolve("unused.xml")); - preferences.setStn_loginCallSign(callsign); - preferences.setStn_loginPassword(password); - return preferences; - } - - @Test - void anEmptyCallsignIsUnconfigured() { - assertTrue(LoginConfiguration.isUnconfigured(preferences("", "secret"))); - assertTrue(LoginConfiguration.isUnconfigured(preferences(" ", "secret"))); - } - - @Test - void theTemplateCredentialsAreUnconfigured() { - ChatPreferences template = preferences("DO5AMF", "changeMe"); - - assertTrue(LoginConfiguration.carriesTemplateCredentials(template)); - assertTrue(LoginConfiguration.isUnconfigured(template)); - } - - @Test - void theTemplateCallsignWithItsOwnPasswordIsConfigured() { - // The callsign belongs to a real operator; only the pair marks an untouched template. - ChatPreferences owner = preferences("DO5AMF", "a-real-password"); - - assertFalse(LoginConfiguration.carriesTemplateCredentials(owner)); - assertFalse(LoginConfiguration.isUnconfigured(owner)); - } - - @Test - void aRealLoginIsConfigured() { - assertFalse(LoginConfiguration.isUnconfigured(preferences("DL0TEST", "secret"))); - assertFalse(LoginConfiguration.isUnconfigured(preferences("DL0TEST/P", ""))); - } - - @Test - void theConstantsMatchTheBundledTemplate() throws IOException { - Path templateCopy = temporaryDirectory.resolve("template.xml"); - try (InputStream template = ChatPreferences.class - .getResourceAsStream(ChatPreferences.PREFERENCE_RESOURCE)) { - assertNotNull(template, "bundled resource " + ChatPreferences.PREFERENCE_RESOURCE); - Files.copy(template, templateCopy, StandardCopyOption.REPLACE_EXISTING); - } - - ChatPreferences fromTemplate = new ChatPreferences(templateCopy); - assertTrue(fromTemplate.readPreferencesFromXmlFile()); - - assertTrue(LoginConfiguration.carriesTemplateCredentials(fromTemplate), - "the template's credentials changed; a fresh installation would no longer " - + "be recognised as unconfigured"); - } -} -``` - -- [ ] **Step 2: Run test to verify it fails** - -Run: `./gradlew :core:test --tests 'kst4contest.controller.LoginConfigurationTest'` -Expected: Kompilierfehler, `cannot find symbol ... LoginConfiguration`. - -- [ ] **Step 3: Write minimal implementation** - -```java -package kst4contest.controller; - -import kst4contest.model.ChatPreferences; - -/** - * Tells whether a profile has login credentials an operator entered. - * - *

Two states count as unconfigured. An empty callsign is what every created or duplicated - * profile starts with, because {@link OperatorProfileManagementService} clears the - * credentials on purpose. The bundled template's credentials are what the root profile of a - * fresh installation carries. Neither can log in as the operator, so neither needs a flag of - * its own in {@code preferences.xml}.

- */ -public final class LoginConfiguration { - - /** Callsign shipped in {@code praktiKSTpreferences.xml}; held equal by a test. */ - public static final String TEMPLATE_CALLSIGN = "DO5AMF"; - - /** Password shipped in {@code praktiKSTpreferences.xml}; held equal by a test. */ - public static final String TEMPLATE_PASSWORD = "changeMe"; - - private LoginConfiguration() { - // Utility class. - } - - /** - * Whether the preferences still hold the bundled template's credentials. - * - *

Only the pair counts. The callsign alone belongs to a real operator.

- * - * @param preferences preferences of the profile to judge - * @return true for an untouched template - */ - public static boolean carriesTemplateCredentials(final ChatPreferences preferences) { - return TEMPLATE_CALLSIGN.equalsIgnoreCase(trimmed(preferences.getStn_loginCallSign())) - && TEMPLATE_PASSWORD.equals(preferences.getStn_loginPassword()); - } - - /** - * Whether the profile has no login an operator entered. - * - * @param preferences preferences of the profile to judge - * @return true when the callsign is empty or the template's credentials are still there - */ - public static boolean isUnconfigured(final ChatPreferences preferences) { - return trimmed(preferences.getStn_loginCallSign()).isEmpty() - || carriesTemplateCredentials(preferences); - } - - private static String trimmed(final String value) { - return value == null ? "" : value.trim(); - } -} -``` - -- [ ] **Step 4: Run test to verify it passes** - -Run: `./gradlew :core:test --tests 'kst4contest.controller.LoginConfigurationTest'` -Expected: 5 Tests, 0 Fehler in `core/build/test-results/test/TEST-kst4contest.controller.LoginConfigurationTest.xml`. - -- [ ] **Step 5: Commit** - -```bash -git add core/src/main/java/kst4contest/controller/LoginConfiguration.java core/src/test/java/kst4contest/controller/LoginConfigurationTest.java -git commit -m "Detect operator profiles without entered login credentials" -``` - ---- - -### Task 2: Zustand und Ablauf des Assistenten - -**Files:** -- Create: `app-desktop/src/main/kotlin/kst4contest/view/compose/wizard/SetupWizardState.kt` -- Test: `app-desktop/src/test/kotlin/kst4contest/view/compose/wizard/SetupWizardStateTest.kt` - -**Interfaces:** -- Consumes: `LoginConfiguration.isUnconfigured`, `LoginConfiguration.carriesTemplateCredentials` (Task 1); Getter von `ChatPreferences`. -- Produces (alle in Paket `kst4contest.view.compose.wizard`): - - `enum class WizardSource { NEW, KEEP }` - - `enum class WizardPage { ENTRY, PERSONAL, LOGIN, SITE, SUMMARY }` - - `enum class WizardBand(val label: String, val megahertz: Int)` mit `B50, B70, B144, B432, B1240, B2300, B3400, B5600, B10G` - - `class SetupWizardState(prefs: ChatPreferences)` mit - - `val loginSources: List`, `val stationSources: List`, `val hasEntryPage: Boolean` - - `val loginSource: WizardSource?`, `val stationSource: WizardSource?`, `fun chooseLoginSource(WizardSource)`, `fun chooseStationSource(WizardSource)` - - `val storedCallsign: String`, `val storedLocator: String` - - `var language: String`, `var name: String`, `var callsign: String`, `var password: String`, `var locator: String` - - `val bands: Set`, `fun setBand(WizardBand, Boolean)` - - `val category: Int?`, `fun chooseCategory(Int)`, `val suggestedCategory: Int?` - - `val secondChat: Boolean`, `fun chooseSecondChat(Boolean)`, `var secondCategory: Int?`, `val secondCategoryOptions: List` - - `val page: WizardPage`, `val pages: List` - - `val canGoNext: Boolean`, `val canGoBack: Boolean`, `val canFinish: Boolean`, `val mandatoryComplete: Boolean` - - `val callsignRefused: Boolean`, `val locatorRefused: Boolean` - - `fun next()`, `fun back()`, `fun finish()`, `fun edit(WizardPage)` - - `val turnsOffSecondChat: Boolean`, `val leavesIntegrationsUntouched: Boolean` - - `companion`: `val CATEGORY_NUMBERS: List`, `fun isPlausibleCallsign(String): Boolean`, `fun isLocator(String): Boolean`, `fun suggestCategory(Set): Int?` - -- [ ] **Step 1: Write the failing test** - -```kotlin -package kst4contest.view.compose.wizard - -import kst4contest.model.ChatCategory -import kst4contest.model.ChatPreferences -import org.junit.jupiter.api.Assertions.assertEquals -import org.junit.jupiter.api.Assertions.assertFalse -import org.junit.jupiter.api.Assertions.assertNull -import org.junit.jupiter.api.Assertions.assertTrue -import org.junit.jupiter.api.Test -import java.nio.file.Path - -/** - * The wizard's rules without a window: which pages appear, what they start with, and when - * the operator may go on. Nothing here reads or writes a file. - */ -class SetupWizardStateTest { - - /** Preferences that never touch a file: the path is only read by read/write calls. */ - private fun prefs(configure: ChatPreferences.() -> Unit = {}): ChatPreferences = - ChatPreferences(Path.of("setup-wizard-state-test-unused.xml")).apply(configure) - - private fun freshInstallation() = prefs { - setStn_loginCallSign("DO5AMF") - setStn_loginPassword("changeMe") - setStn_loginNameMainCat("KST4Contest1263") - setStn_loginLocatorMainCat("JO54ME") - setStn_bandActive144(true) - setLoginChatCategoryMain(ChatCategory(2)) - setLoginToSecondChatEnabled(true) - setLoginChatCategorySecond(ChatCategory(3)) - } - - private fun duplicatedProfile() = prefs { - setStn_loginCallSign("") - setStn_loginPassword("") - setStn_loginNameMainCat("Other Operator") - setStn_loginLocatorMainCat("JO50AA") - setStn_bandActive144(true) - setStn_bandActive432(true) - setLoginChatCategoryMain(ChatCategory(2)) - setLoginToSecondChatEnabled(false) - } - - private fun configuredProfile() = duplicatedProfile().apply { - setStn_loginCallSign("DL0TEST") - setStn_loginPassword("secret") - setStn_loginNameMainCat("Philipp") - } - - /** Fills every mandatory answer of a first installation, leaving the wizard on SITE. */ - private fun SetupWizardState.fillFirstInstallation() { - name = "Philipp" - next() - callsign = "DL0TEST" - password = "secret" - next() - locator = "JO50AA" - setBand(WizardBand.B144, true) - } - - @Test - fun aFreshInstallationHasNoEntryPageAndStartsEmpty() { - val state = SetupWizardState(freshInstallation()) - - assertFalse(state.hasEntryPage) - assertEquals(WizardPage.PERSONAL, state.page) - assertEquals( - listOf(WizardPage.PERSONAL, WizardPage.LOGIN, WizardPage.SITE, WizardPage.SUMMARY), - state.pages, - ) - assertEquals("", state.name, "the template's name is nobody's name") - assertEquals("", state.callsign) - assertEquals("", state.locator) - assertTrue(state.bands.isEmpty()) - assertNull(state.category) - assertFalse(state.secondChat) - } - - @Test - fun aDuplicatedProfileIsAskedOnlyAboutTheStation() { - val state = SetupWizardState(duplicatedProfile()) - - assertEquals(listOf(WizardSource.NEW), state.loginSources) - assertEquals(listOf(WizardSource.NEW, WizardSource.KEEP), state.stationSources) - assertTrue(state.hasEntryPage) - assertEquals(WizardPage.ENTRY, state.page) - assertEquals(WizardSource.NEW, state.loginSource, "a single option is chosen already") - assertNull(state.stationSource, "nothing is preselected where there is a choice") - assertFalse(state.canGoNext) - } - - @Test - fun aConfiguredProfileMayKeepBoth() { - val state = SetupWizardState(configuredProfile()) - - assertEquals(listOf(WizardSource.NEW, WizardSource.KEEP), state.loginSources) - assertEquals(listOf(WizardSource.NEW, WizardSource.KEEP), state.stationSources) - assertEquals("Philipp", state.name, "a configured profile keeps its operator's name") - } - - @Test - fun keepingTheStationSkipsItsStepAndCarriesTheStoredValues() { - val state = SetupWizardState(duplicatedProfile()) - state.chooseStationSource(WizardSource.KEEP) - state.next() - - assertEquals( - listOf(WizardPage.ENTRY, WizardPage.PERSONAL, WizardPage.LOGIN, WizardPage.SUMMARY), - state.pages, - ) - assertEquals("JO50AA", state.locator) - assertEquals(setOf(WizardBand.B144, WizardBand.B432), state.bands) - assertEquals(2, state.category) - } - - @Test - fun aNewStationStartsEmptyEvenOnAProfileThatHasOne() { - val state = SetupWizardState(duplicatedProfile()) - state.chooseStationSource(WizardSource.NEW) - state.next() - - assertEquals("", state.locator) - assertTrue(state.bands.isEmpty()) - assertNull(state.category) - assertTrue(state.pages.contains(WizardPage.SITE)) - } - - @Test - fun goingBackToTheEntryPageAndOnAgainKeepsWhatWasTyped() { - val state = SetupWizardState(duplicatedProfile()) - state.chooseStationSource(WizardSource.NEW) - state.next() - state.name = "Philipp" - state.back() - state.next() - - assertEquals("Philipp", state.name) - - state.next() - state.callsign = "DL0TEST" - state.back() - state.back() - state.chooseStationSource(WizardSource.KEEP) - state.next() - - assertEquals("JO50AA", state.locator, "a changed source loads its own values") - state.next() - assertEquals("DL0TEST", state.callsign, "the login source did not change") - } - - @Test - fun callsignsWithSuffixAndLowerCaseAreAccepted() { - listOf("DL0TEST", "DL0TEST/P", "DO5AMF-2", "do5amf", " DL0TEST ").forEach { - assertTrue(SetupWizardState.isPlausibleCallsign(it), "'$it' must be accepted") - } - listOf("", "DL", "ABC", "123", "DL0 TEST", "DL0TEST|X", "DL0-TEST-2", "DL0TEST/").forEach { - assertFalse(SetupWizardState.isPlausibleCallsign(it), "'$it' must be refused") - } - } - - @Test - fun onlyASixCharacterLocatorIsAccepted() { - listOf("JO50AA", "jo50aa", " JN49FL ").forEach { - assertTrue(SetupWizardState.isLocator(it), "'$it' must be accepted") - } - listOf("", "JO50", "JO50AAA", "SS50AA", "JO50YY", "JO5OAA").forEach { - assertFalse(SetupWizardState.isLocator(it), "'$it' must be refused") - } - } - - @Test - fun theCategoryIsSuggestedFromTheLowestBand() { - assertNull(SetupWizardState.suggestCategory(emptySet())) - assertEquals(1, SetupWizardState.suggestCategory(setOf(WizardBand.B50, WizardBand.B144))) - assertEquals(1, SetupWizardState.suggestCategory(setOf(WizardBand.B70))) - assertEquals(2, SetupWizardState.suggestCategory(setOf(WizardBand.B144, WizardBand.B1240))) - assertEquals(2, SetupWizardState.suggestCategory(setOf(WizardBand.B432))) - assertEquals(3, SetupWizardState.suggestCategory(setOf(WizardBand.B1240, WizardBand.B10G))) - } - - @Test - fun theSuggestionFollowsTheBandsUntilTheOperatorChooses() { - val state = SetupWizardState(freshInstallation()) - - state.setBand(WizardBand.B1240, true) - assertEquals(3, state.category) - - state.setBand(WizardBand.B144, true) - assertEquals(2, state.category) - - state.chooseCategory(3) - state.setBand(WizardBand.B50, true) - assertEquals(3, state.category, "an operator's choice is not overwritten") - assertEquals(1, state.suggestedCategory, "the suggestion is still shown") - } - - @Test - fun aSecondChatNeedsADifferentCategory() { - val state = SetupWizardState(freshInstallation()) - state.fillFirstInstallation() - assertTrue(state.canGoNext) - - state.chooseSecondChat(true) - assertFalse(state.canGoNext, "the second chat has no category yet") - assertFalse(state.secondCategoryOptions.contains(2), "the main category is not offered twice") - - state.secondCategory = 3 - assertTrue(state.canGoNext) - - state.chooseCategory(3) - assertNull(state.secondCategory, "the same chat cannot be opened twice") - assertFalse(state.canGoNext) - } - - @Test - fun finishNeedsEveryMandatoryAnswer() { - val state = SetupWizardState(freshInstallation()) - - state.name = "Philipp" - assertFalse(state.canFinish) - state.next() - state.callsign = "DL0TEST" - state.password = "secret" - assertFalse(state.canFinish, "a new station still lacks its locator") - state.next() - state.locator = "JO50AA" - assertFalse(state.canFinish, "no band yet") - state.setBand(WizardBand.B144, true) - assertTrue(state.canFinish) - - state.finish() - assertEquals(WizardPage.SUMMARY, state.page) - assertTrue(state.mandatoryComplete) - assertFalse(state.canFinish, "the summary has Save instead") - } - - @Test - fun aKeptStationLetsTheOperatorFinishAfterTheLogin() { - val state = SetupWizardState(duplicatedProfile()) - state.chooseStationSource(WizardSource.KEEP) - state.next() - state.name = "Philipp" - state.next() - state.callsign = "DL0TEST/P" - state.password = "secret" - - assertTrue(state.canFinish) - } - - @Test - fun aRefusedEntryIsOnlyShownOnceSomethingWasTyped() { - val state = SetupWizardState(freshInstallation()) - - assertFalse(state.callsignRefused, "an empty field is not an error yet") - state.callsign = "DL" - assertTrue(state.callsignRefused) - state.callsign = "DL0TEST" - assertFalse(state.callsignRefused) - - assertFalse(state.locatorRefused) - state.locator = "JO50" - assertTrue(state.locatorRefused) - } - - @Test - fun changeFromTheSummaryOpensAStepThatWasSkipped() { - val state = SetupWizardState(configuredProfile()) - state.chooseLoginSource(WizardSource.KEEP) - state.chooseStationSource(WizardSource.KEEP) - state.next() - state.next() - assertEquals(WizardPage.SUMMARY, state.page) - - state.edit(WizardPage.LOGIN) - - assertEquals(WizardPage.LOGIN, state.page) - assertEquals("DL0TEST", state.callsign, "the kept value is there to be changed") - state.callsign = "DL0TEST/P" - state.next() - assertEquals(WizardPage.SUMMARY, state.page) - } - - @Test - fun theSummarySaysWhatIsSwitchedOffAndWhatIsLeftAlone() { - val fresh = SetupWizardState(freshInstallation()) - assertTrue(fresh.turnsOffSecondChat, "the template has the second chat on, a new station has it off") - assertTrue(fresh.leavesIntegrationsUntouched) - - val kept = SetupWizardState(duplicatedProfile()) - kept.chooseStationSource(WizardSource.KEEP) - kept.next() - assertFalse(kept.turnsOffSecondChat) - assertFalse(kept.leavesIntegrationsUntouched) - } -} -``` - -- [ ] **Step 2: Run test to verify it fails** - -Run: `./gradlew :app-desktop:test --tests 'kst4contest.view.compose.wizard.SetupWizardStateTest'` -Expected: Kompilierfehler, `Unresolved reference: SetupWizardState`. - -- [ ] **Step 3: Write minimal implementation** - -```kotlin -package kst4contest.view.compose.wizard - -import androidx.compose.runtime.getValue -import androidx.compose.runtime.mutableStateOf -import androidx.compose.runtime.setValue -import kst4contest.controller.LoginConfiguration -import kst4contest.model.ChatCategory -import kst4contest.model.ChatPreferences - -/** Where the answers of one group come from. */ -enum class WizardSource { - /** Entered in the wizard, starting from the wizard's own empty values. */ - NEW, - - /** What the profile already holds. */ - KEEP, -} - -/** The pages, in the order they can appear. */ -enum class WizardPage { ENTRY, PERSONAL, LOGIN, SITE, SUMMARY } - -/** - * A band the station can be active on. - * - * The labels are amateur shorthand and deliberately not in the translation files. - */ -enum class WizardBand( - val label: String, - val megahertz: Int, - internal val isActive: (ChatPreferences) -> Boolean, - internal val setActive: (ChatPreferences, Boolean) -> Unit, -) { - B50("50 MHz", 50, { it.isStn_bandActive50() }, { p, on -> p.setStn_bandActive50(on) }), - B70("70 MHz", 70, { it.isStn_bandActive70() }, { p, on -> p.setStn_bandActive70(on) }), - B144("144 MHz", 144, { it.isStn_bandActive144() }, { p, on -> p.setStn_bandActive144(on) }), - B432("432 MHz", 432, { it.isStn_bandActive432() }, { p, on -> p.setStn_bandActive432(on) }), - B1240("1240 MHz", 1240, { it.isStn_bandActive1240() }, { p, on -> p.setStn_bandActive1240(on) }), - B2300("2300 MHz", 2300, { it.isStn_bandActive2300() }, { p, on -> p.setStn_bandActive2300(on) }), - B3400("3400 MHz", 3400, { it.isStn_bandActive3400() }, { p, on -> p.setStn_bandActive3400(on) }), - B5600("5600 MHz", 5600, { it.isStn_bandActive5600() }, { p, on -> p.setStn_bandActive5600(on) }), - B10G("10 GHz", 10000, { it.isStn_bandActive10G() }, { p, on -> p.setStn_bandActive10G(on) }), -} - -/** - * The setup wizard's answers and the rules of its course, free of any window. - * - * It reads the preferences once, when it is built, and does not touch them again until - * [writeTo]: closing the wizard without saving therefore leaves the profile exactly as it - * was. The design is in `docs/superpowers/specs/2026-11-18-einrichtungsassistent-design.md`. - * - * The answers are Compose state, so a composition reading them follows; nothing else here - * depends on Compose. - * - * @param prefs the profile's preferences, already read from its file - */ -class SetupWizardState(prefs: ChatPreferences) { - - private val loginConfigured = !LoginConfiguration.isUnconfigured(prefs) - private val templateCredentials = LoginConfiguration.carriesTemplateCredentials(prefs) - - /** The callsign the profile holds, for the label of "leave unchanged". */ - val storedCallsign: String = prefs.getStn_loginCallSign().orEmpty() - private val storedPassword: String = prefs.getStn_loginPassword().orEmpty() - private val storedName: String = prefs.getStn_loginNameMainCat().orEmpty() - private val storedSecondName: String = prefs.getStn_loginNameSecondCat().orEmpty() - - /** The locator the profile holds, for the label of "leave unchanged". */ - val storedLocator: String = prefs.getStn_loginLocatorMainCat().orEmpty() - private val storedBands: Set = WizardBand.entries.filter { it.isActive(prefs) }.toSet() - private val storedCategory: Int? = prefs.getLoginChatCategoryMain()?.categoryNumber - private val storedSecondChat: Boolean = prefs.isLoginToSecondChatEnabled() - private val storedSecondCategory: Int? = prefs.getLoginChatCategorySecond()?.categoryNumber - - /** A login can only be kept where an operator entered one. */ - val loginSources: List = buildList { - add(WizardSource.NEW) - if (loginConfigured) add(WizardSource.KEEP) - } - - /** - * A station can be kept unless the profile is the untouched template: its locator and - * bands are then nobody's. - */ - val stationSources: List = buildList { - add(WizardSource.NEW) - if (!templateCredentials) add(WizardSource.KEEP) - } - - /** Whether there is anything to choose on the entry page. */ - val hasEntryPage: Boolean = loginSources.size > 1 || stationSources.size > 1 - - var loginSource: WizardSource? by mutableStateOf(loginSources.singleOrNull()) - private set - - var stationSource: WizardSource? by mutableStateOf(stationSources.singleOrNull()) - private set - - private var appliedLoginSource: WizardSource? = null - private var appliedStationSource: WizardSource? = null - - /** The stored form of the language: a code, or empty for the system language. */ - var language: String by mutableStateOf(prefs.getGuiOptions_language().orEmpty()) - - /** Empty on an unconfigured profile: its stored name is the template's or another operator's. */ - var name: String by mutableStateOf(if (loginConfigured) storedName else "") - - var callsign: String by mutableStateOf("") - var password: String by mutableStateOf("") - var locator: String by mutableStateOf("") - - var bands: Set by mutableStateOf(emptySet()) - private set - - var category: Int? by mutableStateOf(null) - private set - - private var categoryChosenByOperator = false - - var secondChat: Boolean by mutableStateOf(false) - private set - - var secondCategory: Int? by mutableStateOf(null) - - private var loginShown by mutableStateOf(false) - private var stationShown by mutableStateOf(false) - - var page: WizardPage by mutableStateOf(if (hasEntryPage) WizardPage.ENTRY else WizardPage.PERSONAL) - private set - - init { - if (!hasEntryPage) applySources() - } - - fun chooseLoginSource(source: WizardSource) { - if (source in loginSources) loginSource = source - } - - fun chooseStationSource(source: WizardSource) { - if (source in stationSources) stationSource = source - } - - /** - * Loads the answers of a group whose source changed. A group whose source is the one - * already applied is left alone, so going back to the entry page costs nothing typed. - */ - private fun applySources() { - if (loginSource != appliedLoginSource) { - val keep = loginSource == WizardSource.KEEP - callsign = if (keep) storedCallsign else "" - password = if (keep) storedPassword else "" - loginShown = !keep - appliedLoginSource = loginSource - } - - if (stationSource != appliedStationSource) { - val keep = stationSource == WizardSource.KEEP - locator = if (keep) storedLocator else "" - bands = if (keep) storedBands else emptySet() - category = if (keep) storedCategory else null - secondChat = keep && storedSecondChat - secondCategory = if (keep) storedSecondCategory else null - // A kept category is the operator's; the suggestion must not replace it. - categoryChosenByOperator = keep - stationShown = !keep - appliedStationSource = stationSource - } - } - - fun setBand(band: WizardBand, active: Boolean) { - bands = if (active) bands + band else bands - band - if (!categoryChosenByOperator) setCategory(suggestCategory(bands)) - } - - /** What the bands suggest, shown beside the picker whatever is chosen. */ - val suggestedCategory: Int? - get() = suggestCategory(bands) - - fun chooseCategory(number: Int) { - categoryChosenByOperator = true - setCategory(number) - } - - private fun setCategory(number: Int?) { - category = number - if (secondCategory == number) secondCategory = null - } - - fun chooseSecondChat(enabled: Boolean) { - secondChat = enabled - } - - /** The main category is left out, as the Station tab does. */ - val secondCategoryOptions: List - get() = CATEGORY_NUMBERS.filter { it != category } - - /** The pages of this run, in order. */ - val pages: List - get() = buildList { - if (hasEntryPage) add(WizardPage.ENTRY) - add(WizardPage.PERSONAL) - if (loginShown) add(WizardPage.LOGIN) - if (stationShown) add(WizardPage.SITE) - add(WizardPage.SUMMARY) - } - - private val personalComplete: Boolean - get() = name.isNotBlank() - - private val loginComplete: Boolean - get() = isPlausibleCallsign(callsign) && password.isNotEmpty() - - private val stationComplete: Boolean - get() = isLocator(locator) && bands.isNotEmpty() && category != null && - (!secondChat || (secondCategory != null && secondCategory != category)) - - /** Whether everything the profile needs to log in is there. */ - val mandatoryComplete: Boolean - get() = personalComplete && loginComplete && stationComplete - - /** A callsign that was typed and does not look like one. An empty field is not an error yet. */ - val callsignRefused: Boolean - get() = callsign.isNotBlank() && !isPlausibleCallsign(callsign) - - /** A locator that was typed and is not one. An empty field is not an error yet. */ - val locatorRefused: Boolean - get() = locator.isNotBlank() && !isLocator(locator) - - val canGoNext: Boolean - get() = when (page) { - WizardPage.ENTRY -> loginSource != null && stationSource != null - WizardPage.PERSONAL -> personalComplete - WizardPage.LOGIN -> loginComplete - WizardPage.SITE -> stationComplete - WizardPage.SUMMARY -> false - } - - val canGoBack: Boolean - get() = pages.indexOf(page) > 0 - - /** - * Whether the remaining steps may be skipped. Only with every mandatory answer, because - * a summary that cannot be saved helps nobody. - */ - val canFinish: Boolean - get() = page != WizardPage.ENTRY && page != WizardPage.SUMMARY && mandatoryComplete - - fun next() { - if (!canGoNext) return - if (page == WizardPage.ENTRY) applySources() - page = pages[pages.indexOf(page) + 1] - } - - fun back() { - if (canGoBack) page = pages[pages.indexOf(page) - 1] - } - - fun finish() { - if (canFinish) page = WizardPage.SUMMARY - } - - /** Opens a step from the summary, also one this run skipped. */ - fun edit(target: WizardPage) { - when (target) { - WizardPage.LOGIN -> loginShown = true - WizardPage.SITE -> stationShown = true - WizardPage.PERSONAL -> Unit - WizardPage.ENTRY, WizardPage.SUMMARY -> return - } - page = target - } - - /** The profile had a second chat and will have none. */ - val turnsOffSecondChat: Boolean - get() = storedSecondChat && !secondChat - - /** - * A new station is set up, and this stage does not ask about log program, rotator, - * AirScout and DX cluster server: they keep their stored values, and the summary says so. - */ - val leavesIntegrationsUntouched: Boolean - get() = stationSource == WizardSource.NEW - - companion object { - - /** The categories the pickers offer, the way the Station tab builds them. */ - val CATEGORY_NUMBERS: List = ChatCategory(0).possibleCategoryNumbers.toList() - - private val CALLSIGN = Regex("[A-Za-z0-9]+([-/][A-Za-z0-9]+)?") - private val LOCATOR = Regex("[A-Ra-r]{2}[0-9]{2}[A-Xa-x]{2}") - - /** - * Whether a text can be a login callsign: letters and digits, at most one "-" or "/" - * suffix, and a base of three characters with a letter and a digit. Deliberately - * loose -- ON4KST decides what it accepts, this only catches a slip. - */ - fun isPlausibleCallsign(text: String): Boolean { - val trimmed = text.trim() - if (!CALLSIGN.matches(trimmed)) return false - val base = trimmed.substringBefore('-').substringBefore('/') - return base.length >= 3 && base.any(Char::isDigit) && base.any(Char::isLetter) - } - - /** Whether a text is a six-character Maidenhead locator, in either case. */ - fun isLocator(text: String): Boolean = LOCATOR.matches(text.trim()) - - /** - * The chat category the lowest band belongs to: 1 for 50/70 MHz, 2 for 144/432 MHz, - * 3 above. Null without a band. A suggestion only -- the operator confirms it. - */ - fun suggestCategory(bands: Set): Int? { - val lowest = bands.minOfOrNull { it.megahertz } ?: return null - return when { - lowest <= 70 -> ChatCategory.FIFTYSEVENTYMHz - lowest <= 432 -> ChatCategory.VUHF - else -> ChatCategory.MICROWAVE - } - } - } -} -``` - -- [ ] **Step 4: Run test to verify it passes** - -Run: `./gradlew :app-desktop:test --tests 'kst4contest.view.compose.wizard.SetupWizardStateTest'` -Expected: 16 Tests, 0 Fehler in `app-desktop/build/test-results/test/TEST-kst4contest.view.compose.wizard.SetupWizardStateTest.xml`. - -- [ ] **Step 5: Commit** - -```bash -git add app-desktop/src/main/kotlin/kst4contest/view/compose/wizard/SetupWizardState.kt app-desktop/src/test/kotlin/kst4contest/view/compose/wizard/SetupWizardStateTest.kt -git commit -m "Add setup wizard state and its course rules" -``` - ---- - -### Task 3: Antworten in die Profildatei schreiben - -**Files:** -- Modify: `app-desktop/src/main/kotlin/kst4contest/view/compose/wizard/SetupWizardState.kt` (Methode `writeTo` vor dem `companion object` ergänzen) -- Test: `app-desktop/src/test/kotlin/kst4contest/view/compose/wizard/SetupWizardWriteTest.kt` - -**Interfaces:** -- Consumes: `SetupWizardState` aus Task 2; Setter und `writePreferencesToXmlFile()` von `ChatPreferences`. -- Produces: `fun SetupWizardState.writeTo(prefs: ChatPreferences): Boolean` — setzt die Antworten und schreibt die Datei; `false`, wenn Pflichtangaben fehlen oder das Schreiben scheitert. Bei fehlenden Pflichtangaben wird `prefs` nicht angefasst. - -- [ ] **Step 1: Write the failing test** - -```kotlin -package kst4contest.view.compose.wizard - -import kst4contest.model.ChatCategory -import kst4contest.model.ChatPreferences -import org.junit.jupiter.api.Assertions.assertArrayEquals -import org.junit.jupiter.api.Assertions.assertEquals -import org.junit.jupiter.api.Assertions.assertFalse -import org.junit.jupiter.api.Assertions.assertTrue -import org.junit.jupiter.api.Test -import org.junit.jupiter.api.io.TempDir -import java.nio.file.Files -import java.nio.file.Path -import java.nio.file.StandardCopyOption - -/** - * What the wizard does to a real preferences file: nothing until Save, exactly the answers - * afterwards, and every setting it never asked about left as it was. - */ -class SetupWizardWriteTest(@TempDir private val directory: Path) { - - /** A copy of the bundled template, read the way the runtime reads a profile. */ - private fun templateFile(): Path { - val file = directory.resolve("preferences.xml") - ChatPreferences::class.java.getResourceAsStream(ChatPreferences.PREFERENCE_RESOURCE).use { template -> - Files.copy(requireNotNull(template), file, StandardCopyOption.REPLACE_EXISTING) - } - return file - } - - private fun read(file: Path): ChatPreferences = - ChatPreferences(file).also { assertTrue(it.readPreferencesFromXmlFile(), "reading $file failed") } - - /** A profile an operator set up: read the template, change it, write it back. */ - private fun configuredFile(change: ChatPreferences.() -> Unit = {}): Path { - val file = templateFile() - read(file).apply { - setStn_loginCallSign("DL0TEST") - setStn_loginPassword("secret") - setStn_loginNameMainCat("Philipp") - setStn_loginNameSecondCat("Philipp") - setStn_loginLocatorMainCat("JO50AA") - setStn_bandActive144(true) - setLoginChatCategoryMain(ChatCategory(2)) - setLoginToSecondChatEnabled(false) - change() - assertTrue(writePreferencesToXmlFile()) - } - return file - } - - private fun SetupWizardState.answerFirstInstallation() { - name = "Philipp" - next() - callsign = "DL0TEST" - password = "secret" - next() - locator = "JO50AA" - setBand(WizardBand.B144, true) - setBand(WizardBand.B1240, true) - finish() - } - - @Test - fun nothingIsWrittenBeforeSave() { - val file = templateFile() - val prefs = read(file) - // Taken after the read, so only the wizard is measured here. - val before = Files.readAllBytes(file) - - SetupWizardState(prefs).answerFirstInstallation() - - assertArrayEquals(before, Files.readAllBytes(file), "the file changed without Save") - assertEquals("DO5AMF", prefs.getStn_loginCallSign(), "the preferences changed without Save") - } - - @Test - fun saveWritesExactlyTheAnswers() { - val file = templateFile() - val prefs = read(file) - val state = SetupWizardState(prefs) - state.answerFirstInstallation() - - assertTrue(state.writeTo(prefs)) - - val restored = read(file) - assertEquals("DL0TEST", restored.getStn_loginCallSign()) - assertEquals("secret", restored.getStn_loginPassword()) - assertEquals("Philipp", restored.getStn_loginNameMainCat()) - assertEquals("JO50AA", restored.getStn_loginLocatorMainCat()) - assertTrue(restored.isStn_bandActive144()) - assertTrue(restored.isStn_bandActive1240()) - assertFalse(restored.isStn_bandActive432(), "a band the operator did not tick is off") - assertEquals(2, restored.getLoginChatCategoryMain().categoryNumber) - assertFalse(restored.isLoginToSecondChatEnabled(), "a new station starts without a second chat") - } - - @Test - fun whatTheWizardNeverAskedAboutIsLeftAsItWas() { - val file = templateFile() - val prefs = read(file) - val server = prefs.getStn_on4kstServersDns() - val rotatorPort = prefs.getStn_pstRotatorPort() - val udpListener = prefs.isLogsynch_ucxUDPWkdCallListenerEnabled() - val clusterServer = prefs.isNotify_dxClusterServerEnabled() - val airScout = prefs.isAirScout_asUDPListenerEnabled() - val beamWidth = prefs.getStn_antennaBeamWidthDeg() - - val state = SetupWizardState(prefs) - state.answerFirstInstallation() - assertTrue(state.writeTo(prefs)) - - val restored = read(file) - assertEquals(server, restored.getStn_on4kstServersDns()) - assertEquals(rotatorPort, restored.getStn_pstRotatorPort()) - assertEquals(udpListener, restored.isLogsynch_ucxUDPWkdCallListenerEnabled()) - assertEquals(clusterServer, restored.isNotify_dxClusterServerEnabled()) - assertEquals(airScout, restored.isAirScout_asUDPListenerEnabled()) - assertEquals(beamWidth, restored.getStn_antennaBeamWidthDeg()) - } - - @Test - fun aCallsignIsStoredAsTyped() { - val file = templateFile() - val prefs = read(file) - val state = SetupWizardState(prefs) - state.name = "Philipp" - state.next() - state.callsign = " do5amf-2 " - state.password = "secret" - state.next() - state.locator = " jo50aa " - state.setBand(WizardBand.B144, true) - - assertTrue(state.writeTo(prefs)) - - val restored = read(file) - assertEquals("do5amf-2", restored.getStn_loginCallSign(), "only the surrounding blanks go") - assertEquals("jo50aa", restored.getStn_loginLocatorMainCat(), "the Station tab stores it as typed too") - } - - @Test - fun aKeptCategoryOutsideTheSuggestionsSurvives() { - val file = configuredFile { - setLoginChatCategoryMain(ChatCategory(7)) - setLoginToSecondChatEnabled(true) - setLoginChatCategorySecond(ChatCategory(9)) - } - val prefs = read(file) - val state = SetupWizardState(prefs) - state.chooseLoginSource(WizardSource.KEEP) - state.chooseStationSource(WizardSource.KEEP) - state.next() - state.next() - - assertTrue(state.writeTo(prefs)) - - val restored = read(file) - assertEquals(7, restored.getLoginChatCategoryMain().categoryNumber) - assertTrue(restored.isLoginToSecondChatEnabled()) - assertEquals(9, restored.getLoginChatCategorySecond().categoryNumber) - } - - @Test - fun theSecondNameFollowsTheFirstUnlessItWasSetApart() { - val following = configuredFile() - val prefs = read(following) - val state = SetupWizardState(prefs) - state.chooseLoginSource(WizardSource.KEEP) - state.chooseStationSource(WizardSource.KEEP) - state.next() - state.name = "Marc" - state.next() - assertTrue(state.writeTo(prefs)) - assertEquals("Marc", read(following).getStn_loginNameSecondCat()) - - val apart = configuredFile { setStn_loginNameSecondCat("Philipp SHF") } - val apartPrefs = read(apart) - val apartState = SetupWizardState(apartPrefs) - apartState.chooseLoginSource(WizardSource.KEEP) - apartState.chooseStationSource(WizardSource.KEEP) - apartState.next() - apartState.name = "Marc" - apartState.next() - assertTrue(apartState.writeTo(apartPrefs)) - assertEquals("Philipp SHF", read(apart).getStn_loginNameSecondCat(), "a name set apart is the operator's") - } - - @Test - fun anUntouchedLanguageStaysEvenIfThisBuildDoesNotKnowIt() { - val file = configuredFile { setGuiOptions_language("fr") } - val prefs = read(file) - val state = SetupWizardState(prefs) - state.chooseLoginSource(WizardSource.KEEP) - state.chooseStationSource(WizardSource.KEEP) - state.next() - state.next() - - assertTrue(state.writeTo(prefs)) - - assertEquals("fr", read(file).getGuiOptions_language()) - } - - @Test - fun incompleteAnswersAreNotWritten() { - val file = templateFile() - val prefs = read(file) - val before = Files.readAllBytes(file) - val state = SetupWizardState(prefs) - state.name = "Philipp" - - assertFalse(state.writeTo(prefs)) - - assertArrayEquals(before, Files.readAllBytes(file)) - assertEquals("DO5AMF", prefs.getStn_loginCallSign()) - } - - @Test - fun aFailedWriteIsReported() { - val source = read(templateFile()) - // A directory where the file should be: the write cannot succeed. - val unwritable = ChatPreferences(Files.createDirectory(directory.resolve("not-a-file"))) - val state = SetupWizardState(source) - state.answerFirstInstallation() - - assertFalse(state.writeTo(unwritable), "a write that failed must not read as saved") - } -} -``` - -- [ ] **Step 2: Run test to verify it fails** - -Run: `./gradlew :app-desktop:test --tests 'kst4contest.view.compose.wizard.SetupWizardWriteTest'` -Expected: Kompilierfehler, `Unresolved reference: writeTo`. - -- [ ] **Step 3: Write minimal implementation** - -In `SetupWizardState.kt` unmittelbar vor `companion object {` einfügen: - -```kotlin - /** - * Puts the answers into [prefs] and writes its file. - * - * Everything the wizard did not ask about stays as [prefs] read it, because the whole - * file is read and written back. The callsign and the locator are stored as typed, the - * way the Station tab stores them; only surrounding blanks go. - * - * The second chat's name follows the first unless the operator had set it apart, and the - * second category is left alone while the second chat is off. - * - * @return false when a mandatory answer is missing -- nothing is touched then -- or when - * the file could not be written - */ - fun writeTo(prefs: ChatPreferences): Boolean { - if (!mandatoryComplete) return false - - val newName = name.trim() - - prefs.setGuiOptions_language(language) - prefs.setStn_loginNameMainCat(newName) - if (storedSecondName.isBlank() || storedSecondName == storedName) { - prefs.setStn_loginNameSecondCat(newName) - } - - prefs.setStn_loginCallSign(callsign.trim()) - prefs.setStn_loginPassword(password) - - prefs.setStn_loginLocatorMainCat(locator.trim()) - WizardBand.entries.forEach { it.setActive(prefs, it in bands) } - prefs.setLoginChatCategoryMain(ChatCategory(requireNotNull(category))) - prefs.setLoginToSecondChatEnabled(secondChat) - if (secondChat) { - prefs.setLoginChatCategorySecond(ChatCategory(requireNotNull(secondCategory))) - } - - // A write that throws is a write that failed; the wizard must stay open either way. - return runCatching { prefs.writePreferencesToXmlFile() }.getOrDefault(false) - } -``` - -- [ ] **Step 4: Run test to verify it passes** - -Run: `./gradlew :app-desktop:test --tests 'kst4contest.view.compose.wizard.SetupWizardWriteTest'` -Expected: 9 Tests, 0 Fehler in `app-desktop/build/test-results/test/TEST-kst4contest.view.compose.wizard.SetupWizardWriteTest.xml`. - -Schlägt `aFailedWriteIsReported` fehl, weil `writePreferencesToXmlFile` für ein Verzeichnis `true` liefert: **nicht** den Test abschwächen. Den Befund melden — dann meldet auch „Save settings" im Einstellungsfenster einen Erfolg, den es nicht gab, und das ist ein eigener Fehler in `ChatPreferences`. - -- [ ] **Step 5: Commit** - -```bash -git add app-desktop/src/main/kotlin/kst4contest/view/compose/wizard/SetupWizardState.kt app-desktop/src/test/kotlin/kst4contest/view/compose/wizard/SetupWizardWriteTest.kt -git commit -m "Write setup wizard answers to the profile's preferences file" -``` - ---- - -### Task 4: Die Seiten des Assistenten - -**Files:** -- Create: `app-desktop/src/main/kotlin/kst4contest/view/compose/wizard/SetupWizardContent.kt` -- Modify: `app-desktop/src/main/i18n/strings_en.properties`, `app-desktop/src/main/i18n/strings_de.properties` (Schlüssel am Dateiende anfügen) -- Test: `app-desktop/src/test/kotlin/kst4contest/view/compose/wizard/SetupWizardContentScreenTest.kt` - -**Interfaces:** -- Consumes: `SetupWizardState`, `WizardPage`, `WizardSource`, `WizardBand` (Task 2); `Form`, `Density`, `Kst4ContestTheme` aus `kst4contest.view.compose`; `LanguageStore`, `LocalStrings`, `Strings`, `Translations`, `SYSTEM_LANGUAGE` aus `kst4contest.view.i18n`; vorhandene Texte `stationCallsign`, `stationPassword`, `stationLocator`, `stationMainCategory`, `stationSecondCategory`, `guiLanguage`, `guiLanguageSystem`. -- Produces: - - `@Composable fun SetupWizardContent(state: SetupWizardState, languageStore: LanguageStore, saveFailed: Boolean, onLater: () -> Unit, onSave: (connect: Boolean) -> Unit)` - - `fun wizardLanguageStore(state: SetupWizardState): LanguageStore` — ein `LanguageStore`, dessen Wahl in `state.language` landet und nicht in den Einstellungen - - die Textschlüssel `wizard.*` (als `strings.wizard…` erzeugt) - -- [ ] **Step 1: Texte anlegen** - -An das Ende von `app-desktop/src/main/i18n/strings_en.properties` anfügen: - -```properties -wizard.title=Setup assistant -wizard.later=Later -wizard.back=Back -wizard.next=Next -wizard.finish=Finish -wizard.save=Save -wizard.saveAndConnect=Save and connect -wizard.change=Change -wizard.saveFailed=The settings could not be written. Nothing was changed. -wizard.missing=Some required entries are still missing. Use Change to complete them. -wizard.entry.title=Where do the entries come from? -wizard.entry.lead=Choose separately for login and station. -wizard.entry.login=Login (callsign, password) -wizard.entry.station=Station (locator, bands, chat category) -wizard.source.loginNew=Enter a new login -wizard.source.loginKeep=Leave the login unchanged ({0}) -wizard.source.stationNew=Set up a new station -wizard.source.stationKeep=Leave the station unchanged (locator {0}) -wizard.personal.title=Personal -wizard.personal.lead=Belongs to the operator. -wizard.personal.name=Name shown in the chat -wizard.login.title=ON4KST login -wizard.login.lead=The credentials of your ON4KST account. -wizard.login.callsignInvalid=This does not look like a callsign. -wizard.site.title=Location and bands -wizard.site.lead=Belongs to the station, not to the operator. -wizard.site.locatorInvalid=Six-character Maidenhead locator, for example JO50AA. -wizard.site.bands=Active bands -wizard.site.bandsHint=No frequency is derived from the bands. -wizard.site.categorySuggestion=Suggested from the bands: {0} -wizard.site.secondChat=Open a second chat -wizard.summary.title=Summary -wizard.summary.lead=Nothing is written until you save. -wizard.summary.personal=Personal -wizard.summary.login=Login -wizard.summary.station=Station -wizard.summary.bands=Bands -wizard.summary.turnedOff=Will be switched off: second chat. -wizard.summary.integrationsUnchanged=Log program, rotator, AirScout and DX cluster server keep their stored settings. Check them in the settings window. -wizard.summary.none=none -wizard.summary.passwordSet=set -``` - -An das Ende von `app-desktop/src/main/i18n/strings_de.properties` anfügen: - -```properties -wizard.title=Einrichtungsassistent -wizard.later=Später -wizard.back=Zurück -wizard.next=Weiter -wizard.finish=Fertig -wizard.save=Speichern -wizard.saveAndConnect=Speichern und verbinden -wizard.change=Ändern -wizard.saveFailed=Die Einstellungen konnten nicht geschrieben werden. Es wurde nichts geändert. -wizard.missing=Es fehlen noch Pflichtangaben. Über „Ändern" ergänzen. -wizard.entry.title=Woher kommen die Angaben? -wizard.entry.lead=Für Anmeldung und Station getrennt wählen. -wizard.entry.login=Anmeldung (Rufzeichen, Passwort) -wizard.entry.station=Station (Locator, Bänder, Chatkategorie) -wizard.source.loginNew=Anmeldung neu eingeben -wizard.source.loginKeep=Anmeldung unverändert lassen ({0}) -wizard.source.stationNew=Station neu einrichten -wizard.source.stationKeep=Station unverändert lassen (Locator {0}) -wizard.personal.title=Persönliches -wizard.personal.lead=Gehört zum Operator. -wizard.personal.name=Anzeigename im Chat -wizard.login.title=Anmeldung bei ON4KST -wizard.login.lead=Die Zugangsdaten deines ON4KST-Kontos. -wizard.login.callsignInvalid=Das sieht nicht nach einem Rufzeichen aus. -wizard.site.title=Standort und Bänder -wizard.site.lead=Gehört zur Station, nicht zum Operator. -wizard.site.locatorInvalid=Sechsstelliger Maidenhead-Locator, zum Beispiel JO50AA. -wizard.site.bands=Aktive Bänder -wizard.site.bandsHint=Aus den Bändern wird keine Frequenz abgeleitet. -wizard.site.categorySuggestion=Vorschlag aus den Bändern: {0} -wizard.site.secondChat=Zweiten Chat öffnen -wizard.summary.title=Zusammenfassung -wizard.summary.lead=Erst „Speichern" schreibt in die Einstellungsdatei. -wizard.summary.personal=Persönliches -wizard.summary.login=Anmeldung -wizard.summary.station=Station -wizard.summary.bands=Bänder -wizard.summary.turnedOff=Wird abgeschaltet: Zweitchat. -wizard.summary.integrationsUnchanged=Logprogramm, Rotor, AirScout und DX-Cluster-Server behalten ihre gespeicherten Werte. Im Einstellungsfenster prüfen. -wizard.summary.none=keine -wizard.summary.passwordSet=gesetzt -``` - -Run: `./gradlew :app-desktop:compileKotlin` -Expected: BUILD SUCCESSFUL. Ein Fehler des Erzeugers nennt den Schlüssel; er prüft doppelte Schlüssel, Waisen und die Zahl der Platzhalter. - -- [ ] **Step 2: Write the failing test** - -```kotlin -package kst4contest.view.compose.wizard - -import androidx.compose.ui.test.ComposeUiTest -import androidx.compose.ui.test.ExperimentalTestApi -import androidx.compose.ui.test.onNodeWithText -import androidx.compose.ui.test.performClick -import androidx.compose.ui.test.runComposeUiTest -import kst4contest.model.ChatCategory -import kst4contest.model.ChatPreferences -import kst4contest.view.compose.Kst4ContestTheme -import kst4contest.view.i18n.LanguageStore -import org.junit.jupiter.api.Assertions.assertEquals -import org.junit.jupiter.api.Assertions.assertTrue -import org.junit.jupiter.api.Test -import java.nio.file.Path -import java.util.Locale - -/** - * The drawn wizard, clicked the way an operator clicks it. The rules live in - * SetupWizardState and are tested there; this holds the wiring -- that a button reaches the - * state, and that a button which must not work does not. - */ -@OptIn(ExperimentalTestApi::class) -class SetupWizardContentScreenTest { - - private fun configuredProfile() = - ChatPreferences(Path.of("setup-wizard-screen-test-unused.xml")).apply { - setStn_loginCallSign("DL0TEST") - setStn_loginPassword("secret") - setStn_loginNameMainCat("Philipp") - setStn_loginLocatorMainCat("JO50AA") - setStn_bandActive144(true) - setLoginChatCategoryMain(ChatCategory(2)) - // Stated, not left to the compiled-in default: with a second chat and no second - // category the summary could not be saved. - setLoginToSecondChatEnabled(false) - } - - private class Recorded { - var later = 0 - val saves = mutableListOf() - } - - private fun ComposeUiTest.show(state: SetupWizardState, saveFailed: Boolean = false): Recorded { - val recorded = Recorded() - // English, whatever language an earlier test in this JVM left behind. - val english = LanguageStore({ "en" }, {}, Locale.ENGLISH) - setContent { - Kst4ContestTheme(darkMode = false, baseFontSizeSp = 12f) { - SetupWizardContent( - state = state, - languageStore = english, - saveFailed = saveFailed, - onLater = { recorded.later++ }, - onSave = { recorded.saves += it }, - ) - } - } - return recorded - } - - @Test - fun nextDoesNothingUntilBothSourcesAreChosen() = runComposeUiTest { - val state = SetupWizardState(configuredProfile()) - show(state) - - onNodeWithText("Next").performClick() - assertEquals(WizardPage.ENTRY, state.page, "Next worked without a choice") - - onNodeWithText("Leave the login unchanged (DL0TEST)").performClick() - onNodeWithText("Leave the station unchanged (locator JO50AA)").performClick() - assertEquals(WizardSource.KEEP, state.loginSource) - assertEquals(WizardSource.KEEP, state.stationSource) - - onNodeWithText("Next").performClick() - assertEquals(WizardPage.PERSONAL, state.page) - } - - @Test - fun laterIsReportedAndNothingElse() = runComposeUiTest { - val recorded = show(SetupWizardState(configuredProfile())) - - onNodeWithText("Later").performClick() - - assertEquals(1, recorded.later) - assertTrue(recorded.saves.isEmpty()) - } - - @Test - fun theSummaryOffersBothWaysOfSaving() = runComposeUiTest { - val state = SetupWizardState(configuredProfile()) - state.chooseLoginSource(WizardSource.KEEP) - state.chooseStationSource(WizardSource.KEEP) - state.next() - state.next() - val recorded = show(state) - - onNodeWithText("Save").performClick() - onNodeWithText("Save and connect").performClick() - - assertEquals(listOf(false, true), recorded.saves) - } - - @Test - fun aFailedSaveIsToldToTheOperator() = runComposeUiTest { - val state = SetupWizardState(configuredProfile()) - state.chooseLoginSource(WizardSource.KEEP) - state.chooseStationSource(WizardSource.KEEP) - state.next() - state.next() - show(state, saveFailed = true) - - onNodeWithText("The settings could not be written. Nothing was changed.").assertExists() - } -} -``` - -- [ ] **Step 3: Run test to verify it fails** - -Run: `./gradlew :app-desktop:test --tests 'kst4contest.view.compose.wizard.SetupWizardContentScreenTest'` -Expected: Kompilierfehler, `Unresolved reference: SetupWizardContent`. - -- [ ] **Step 4: Write minimal implementation** - -```kotlin -package kst4contest.view.compose.wizard - -import androidx.compose.foundation.layout.Arrangement -import androidx.compose.foundation.layout.Column -import androidx.compose.foundation.layout.Row -import androidx.compose.foundation.layout.Spacer -import androidx.compose.foundation.layout.fillMaxSize -import androidx.compose.foundation.layout.fillMaxWidth -import androidx.compose.foundation.layout.padding -import androidx.compose.foundation.rememberScrollState -import androidx.compose.foundation.selection.selectable -import androidx.compose.foundation.verticalScroll -import androidx.compose.material3.MaterialTheme -import androidx.compose.material3.RadioButton -import androidx.compose.material3.Surface -import androidx.compose.material3.Text -import androidx.compose.runtime.Composable -import androidx.compose.runtime.CompositionLocalProvider -import androidx.compose.ui.Alignment -import androidx.compose.ui.Modifier -import androidx.compose.ui.semantics.Role -import androidx.compose.ui.unit.dp -import kst4contest.model.ChatCategory -import kst4contest.view.compose.Density -import kst4contest.view.compose.Form -import kst4contest.view.i18n.LanguageStore -import kst4contest.view.i18n.LocalStrings -import kst4contest.view.i18n.SYSTEM_LANGUAGE -import kst4contest.view.i18n.Strings -import kst4contest.view.i18n.Translations - -/** - * A language store for the wizard: a choice takes effect on screen at once and is kept in - * the wizard's answers, not in the preferences. "Later" therefore stores no language, and - * the runtime built afterwards puts the stored one back in force. - */ -fun wizardLanguageStore(state: SetupWizardState): LanguageStore = - LanguageStore(storedLanguage = { state.language }, storeLanguage = { state.language = it }) - -/** The name a chat category carries in the pickers, the one the Station tab shows. */ -private fun categoryName(number: Int): String = ChatCategory(number).getChatCategoryName(number) - -/** - * The wizard's pages and its button row. - * - * All decisions are in [state]; this draws them. The texts are read from [languageStore] in - * the composition, so the language picker on the first page switches the wizard itself. - * - * @param saveFailed whether the last Save could not write the file - * @param onLater the operator does not want to set up now; nothing is written - * @param onSave the operator saves; true when the session should be started afterwards - */ -@Composable -fun SetupWizardContent( - state: SetupWizardState, - languageStore: LanguageStore, - saveFailed: Boolean, - onLater: () -> Unit, - onSave: (connect: Boolean) -> Unit, -) { - val strings = languageStore.strings - - CompositionLocalProvider(LocalStrings provides strings) { - Surface(modifier = Modifier.fillMaxSize()) { - Column(modifier = Modifier.padding(15.dp)) { - Column( - modifier = Modifier.weight(1f).fillMaxWidth().verticalScroll(rememberScrollState()), - verticalArrangement = Arrangement.spacedBy(6.dp), - ) { - when (state.page) { - WizardPage.ENTRY -> EntryPage(state, strings) - WizardPage.PERSONAL -> PersonalPage(state, strings, languageStore) - WizardPage.LOGIN -> LoginPage(state, strings) - WizardPage.SITE -> SitePage(state, strings) - WizardPage.SUMMARY -> SummaryPage(state, strings, saveFailed) - } - } - - Row( - modifier = Modifier.fillMaxWidth().padding(top = 10.dp), - horizontalArrangement = Arrangement.spacedBy(Density.BUTTON_GAP), - ) { - Form.button(strings.wizardLater, onClick = onLater) - Spacer(Modifier.weight(1f)) - if (state.canGoBack) { - Form.button(strings.wizardBack, onClick = state::back) - } - if (state.page == WizardPage.SUMMARY) { - Form.button(strings.wizardSave, enabled = state.mandatoryComplete) { onSave(false) } - Form.button( - strings.wizardSaveAndConnect, - enabled = state.mandatoryComplete, - accented = true, - ) { onSave(true) } - } else { - if (state.canFinish) { - Form.button(strings.wizardFinish, onClick = state::finish) - } - Form.button( - strings.wizardNext, - enabled = state.canGoNext, - accented = true, - onClick = state::next, - ) - } - } - } - } - } -} - -@Composable -private fun Heading(title: String, lead: String) { - Text(title, style = MaterialTheme.typography.titleMedium) - Text(lead, style = MaterialTheme.typography.bodySmall) -} - -@Composable -private fun Refusal(text: String) { - Text(text, color = MaterialTheme.colorScheme.error, style = MaterialTheme.typography.bodySmall) -} - -@Composable -private fun SourceOption(label: String, selected: Boolean, onSelect: () -> Unit) { - Row( - modifier = Modifier - .fillMaxWidth() - .selectable(selected = selected, role = Role.RadioButton, onClick = onSelect) - .padding(vertical = 2.dp), - verticalAlignment = Alignment.CenterVertically, - ) { - RadioButton(selected = selected, onClick = null) - Text(label, modifier = Modifier.padding(start = 6.dp)) - } -} - -@Composable -private fun EntryPage(state: SetupWizardState, strings: Strings) { - Heading(strings.wizardEntryTitle, strings.wizardEntryLead) - - /* An axis with a single option is decided already and is not asked about. */ - if (state.loginSources.size > 1) { - Form.section(strings.wizardEntryLogin) { - state.loginSources.forEach { source -> - SourceOption( - label = when (source) { - WizardSource.NEW -> strings.wizardSourceLoginNew - WizardSource.KEEP -> strings.wizardSourceLoginKeep(state.storedCallsign) - }, - selected = state.loginSource == source, - onSelect = { state.chooseLoginSource(source) }, - ) - } - } - } - - if (state.stationSources.size > 1) { - Form.section(strings.wizardEntryStation) { - state.stationSources.forEach { source -> - SourceOption( - label = when (source) { - WizardSource.NEW -> strings.wizardSourceStationNew - WizardSource.KEEP -> strings.wizardSourceStationKeep(state.storedLocator) - }, - selected = state.stationSource == source, - onSelect = { state.chooseStationSource(source) }, - ) - } - } - } -} - -@Composable -private fun PersonalPage(state: SetupWizardState, strings: Strings, languageStore: LanguageStore) { - Heading(strings.wizardPersonalTitle, strings.wizardPersonalLead) - - Form.choice( - label = strings.guiLanguage, - items = listOf(SYSTEM_LANGUAGE) + Translations.BY_LANGUAGE.keys.sorted(), - selected = languageStore.stored, - // The code in capitals, as the GUI tab shows it. - describe = { code -> if (code == SYSTEM_LANGUAGE) strings.guiLanguageSystem else code.uppercase() }, - onSelect = { languageStore.use(it) }, - ) - Form.text(strings.wizardPersonalName, state.name) { state.name = it } -} - -@Composable -private fun LoginPage(state: SetupWizardState, strings: Strings) { - Heading(strings.wizardLoginTitle, strings.wizardLoginLead) - - Form.text(strings.stationCallsign, state.callsign) { state.callsign = it } - if (state.callsignRefused) Refusal(strings.wizardLoginCallsignInvalid) - Form.password(strings.stationPassword, state.password) { state.password = it } -} - -@Composable -private fun SitePage(state: SetupWizardState, strings: Strings) { - Heading(strings.wizardSiteTitle, strings.wizardSiteLead) - - Form.text(strings.stationLocator, state.locator) { state.locator = it } - if (state.locatorRefused) Refusal(strings.wizardSiteLocatorInvalid) - - Form.flowingSection(strings.wizardSiteBands) { - WizardBand.entries.forEach { band -> - Form.check(band.label, band in state.bands) { state.setBand(band, it) } - } - } - Text(strings.wizardSiteBandsHint, style = MaterialTheme.typography.bodySmall) - - Form.choice( - label = strings.stationMainCategory, - items = SetupWizardState.CATEGORY_NUMBERS, - selected = state.category, - describe = ::categoryName, - onSelect = state::chooseCategory, - ) - state.suggestedCategory?.let { suggested -> - Text( - strings.wizardSiteCategorySuggestion(categoryName(suggested)), - style = MaterialTheme.typography.bodySmall, - ) - } - - Form.check(strings.wizardSiteSecondChat, state.secondChat) { state.chooseSecondChat(it) } - if (state.secondChat) { - Form.choice( - label = strings.stationSecondCategory, - items = state.secondCategoryOptions, - selected = state.secondCategory, - describe = ::categoryName, - onSelect = { state.secondCategory = it }, - ) - } -} - -@Composable -private fun SummaryRow(label: String, value: String) { - Form.labelledRow(label) { Text(value) } -} - -@Composable -private fun SummaryPage(state: SetupWizardState, strings: Strings, saveFailed: Boolean) { - Heading(strings.wizardSummaryTitle, strings.wizardSummaryLead) - - if (saveFailed) Refusal(strings.wizardSaveFailed) - if (!state.mandatoryComplete) Refusal(strings.wizardMissing) - if (state.turnsOffSecondChat) Text(strings.wizardSummaryTurnedOff) - if (state.leavesIntegrationsUntouched) Text(strings.wizardSummaryIntegrationsUnchanged) - - Form.section(strings.wizardSummaryPersonal) { - SummaryRow(strings.wizardPersonalName, state.name.ifBlank { strings.wizardSummaryNone }) - Form.button(strings.wizardChange) { state.edit(WizardPage.PERSONAL) } - } - - Form.section(strings.wizardSummaryLogin) { - SummaryRow(strings.stationCallsign, state.callsign.ifBlank { strings.wizardSummaryNone }) - // Never the password itself: the summary may be read over a shoulder. - SummaryRow( - strings.stationPassword, - if (state.password.isEmpty()) strings.wizardSummaryNone else strings.wizardSummaryPasswordSet, - ) - Form.button(strings.wizardChange) { state.edit(WizardPage.LOGIN) } - } - - Form.section(strings.wizardSummaryStation) { - SummaryRow(strings.stationLocator, state.locator.ifBlank { strings.wizardSummaryNone }) - SummaryRow( - strings.wizardSummaryBands, - WizardBand.entries.filter { it in state.bands }.joinToString(", ") { it.label } - .ifEmpty { strings.wizardSummaryNone }, - ) - SummaryRow( - strings.stationMainCategory, - state.category?.let(::categoryName) ?: strings.wizardSummaryNone, - ) - SummaryRow( - strings.stationSecondCategory, - state.secondCategory?.takeIf { state.secondChat }?.let(::categoryName) ?: strings.wizardSummaryNone, - ) - Form.button(strings.wizardChange) { state.edit(WizardPage.SITE) } - } -} -``` - -- [ ] **Step 5: Run test to verify it passes** - -Run: `./gradlew :app-desktop:test --tests 'kst4contest.view.compose.wizard.SetupWizardContentScreenTest'` -Expected: 4 Tests, 0 Fehler. - -Meldet der Übersetzer, dass `Density.BUTTON_GAP` oder `Form.labelledRow` nicht sichtbar ist: beide werden in `OperatorProfilePickerWindow.kt` bzw. `FormControls.kt` im Paket `kst4contest.view.compose` benutzt. Ist eines davon `internal`, bleibt es das — der Assistent liegt im selben Modul. - -- [ ] **Step 6: Die Sprachtests laufen lassen** - -Run: `./gradlew :app-desktop:test --tests 'kst4contest.view.i18n.*'` -Expected: alle grün. `TranslationBoundaryTest` hält Deutsch vollständig; ein fehlender deutscher Schlüssel fällt hier auf. - -- [ ] **Step 7: Commit** - -```bash -git add app-desktop/src/main/kotlin/kst4contest/view/compose/wizard/SetupWizardContent.kt app-desktop/src/main/i18n/strings_en.properties app-desktop/src/main/i18n/strings_de.properties app-desktop/src/test/kotlin/kst4contest/view/compose/wizard/SetupWizardContentScreenTest.kt -git commit -m "Draw the setup wizard pages" -``` - ---- - -### Task 5: Fenster und Starter - -**Files:** -- Create: `app-desktop/src/main/kotlin/kst4contest/view/compose/wizard/SetupWizardWindow.kt` -- Test: `app-desktop/src/test/kotlin/kst4contest/view/compose/wizard/SetupWizardLauncherTest.kt` -- Test: `app-desktop/src/test/kotlin/kst4contest/view/compose/wizard/SetupWizardWindowTest.kt` - -**Interfaces:** -- Consumes: `SetupWizardState`, `writeTo` (Task 2, 3); `SetupWizardContent`, `wizardLanguageStore` (Task 4); `LoginConfiguration.isUnconfigured` (Task 1); `openOnEventThread`, `Kst4ContestTheme`, `WindowPlacementOnScreen.centreOnMainWindowScreen` aus `kst4contest.view.compose`; Testhelfer `kst4contest.testing.Await.awaitUntil`. -- Produces: - - `enum class SetupWizardOutcome { NOT_SHOWN, LATER, SAVED, SAVED_AND_CONNECT }` - - `object SetupWizardWindow { fun show(state: SetupWizardState, prefs: ChatPreferences): SetupWizardOutcome }` — blockiert, bis das Fenster zu ist - - `object SetupWizardLauncher` mit - - `@JvmStatic fun runIfNeeded(preferencesRelativeFileName: String, forced: Boolean): SetupWizardOutcome` - - `internal fun run(prefs: ChatPreferences, forced: Boolean, show: (SetupWizardState, ChatPreferences) -> SetupWizardOutcome): SetupWizardOutcome` - - `internal fun saveFromWizard(state: SetupWizardState, prefs: ChatPreferences, connect: Boolean): SetupWizardOutcome?` — `null`, wenn das Schreiben scheiterte - -- [ ] **Step 1: Write the failing tests** - -`SetupWizardLauncherTest.kt`: - -```kotlin -package kst4contest.view.compose.wizard - -import kst4contest.model.ChatPreferences -import org.junit.jupiter.api.Assertions.assertArrayEquals -import org.junit.jupiter.api.Assertions.assertEquals -import org.junit.jupiter.api.Assertions.assertNull -import org.junit.jupiter.api.Assertions.assertTrue -import org.junit.jupiter.api.Test -import org.junit.jupiter.api.io.TempDir -import java.nio.file.Files -import java.nio.file.Path -import java.nio.file.StandardCopyOption - -/** When the wizard opens at all, decided without a window. */ -class SetupWizardLauncherTest(@TempDir private val directory: Path) { - - private fun templateFile(): Path { - val file = directory.resolve("preferences.xml") - ChatPreferences::class.java.getResourceAsStream(ChatPreferences.PREFERENCE_RESOURCE).use { template -> - Files.copy(requireNotNull(template), file, StandardCopyOption.REPLACE_EXISTING) - } - return file - } - - private fun configuredFile(): Path { - val file = templateFile() - ChatPreferences(file).apply { - assertTrue(readPreferencesFromXmlFile()) - setStn_loginCallSign("DL0TEST") - setStn_loginPassword("secret") - assertTrue(writePreferencesToXmlFile()) - } - return file - } - - private val neverShown: (SetupWizardState, ChatPreferences) -> SetupWizardOutcome = - { _, _ -> throw AssertionError("the wizard must not open here") } - - @Test - fun anUnconfiguredProfileOpensTheWizard() { - var shown = 0 - - val outcome = SetupWizardLauncher.run(ChatPreferences(templateFile()), forced = false) { _, _ -> - shown++ - SetupWizardOutcome.LATER - } - - assertEquals(1, shown) - assertEquals(SetupWizardOutcome.LATER, outcome) - } - - @Test - fun aConfiguredProfileStartsWithoutTheWizard() { - assertEquals( - SetupWizardOutcome.NOT_SHOWN, - SetupWizardLauncher.run(ChatPreferences(configuredFile()), forced = false, neverShown), - ) - } - - @Test - fun theMenuOpensItOnAConfiguredProfileToo() { - val outcome = SetupWizardLauncher.run(ChatPreferences(configuredFile()), forced = true) { state, _ -> - assertEquals(listOf(WizardSource.NEW, WizardSource.KEEP), state.loginSources) - SetupWizardOutcome.SAVED - } - - assertEquals(SetupWizardOutcome.SAVED, outcome) - } - - @Test - fun anUnreadableFileNeverOpensTheWizard() { - val garbage = directory.resolve("broken.xml") - Files.writeString(garbage, "this is not xml <<<") - val before = Files.readAllBytes(garbage) - - // Forced as well: a wizard over a file it could not read would save over it. - assertEquals( - SetupWizardOutcome.NOT_SHOWN, - SetupWizardLauncher.run(ChatPreferences(garbage), forced = true, neverShown), - ) - assertArrayEquals(before, Files.readAllBytes(garbage), "the unreadable file was touched") - } - - @Test - fun aFailedSaveKeepsTheWizardOpen() { - val source = ChatPreferences(templateFile()).apply { assertTrue(readPreferencesFromXmlFile()) } - val state = SetupWizardState(source).apply { - name = "Philipp" - next() - callsign = "DL0TEST" - password = "secret" - next() - locator = "JO50AA" - setBand(WizardBand.B144, true) - } - val unwritable = ChatPreferences(Files.createDirectory(directory.resolve("not-a-file"))) - - assertNull(saveFromWizard(state, unwritable, connect = true), "a failed write must not close the wizard") - } - - @Test - fun aSaveReportsWhetherToConnect() { - val file = templateFile() - val prefs = ChatPreferences(file).apply { assertTrue(readPreferencesFromXmlFile()) } - val state = SetupWizardState(prefs).apply { - name = "Philipp" - next() - callsign = "DL0TEST" - password = "secret" - next() - locator = "JO50AA" - setBand(WizardBand.B144, true) - } - - assertEquals(SetupWizardOutcome.SAVED, saveFromWizard(state, prefs, connect = false)) - assertEquals(SetupWizardOutcome.SAVED_AND_CONNECT, saveFromWizard(state, prefs, connect = true)) - } -} -``` - -`SetupWizardWindowTest.kt`: - -```kotlin -package kst4contest.view.compose.wizard - -import kst4contest.model.ChatPreferences -import kst4contest.testing.Await.awaitUntil -import org.junit.jupiter.api.Assertions.assertEquals -import org.junit.jupiter.api.Assumptions.assumeFalse -import org.junit.jupiter.api.Test -import java.awt.EventQueue -import java.awt.GraphicsEnvironment -import java.awt.Window -import java.nio.file.Path -import java.time.Duration -import java.util.concurrent.Executors -import java.util.concurrent.Future -import java.util.concurrent.TimeUnit - -/** - * The wizard's dialog must open from both threads that open it: `main` at startup, and the - * event thread when the menu rebuilds the runtime. A latch-based wait deadlocked the profile - * picker in exactly the second case; see OperatorProfilePickerWindow. - */ -class SetupWizardWindowTest { - - private fun prefs() = ChatPreferences(Path.of("setup-wizard-window-test-unused.xml")) - - private fun showingDialog(): Window? = - Window.getWindows().firstOrNull { it.isShowing && it.javaClass.name.contains("ComposeDialog") } - - private val closer = Executors.newSingleThreadExecutor() - - /** Closes the dialog the way its X does, as soon as it is on screen. */ - private fun disposeOnceShowing(): Future<*> = - closer.submit { - awaitUntil(Duration.ofSeconds(10), "the wizard's dialog never appeared") { - showingDialog() != null - } - EventQueue.invokeLater { showingDialog()?.dispose() } - } - - @Test - fun closingTheWindowCountsAsLater() { - assumeFalse(GraphicsEnvironment.isHeadless(), "needs a display") - - try { - val closing = disposeOnceShowing() - val prefs = prefs() - - val outcome = SetupWizardWindow.show(SetupWizardState(prefs), prefs) - - assertEquals(SetupWizardOutcome.LATER, outcome) - assertEquals("", prefs.getStn_loginCallSign(), "closing the window wrote something") - closing.get(1, TimeUnit.SECONDS) - } finally { - closer.shutdownNow() - } - } - - @Test - fun opensAndReturnsWhenCalledOnTheEventThread() { - assumeFalse(GraphicsEnvironment.isHeadless(), "needs a display") - - val worker = Executors.newSingleThreadExecutor() - try { - val closing = disposeOnceShowing() - val prefs = prefs() - val call = worker.submit { - EventQueue.invokeAndWait { SetupWizardWindow.show(SetupWizardState(prefs), prefs) } - } - - // A deadlock here has no timeout of its own: without one this never completes. - call.get(20, TimeUnit.SECONDS) - closing.get(1, TimeUnit.SECONDS) - } finally { - worker.shutdownNow() - closer.shutdownNow() - } - } -} -``` - -- [ ] **Step 2: Run tests to verify they fail** - -Run: `./gradlew :app-desktop:test --tests 'kst4contest.view.compose.wizard.SetupWizardLauncherTest' --tests 'kst4contest.view.compose.wizard.SetupWizardWindowTest'` -Expected: Kompilierfehler, `Unresolved reference: SetupWizardLauncher`. - -- [ ] **Step 3: Write minimal implementation** - -```kotlin -package kst4contest.view.compose.wizard - -import androidx.compose.runtime.getValue -import androidx.compose.runtime.mutableStateOf -import androidx.compose.runtime.setValue -import androidx.compose.ui.awt.ComposeDialog -import kst4contest.controller.LoginConfiguration -import kst4contest.model.ChatPreferences -import kst4contest.view.compose.Kst4ContestTheme -import kst4contest.view.compose.WindowPlacementOnScreen -import kst4contest.view.compose.openOnEventThread -import java.awt.Dialog -import java.awt.Dimension -import java.util.concurrent.atomic.AtomicReference -import javax.swing.WindowConstants - -/** How a run of the setup wizard ended. */ -enum class SetupWizardOutcome { - /** The profile is set up, or its file could not be read: the wizard did not open. */ - NOT_SHOWN, - - /** Closed without saving; the file is as it was. */ - LATER, - - /** The answers are in the file. */ - SAVED, - - /** The answers are in the file and the operator wants the session started. */ - SAVED_AND_CONNECT, -} - -/** - * Writes the answers and says how the wizard ends. - * - * @return the outcome to close with, or null when the file could not be written -- the - * wizard then stays open, because "saved" would be a lie - */ -internal fun saveFromWizard( - state: SetupWizardState, - prefs: ChatPreferences, - connect: Boolean, -): SetupWizardOutcome? = - when { - !state.writeTo(prefs) -> null - connect -> SetupWizardOutcome.SAVED_AND_CONNECT - else -> SetupWizardOutcome.SAVED - } - -/** - * The setup wizard's window. - * - * A modal [ComposeDialog] opened through [openOnEventThread], the construction - * OperatorProfilePickerWindow uses and for the reason given there: a wait that does not - * pump events deadlocks once the caller is the event thread, and this one is called from - * `main` at startup and from the event thread when the menu rebuilds the runtime. - */ -object SetupWizardWindow { - - /** Runs before a profile's runtime exists, so there is no configured size to read. */ - private const val DIALOG_FONT_SIZE_SP = 12f - - private val DIALOG_SIZE = Dimension(640, 620) - - /** - * Opens the wizard and blocks until it is closed. - * - * @param prefs the profile's preferences; written only by Save - * @return never [SetupWizardOutcome.NOT_SHOWN] - */ - fun show(state: SetupWizardState, prefs: ChatPreferences): SetupWizardOutcome { - /* The window's X leaves this untouched: closing is "later". */ - val outcome = AtomicReference(SetupWizardOutcome.LATER) - - openOnEventThread { open(state, prefs, outcome) } - - return outcome.get() - } - - private fun open( - state: SetupWizardState, - prefs: ChatPreferences, - outcome: AtomicReference, - ) { - val languageStore = wizardLanguageStore(state) - var saveFailed by mutableStateOf(false) - - val dialog = ComposeDialog(owner = null, modalityType = Dialog.ModalityType.APPLICATION_MODAL) - dialog.title = languageStore.strings.wizardTitle - dialog.size = DIALOG_SIZE - WindowPlacementOnScreen.centreOnMainWindowScreen(dialog) - /* Disposed and not hidden: a hidden dialog keeps its window and Skia layer alive. */ - dialog.defaultCloseOperation = WindowConstants.DISPOSE_ON_CLOSE - - dialog.setContent { - Kst4ContestTheme( - darkMode = prefs.isGUI_darkModeActiveByDefault(), - baseFontSizeSp = DIALOG_FONT_SIZE_SP, - ) { - SetupWizardContent( - state = state, - languageStore = languageStore, - saveFailed = saveFailed, - onLater = { dialog.dispose() }, - onSave = { connect -> - val saved = saveFromWizard(state, prefs, connect) - if (saved == null) { - saveFailed = true - } else { - outcome.set(saved) - dialog.dispose() - } - }, - ) - } - } - - dialog.isVisible = true - } -} - -/** Decides whether the wizard opens for a profile, and opens it. */ -object SetupWizardLauncher { - - /** - * Opens the wizard when the profile needs it, before the profile's runtime is built. - * - * @param preferencesRelativeFileName the profile's preferences file below the - * application directory; a missing one is seeded from the bundled template, as - * the runtime itself would do - * @param forced the operator asked for the wizard from the menu - */ - @JvmStatic - fun runIfNeeded(preferencesRelativeFileName: String, forced: Boolean): SetupWizardOutcome = - run(ChatPreferences(preferencesRelativeFileName), forced, SetupWizardWindow::show) - - /** - * @param prefs bound to the profile's file and not read yet - * @param show opens the window; replaced in the tests - */ - internal fun run( - prefs: ChatPreferences, - forced: Boolean, - show: (SetupWizardState, ChatPreferences) -> SetupWizardOutcome, - ): SetupWizardOutcome { - /* - * A file that cannot be read is not a profile to set up: the wizard would start from - * compiled-in defaults and Save would write them over whatever the file holds. The - * runtime deals with such a file as it always did. - */ - if (!prefs.readPreferencesFromXmlFile()) return SetupWizardOutcome.NOT_SHOWN - - if (!forced && !LoginConfiguration.isUnconfigured(prefs)) return SetupWizardOutcome.NOT_SHOWN - - return show(SetupWizardState(prefs), prefs) - } -} -``` - -- [ ] **Step 4: Run tests to verify they pass** - -Run: `./gradlew :app-desktop:test --tests 'kst4contest.view.compose.wizard.*'` -Expected: alle Tests der vier Klassen grün; `SetupWizardWindowTest` läuft nur mit Bildschirm und wird sonst übersprungen (`skipped` in der XML, kein Fehler). - -Liefert `readPreferencesFromXmlFile` für die kaputte Datei `true`: den Test nicht abschwächen, den Befund melden. Dann liest `ChatPreferences` Müll als gültig, und das betrifft auch den normalen Start. - -- [ ] **Step 5: Commit** - -```bash -git add app-desktop/src/main/kotlin/kst4contest/view/compose/wizard/SetupWizardWindow.kt app-desktop/src/test/kotlin/kst4contest/view/compose/wizard/SetupWizardLauncherTest.kt app-desktop/src/test/kotlin/kst4contest/view/compose/wizard/SetupWizardWindowTest.kt -git commit -m "Open the setup wizard as a modal dialog" -``` - ---- - -### Task 6: Der Assistent im Programmstart - -**Files:** -- Modify: `app-desktop/src/main/java/kst4contest/view/ApplicationRuntimeLauncher.java` -- Modify: `app-desktop/src/main/java/kst4contest/view/Kst4ContestApplication.java` (Methode `startRuntime`, ab Zeile 2174) -- Test: `app-desktop/src/test/java/kst4contest/view/ApplicationRuntimeLauncherSetupWizardTest.java` - -**Interfaces:** -- Consumes: `SetupWizardLauncher.runIfNeeded(String, boolean)`, `SetupWizardOutcome` (Task 5); `ActiveOperatorProfile.get().getPreferencesRelativeFileName()`; `Kst4ContestApplication.menuActionConnect()`. -- Produces: - - `static void ApplicationRuntimeLauncher.requestSetupWizard()` (paketsichtbar) - - `static boolean ApplicationRuntimeLauncher.consumeSetupWizardRequest()` (paketsichtbar) — liefert den Wunsch genau einmal - -- [ ] **Step 1: Write the failing test** - -```java -package kst4contest.view; - -import org.junit.jupiter.api.Test; - -import static org.junit.jupiter.api.Assertions.assertFalse; -import static org.junit.jupiter.api.Assertions.assertTrue; - -/** - * The request to show the setup wizard on the next runtime start is honoured exactly once. - * A request that stuck would open the wizard on every later profile switch. - */ -class ApplicationRuntimeLauncherSetupWizardTest { - - @Test - void aRequestIsHonouredOnce() { - assertFalse(ApplicationRuntimeLauncher.consumeSetupWizardRequest(), "nothing was requested"); - - ApplicationRuntimeLauncher.requestSetupWizard(); - - assertTrue(ApplicationRuntimeLauncher.consumeSetupWizardRequest()); - assertFalse(ApplicationRuntimeLauncher.consumeSetupWizardRequest(), "the request must not stick"); - } -} -``` - -- [ ] **Step 2: Run test to verify it fails** - -Run: `./gradlew :app-desktop:test --tests 'kst4contest.view.ApplicationRuntimeLauncherSetupWizardTest'` -Expected: Kompilierfehler, `cannot find symbol ... consumeSetupWizardRequest`. - -- [ ] **Step 3: Den Wunsch in `ApplicationRuntimeLauncher` anlegen** - -Nach dem Feld `private static Kst4ContestApplication currentRuntime;` einfügen: - -```java - /** - * Whether the next runtime start shows the setup wizard although the profile is set up. - * Set by the menu entry and cleared by the start that honours it. - */ - private static final java.util.concurrent.atomic.AtomicBoolean SETUP_WIZARD_REQUESTED = - new java.util.concurrent.atomic.AtomicBoolean(false); -``` - -Vor `public static boolean switchProfile(` einfügen: - -```java - /** Asks the next runtime start to show the setup wizard. */ - static void requestSetupWizard() { - SETUP_WIZARD_REQUESTED.set(true); - } - - /** - * Tells a starting runtime whether the wizard was asked for, and forgets the request. - * - * @return true exactly once per request - */ - static boolean consumeSetupWizardRequest() { - return SETUP_WIZARD_REQUESTED.getAndSet(false); - } -``` - -- [ ] **Step 4: Run test to verify it passes** - -Run: `./gradlew :app-desktop:test --tests 'kst4contest.view.ApplicationRuntimeLauncherSetupWizardTest'` -Expected: 1 Test, 0 Fehler. - -- [ ] **Step 5: Den Assistenten in `startRuntime` aufrufen** - -In `Kst4ContestApplication.java` die Importe ergänzen: - -```java -import kst4contest.view.compose.wizard.SetupWizardLauncher; -import kst4contest.view.compose.wizard.SetupWizardOutcome; -``` - -In `startRuntime` den Anfang ersetzen. Alt: - -```java - if (!resolveOperatorProfileIfRequired()) { - return; - } - - ApplicationRuntimeLauncher.setCurrent(this); -``` - -Neu: - -```java - if (!resolveOperatorProfileIfRequired()) { - return; - } - - /* - * The setup wizard, before anything of this profile's runtime exists. It writes - * preferences.xml and the ChatController built below reads it like any stored - * setting, so there is no running session to bring up to date and no reload. - * Blocks until the wizard is closed; see SetupWizardWindow for why that is safe on - * either thread this method is called from. - */ - SetupWizardOutcome setupWizardOutcome = SetupWizardLauncher.runIfNeeded( - ActiveOperatorProfile.get().getPreferencesRelativeFileName(), - ApplicationRuntimeLauncher.consumeSetupWizardRequest()); - - ApplicationRuntimeLauncher.setCurrent(this); -``` - -Am Ende von `startRuntime`, unmittelbar vor dem Kommentar `Replaces Application.stop()` und dem `Runtime.getRuntime().addShutdownHook(`, einfügen: - -```java - /* - * "Save and connect" in the setup wizard. Here and not earlier: connecting needs the - * runtime this method has just finished building. The same path as File -> Connect, - * so a refused or failed connection is reported the way it is there. - */ - if (setupWizardOutcome == SetupWizardOutcome.SAVED_AND_CONNECT) { - uiDispatcher.runOnUi(this::menuActionConnect); - } - -``` - -Die Spec nennt hier `connectFromSettings`. `menuActionConnect` ruft dasselbe `chatcontroller.execute()` und zeigt einen Fehlschlag selbst an; `connectFromSettings` gibt nur einen Text zurück, den das Einstellungsfenster anzeigt, und das ist zu diesem Zeitpunkt nicht der Aufrufer. - -- [ ] **Step 6: Bauen und die berührten Tests laufen lassen** - -Run: `./gradlew :app-desktop:compileJava :app-desktop:test --tests 'kst4contest.view.*'` -Expected: BUILD SUCCESSFUL; in `app-desktop/build/test-results/test/` kein `The running runtime is torn down first and the wizard shown afterwards, not the - * other way round: a runtime shutting down flushes its pending layout write, and that - * must not land on the file the wizard has just written.

- * - * @return true if the new runtime was built - */ - public static boolean rerunSetupWizard() { - OperatorProfileSelection active = ActiveOperatorProfile.get(); - - if (active == null) { - return false; - } - - requestSetupWizard(); - return switchProfile(active.getProfile()); - } -``` - -und die Importe ergänzen, soweit sie fehlen: - -```java -import kst4contest.controller.ActiveOperatorProfile; -import kst4contest.model.OperatorProfileSelection; -``` - -- [ ] **Step 6: Menüaktion in `Kst4ContestApplication`** - -Nach der Methode `menuActionToggleSettingsWindow()` einfügen: - -```java - /** - * Options -> setup assistant. Rebuilds the runtime of the active profile with the wizard - * in front of it, which costs the running session; hence the question, and hence the - * settings edits are settled first, as before a profile switch. - */ - void menuActionOpenSetupWizard() { - SettingsWindow.settleThen(() -> { - boolean confirmed = ComposeAlert.confirm( - kst4contest.view.i18n.CurrentStrings.get().getAlertSetupWizardTitle(), - kst4contest.view.i18n.CurrentStrings.get().getAlertSetupWizardQuestion(), - kst4contest.view.i18n.CurrentStrings.get().getAlertSetupWizardBody(), - kst4contest.view.i18n.CurrentStrings.get().getDialogStartSetupWizard(), - kst4contest.view.i18n.CurrentStrings.get().getDialogCancel(), - chatcontroller.getChatPreferences().isGUI_darkModeActive()); - - if (confirmed) { - ApplicationRuntimeLauncher.rerunSetupWizard(); - } - }); - } -``` - -- [ ] **Step 7: Run tests to verify they pass** - -Run: `./gradlew :app-desktop:test --tests 'kst4contest.view.compose.MainMenuModelTest' --tests 'kst4contest.view.compose.MainMenuRowScreenTest' --tests 'kst4contest.view.i18n.*'` -Expected: alle grün. - -- [ ] **Step 8: Von Hand prüfen** - -1. `./gradlew :app-desktop:run`, mit dem eigenen Profil verbinden. -2. Im Einstellungsfenster einen Wert ändern, **nicht** übernehmen. „Options → Setup assistant..." wählen. -3. Erwartet: zuerst die Frage des Einstellungsfensters nach den offenen Änderungen; „Zurück" bricht alles ab, die Sitzung steht noch. -4. Erneut wählen, Änderungen verwerfen. Erwartet: die Rückfrage „Sitzung beenden …". „Abbrechen" lässt die Sitzung stehen. -5. Erneut, „Assistent starten". Erwartet: alle Fenster schließen, der Assistent erscheint, die Einstiegsseite bietet für Anmeldung und Station je „neu" und „unverändert". -6. Beides „unverändert", bis zur Zusammenfassung, „Speichern". Erwartet: das Programm startet neu; Rufzeichen, Locator, Bänder, Fensteranordnung und alle Reiter wie vorher. -7. `~/.praktiKST/preferences.xml` vor Schritt 5 kopieren und nach Schritt 6 vergleichen (`diff`). Erwartet: kein Unterschied in fachlichen Werten. - -Schritt 7 prüft die Annahme der Spec, dass die Laufzeit beim Abbau nicht über die Datei des Assistenten schreibt. Zeigt der Vergleich einen Verlust, das melden und nicht weitermachen. - -- [ ] **Step 9: Commit** - -```bash -git add app-desktop/src/main/i18n/strings_en.properties app-desktop/src/main/i18n/strings_de.properties app-desktop/src/main/kotlin/kst4contest/view/compose/MainMenuBar.kt app-desktop/src/main/kotlin/kst4contest/view/compose/MainMenuModel.kt app-desktop/src/main/java/kst4contest/view/ComposeMenuActions.java app-desktop/src/main/java/kst4contest/view/ApplicationRuntimeLauncher.java app-desktop/src/main/java/kst4contest/view/Kst4ContestApplication.java app-desktop/src/test/kotlin/kst4contest/view/compose/MainMenuModelTest.kt app-desktop/src/test/kotlin/kst4contest/view/compose/MainMenuRowScreenTest.kt -git commit -m "Reach the setup wizard from the Options menu" -``` - ---- - -### Task 8: Dokumentation und Abschluss - -**Files:** -- Modify: `docs/PROJECT_CONTEXT.md` (Abschnitt „Important Decisions and Workarounds", ein Punkt am Ende der Liste) -- Modify: `github_docs/de-Konfiguration.md`, `github_docs/en-Configuration.md` (neuer Abschnitt vor „Station Settings") -- Modify: `app-desktop/src/main/i18n/strings_en.properties`, `strings_de.properties` (Schlüssel `profiles.createdWithoutCredentials`) -- Delete: `docs/superpowers/plans/2026-11-18-einrichtungsassistent-stufe-1.md` - -**Interfaces:** -- Consumes: das fertige Verhalten aus Task 1 bis 7. -- Produces: nichts, worauf Code aufbaut. - -- [ ] **Step 1: Der Hinweis beim Anlegen eines Profils** - -Der Text schickt den Nutzer heute in den Reiter „Station". Nach dem Wechsel erscheint jetzt der Assistent. - -In `strings_de.properties` die Zeile `profiles.createdWithoutCredentials=…` ersetzen durch: - -```properties -profiles.createdWithoutCredentials=Das Profil „{0}" wurde ohne Rufzeichen und Passwort angelegt. Nach dem Wechsel zu diesem Profil fragt der Einrichtungsassistent beides ab. -``` - -In `strings_en.properties` die Zeile mit demselben Schlüssel ersetzen durch: - -```properties -profiles.createdWithoutCredentials=The profile "{0}" was created without callsign and password. After switching to it, the setup assistant asks for both. -``` - -Run: `grep -rn 'profilesCreatedWithoutCredentials\|createdWithoutCredentials' app-desktop/src/test` -Jeden Test, der den alten Wortlaut festhält, auf den neuen ändern. - -- [ ] **Step 2: `docs/PROJECT_CONTEXT.md`** - -Am Ende der Liste unter „Important Decisions and Workarounds" anfügen: - -```markdown -- **The setup wizard writes `preferences.xml` and does not touch a running session.** It runs - in `startRuntime` after the profile is resolved and before the `ChatController` exists, on - a `ChatPreferences` of its own, so what it stores is read like any stored setting. That is - why it needs neither `SettingsDraft` nor the tab states: there is no session to bring up to - date. From the menu the runtime is torn down first and the same profile restarted - (`ApplicationRuntimeLauncher.rerunSetupWizard`), which costs the session and asks first. A - profile counts as unconfigured when its callsign is empty or it still carries the bundled - template's credentials (`LoginConfiguration`); there is no flag for it in the file. Stage 1 - asks for name, login, locator, bands and chat category; the reasons and the later stages - are in `docs/superpowers/specs/2026-11-18-einrichtungsassistent-design.md`. -``` - -- [ ] **Step 3: Handbuch, deutsch** - -In `github_docs/de-Konfiguration.md` den ersten Absatz nach der Sprachzeile ersetzen. Alt: - -```markdown -Nach dem ersten Start öffnet sich das **Einstellungsfenster** – dieses ist der zentrale Ausgangspunkt für alle Konfigurationen. Es empfiehlt sich, das Einstellungsfenster während des Betriebs geöffnet zu lassen (z. B. um den Beacon schnell ein- und auszuschalten). -``` - -Neu: - -```markdown -Beim ersten Start fragt der **Einrichtungsassistent** das Nötigste ab (siehe unten). Danach öffnet sich das **Einstellungsfenster** – dieses ist der zentrale Ausgangspunkt für alle Konfigurationen. Es empfiehlt sich, das Einstellungsfenster während des Betriebs geöffnet zu lassen (z. B. um den Beacon schnell ein- und auszuschalten). -``` - -Unmittelbar vor `## Station Settings (Stationseinstellungen)` einfügen: - -```markdown -## Einrichtungsassistent (ab v1.51) - -Solange ein Profil kein eigenes Rufzeichen hat, startet es mit dem Einrichtungsassistenten. Das gilt für die erste Installation und für jedes neu angelegte oder duplizierte Operator-Profil. - -Der Assistent fragt: - -1. **Persönliches** – Sprache und Anzeigename im Chat. -2. **Anmeldung** – Rufzeichen und Passwort des ON4KST-Kontos. -3. **Standort und Bänder** – Locator, aktive Bänder und Chatkategorie. Die Kategorie wird aus den Bändern vorgeschlagen und lässt sich ändern. Ein zweiter Chat ist freiwillig. -4. **Zusammenfassung** – erst **Speichern** schreibt die Einstellungen. **Speichern und verbinden** meldet danach gleich am Chat an. - -Hat das Profil schon eine Station (etwa nach dem Duplizieren), fragt die erste Seite, ob sie **unverändert** bleiben oder **neu eingerichtet** werden soll. So braucht ein weiterer Operator an derselben Station nur Namen und Anmeldung einzutragen. - -**Später** schließt den Assistenten, ohne etwas zu schreiben. Er erscheint beim nächsten Start des Profils wieder, solange das Rufzeichen fehlt. - -Über **Options → Einrichtungsassistent...** lässt er sich jederzeit erneut aufrufen. Dabei wird die laufende Sitzung nach einer Rückfrage beendet und das Profil neu gestartet. Für einzelne Änderungen im Betrieb ist das Einstellungsfenster gedacht. - -Logprogramm, Rotor, AirScout und DX-Cluster-Server fragt der Assistent noch nicht ab; sie behalten ihre Werte und werden wie bisher im Einstellungsfenster eingestellt. - ---- - -``` - -Die Versionsangabe „ab v1.51" gegen `gradle.properties` prüfen und auf die Version setzen, in der die Änderung erscheint. Kein Versionssprung in `gradle.properties` selbst. - -- [ ] **Step 4: Handbuch, englisch** - -In `github_docs/en-Configuration.md` den ersten Absatz ersetzen. Alt: - -```markdown -After the first start, the **settings window** opens – this is the central starting point for all configuration. It is recommended to keep the settings window open during operation (e.g. to quickly toggle the beacon on and off). -``` - -Neu: - -```markdown -On the first start, the **setup assistant** asks for the essentials (see below). After that the **settings window** opens – this is the central starting point for all configuration. It is recommended to keep the settings window open during operation (e.g. to quickly toggle the beacon on and off). -``` - -Unmittelbar vor `## Station Settings` einfügen: - -```markdown -## Setup Assistant (since v1.51) - -As long as a profile has no callsign of its own, it starts with the setup assistant. This applies to the first installation and to every newly created or duplicated operator profile. - -The assistant asks for: - -1. **Personal** – language and the name shown in the chat. -2. **Login** – callsign and password of the ON4KST account. -3. **Location and bands** – locator, active bands and chat category. The category is suggested from the bands and can be changed. A second chat is optional. -4. **Summary** – nothing is written until you click **Save**. **Save and connect** logs into the chat right afterwards. - -If the profile already has a station (after duplicating one, for example), the first page asks whether to leave it **unchanged** or to **set it up anew**. A further operator at the same station then only enters a name and a login. - -**Later** closes the assistant without writing anything. It appears again on the next start of the profile as long as the callsign is missing. - -**Options → Setup assistant...** opens it again at any time. This ends the running session after a confirmation and restarts the profile. Use the settings window for single changes during operation. - -The assistant does not ask about log program, rotator, AirScout and DX cluster server yet; they keep their values and are configured in the settings window as before. - ---- - -``` - -- [ ] **Step 5: Der ganze Bau** - -Run: `./gradlew clean build` -Expected: BUILD SUCCESSFUL. - -Danach, weil der Rückgabewert allein nichts beweist: - -```bash -grep -l '