VersaGUI/AGENTS.md

Arbeitsanweisungen für Coding-Agents

Diese Datei gilt für das gesamte VersaGUI-Repository.

Ziel und Nachbar-Repository

VersaGUI ist die Windows-/WinForms-Konfigurationsanwendung für VersaPad v2. Sie läuft auf .NET 7 und kommuniziert über feste 8-Byte-CDC-Pakete mit der Firmware im benachbarten, eigenständigen Repository ../VersaMCU.

DelphiGUI gehört nicht zum gepflegten Scope und darf bei Änderungen nicht als Referenz oder Ziel verwendet werden.

Vor Änderungen lesen

1. README.md
2. doc/INDEX.md
3. doc/00_architecture.md
4. bei Protokoll-/Layoutänderungen zusätzlich:
   • src/Protocol.cs
   • src/DeviceConfig.cs
   • ../VersaMCU/AGENTS.md
   • ../VersaMCU/doc/06_nvm_config.md
   • ../VersaMCU/doc/07_serial_protocol.md

Gemeinsame Binärverträge

• DeviceConfig muss exakt SDeviceConfig entsprechen: Config v3, 740 Byte.
• MacroTable muss exakt SMacroTable entsprechen: 512 Byte.
• Enum-Werte, Packing, Offsets, CRC-Bereich, Chunkgrößen und USB-IDs sind gemeinsame Verträge mit VersaMCU.
• Änderungen daran in beiden Repositories implementieren, dokumentieren, bauen und getrennt committen.
• Host-Command-IDs niemals ungeprüft als Shellkommando ausführen. Eine spätere Host-Aktionsfunktion benötigt ein explizites sicheres Mapping.

Threading und Transfers

• WinForms-Controls ausschließlich auf dem UI-Thread anfassen.
• SerialManager.ReadLoop() läuft im Hintergrund und postet Events über den SynchronizationContext.
• SerialPort-Pakete müssen unter dem Write-Lock vollständig geschrieben werden.
• Config-/Makrotransfers nicht parallel ausführen.
• Dumps und Uploads nur akzeptieren, wenn Chunkzahl, Indizes und Vollständigkeit stimmen.
• DTR muss vor SerialPort.Open() aktiviert sein.

Verifikation

Mindestens:

dotnet build src/VersaGUI.csproj --no-restore
dotnet run --project tests/VersaGUI.ContractTests/VersaGUI.ContractTests.csproj
git diff --check

Bei gemeinsamen Vertragsänderungen zusätzlich:

pio run -d ../VersaMCU -e versapad

Die Contract-Tests prüfen Config-/Makrogrößen, CRC, Feldvalidierung, Chunkvollständigkeit und Host-Command-Payloads. Sie ersetzen keinen Test mit angeschlossenem Board.