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