mirror of
https://github.com/praktimarc/kst4contest.git
synced 2026-11-19 01:52:29 +01:00
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:
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.
|
||||
Reference in new issue
Block a user