maszyna/pr-reviews/PR-172.md

# Review PR #172 — UART MaSzyna Hardware Protocol v2

Autor: @Hirek193 · base: `master` · 34 pliki, +4860/−185 · ostatnia aktualizacja 10.10
https://github.com/MaSzyna-EU07/maszyna/pull/172

**Werdykt: Request changes — konflikty, wątek startowany zawsze, brak testów kodeka**

> Przegląd wyrywkowy: architektura, `hardware_manager`, `protocol_codec`, konfiguracja, zmiany w `Train.cpp`/`zmq_input`. `protocol_session.cpp` (1327 linii) tylko pobieżnie.

## Podsumowanie
Nowy podsystem `hardware/`: transport (serial, przygotowany pod TCP), kodek ramek (COBS + CRC32C), sesja protokołu z heartbeatem, rejestry stanów/komend/symboli, subskrypcje, panel diagnostyczny w UI. Wspólny rejestr stanu `TrainState` używany też przez ZMQ. Nowe klucze `uart2*` w `eu07.ini`; stary UART działa bez zmian.

## Co jest dobrze
- Przemyślany protokół z dokumentacją na wiki i biblioteką Arduino.
- Kodek ostrożny wobec danych z portu: `cobs_decode` sprawdza `index + runlength > Size`, `reader::require()` przed odczytem, limit rozmiaru ramki, CRC32C. ✔
- Stary UART nietknięty, nowy włączany osobnymi kluczami — zgodne z zasadami kompatybilności `eu07.ini`.
- `get_engine_voltage()` wydzielone z `TTrain::Update()` bez zmiany logiki (sprawdziłem gałęzie: ED → `|Im·5|`, `Mn > 0 && |Im| > 0` → wzór, inaczej 0). ✔
- ZMQ: nazwy pól wyjściowych zachowane w rejestrze (sprawdziłem m.in. `shp`, `springbrake_active`, `hv_current_3`, `time_millisecond_of_day`). ✔

## Uwagi blokujące
1. **Konflikty** — GitHub pokazuje stan `dirty`, ostatnia aktualizacja 10.10. Rebase na aktualny `master`.
2. **Wątek roboczy startuje zawsze.** `WITH_HARDWARE_PROTOCOL_V2` jest domyślnie `ON`, a `hardware_manager` uruchamia `std::thread` „even with no links configured” i co kilka sekund skanuje porty szeregowe. U każdego gracza, który nie ma żadnego sprzętu. Na Windows enumeracja COM-ów (np. porty Bluetooth) potrafi trwać, a dla niektórych sterowników jest widoczna. `CLAUDE.md`: nowa funkcja ma się dać wyłączyć i bez niej ma być jak dawniej. Proponuję startować wątek dopiero gdy jest `uart2` w `eu07.ini` albo gdy użytkownik otworzy panel diagnostyczny.
3. **Testy jednostkowe kodeka.** `protocol_codec` (COBS, CRC32C, `frame_decoder::feed`, reader/writer) to czyste funkcje — idealne do `tests/unit`. Proszę o testy: round-trip, ramka uszkodzona/ucięta, przekroczony limit rozmiaru, sklejone ramki w jednym `feed()`. To kod parsujący dane z zewnątrz, więc testy są tu szczególnie ważne.

## Pozostałe uwagi
4. **Sonar / `CLAUDE.md`:**
   - `std::thread` → `std::jthread` (S6168; tutaj wątek jest zawsze joinowany w destruktorze, więc zamiana bezpieczna),
   - `std::lock_guard` → `std::scoped_lock` (S5997),
   - `s_instance` — globalny wskaźnik na singleton (S5421); rozważyć przekazanie przez `drivermode_input`,
   - `protocol_session.cpp` 1327 linii — prawie na pewno S3776/S134; proszę przejrzeć raport Sonara po rebase.
5. **`uart2ratelimit`** czyta 3 wartości bez walidacji (w odróżnieniu od pozostałych kluczy z `ParseOneClamped`) — wartości ujemne/zero mogą zablokować komunikację.
6. **Refaktor ZMQ w tym samym PR.** Przeniesienie pól ZMQ do wspólnego rejestru jest sensowne, ale zmienia działające API dla istniejących klientów. Proszę potwierdzić test z realnym klientem ZMQ (np. pulpit z kolejki SOPI) albo wydzielić do osobnego PR-a.
7. **`version_info.h.in` / gałąź w `VERSION_INFO`** — niezwiązane z UART, a zmienia linię wersji w logu. W CI (detached HEAD) `rev-parse --abbrev-ref HEAD` zwróci `HEAD`. Osobny mały PR.
8. Opis PR to tylko 2 linki — dopisać: co testowano (jaki sprzęt, ile linków naraz, reconnect po wypięciu kabla), wpływ na wydajność, i że stary `uart` działa obok (na różnych portach).
9. Komentarze po polsku bez polskich znaków (`napiecie`, `pradu`) — drobne, ale reszta kodu używa UTF-8.