From 1615c4dffc72ba0efeb12889181c485ea2a27bec Mon Sep 17 00:00:00 2001 From: Philipp Wagner Date: Wed, 18 Nov 2026 19:12:47 +0100 Subject: [PATCH] Add implementation plan for setup wizard stage 1 Written-by: Claude Fable 5.2 --- ...026-11-18-einrichtungsassistent-stufe-1.md | 2694 +++++++++++++++++ 1 file changed, 2694 insertions(+) create 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 new file mode 100644 index 00000000..d351a53f --- /dev/null +++ b/docs/superpowers/plans/2026-11-18-einrichtungsassistent-stufe-1.md @@ -0,0 +1,2694 @@ +# 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 '