Review PR #187 — AI braking: descents, approaches to a lower speed, and stopping 8-15 m short of a signal

Autor: @pwarszawski · base: master (merge-base 66a940d, 21.10) · 6 plików, +319/−54 · Fixes #180 https://github.com/MaSzyna-EU07/maszyna/pull/187

Werdykt: Approve kierunku; Request changes — poprawki pod Sonar/GCC przed merge

To jest podstawa stosu #187 → #263 → #264 → #265. Recenzje tamtych PR-ów dotyczą tylko ich przyrostu ponad ten PR.

Podsumowanie

BrakeForceR() bierze próg rapidu z rozrządu (TBrake::GetRapidRatio, NESt3/ESt4: 50 km/h zamiast stałych 40 km/h).
Utrzymywanie prędkości na spadku: horyzont przewidywania = połowa czasu reakcji hamulca (brake_response_horizon), ciągłe prawo regulacji zamiast skoku hamuj/jedź, rozdzielenie AccDesired (tylko hamulec) i fAccDesiredGravity.
Planowanie dojazdu z tablicy hamowania składu (shaped_braking_demand — bisekcja po stopniu hamowania), zatrzymanie 8–15 m przed semaforem, na wzniesieniu trzymanie składu hamulcem zespolonym.
Brak „puszczania” hamulca w strefie zbliżenia przy dojeździe do niższej prędkości; próba hamowania nie nadpisuje stopu/ograniczenia przed pociągiem.

Wyjątkowo rzetelna metodyka: 32 składy × 4 profile, czas rzeczywisty i x20, recheck na aktualnym master, testy na śliskiej szynie (0.3/0.5), konsultacja z youBy. Wyniki jednoznaczne (np. spadek: defekty 21/32 → 5/32, przejechania semafora 4 → 0).
Zmiany predykcji (GetRapidRatio) zrobione wirtualnie w TBrake z domyślną dotychczasową aproksymacją — inne rozrządy bez zmian.
Dobrze opisane znane ograniczenia (Rlmmp, 764, 413S/AL2) zamiast ich zamiatania.

S107 — shaped_braking_demand() ma 8 parametrów (limit 7). Proponuję struct, np. consist_brake_table { double vmax; std::span<double const> a0, a1; } — przy okazji znikną surowe wskaźniki na tablice C (double const *Brakea0).
S3358 — zagnieżdżony ?: w brake_response_horizon() (… ? BrakeDelay[isrelease ? 0 : 1] : BrakeDelay[isrelease ? 2 : 3]). Ten sam wybór „opóźnienie napełniania wg G/P” pojawia się też w IncBrake() i control_braking_force() — warto helper brake_fill_time(Vehicle) / brake_release_time(Vehicle).
&& mieszane z || bez nawiasów w control_tractive_force() (velocity + 1.0 < VelNext || VelNext == 0.0 && … && …) — GCC -Wparentheses i Sonar. Proszę dodać nawiasy (bez zmiany semantyki).
S3608 — lambdy fullbraking/travel łapią [&]; jawne capture.
S134/S3776 — adjust_desired_speed_for_target_speed() było już mocno zagnieżdżone, nowy blok „final approach” dokłada 2–3 poziomy. Wydzielenie gałęzi pociągowej (Obey_train) do osobnej metody, np. final_approach_demand(vel, stoppingroom), i bloku „uphill coasting” (powtarza się 2×, różni się tylko offsetem) do helpera.
Funkcje static w pliku → anonimowy namespace (konwencja z CLAUDE.md).

Przełącznik w eu07.ini? CLAUDE.md: zmiana tego, co symulator robi z istniejącymi sceneriami, ma się dać wyłączyć. Tu można bronić tezy, że to poprawka błędów (przejechania semafora, piłowanie hamulcem), ale skala zmiany zachowania AI jest duża (np. zatrzymanie 8–15 m zamiast dotychczasowych marginesów zależnych od długości). Proszę maintainerów o świadomą decyzję: poprawka vs. funkcja z przełącznikiem.
Koszt obliczeń. shaped_braking_demand = do 30 iteracji bisekcji × 24 kroki całkowania, wołane do 2× na przebłysk AI. Przy scenerii z kilkudziesięcioma składami AI to wciąż mało, ale warto zmierzyć (profiler na l053_poludnie) albo zmniejszyć liczbę iteracji (tolerancja ~0.01 osiągana po ~9).
Magiczne liczby: 0.025 (próg „pod górę”), 0.15, 3.5, 50.0, 0.04, 15.0/7.5 — przynajmniej te używane w kilku miejscach jako constexpr z nazwą.
Konflikt z #205: wspomniane w komentarzu int autoswitch; — dobrze, że pominięte; potwierdzić kolejność merge.
Komentarze w Driver.h dla nowych pól są po polsku, a w .cpp po angielsku — drobne, ale lepiej jednolicie.
Opis PR bardzo długi; do merge commitu warto dać streszczenie + link, a szczegóły pomiarów zostawić w PR.