maszyna/TURNOUT_REDESIGN.md

# Rozjazdy — jak to powinno być zrobione

Dokument projektowy, nie opis stanu. `TURNOUT_SPEC.md` mówi, co edytor oddaje
runtime'owi; ten mówi, **jak edytor powinien trzymać rozjazd u siebie**, bo obecny
model się nie broni i każda kolejna funkcja jest w nim przypadkiem szczególnym.

## 1. Co jest dziś

Fakty, nie opinie:

- `NiweletaSpec` = lista **prostych zakotwiczonych w XY** + `fits` w lukach między
  kolejnymi prostymi. Krzywa nie jest bytem — jest wynikiem wpasowania w lukę.
- `Junction` (rozjazd) to **relacja** na niwelecie zasadniczej: stacja + liczby
  katalogowe. Kładzie własną ścieżkę odgałęzienia (`lay_turnout`), ale ta ścieżka
  **nie należy do żadnej niwelety** — jest rysowana osobno z `JunctionGeom`.
- Odnoga to osobna niweleta, **przypinana sztywno** do krzyżownicy przy każdym
  rozwiązaniu (`pin_branch_to_frog`).
- Równolegle istnieje `BasketDraft` (395 linii) — drugi, własny mechanizm
  budowania krzywych, nie przechodzący przez model luk.
- `Junction` niesie **jednocześnie** liczby katalogowe (skos, R, długość, iglica)
  i swobodną krzywą wewnętrzną (`GapFit curve` z dowolnym koszem).
- Rozjazdy są serializowane **pozycyjnie i ręcznie**. `pre_blade`, `blade_angle`
  i `blade_length` nie są zapisywane w ogóle — doszły do modelu i wypadły z pliku.

## 2. Cztery przyczyny źródłowe

**2.1. Geometria rozjazdu leży poza grafem toru.**
Tor zasadniczy nie jest dzielony (słusznie), ale odgałęzienie rozjazdu nie należy
do niczego, a odnoga jest osobnym bytem. Ciągłość między krzyżownicą a odnogą nie
wynika z konstrukcji, tylko z **doklejania jej z powrotem przy każdym solve**.
Stąd błąd „odnoga uciekła 1,4 km", stąd konieczność oddawania `pinned` do
dokumentu, stąd szkic startujący ze starego miejsca.

**2.2. Krzywa jest obywatelem drugiej kategorii.**
Model brzmi „proste i luki między nimi". Wszystko, co nie jest łukiem między
dwiema prostymi, wymaga wyjątku: ukryta prosta-prowadnica, tryb 5, `BasketDraft`.
Dlatego „dodaj łuk wprost z krzyżownicy" było trudne — w danych **nie ma jak
powiedzieć „element: łuk, zaczyna się tutaj"**.

**2.3. Dwa źródła prawdy o współrzędnych.**
Dokument trzyma to, co narysowane; solver trzyma przypięte i przycięte
(`rendered_straights`). GUI czyta raz jedno, raz drugie. Stąd łuk startujący z
azymutem 0 i cała rodzina błędów „to nie jest tam, gdzie jest narysowane".

**2.4. Typ katalogowy zmieszany z egzemplarzem.**
„Rz 1:9 R190" ma geometrię **określoną przez typ**. Pozwalanie, by egzemplarz
miał dowolny łuk koszowy w środku, jest bez sensu — a jednocześnie to, co
naprawdę jest swobodne (dokąd biegnie tor za krzyżownicą), było najtrudniejsze do
edycji. Skutek uboczny: każda liczba katalogowa to kolejne pole doklejane do
formatu pliku.

## 3. Model docelowy

### 3.1. KR jest prostą  *(zrobione)*

Najprostsze możliwe ujęcie, i to ono wygrało: **koniec rozjazdu to zwyczajna
prosta**, tylko inaczej związana niż narysowana ręcznie.

```
StraightSpec {
    ...
    int frog_of;   // indeks rozjazdu, którego KR opuszcza ta prosta; -1 = zwykła
}
```

Początek i kierunek pisze solver z krzyżownicy, długość zostaje jej własna.
I to wszystko — **łuk za rozjazdem przestaje istnieć jako pojęcie**. Jest fitem w
luce między dwiema prostymi, jak każdy inny: to samo combo, ten sam promień, ten
sam kosz, ten sam komunikat „does not fit".

Styczność w krzyżownicy nie jest pilnowana, tylko **wynika**: prosta z KR leży na
stycznej, a fit między prostymi jest styczny z definicji.

Skasowało to: przypinanie całej odnogi, tryb 5, ukrytą kotwicę, `LeadArc`,
`StartPose` i cały `pose_fitter`. Odnoga przestała być bytem specjalnym — jest
niweletą, której pierwsza prosta ma jedną więź więcej.

Efekt uboczny, ważniejszy niż czystość: **to, co narysowane, zostaje tam, gdzie
narysowane**. Wcześniej cała odnoga jechała sztywno za krzyżownicą.

### 3.2. Element  *(do zrobienia, ale już nie dla rozjazdów)*

„Proste i luki" nadal wymaga wyjątku wszędzie tam, gdzie krzywa ma istnieć sama
z siebie — stąd `BasketDraft`. Docelowo prosta, łuk i klotoida są równorzędnymi
elementami ciągu, a to, co dziś robi szkic kosza, jest zwykłym dokładaniem
elementów. Rozjazdów to już nie dotyczy: 3.1 załatwiło je bez tego.

### 3.3. Rozjazd jako urządzenie typu  *(do zrobienia)*

Rozdzielić dwie rzeczy, dziś zlepione w `Junction`:

```
TurnoutType {                    // katalog, dane z Id-1, niezmienne
    name, crossing_n, radius, length,
    pre_blade, blade_angle, blade_length, rail_profile
}

TurnoutPlacement {               // to, co edytuje użytkownik
    type : TurnoutTypeRef        // po nazwie, nie przez kopiowanie liczb
    on : AlignmentRef, station, hand : L|P, facing
}
```

**Strefa rozjazdu jest nienaruszalna, bo jest egzemplarzem typu.** Nie da się jej
edytować, bo nie ma czego — liczby należą do typu. Rozjazd nietypowy to własny
typ, nie dowolność w egzemplarzu.

Serializacja przestaje puchnąć: egzemplarz zapisuje `type` po nazwie plus
umiejscowienie. Nowa liczba katalogowa (jak dzisiejsze `blade_angle`, które wciąż
nie trafia do pliku) idzie do katalogu i **nie dotyka formatu**.

## 4. Co to naprawia — konkretnie

| dzisiejszy problem | dlaczego znika |
|---|---|
| odnoga ucieka / dryfuje od krzyżownicy | start odnogi jest referencją do portu |
| szkic z azymutem 0 | nie ma drugiego źródła współrzędnych |
| „robi się sztywna prosta" za rozjazdem | pierwszy element odnogi może być łukiem |
| łuk wymaga dwóch prostych | element powstaje z pozy i punktu |
| kosz w środku „Rz 1:9" | geometria wewnętrzna należy do typu |
| liczby iglicy nie zapisują się | egzemplarz odwołuje się do typu po nazwie |
| `BasketDraft` obok modelu | kosz to ciąg elementów-łuków, nic osobnego |

## 5. Etapy

1. ~~Odnoga przestaje być przypinana~~ — **zrobione** przez 3.1: `frog_of`.
   Zniknęły `pin_branch_to_frog`, tryb 5, ukryta kotwica, `LeadArc` i
   `pose_fitter`.
2. **Typ oddzielony od umiejscowienia** (3.3). Katalog Id-1 jako dane; egzemplarz
   trzyma nazwę typu. Naprawia przy okazji serializację liczb iglicy.
3. **Elementy pierwszej kategorii** (3.2) i wycofanie `BasketDraft` — 395 linii
   równoległego świata.

## 6. Co zostaje bez zmian

Warto powiedzieć wprost, bo to nie jest przepisywanie wszystkiego:

- `domain::lay_turnout` i cała geometria rozjazdu — dobre, zostaje.
- `TurnoutPart` i punkty konstrukcyjne (`JunctionMark`) — zostają.
- `fit_arc_from_pose`, `fit_arc_from_pose_through` — to **są** właściwe prymitywy
  nowego modelu, przechodzą nietknięte.
- `GapFitter` i fitowanie między prostymi — zostaje, jako jeden ze sposobów
  wyznaczania elementu swobodnego.
- Rysowanie szyn, kafle, georeferencja — bez związku.

Do wyrzucenia jest przede wszystkim **klej**: przypinanie, ukryte prowadnice,
tryb 5 jako wyjątek i `BasketDraft`.