72 lines
2.5 KiB
Markdown
72 lines
2.5 KiB
Markdown
# 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. `doc/07_known_limitations.md`
|
|
5. 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.
|
|
- Das Binärmodell akzeptiert alle Firmware-Animationen `0..6`; der aktuelle
|
|
`ActionDialog` bietet davon nur Static, Blink, Pulse und ColorCycle an.
|
|
Bestehende, im Dialog nicht angebotene Werte nicht stillschweigend
|
|
überschreiben.
|
|
|
|
## 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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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.
|