maszyna/pr-reviews/PR-264.md

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ść.