# 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
1. `BrakeForceR()` bierze próg rapidu z rozrządu (`TBrake::GetRapidRatio`, NESt3/ESt4: 50 km/h zamiast stałych 40 km/h).
2. 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`.
3. 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.
4. 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.

## Co jest dobrze
- 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.

## Uwagi do poprawy (Sonar / GCC — wg `CLAUDE.md`)
1. **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`).
2. **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)`.
3. **`&&` 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).
4. **S3608** — lambdy `fullbraking`/`travel` łapią `[&]`; jawne capture.
5. **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.
6. Funkcje `static` w pliku → anonimowy namespace (konwencja z `CLAUDE.md`).

## Uwagi merytoryczne / pytania
7. **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.
8. **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).
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ą.
10. **Konflikt z #205**: wspomniane w komentarzu `int autoswitch;` — dobrze, że pominięte; potwierdzić kolejność merge.
11. **Komentarze w `Driver.h`** dla nowych pól są po polsku, a w `.cpp` po angielsku — drobne, ale lepiej jednolicie.
12. Opis PR bardzo długi; do merge commitu warto dać streszczenie + link, a szczegóły pomiarów zostawić w PR.