fix: the bugs and vulnerabilities SonarCloud reports on PR #216

pr-reviews/PR-264.md

@@ -0,0 +1,27 @@
+# Review PR #264 — AI braking: smaller steps, earlier, while approaching a stop or a lower speed
+
+Autor: @pwarszawski · base: `master` (zbudowany na #187 + #263 + #262) · przyrost: `Driver.cpp/.h`, ~+70/−10
+https://github.com/MaSzyna-EU07/maszyna/pull/264
+
+**Werdykt: Approve z uwagami (struktura logiki, stałe)**
+
+> Recenzja dotyczy tylko przyrostu ponad #263 (interdiff policzony lokalnie). Przyrost zawiera też zmianę z #262 (odluźniacz < 1 km/h) — po merge #262 zniknie z diffu.
+
+## Podsumowanie
+- Margines dociążenia hamulca przy dojeździe do niższej prędkości: pół stopnia zamiast pełnego (`brake_increase_margin()`).
+- Śledzenie „niedoboru” opóźnienia co 3 s (`fShortfall`, `iShortfallGrowth`) — rosnący niedobór przy nieruszanym kranie → mały stopień od razu.
+- `DecBrake()`: pozycja poniżej pierwszej traktowana jak pierwsza (minimalny stopień z #263).
+- Utrzymywanie prędkości na spadku: wzmocnienie ograniczone do `1/(3.6·horizon)`, czyli różnica zdejmowana w czasie reakcji hamulca.
+
+## Co jest dobrze
+- Każda zmiana ma uzasadnienie fizyczne w komentarzu.
+- Wynik na śliskim spadku wyraźny (defekty 7.0 % → 1.0 %, >30 m przed semaforem 7.3 % → 4.3 %).
+
+## Uwagi
+1. **Wyniki mieszane na suchym spadku.** „Stops more than 30 m short” 3.2 % → 5.4 % i defekty 3.9 % → 4.2 %. Przy 3 vs 4 przebiegach to może być szum — proszę podać rozrzut między przebiegami albo dorobić 4. przebieg, żeby porównanie było symetryczne.
+2. **Dwie ścieżki „dodaj stopień, bo pociąg nie nadąża”.** Jedna w `IncBrake()` (`fShortfall > 0.02 && fBrakeHeldTime > horizon`), druga w `control_braking_force()` (`iShortfallGrowth >= 2 && …`), która i tak woła `IncBrake()` przez `cue_action`. Trudno to śledzić — proszę o jeden helper typu `bool is_falling_behind() const` używany w obu miejscach, albo komentarz opisujący, jak się te warunki składają.
+3. **Deklaracja zapowiadająca `static brake_response_horizon(...)`** w środku pliku — lepiej przenieść definicję wyżej (lub wszystkie helpery do anonimowego namespace na początku pliku).
+4. **Magiczne liczby**: `0.02`, `0.005`, `3.0` s, `2` sprawdzenia, `0.04` — `constexpr` z nazwami (część jest współdzielona z #187/#265).
+5. **Zmiana w warunku `room`** (usunięcie `VelNext > 0.0`) zmienia też dojazd do *niższej prędkości* z już zaciągniętym hamulcem — opis PR o tym nie wspomina. Proszę dopisać jedno zdanie.
+6. **Zakres `brake_increase_margin()`** — tylko `TBrakeSystem::Pneumatic`; dla EP/ED zostaje pełny stopień. OK, ale warto to zaznaczyć w komentarzu (EP reaguje od razu, więc nie potrzebuje).
+7. Komentarze nowych pól w `Driver.h` są po angielsku, sąsiednie po polsku — drobne, jednolitość.