Der Squad-Reiter braucht kein Konto mehr: Spielername eingeben, der PC
bekommt einen Schluessel (Token ohne Ablauf), die Akten werden fuer alle
sichtbar. E-Mail und Passwort sind optional ("Konto sichern") und machen
die Charaktere reset- und mehr-PC-fest. Ohne gesichertes Konto bietet das
Menue kein Abmelden, weil das den Schluessel loeschte.
Server: Aktionen mitmachen und konto_sichern, Konten ohne E-Mail
(Datenbank-Stand 2, eingespielt von DB::migrieren() bei der ersten
Anfrage), Loeschen ohne Passwort fuer reine Schluessel-Konten, Verwaltung
zeigt sie als "nur Schluessel". Deinstallationsfrage nennt den Schluessel.
Tests: Server 108, Zwei-PC 34, Oberflaeche 24 - auch gegen das Paket.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
631 lines
32 KiB
Markdown
631 lines
32 KiB
Markdown
# Projektübergabe: Squad Manager
|
||
|
||
Stand: 15. September 2026 · Version 1.7.0 (Build 5) · Git-Repository im Quellordner
|
||
|
||
Seit 3.2 wird über einen Inno-Setup-Installer und einen eingebauten
|
||
Auto-Updater verteilt (Server: https://sva.tyrveil.com), siehe Abschnitt 4.
|
||
|
||
Das Projekt heißt seit 3.2 **Squad Manager** (vorher „Squad Voice
|
||
Activation"). Repository: `github.com/DannyShepard312/squad-manager`
|
||
(privat). Geplant ist ein zweites Modul „Akte" für Rollenspiel-Charaktere.
|
||
|
||
Dieses Dokument richtet sich an eine neue Claude-Sitzung ohne Vorwissen.
|
||
Es beschreibt, was das Projekt ist, wie es aufgebaut ist und vor allem:
|
||
welche Fallstricke bereits teuer gelernt wurden. Die Abschnitte
|
||
„Hart erkaufte Erkenntnisse" und „Offene Punkte" sind die wichtigsten.
|
||
|
||
---
|
||
|
||
## 1. Was es ist
|
||
|
||
Ein Windows-Desktop-Werkzeug in Python für den Taktik-Shooter **Squad**.
|
||
Es misst laufend den Mikrofonpegel und hält per simuliertem Tastendruck die
|
||
Sprechtaste des Spiels gedrückt, solange der Nutzer redet — also Voice
|
||
Activation für ein Spiel, das nur Push-to-Talk kennt.
|
||
|
||
Kein Eingriff ins Spiel: kein Hook, keine DLL-Injektion, kein
|
||
Speicherzugriff, keine veränderten Spieldateien. Ausschließlich
|
||
`SendInput` und `GetAsyncKeyState` über `ctypes`.
|
||
|
||
**Nutzer:** Ein einzelner Anwender (deutschsprachig, spielt Squad) und sein
|
||
Freundeskreis, an den er das Programm weitergibt. Sprache der Oberfläche
|
||
und aller Dokumente ist Deutsch.
|
||
|
||
---
|
||
|
||
## 2. Ordner
|
||
|
||
Es gibt drei getrennte Orte. Das zu verwechseln war bereits mehrfach die
|
||
Fehlerquelle.
|
||
|
||
### `C:\Users\danie\Desktop\squad-manager\` — Quelle
|
||
|
||
Arbeitsverzeichnis. Hier wird entwickelt. Der Code enthält hier
|
||
**Kommentare**, und Texte stehen teils in Ersatzschreibung („Haelt").
|
||
|
||
```
|
||
squad_manager.py Hauptfenster, Funk-Modul, Updater (~1500 Zeilen)
|
||
theme.py Farben, Schriften, ttk-Stil, Pegelanzeige
|
||
akte.py Akte: Oberfläche (Liste, Formular, Dokumentansicht)
|
||
akte_modell.py Akte: Datenmodell und Speicherung, ohne tkinter
|
||
akte_vorlagen.py Akte: Fraktionen, Dienstgrade, Verwendungen
|
||
akte_karte.py Akte: PNG-Karte zum Teilen, Zwischenablage
|
||
konto.py Verbindung zum Server, Anmeldung (Token per DPAPI)
|
||
abgleich.py Abgleich lokaler Akten mit dem Server, ohne tkinter
|
||
hintergrund.py Netzwerkarbeit im Thread, Ergebnis im Tk-Hauptthread
|
||
squad.py Hauptreiter SQUAD: Anmeldung, Charaktere, Squads
|
||
update_helfer.py spielt Updates ein, bei Bedarf mit Adminrechten
|
||
server/ PHP-Server für Konten und Squads, siehe Abschnitt 4
|
||
start.pyw Startskript ohne Konsolenfenster
|
||
make_icon.py erzeugt icon.ico aus icon.png
|
||
icon.png / icon.ico Programmsymbol (vom Nutzer geliefert)
|
||
requirements.txt numpy, sounddevice
|
||
installer/ Inno-Setup-Skript, Einrichtung, Server-Anleitung
|
||
werkzeuge/ Release-Bau und Testhilfen, siehe Abschnitt 4
|
||
README.md kurze Orientierung
|
||
PROJEKT-UEBERGABE.md dieses Dokument
|
||
Design-Briefing.md Auftrag für Claude Design, siehe Offene Punkte
|
||
```
|
||
|
||
**Aufteilung:** Die Python-Dateien werden beim Release aufbereitet
|
||
(Kommentare raus, Umlaute rein). Alles unter `installer/` wird unverändert
|
||
übernommen: `setup.iss`, `einrichten.bat`, `HOCHLADEN.txt` und in
|
||
`installer/paketdateien/` die Skripte `Starter.vbs` und `Fehlersuche.bat`.
|
||
`Setup.bat`, `Update.bat` und `Deinstallieren.bat` gehören zum alten
|
||
Paketweg und sind nicht im Repository.
|
||
|
||
### `C:\Users\danie\Downloads\Squad Voice Activation 3.1\` — altes Paket
|
||
|
||
**Vorgängerweg, seit 3.2 ersetzt** durch `dist/` und den Installer
|
||
(Abschnitt 4). Nur noch relevant, weil die lokale Installation des Nutzers
|
||
darüber eingerichtet wurde. Enthält Code ohne Kommentare und mit echten
|
||
Umlauten.
|
||
|
||
```
|
||
Setup.bat Erstinstallation
|
||
Update.bat Aktualisierung einer vorhandenen Installation
|
||
ANLEITUNG.txt Endnutzer-Dokumentation
|
||
Programm/
|
||
squad_voice_activation.py
|
||
start.pyw
|
||
make_icon.py
|
||
Starter.vbs portabler Start ohne Installation
|
||
Fehlersuche.bat Start mit sichtbarer Konsole
|
||
Deinstallieren.bat
|
||
requirements.txt
|
||
icon.png / icon.ico
|
||
```
|
||
|
||
Dazu `Downloads\SquadVoiceActivation-3.1.zip` als Versandfassung.
|
||
|
||
### `%LOCALAPPDATA%\Programs\SquadManager\` — Installation
|
||
|
||
Standardziel des Installers, frei wählbar. Enthält zusätzlich `.venv\`.
|
||
Seit 4.0 installiert der Installer immer nur für den aktuellen Benutzer;
|
||
die Wahl „für alle Benutzer" ist entfernt (Erkenntnis 19). Findet er eine
|
||
alte Installation für alle Benutzer, entfernt er sie vorher mit
|
||
Adminrechten.
|
||
Konfiguration und Fehlerlog liegen getrennt davon in
|
||
`%APPDATA%\SquadManager\`. Beim ersten Start werden Einstellungen aus
|
||
`%APPDATA%\SquadVoiceActivation\` übernommen — kopiert, nicht verschoben
|
||
(`alte_einstellungen_uebernehmen()`). Die frühere Installation des Nutzers
|
||
unter `…\Programs\SquadVoiceActivation\` ist gelöscht; er installiert 3.3
|
||
frisch.
|
||
|
||
---
|
||
|
||
## 3. Aufbau des Programms
|
||
|
||
`tkinter`/`ttk`, fünf flache Dateien: `squad_manager.py` mit Hauptfenster,
|
||
Funk-Modul und Updater (Hauptklasse `VoiceActivationApp`), `theme.py` mit
|
||
dem Stil, und das Modul Akte in drei Teilen — `akte.py` (Oberfläche),
|
||
`akte_modell.py` (Datenmodell und Speicherung, bewusst ohne tkinter und
|
||
damit ohne Fenster testbar), `akte_vorlagen.py` (Vorschlagslisten) und
|
||
`akte_karte.py` (Karte zum Teilen). `theme.py` gibt es, damit
|
||
`akte.py` die Farben nicht aus `squad_manager.py` holen muss — das wäre
|
||
ein zirkulärer Import, weil `squad_manager.py` die Akte einbindet.
|
||
Weitere Module gehören ebenfalls flach daneben: Installer, Update-Paket
|
||
und `start.pyw` erwarten flache Dateien.
|
||
|
||
**Ablauf:** `sounddevice.InputStream` liefert Audioblöcke an einen
|
||
Callback, der den RMS-Pegel berechnet und in eine Queue legt. Ein
|
||
Arbeitsthread (`worker_loop`) liest daraus, prüft Sperrgründe und drückt
|
||
bzw. löst die Taste. Die Oberfläche aktualisiert sich unabhängig alle 80 ms
|
||
über `ui_tick`.
|
||
|
||
**Zentrale Funktion:** `blocking_reason()` gibt den Grund zurück, warum
|
||
gerade nicht gesendet werden darf, oder einen leeren String. Reihenfolge:
|
||
|
||
1. Spiel nicht im Vordergrund
|
||
2. per Hotkey stummgeschaltet
|
||
3. eine Funktaste wird gehalten
|
||
4. die Sprechtaste wird manuell gedrückt
|
||
5. Mauszeiger sichtbar (optional)
|
||
|
||
**Funktionen von Bedeutung:**
|
||
|
||
| Funktion | Zweck |
|
||
|---|---|
|
||
| `enumerate_inputs()` | Geräteliste, siehe Erkenntnis 5 |
|
||
| `squad_focused()` | Prozessname des Vordergrundfensters prüfen |
|
||
| `send_binding()` | Taste plus Zusatztaste drücken/lösen |
|
||
| `apply_tactical_theme()` | dunkles Farbschema (`theme.py`) |
|
||
| `LevelMeter` | segmentierte Pegelanzeige mit Schwellenmarke (`theme.py`) |
|
||
| `set_dark_titlebar()` | Fenstertitelleiste dunkel |
|
||
| `arm_autosave()` | speichert Einstellungen 600 ms nach jeder Änderung |
|
||
|
||
**Oberfläche:** Drei Hauptreiter, *FUNK* (mit den Unterreitern „Mikrofon"
|
||
und „Tasten und Verhalten"), *AKTE* und seit 1.6.0 *SQUAD*. Darunter für alle Module die
|
||
Statusleiste mit den Knöpfen und der Zustandsanzeige (BEREITSCHAFT /
|
||
HORCHT / SENDET / GESPERRT) — die Sprachaktivierung läuft weiter, während
|
||
man in einem anderen Modul arbeitet. Der zuletzt gewählte Hauptreiter
|
||
steht als `modul` in der `config.json`.
|
||
|
||
**Akte:** Ablage je Akte unter `%APPDATA%\SquadManager\akten\<id>\` als
|
||
`akte.json`, dazu `portraet.png` (auf höchstens 512 px verkleinerte
|
||
Kopie). Geschrieben wird atomar über eine `.tmp`-Datei, die vorige Fassung
|
||
bleibt als `.bak`; ist `akte.json` beim Lesen defekt, wird die Sicherung
|
||
genommen. Löschen heißt Verschieben nach `akten\_papierkorb\`.
|
||
Aktennummern `SM-<Jahr>-<n>`, der Papierkorb zählt mit, damit keine Nummer
|
||
doppelt vergeben wird. Das Feld `schema` erlaubt spätere Formatänderungen;
|
||
`migrieren()` ergänzt fehlende Felder und lässt unbekannte stehen. Offene
|
||
Änderungen werden 800 ms nach der letzten Eingabe gespeichert, außerdem beim
|
||
Schließen und vor einem Update.
|
||
|
||
**Auswahllisten (seit 1.5.1):** `akte_vorlagen.FRAKTIONEN` ist
|
||
verschachtelt: Fraktion → `teilstreitkraefte` → Dienstgrade je
|
||
Teilstreitkraft; die erste Teilstreitkraft ist die Vorbelegung. Fraktion,
|
||
Teilstreitkraft, Dienstgrad und Verwendung sind reine Auswahllisten
|
||
(Combobox `readonly`). `_auswahl_anpassen()` ersetzt nach einem Wechsel,
|
||
was nicht mehr passt; beim Laden ändert es nichts. Alte Akten aus der
|
||
Freitext-Zeit meldet `vorlagen.pruefen()` als gelben Hinweis unter dem
|
||
Dienst-Abschnitt — nicht still korrigieren. Island hat nur die vier
|
||
Bereiche der Küstenwache, die Bundeswehr Heer, Luftwaffe und Marine mit
|
||
eigenen Marine-Dienstgraden.
|
||
|
||
**Squad-Reiter und Abgleich (seit 1.6.0):** Solange ein PC nicht
|
||
mitmacht, zeigt *SQUAD* den Einstieg; alles andere läuft ohne wie vorher.
|
||
Seit 1.7.0 braucht Mitmachen **kein Konto**: Spielername eingeben, der
|
||
Server legt einen Nutzer ohne E-Mail an (`aktion mitmachen`), das
|
||
Sitzungstoken ist der Schlüssel des PCs und läuft nicht ab. Solange das
|
||
Konto nicht gesichert ist, zeigt der Reiter einen gelben Hinweis, und das
|
||
Konto-Menü bietet „Konto sichern" statt „Abmelden" – Abmelden würde den
|
||
Schlüssel löschen und die Charaktere verwaisen lassen. „Konto sichern"
|
||
hängt E-Mail und Passwort an (`konto_sichern`, mit Bestätigungsmail);
|
||
danach geht die Anmeldung auch auf anderen PCs. Verwaiste Charaktere
|
||
bleiben stehen, bis der Admin sie löscht (Wunsch des Nutzers). Die
|
||
Datenbank bekam dafür Stand 2 (`sm_nutzer.email` darf NULL sein);
|
||
`DB::migrieren()` spielt das bei der ersten Anfrage ein und merkt sich den
|
||
Stand als `daten/schema-2.ok`.
|
||
Angemeldet: Unterreiter *Charaktere* (alle Spieler, Zustand KIA/MIA/WIA,
|
||
Suche, Fraktionsfilter, fremde Akte als Dokument), *Squads* (gründen,
|
||
Mitglieder, Führung übergeben, verlassen, auflösen) und *Einladungen*.
|
||
Konto → Abmelden oder Konto löschen. Alle Serveraufrufe über
|
||
`hintergrund.Hintergrund`, nie im Tk-Hauptthread.
|
||
|
||
Die lokalen Akten bleiben Arbeitskopie. `squad.AbgleichSteuerung` stößt
|
||
`abgleich.abgleichen()` an: nach dem Anmelden, 4 s nach jeder Änderung
|
||
(`AkteSeite.bei_gespeichert`) und alle 5 min. Neben jeder Akte liegt
|
||
`server.json` mit Server-ID, Version, Prüfwert des Inhalts und
|
||
Porträt-Kennung des letzten Abgleichs. Nur lokal geändert → hochladen, nur
|
||
Server → herunterladen, beides → Konflikt: Serverfassung als
|
||
`konflikt-<Zeit>.json` neben die Akte, lokale Fassung gewinnt. Auf dem
|
||
Server gelöschte Akten wandern lokal in den Papierkorb. Der Papierkorb im
|
||
Programm merkt Akten in `akten/_abgleich_loeschen.json` zum Löschen auf dem
|
||
Server vor. Die Aktennummer vergibt der Server; der Abgleich schreibt sie
|
||
lokal zurück (`modell.speichern(zeit_setzen=False)`). Danach lädt
|
||
`AkteSeite.nach_abgleich()` geänderte Akten neu, die offene nur, wenn sie
|
||
selbst betroffen ist.
|
||
|
||
Tests: `werkzeuge/abgleich_test.py` (zwei Rechner als eigene Prozesse mit
|
||
eigenem `%APPDATA%`, 34 Fälle) und `werkzeuge/oberflaeche_test.py`
|
||
(Programm gegen den Testserver, Anmeldung, Einladung annehmen, fremde
|
||
Akte, Konto löschen, mit Bildschirmfotos). Beide nutzen den Testserver aus
|
||
`server_test.py`; `konto.py` liest die Serveradresse aus `SM_SERVER`
|
||
(nur `http://127.0.0.1` ist neben HTTPS erlaubt).
|
||
|
||
**Teilen:** Knopf „Teilen …" in der Leiste der Akte. `akte_karte.karte()`
|
||
zeichnet mit Pillow eine Karte 1200 × 675 (Discord zeigt das groß) —
|
||
bewusst kein Bildschirmfoto, damit sie überall gleich aussieht. Inhalt:
|
||
Porträt (bei *gefallen* grau), Callsign in der größten passenden Schrift,
|
||
Dienstzeilen bis der Platz endet, unten Auszeichnungen als ganze Einträge
|
||
mit „+ n weitere", sonst eine Zeile Beschreibung; Fußzeile wirbt mit
|
||
`sva.tyrveil.com`. „Kopieren" legt die Karte zweimal in die
|
||
Zwischenablage, als `CF_DIB` und als registriertes Format `PNG` — Discord
|
||
nimmt dann das verlustfreie PNG. Schriften kommen aus `C:\Windows\Fonts`
|
||
(Segoe UI, Consolas), mit Pillows Standardschrift als Ausweg. Prüfen:
|
||
Karten für Grenzfälle erzeugen und ansehen — volle Akte, leere, gefallen,
|
||
überlange Namen ohne Porträt; der Test überschreibt die Zwischenablage.
|
||
|
||
---
|
||
|
||
## 4. Release bauen, Installer und Updater
|
||
|
||
Ein Befehl erzeugt alles:
|
||
|
||
```
|
||
.venv\Scripts\python.exe werkzeuge\baue_release.py
|
||
```
|
||
|
||
Die angezeigte Version kommt aus `VERSION`, die Zählnummer für den
|
||
Update-Vergleich aus `BUILD` in `squad_manager.py` (Erkenntnis 20). Ergebnis in
|
||
`dist/` (nicht im Repository): aufbereitete Programmdateien, das
|
||
Update-Paket `SquadManager-<v>.zip`, der Installer
|
||
`SquadManager-Setup-<v>.exe` und `dist/server/` mit genau den
|
||
Dateien zum Hochladen samt `version.json` (Prüfsumme wird eingetragen).
|
||
|
||
**Installer:** Inno Setup 6.7.3 unter
|
||
`%LOCALAPPDATA%\Programs\Inno Setup 6\ISCC.exe`. Skript
|
||
`installer/setup.iss`; es kopiert die Dateien und ruft danach
|
||
`installer/einrichten.bat` auf, das venv, Pakete und Verknüpfungen
|
||
anlegt. Norton lässt Inno-Setup-EXEs durch — anders als PyInstaller.
|
||
`einrichten.bat` wird **direkt** aufgerufen, nicht über `cmd /c`: dort
|
||
scheitern die verschachtelten Anführungszeichen, das venv wurde dann still
|
||
nicht angelegt.
|
||
|
||
**Updater:** `pruefe_update()` holt beim Start
|
||
`https://sva.tyrveil.com/version.json`. Neuere Version → Hinweisbalken
|
||
unten. `lade_update()` prüft SHA-256, `spiele_update_ein()` entpackt und
|
||
startet `update_helfer.py` als eigenen Prozess. Nur `https://` wird
|
||
akzeptiert. Getestet: manipulierte Datei wird abgelehnt, Dateiersatz
|
||
funktioniert, `3.9 < 3.10` korrekt.
|
||
|
||
**Update-Helfer (seit 4.0):** `update_helfer.py`, nur Standardbibliothek.
|
||
Wartet auf das Ende des Programms (per Prozess-ID, keine geratene
|
||
Wartezeit), prüft per Schreibprobe, ob der Programmordner beschreibbar ist,
|
||
und kopiert. Ist er es nicht, startet er sich ein zweites Mal mit
|
||
Adminrechten (`ShellExecuteEx` mit `runas`), aber **nur zum Kopieren** —
|
||
das Programm startet danach wieder mit normalen Rechten. Scheitert es,
|
||
erscheint eine Meldung mit Link zum Installer (`installer` in
|
||
`version.json`), der Fehler steht im Log, und das Programm startet in der
|
||
alten Fassung. Das Programm prüft den Ordner schon vor dem Download und
|
||
kündigt die Windows-Abfrage an. Genommen wird der Helfer **aus dem neuen
|
||
Paket**, sonst der mitgelieferte; seine Aufrufparameter
|
||
`<quelle> <ziel> <pid> [<installer-url>]` sind damit eine Schnittstelle
|
||
und müssen gleich bleiben. Bis 3.4 war der Helfer eine Batchdatei, deren
|
||
`xcopy`-Fehler in `>nul` verschwanden. Test: Die Prüfskripte legen alles in
|
||
einem Testordner an; den Adminweg dort mit `verb="open"` statt `runas`
|
||
prüfen, sonst wartet ein UAC-Fenster auf einen Klick.
|
||
|
||
**Nachinstallation:** `start.pyw` installiert fehlende Pakete aus
|
||
`requirements.txt` beim Start nach, mit Hinweisfenster. Das liegt bewusst
|
||
dort und nicht im Update-Helfer: Bis 3.4 stammt der Helfer aus der *alten*
|
||
Fassung, `start.pyw` aus der neuen. So bekommt auch ein 3.2-Client, dessen
|
||
Helfer nichts von neuen Paketen weiß, später etwa Pillow für die Akte.
|
||
|
||
`installer/HOCHLADEN.txt` ist die Server-Anleitung für den Nutzer; der Bau
|
||
setzt die Version ein und legt sie nach `dist/server/`. `dist/server/` wird
|
||
bei jedem Bau gelöscht — nichts von Hand dort ablegen.
|
||
|
||
**Downloadseite:** Der Bau erzeugt aus `installer/downloadseite.html` die
|
||
Seite `index.html` samt `icon.png` für das Wurzelverzeichnis. Die Seite
|
||
liest beim Aufruf `version.json` und baut den Download-Knopf daraus
|
||
(Feld `installer`, sonst aus `datei` abgeleitet); die beim Bau eingesetzte
|
||
Version, Größe und das Datum sind nur Rückfallebene. Der Link für Freunde
|
||
ist damit dauerhaft `https://sva.tyrveil.com`, auch wenn beim Hochladen
|
||
nur `version.json` und die neuen Dateien erneuert werden. Mit Vorschau
|
||
für Discord (`og:`-Angaben) und Hinweis auf dem Handy, dass der Installer
|
||
nur unter Windows läuft. Lokal ansehen: `.claude/launch.json`,
|
||
Konfiguration „downloadseite" (Port 8765, liefert `dist/server/` aus).
|
||
Den Zweig „Server hat neuere Version" prüft man, indem man im Browser
|
||
`fetch` durch eine Attrappe ersetzt und das Seitenskript erneut ausführt —
|
||
lokal steht in `version.json` ja dieselbe Version wie in der Seite.
|
||
|
||
**Einzelschritte**, falls nötig: `werkzeuge/strip.py` entfernt
|
||
Kommentare, `werkzeuge/umlaute.py` setzt echte Umlaute. Danach
|
||
Zeilenenden vereinheitlichen (`.bat`/`.vbs`/`.txt` als CRLF, `.py` als LF)
|
||
und **jede BOM entfernen** — siehe Erkenntnis 7.
|
||
|
||
`werkzeuge/umlaute.py` arbeitet über `tokenize` und ersetzt nur in
|
||
STRING-Token. Achtung: In Python 3.12+ sind f-Strings **keine**
|
||
STRING-Token mehr, die müssen per Textersetzung nachbehandelt werden.
|
||
|
||
Weitere Hilfsskripte: `werkzeuge/mictest.py` prüft jedes Audiogerät in
|
||
einem eigenen Prozess mit Zeitlimit (ein hängendes Gerät blockiert sonst
|
||
alles), `werkzeuge/screenshot.py` nimmt das Fenster inklusive Titelleiste
|
||
auf.
|
||
|
||
---
|
||
|
||
### Server für Konten und Squads (ab 1.6.0)
|
||
|
||
PHP 8 ohne Framework in `server/`, getrennt nach Sichtbarkeit:
|
||
|
||
```
|
||
server/sva.tyrveil.com/ → /sva.tyrveil.com (Dokumentenstamm, öffentlich)
|
||
api/index.php Schnittstelle fürs Programm (POST, JSON)
|
||
api/bild.php Porträts, nur mit Token
|
||
konto/ Links aus Mails: bestätigen, Passwort, vergessen
|
||
verwaltung/ Admin-Oberfläche
|
||
einrichten.php Ersteinrichtung, nur mit Schlüssel aus config.php
|
||
server/sva-privat/ → /sva-privat, NEBEN dem Dokumentenstamm
|
||
app/ gesamte Logik
|
||
config.beispiel.php Vorlage; config.php liegt nur auf dem Server
|
||
daten/ Porträts, Fehlerlog (nicht im Repository)
|
||
```
|
||
|
||
Plesk: PHP 8.5, Dokumentenstamm `/sva.tyrveil.com`, Datenbank und Benutzer
|
||
`214729_sva` (MySQL/MariaDB). Das Datenbank-Passwort steht nur in
|
||
`sva-privat/config.php` auf dem Server — nie ins Repository, nie in den
|
||
Chat. Mails verschickt `mail()` über den Plesk-Mailserver mit Absender
|
||
`info@tyrveil.com`, ohne Postfach-Passwort. Verwaltungszugang:
|
||
`info@tyrveil.com`, Passwort über den Link aus `einrichten.php`.
|
||
|
||
**Schnittstelle:** `POST /api/` mit `{"aktion": …}`, Token im Kopf
|
||
`X-SM-Token` (nicht `Authorization`, das verschlucken Plesk-Setups gern).
|
||
Antwort `{"ok": true, …}` oder `{"ok": false, "fehler": code, "meldung":
|
||
Text}`. Die Aktionen stehen gesammelt in `app/api.php`.
|
||
|
||
**Regeln, die der Server durchsetzt:** Aktennummern vergibt der Server
|
||
(`SM-<Jahr>-<id>`), weil lokale Nummern bei allen Spielern mit 0001
|
||
beginnen. Speichern mit `basis_version`: Weicht sie ab, kommt `konflikt`
|
||
(409) mit dem Serverstand zurück. Ein Charakter ist in höchstens einem
|
||
Squad; Einladungen muss der Besitzer annehmen; nimmt er an, verfallen seine
|
||
anderen offenen Einladungen. Der Führer kann nur gehen, wenn er allein ist
|
||
oder die Führung übergeben hat; wird er gelöscht, übernimmt das
|
||
dienstälteste Mitglied. Porträts werden mit GD neu als PNG (≤ 512 px)
|
||
gespeichert, das Original verworfen. Token liegen nur als SHA-256 in der
|
||
Datenbank. Bremsen: Anmelden 10 je 15 min pro IP und Name, Registrieren 5
|
||
je Stunde pro IP, Verwaltung 8 je 15 min.
|
||
|
||
**Testen:** `werkzeuge/server_test.py` kopiert `server/` in einen
|
||
Testordner, nutzt SQLite und Mails als Dateien und spielt über 90 Fälle
|
||
durch — Einrichtung, Konten, Akten, Porträts, Squads, Verwaltung, Sperren,
|
||
Bremsen. Braucht `php` im Suchpfad (auf dem Entwicklungsrechner PHP 8.4 aus
|
||
winget). MySQL selbst ist lokal nicht testbar; `DB::sperre()` und
|
||
`DB::schemaAnlegen()` enthalten die Unterschiede.
|
||
|
||
---
|
||
|
||
## 5. Hart erkaufte Erkenntnisse
|
||
|
||
Diese Punkte wurden durch Fehlschläge gefunden. Wer sie „aufräumt", baut
|
||
die Fehler wieder ein.
|
||
|
||
**1 — `pythonw.exe` im venv ist ein Weiterleiter.**
|
||
Sie startet intern die Konsolenfassung `python.exe`, wodurch ein
|
||
Terminalfenster erscheint. Sie durch eine Kopie der echten `pythonw.exe`
|
||
zu ersetzen scheitert ebenfalls: Die Kopie findet ihre `python313.dll`
|
||
nicht (die liegt im Python-Ordner). **Lösung:** Die Verknüpfung startet die
|
||
echte `pythonw.exe` an ihrem Platz mit `start.pyw` als Argument;
|
||
`start.pyw` hängt `.venv\Lib\site-packages` selbst in `sys.path` ein.
|
||
|
||
**2 — Ein venv erbt die Tcl/Tk-Pfade nicht.**
|
||
`tkinter` findet `init.tcl` nicht und bricht mit `TclError` ab. Deshalb
|
||
läuft `_ensure_tcl_paths()` **vor** dem `tkinter`-Import und setzt
|
||
`TCL_LIBRARY`/`TK_LIBRARY` aus `sys.base_prefix`. Die ungewöhnliche
|
||
Importreihenfolge im Kopf der Datei ist Absicht.
|
||
|
||
**3 — Ein venv ist nicht portabel.**
|
||
`.venv\pyvenv.cfg` enthält feste Pfade. Auf einem anderen Rechner ist die
|
||
Umgebung unbrauchbar. Setup und Fehlersuche prüfen deshalb mit
|
||
`python -c "pass"`, ob sie überhaupt startet, und legen sie sonst neu an.
|
||
Das Weitergabepaket enthält kein `.venv`.
|
||
|
||
**4 — PortAudio-Geräteindizes wandern.**
|
||
Sie ändern sich, sobald ein Treiber dazukommt oder verschwindet. Deshalb
|
||
wird überall mit dem Anzeigenamen gearbeitet und der Index erst
|
||
unmittelbar vor dem Öffnen aufgelöst (`selected_device()`).
|
||
|
||
**5 — Windows meldet jedes Gerät über vier Schnittstellen.**
|
||
MME, DirectSound, WASAPI, WDM-KS. Beim Nutzer ergab das 18 Einträge für
|
||
2 echte Mikrofone. Regeln in `enumerate_inputs()`:
|
||
- WASAPI hat Vorrang, dann DirectSound, MME, WDM-KS
|
||
- MME kürzt Namen auf 31 Zeichen, deshalb Präfixvergleich in
|
||
`gleiches_geraet()`
|
||
- WDM-KS wird ausgeblendet, sobald WASAPI etwas liefert — dort erscheinen
|
||
Zweitnamen derselben Hardware (`wc19200_8211` war das Focusrite) und
|
||
Geräte, die in Windows gar nicht aktiv sind
|
||
- Platzhalter wie „Microsoft Soundmapper" werden entfernt
|
||
Ein Kontrollkästchen blendet die vollständige Liste wieder ein.
|
||
|
||
**6 — Batch: Pipe in `for /f`-Backticks ist unzuverlässig.**
|
||
Hat zweimal still Leerwerte geliefert (Größenangabe blieb 0, ein
|
||
Prozess-Kill lief ins Leere). PowerShell-Aufrufe in Batch deshalb **ohne
|
||
Pipe** schreiben, stattdessen `foreach` mit `if`.
|
||
|
||
**7 — PowerShell `-Encoding utf8` erzeugt in Windows PowerShell 5.1 eine BOM.**
|
||
VBScript bricht damit sofort ab (`Invalid character`, Zeile 1). Nach jeder
|
||
Bearbeitung von `.bat`/`.vbs` prüfen, dass keine BOM vorne steht.
|
||
|
||
**8 — Norton 360 verhindert PyInstaller-Builds.**
|
||
Der Build bricht mit `Permission denied` ab, unabhängig von Dateiname,
|
||
Zielordner und `--onefile`/`--onedir`. Eine fertige EXE wird beim Start
|
||
blockiert und gelöscht. Deshalb gibt es **keine EXE**; die Verteilung
|
||
läuft über Setup.bat und setzt Python beim Empfänger voraus. Eine
|
||
Norton-Ausnahme wäre nötig — das ist eine Sicherheitseinstellung und
|
||
bleibt die Entscheidung des Nutzers.
|
||
|
||
**9 — Der Windows-Audiodienst kann abstürzen.**
|
||
Ist auf diesem Rechner zweimal passiert. Dann scheitert jedes Audiogerät.
|
||
`audio_service_running()` prüft das beim Start und weist auf
|
||
`net start Audiosrv` hin (braucht Administratorrechte).
|
||
|
||
**10 — Squad heißt im Prozess `SquadGame-Win64-Shipping.exe`.**
|
||
Verglichen wird per Präfix `SquadGame`. Der frühere Vergleich über den
|
||
Fenstertitel war falsch: Er traf auch auf das eigene Programmfenster und
|
||
jeden Explorer-Ordner mit „Squad" im Namen zu.
|
||
|
||
**11 — Auf diesem Rechner gibt es zwei Python-Installationen.**
|
||
`python` zeigt auf die Microsoft-Store-Fassung (3.12), `py` auf die echte
|
||
3.13. Die Store-Fassung **virtualisiert `%APPDATA%`** — Zugriffe auf die
|
||
Konfigurationsdatei laufen dort ins Leere. Immer den venv-Interpreter
|
||
verwenden: `.venv\Scripts\python.exe`.
|
||
|
||
**12 — Layout: Die Statusleiste muss vor dem Notebook gepackt werden.**
|
||
Mit `side="bottom"`. Sonst nimmt das Notebook (`expand=True`) allen Platz
|
||
und die Knöpfe fallen aus dem Fenster. Genau das ist einmal passiert.
|
||
|
||
**13 — Norton bricht HTTPS auf.**
|
||
Verbindungen kommen mit einem Zertifikat „Norton Web/Mail Shield Root" an.
|
||
Windows vertraut ihm, Git mit seiner eigenen OpenSSL-Liste nicht
|
||
(`SSL peer certificate … was not OK`). Deshalb steht in der
|
||
Repository-Konfiguration `http.sslBackend=schannel` — Git nutzt dann den
|
||
Windows-Zertifikatsspeicher, die Prüfung bleibt aktiv. `winget` braucht
|
||
aus demselben Grund `--source winget`.
|
||
|
||
**14 — Der Projektordner gehört den Administratoren, nicht dem Nutzer.**
|
||
Git verweigert dann die Arbeit (`dubious ownership`). Abhilfe:
|
||
`git config --global --add safe.directory <Pfad>` für genau diesen Ordner.
|
||
Nach einem Umbenennen des Ordners muss der Eintrag neu gesetzt werden.
|
||
|
||
**15 — Inno-Setup-Konstanten genau lesen.**
|
||
`{userstartmenu}` ist der Startmenü-Stamm, `{userprograms}` der Ordner
|
||
„Programme" darin. Die Verknüpfung liegt in letzterem; der Deinstallierer
|
||
räumte deshalb eine Zeit lang daneben ab.
|
||
|
||
**16 — Installer-Tests nie mit der echten App-ID.**
|
||
Inno Setup führt pro App-ID genau einen Eintrag unter *Apps und Features*.
|
||
Ein Test mit `/DIR=` in einen anderen Ordner überschreibt den Eintrag der
|
||
echten Installation, und die Test-Deinstallation entfernt ihn dann ganz.
|
||
Für Tests eine Kopie von `setup.iss` mit eigener `AppId` übersetzen
|
||
(`SourceDir` auf `installer/` setzen, damit die relativen Pfade stimmen).
|
||
Auch stille Deinstallationen können Dialoge öffnen, wenn `[Code]` ein
|
||
normales `MsgBox` verwendet — dort immer `SuppressibleMsgBox`.
|
||
|
||
**17 — Neue Module an zwei Stellen eintragen.**
|
||
In `werkzeuge/baue_release.py` unter `PYTHON_DATEIEN`, sonst fehlen sie im
|
||
Paket, und in `start.pyw` unter `EIGENE_MODULE`. Fehlt der zweite Eintrag,
|
||
hält `start.pyw` einen Importfehler in einem eigenen Modul für ein
|
||
fehlendes Paket und versucht es per pip nachzuinstallieren.
|
||
|
||
**18 — ttk-Stile erben die Zustandsregeln des Themas.**
|
||
Ein eigener Stil wie `Haupt.TNotebook.Tab` übernimmt die `map`-Regeln von
|
||
`TNotebook.Tab`, bei *clam* auch einen eigenen Innenabstand für den
|
||
gewählten Reiter. Die Schrift sprang dadurch beim Umschalten um 4 Pixel.
|
||
Jede Zustandsregel, die man nicht will, im eigenen Stil ausdrücklich
|
||
überschreiben — und die Wirkung nachmessen, nicht nur ansehen.
|
||
|
||
**19 — Unter „Programme" scheitert der Updater still.**
|
||
Mit der Installer-Wahl „für alle Benutzer" landete das Programm unter
|
||
`C:\Program Files`. Es läuft ohne Adminrechte, `xcopy` bekam „Zugriff
|
||
verweigert", die Meldung ging in `>nul` unter, und der Helfer startete
|
||
danach die unveränderte alte Fassung. Ein Kollege des Nutzers sah so nach
|
||
„Jetzt aktualisieren" wieder 3.2. Nachgestellt und bestätigt. Behoben in
|
||
4.0 an drei Stellen: Installer nur noch pro Benutzer, Helfer holt sich bei
|
||
Bedarf Adminrechte fürs Kopieren, jeder Fehler wird gemeldet. Gilt nur für
|
||
Updates **ab** 4.0 — beim Update läuft immer der Helfer der alten Fassung.
|
||
|
||
**20 — Die angezeigte Version darf sinken, die Zählnummer nie.**
|
||
Nach 4.0 wollte der Nutzer zurück auf 1.x. Programme vergleichen aber die
|
||
Nummer vom Server mit ihrer eigenen; „1.5.0" wäre für 4.0 älter, das
|
||
Update käme nie an. Lösung seit 1.5.0: `VERSION` ist nur Anzeige, `BUILD`
|
||
eine Zählnummer ab 1, die jedes Release um eins erhöht. `version.json`
|
||
trägt `"anzeige"`, `"build"` und dauerhaft `"version": "4.1"` — Letzteres
|
||
ausschließlich für Programme bis 4.0, die nur dieses Feld kennen
|
||
(`VERSION_FUER_ALTE_PROGRAMME` im Bauskript, **nie senken**). Neue
|
||
Programme ohne `build` in der Datei vergleichen gegen
|
||
`LETZTE_ALTE_VERSION = "4.0"`. Der Bau warnt, wenn `BUILD` nicht höher ist
|
||
als online. Getestet mit dem echten `pruefe_update()` aus 3.3 und 4.0.
|
||
|
||
**21 — `php -S` hängt unter Windows nach vielen Verbindungen.**
|
||
Der eingebaute Entwicklungsserver nahm nach einigen hundert schnellen
|
||
Anfragen keine Verbindung mehr an, obwohl der Prozess lief – im Test sah das
|
||
aus wie „offline". Der Testserver in `server_test.py` startet deshalb für
|
||
jede Anfrage ein eigenes `php-cgi` hinter einem Python-`ThreadingHTTPServer`.
|
||
Bei rätselhaften Zeitüberschreitungen im Test zuerst das Protokoll
|
||
`php-server.log` im Testordner ansehen.
|
||
|
||
**22 — Änderungen nie am Zeitstempel erkennen.**
|
||
`geaendert` in der Akte ist nur sekundengenau. Der erste Abgleich verglich
|
||
ihn und übersah Änderungen in derselben Sekunde wie ein Abgleich – der
|
||
Zwei-Rechner-Test fand es. Seitdem vergleicht `abgleich.inhalt_hash()` den
|
||
Inhalt.
|
||
|
||
**23 — Der Release-Bau darf keine Bezeichner umschreiben.**
|
||
Der Bau setzt in Zeichenketten echte Umlaute ein. In 1.6.0 machte er so
|
||
aus der Aktion `"konto_loeschen"` ein `"konto_löschen"` – der Server hätte
|
||
„unbekannte Aktion" geantwortet. Alle Tests liefen gegen die Quelle und
|
||
waren grün. Seitdem überspringt `baue_release.ist_bezeichner()`
|
||
Zeichenketten aus Kleinbuchstaben, Ziffern und `_ . - /`. **Vor jedem
|
||
Release die Tests auch gegen das Paket laufen lassen:**
|
||
`SM_PROGRAMM=dist\paket\Programm` für `abgleich_test.py` und
|
||
`oberflaeche_test.py`.
|
||
|
||
---
|
||
|
||
## 6. Umgebung
|
||
|
||
- Windows 11 Pro, kein Git
|
||
- Python 3.13.0 unter `%LOCALAPPDATA%\Programs\Python\Python313`
|
||
- Norton 360 aktiv, Windows Defender dadurch abgeschaltet
|
||
- Audio: Focusrite USB (Hauptmikrofon) und SteelSeries Sonar (virtuell)
|
||
- Der Nutzer testet selbst und meldet zurück; er schließt das Fenster oft
|
||
zwischendurch — ein fehlender Prozess bedeutet nicht zwingend einen Fehler
|
||
|
||
---
|
||
|
||
## 7. Offene Punkte
|
||
|
||
**Design steht aus.** Der Nutzer hat mit Claude Design einen Entwurf
|
||
gebaut („Board mit bedienbarem Fenster"), der Export kam nie an — die ZIP
|
||
lag nicht in `Downloads`. Er soll sie erneut schicken. Der Auftrag dazu
|
||
steht in `Design-Briefing.md`: Teil A ein Design System, Teil B die beiden
|
||
Bildschirme. Wichtig beim Umsetzen: Was in `ttk` nicht geht (runde Ecken,
|
||
Schatten, Verläufe), lässt sich auf einer Zeichenfläche nachbauen — die
|
||
Pegelanzeige ist bereits so gelöst.
|
||
|
||
**Update-Weg von 3.2 ungetestet.** Online liegt noch die erste 3.2 unter
|
||
dem alten Namen `SquadVoiceActivation-3.2.*`. Der Nutzer hat seine
|
||
3.2-Installation gelöscht und installiert 3.3 frisch; der Weg 3.2 → 3.3
|
||
(alter Updater, Umbenennung) ist deshalb nie gegen den Server gelaufen.
|
||
Nach dem Upload von 3.3 die alten Dateien vom Server nehmen, damit niemand
|
||
mehr mit 3.2 anfängt. Den ersten echten Updater-Durchlauf lieferte dann
|
||
3.3 → 4.0.
|
||
|
||
**Stand auf dem Server (11. September):** 4.0 ist online, und zwar der
|
||
Bau mit neuem Updater, aber ohne Karte (Prüfsumme `79a10486…`). 3.4 kam
|
||
nie auf den Server, `dist/server-3.4/` ist hinfällig. Das nächste Release
|
||
ist 1.5.0 (Build 1) mit der Karte, siehe Erkenntnis 20. Noch online und
|
||
zu löschen: `SquadManager-3.3.*` und `SquadVoiceActivation-3.2.*`. Offen,
|
||
ob bei den Freunden die Nachinstallation von Pillow über `start.pyw`
|
||
geklappt hat (erstes Update mit neuem Paket).
|
||
|
||
**Stand 1.6.0:** Server eingerichtet und erreichbar (Tabellen bestätigt,
|
||
`einrichten.php` gelöscht). Vor dem Hochladen von 1.6.0 zuerst
|
||
`sva-privat/app` ersetzen – `charaktere.php` liefert neu die
|
||
`portraet_kennung`. Den Text aus `installer/DATENSCHUTZ-BAUSTEIN.md` muss der
|
||
Nutzer selbst in tyrveil.com/rechtliches einbauen (Laravel-Seite, kein
|
||
Zugriff). Offen: Unbestätigte Konten werden nicht automatisch gelöscht;
|
||
Konfliktdateien meldet das Programm nur in der Statuszeile.
|
||
|
||
**Installationen unter „Programme" (Erkenntnis 19).** Wer 3.x für alle
|
||
Benutzer installiert hat, kommt per Updater nicht weiter und muss 4.0 einmal
|
||
mit dem Installer einspielen. Der entfernt die alte Installation dabei
|
||
selbst. Dieser Weg ist **ungetestet**: Er braucht eine echte Installation
|
||
für alle Benutzer und eine Bestätigung im UAC-Fenster. Beim nächsten
|
||
Betroffenen, etwa dem Kollegen des Nutzers, auf die Rückmeldung achten.
|
||
|
||
**Vorfall 10. September:** Ein Installer-Test mit der *echten* App-ID
|
||
hatte den Eintrag der Nutzerinstallation unter *Apps und Features*
|
||
übernommen. Bereinigt; seitdem gilt Erkenntnis 16.
|
||
|
||
**Installer unsigniert.** Empfänger sehen beim ersten Start die
|
||
SmartScreen-Warnung. Abhilfe nur per Code-Signing-Zertifikat.
|
||
|
||
**Programm selbst bleibt Python.** Eine gebündelte EXE per PyInstaller
|
||
scheitert an Norton (Erkenntnis 8); der Installer setzt Python beim
|
||
Empfänger voraus — bewusste Entscheidung des Nutzers.
|
||
|
||
---
|
||
|
||
## 8. Arbeitsweise, die sich bewährt hat
|
||
|
||
Der Nutzer meldet Symptome, keine Diagnosen („es öffnet sich ein
|
||
Konsolenfenster", „so viele Mikrofone"). Mehrfach lag die Ursache woanders
|
||
als vermutet, deshalb: **erst messen, dann ändern.**
|
||
|
||
Drei Beispiele, in denen Messen die Annahme widerlegt hat:
|
||
|
||
- Das Konsolenfenster kam nicht vom Startskript, sondern von einem
|
||
Kindprozess. Sichtbar wurde das erst über `ParentProcessId`.
|
||
- „Alle Mikrofone scheitern" war kein Gerätefehler, sondern der
|
||
abgestürzte Audiodienst — gefunden im Windows-Ereignisprotokoll.
|
||
- Eine Prüfung auf sichtbare Konsolenfenster meldete Entwarnung, weil die
|
||
Fensterklasse von Windows Terminal fehlte. Der Nutzer sah das Fenster
|
||
trotzdem. Ein negativer Testbefund ist kein Beweis.
|
||
|
||
Änderungen immer an der **Quelle** vornehmen, dann das Paket neu erzeugen,
|
||
dann per `Update.bat` in die Installation bringen — und dort tatsächlich
|
||
starten. Ein Syntaxcheck reicht nicht: Mehrere Fehler zeigten sich erst
|
||
beim echten Doppelklick.
|