Add setup wizard design spec

Describes a first-start assistant for unconfigured operator profiles: what it asks, how it covers multi-operator and multi-station setups, and why it writes preferences.xml before the runtime is built instead of going through the settings draft.

Written-by: Claude Fable 5.2
Written-by: Codex (GPT-6.2 Sol)
Written-by: Gemini 4 Hydrogen (Antigravity)
Written-by: DeepSeek V4 Pro
This commit is contained in:
Rsclub2_2 committed 2026-11-18 21:32:08 +01:00
1 parent b0960a3f04
commit aff9b6e2ff
1 file changed
+246
@@ -0,0 +1,246 @@
# Entwurf — Einrichtungsassistent für unkonfigurierte Profile
Stand 2026-11-18. Konzept mit Philipp abgestimmt, **noch nicht vom Maintainer freigegeben**.
Berührt den Entwurfsmechanismus aus `2026-10-16-settings-apply-drafts-design.md` bewusst nicht.
## Warum
Das Einstellungsfenster hat zwölf Reiter und 74 Felder (`settings-fields.txt`). Wer das
Programm zum ersten Mal startet, landet genau dort (`Kst4ContestApplication.startRuntime`
ruft am Ende `openSettingsWindow()`), und nichts sagt ihm, welche fünf Angaben er braucht
und welche siebzig er lassen kann.
Dazu kommt, dass die mitgelieferte Vorlage `praktiKSTpreferences.xml` keine neutrale
Ausgangslage ist. Sie trägt das Rufzeichen `DO5AMF` mit dem Passwort `changeMe` und schaltet
ein, was nur mit passender Gegenstelle sinnvoll ist: den UDP-Empfang für UCXLog, den
Abgleich über eine Logdatei, die Frequenzübernahme, AirScout, den lokalen DX-Cluster-Server
und den Zweitchat. Ein Neuling ohne Logprogramm hat das alles aktiv, ohne es zu wissen.
Der Assistent fragt das Nötige ab, schaltet ab, was nicht vorhanden ist, und lässt den Rest
auf seinen Werten.
## Wann er erscheint
Ein Profil gilt als **unkonfiguriert**, wenn sein Rufzeichen leer ist oder wenn es noch die
Anmeldedaten der Vorlage trägt (`DO5AMF` mit `changeMe`). Das erste trifft auf jedes neu
angelegte und jedes duplizierte Profil zu, weil `OperatorProfileManagementService` dort
Rufzeichen und Passwort löscht; das zweite auf das Stammprofil einer frischen Installation.
Die Regel gilt **pro Profil**, nicht pro Installation, und sie braucht kein eigenes Merkmal
in `preferences.xml`: ohne Rufzeichen lässt sich ohnehin nicht verbinden.
- Beim Start eines unkonfigurierten Profils öffnet sich der Assistent als eigenes Fenster,
**bevor** die Laufzeit des Profils gebaut wird: nach der Profilwahl, vor dem
`ChatController`.
- Schließt er sich, gleich auf welchem Weg, geht der Start weiter wie heute, und das
Einstellungsfenster öffnet sich. Es bleibt der Weg in den Chat.
- Später ist er über „Optionen → Einrichtungsassistent" erreichbar, für jedes Profil. Dort
kostet er die laufende Sitzung, siehe „Mechanismus", und fragt vorher.
- Assistent und Einstellungsfenster sind nie zugleich offen. Der Aufruf aus dem Menü läuft
durch `SettingsWindow.settleThen`, damit offene Änderungen dort erst entschieden sind.
## Drei Gruppen
Der Assistent ordnet, was er fragt, in drei Gruppen. Die Ordnung folgt der Frage, **woran**
eine Angabe hängt, nicht dem Reiter, auf dem sie heute steht.
**Persönliches** hängt am Operator: Sprache, Anzeigename (`stn_loginNameMainCat`, und
`stn_loginNameSecondCat` folgt ihm, solange es nicht eigens gesetzt wurde).
**Anmeldung**: `stn_loginCallSign`, `stn_loginPassword`.
**Station** hängt am Standort und an der Technik:
- gefragt: Locator (`stn_loginLocatorMainCat`), aktive Bänder (`stn_bandActive…`),
Hauptkategorie, Zweitchat und dessen Kategorie, Logprogramm mit seinen Angaben
(`logsynch_…`, `trxSynch_ucxLogUDPListenerEnabled`, `notify_dxClusterServerEnabled`),
PSTRotator (`stn_pstRotator…`), AirScout (`AirScout_…`);
- nie gefragt, aber Teil der Station: Öffnungswinkel, QTF-Vorgabe, größte Entfernung und
alle Werte der Pfadanalyse (`stn_antennaBeamWidthDeg`, `stn_qtfDefault`,
`stn_maxQRBDefault`, `stn_pathAnalysis…`).
Der Locator steht im Einstellungsfenster bei den Anmeldefeldern und bleibt dort. Im
Assistenten gehört er zur Station: wer mit demselben Rufzeichen an zwei Standorten arbeitet,
hat zwei Locator und eine Anmeldung.
## Die Einstiegsseite
Anmeldung und Station sind zwei unabhängige Entscheidungen. Für jede fragt die erste Seite,
woher sie kommt:
| Wahl | Bedeutung | angeboten, wenn |
|---|---|---|
| neu eingeben | die Schritte der Gruppe erscheinen, mit den Startwerten des Assistenten | immer |
| von Profil X übernehmen | die Werte der Gruppe aus einem anderen Profil | ein anderes, konfiguriertes Profil existiert |
| unverändert lassen | die Werte, die das Profil schon hat | Anmeldung: das Profil ist konfiguriert. Station: das Profil trägt nicht die Anmeldedaten der Vorlage |
Nichts ist vorausgewählt; der Assistent rät nicht, welcher Fall vorliegt. Bleibt für beide
Gruppen nur „neu eingeben" übrig — die frische Installation —, entfällt die Seite.
Damit sind die Betriebsarten abgedeckt, ohne dass der Assistent sie beim Namen kennen muss:
| Fall | Anmeldung | Station |
|---|---|---|
| Erste Installation | neu | neu |
| Mehrmannbetrieb, gemeinsames Rufzeichen | übernehmen | übernehmen oder unverändert |
| Mehrmannbetrieb, eigenes Rufzeichen | neu | übernehmen oder unverändert |
| Ein Operator, mehrere Standorte | übernehmen | neu |
| Neuer Operator, neue Station | neu | neu |
„Unverändert" ist der Fall des duplizierten Profils: `duplicateProfile` hat die Station
schon kopiert und nur die Anmeldung geleert. „Übernehmen" ist derselbe Fall für ein leer
angelegtes Profil.
Die Wahl bestimmt, **womit die Schritte vorbelegt sind**, und ob sie im Ablauf erscheinen:
- neu → Startwerte des Assistenten, Schritte erscheinen;
- übernehmen → Werte des gewählten Profils, Schritte erscheinen nicht;
- unverändert → Werte des eigenen Profils, Schritte erscheinen nicht.
In allen drei Fällen zeigt die Zusammenfassung die Werte, und von dort lässt sich jeder
Schritt öffnen und ändern. Ein übernommenes Rufzeichen bekommt so sein `/P`.
Die **Startwerte des Assistenten** für eine neue Station sind bewusst nicht die der Vorlage:
kein Band gewählt, Locator leer, kein Zweitchat, kein Logprogramm, kein lokaler
DX-Cluster-Server, kein Rotor, kein AirScout. Wer „neu einrichten" wählt, bekommt nur
eingeschaltet, was er bejaht hat.
## Die Schritte
1. **Persönliches** — Sprache, Anzeigename. Immer.
2. **Anmeldung** — Rufzeichen, Passwort.
3. **Standort und Bänder** — Locator, Bänder, Hauptkategorie. Der Assistent schlägt die
Kategorie aus den Bändern vor (1 für 50/70 MHz, 2 für 144/432 MHz, 3 ab 1240 MHz), der
Nutzer bestätigt sie. Der Zweitchat ist eine Ja/Nein-Frage; bei Ja folgt seine Kategorie.
Aus der Bandwahl wird **keine Frequenz** abgeleitet.
4. **Logprogramm** — keines, Win-Test, UCXLog/DXLog.net/N1MM+/QARTEST, oder eine Logdatei.
Erst nach der Wahl erscheinen die zugehörigen Angaben (Port, Stationsnamen, Datei),
vorbelegt mit den gespeicherten Werten. Mit einem Netzwerk-Logprogramm folgen zwei
Ja/Nein-Fragen: eigene Frequenz übernehmen, Spots über den lokalen DX-Cluster-Server
an das Logprogramm geben.
5. **Rotor und AirScout** — je eine Ja/Nein-Frage; Host, Port und Kennungen erst bei Ja.
6. **Zusammenfassung** — alle drei Gruppen, das Passwort verdeckt, je Gruppe „Ändern". Was
der Assistent **abschaltet**, steht dort ausdrücklich. Darunter „Speichern" und
„Speichern und verbinden".
„Fertig" führt ab Schritt 2 von jedem Schritt zur Zusammenfassung, sobald die Anmeldung
gültig ist. Niemand muss durch Logprogramm und Rotor, um in den Chat zu kommen.
„Später" und das Schließen des Fensters schreiben nichts, auch die Sprache nicht: der
Assistent zeigt sich sofort in der gewählten Sprache, gespeichert wird sie erst mit allem
anderen.
## Was unsichtbar bleibt
Serveradresse und -port, Baken, automatische Antworten, Kurzbefehle und Textbausteine,
Töne, Farben, Filter, SO2R, die Worked-Datenbank, der Fehlermitschnitt, die Fensteranordnung
und alle Profilaktionen. Der Assistent fasst keinen dieser Werte an.
Die automatische Antwort auf Frequenzanfragen (`autoAnswerToQrgRequestEnabled`) steht in der
Vorlage auf an. Ob der Assistent sie bei einer Station ohne Frequenzquelle abschalten soll,
ist **nicht entschieden** und nicht Teil dieses Entwurfs.
## Mechanismus
**Der Assistent schreibt `preferences.xml`, und die Laufzeit liest sie beim Start.** Er
ändert keine laufende Sitzung.
Das Einstellungsfenster muss beides können: einen Wert speichern und die laufende Sitzung
nachführen — einen Listener neu binden, den Rotor neu einrichten, die Kategorie am
`ChatController` setzen. Dafür gibt es `SettingsDraft` mit seinen Wirkungen. Der Assistent
braucht das zweite nicht, denn er läuft, bevor es eine Sitzung gibt. Was er schreibt, liest
`startRuntime` danach so ein, wie es jede gespeicherte Einstellung einliest. Dieser Weg ist
der am besten erprobte im Programm: jeder Start und jeder Profilwechsel geht ihn.
Im Einzelnen:
- Der Assistent arbeitet auf einem eigenen `ChatPreferences`-Objekt, das die Datei des
Profils gelesen hat, so wie `OperatorProfileManagementService.createPreferencesFile` es
beim Anlegen eines Profils tut. Bis zum Speichern hält er seine Antworten in einem
`SetupWizardState` und fasst dieses Objekt nicht an.
- „Speichern" setzt die Antworten über die Setter von `ChatPreferences` und ruft
`writePreferencesToXmlFile`. Alles, was der Assistent nicht gefragt hat, steht danach
unverändert in der Datei, weil es gelesen und wieder geschrieben wurde.
- **Beim Start** gibt es danach nichts neu zu laden: die Laufzeit wird erst jetzt gebaut.
- **Aus dem Menü** läuft eine Laufzeit. Der Assistent fragt deshalb zuerst, ob die Sitzung
aufgegeben werden darf, wie der Profilwechsel fragt. Dann wird die Laufzeit abgebaut,
der Assistent gezeigt, und danach das **selbe** Profil neu gestartet — der Weg von
`ApplicationRuntimeLauncher.switchProfile`, der ein Ziel gleich dem aktiven Profil
zulässt. Abgebaut wird **vor** dem Assistenten, nicht danach: sonst schriebe die
Laufzeit beim Abbau (`layoutAutosave.flushPending`) über die Datei, die der Assistent
gerade geschrieben hat.
- **Übernehmen von Profil X** liest dessen Datei in ein zweites `ChatPreferences`-Objekt
und belegt die Antworten der Gruppe damit vor. Geschrieben wird nur in das aktive Profil.
`duplicateProfile` bleibt unverändert und löscht die Anmeldedaten weiterhin: das
Duplizieren kopiert sie nie von selbst, im Assistenten wählt der Nutzer es ausdrücklich.
- **„Speichern und verbinden"** merkt sich den Wunsch; nach dem Start der Laufzeit geht er
den Weg des Verbinden-Knopfs (`connectFromSettings`).
`SetupWizardState` kennt weder Fenster noch Laufzeit und ist ohne Oberfläche prüfbar. Weil
er nur ein `ChatPreferences`-Objekt braucht, hängt er an keinem Reiterzustand, und die
Frage, welche Eigenschaft eines Reiterzustands von außen setzbar ist, stellt sich nicht.
**Die Erkennung** ist eine Abfrage in `core` auf `ChatPreferences`. Die Anmeldedaten der
Vorlage stehen als Konstanten daneben; ein Test liest die mitgelieferte
`praktiKSTpreferences.xml` und hält beide gleich.
Der Preis dieses Wegs: der Assistent aus dem Menü beendet die Sitzung. Das ist hingenommen.
Er ist für die Einrichtung da; wer im Contest einen Port ändert, nimmt das
Einstellungsfenster, das dafür gebaut ist.
## Fäden
Beim Start läuft der Assistent auf dem Weg, den die Profilwahl geht
(`OperatorProfilePickerWindow.showAndSelect`): ein modaler Dialog, auf dem
AWT-Ereignisfaden gebaut, der seinen Aufrufer anhält und dabei weiter Ereignisse
verarbeitet. **Kein** eigener Faden mit Riegel — genau diese Bauart hat sich bei der
Profilwahl verklemmt, die Begründung steht dort im Quelltext. Aus dem Menü kommt der Aufruf
vom Ereignisfaden und geht denselben Weg.
Der Assistent liest die Profilliste und höchstens zwei Profildateien, kleine lokale Dateien.
Netzprüfungen gibt es in diesem Entwurf nicht. Ein Probe-Login wäre eine zweite echte
Sitzung am Server, und ein Lauschen auf UDP sagt bei Stille nichts: die Logprogramme senden
nur bei einem QSO oder Statuswechsel. Geprüft wird lokal — Form von Rufzeichen und Locator,
Portkollisionen wie in `StationTabState` — und danach zeigt „Speichern und verbinden" den
tatsächlichen Anmeldestatus.
## Ausbaustufen
1. Erkennung, Fenster, Menüeintrag, Einstiegsseite mit „neu" und „unverändert", Schritte
1 bis 3, Zusammenfassung, Speichern, Speichern und verbinden.
2. Schritte 4 und 5 mit den Startwerten, die Integrationen abschalten.
3. „Von Profil X übernehmen".
Stufe 1 ist für sich benutzbar; bis Stufe 2 lässt „neu einrichten" die Integrationen auf
ihren gespeicherten Werten und sagt das in der Zusammenfassung.
## Unverändert
Das Format von `preferences.xml`. Das Einstellungsfenster mit seinen zwölf Reitern, ihrer
Reihenfolge und ihren Titeln. Der Vertrag von `SettingsDraft.apply`. Die Sperre der
Anmeldefelder während einer Sitzung. Das Anlegen und Duplizieren von Profilen. Die
Vorlage `praktiKSTpreferences.xml`. Der Start- und der Profilwechselweg. Kein
automatisches Verbinden, außer der Nutzer wählt „Speichern und verbinden".
## Prüfung
- Erkennung: leeres Rufzeichen, Anmeldedaten der Vorlage, konfiguriertes Profil; die
Konstanten gegen die mitgelieferte Vorlage.
- Einstiegsseite: welche Wahl in welcher Lage angeboten wird, und dass sie auf der frischen
Installation entfällt.
- Ablauf: die fünf Fälle der Tabelle, „Fertig" ab gültiger Anmeldung, Zurück erhält die
Eingaben, die Zusammenfassung nennt das Abgeschaltete.
- Schreiben, gegen eine echte Datei wie in `ChatPreferencesRoundTripTest`: nach „Später"
ist die Datei Byte für Byte unverändert; nach „Speichern" liest ein frisches
`ChatPreferences` genau die gewählten Werte; jedes nicht gefragte Feld hat seinen alten
Wert; eine neue Station ohne Logprogramm hat alle Abgleiche aus.
- Aus dem Menü: die Rückfrage kommt vor dem Abbau, „Zurück" lässt die Sitzung stehen, und
nach dem Speichern steht nichts von der abgebauten Laufzeit in der Datei.
- Übernehmen: nur die Felder der gewählten Gruppe wandern, das Quellprofil bleibt
unberührt.
- `SettingsFieldCoverageTest` und `SettingsForeignWriteCoverageTest` bleiben unberührt:
sie prüfen, dass das Einstellungsfenster jeden Setter noch ruft, und der Assistent nimmt
dort nichts weg.
- Oberflächentexte in `strings_de.properties` und `strings_en.properties`; der Erzeuger
prüft beim Bau.