# Przebieg obsługi kierowcy

Strona opisuje kolejne ekrany kiosku i warunki przejść między nimi. Jest dla programistów, którzy zmieniają przepływ, i dla osób, które diagnozują zgłoszenia kierowców.

Cały przepływ obsługuje jeden kontroler, `AppController`. Stan kierowcy trzyma obiekt `SessionData` zapisany w sesji HTTP.

## Przepływ

```
flowchart TD
    start["/ ekran startowy i wybór języka"] --> step["/selectStepType"]
    step --> input["/inputData numer rejestracyjny"]
    input -->|"jeden transport albo wybór automatyczny"| accept{"BHP wymagane?"}
    input -->|"kilka transportów, wybiera kierowca"| select["/selectTransport"]
    input -->|"brak, za wcześnie, za późno"| fail["/validationFalse"]
    input -->|"wyjątek"| err["/error"]
    select --> accept
    accept -->|"tak"| cond["/acceptConditions"]
    accept -->|"nie"| sms["/inputSms"]
    cond --> sms
    sms -->|"poprawny kod"| done["/end"]
    sms -->|"zły kod, są próby"| sms
    sms -->|"zły kod, brak prób"| fail
    classDef problem stroke:#d9534f,stroke-width:2px;
    class fail,err problem
```

Czerwone obramowanie oznacza ekran kończący obsługę błędem.

## Ekrany

| Adres | Co się dzieje |
| --- | --- |
| `/` | ekran powitalny z wyborem języka, kończy poprzednią sesję |
| `/selectStepType` | wybór typu kroku, gdy `KIOSK_SELECT_STEP_TYPE=true`, w przeciwnym razie przekierowanie do `/inputData` |
| `/inputData` | wpisanie numeru rejestracyjnego, wysłanie formularza szuka transportu w Apollo |
| `/selectTransport` | lista transportów, gdy numer pasuje do kilku i `KIOSK_AUTO_SELECT_EARLIEST=false`, posortowana po początku okna czasowego |
| `/transportSelected` | wybór jednego transportu z listy, parametr `transportId` |
| `/acceptConditions` | dokument PDF z BHP w języku kierowcy, tylko gdy `REQUIRE_ACCEPTATION=true` |
| `/documentAccepted` | zapamiętanie akceptacji i przejście do `/inputSms` |
| `/inputSms` | GET wysyła kod SMS, POST sprawdza kod wpisany przez kierowcę |
| `/end` | potwierdzenie rejestracji, kończy sesję |
| `/validationFalse` | komunikat o nieudanej weryfikacji, kończy sesję |
| `/error` | ogólny komunikat o błędzie |

Dwa dodatkowe adresy zwracają pliki z dysku serwera:

| Adres | Plik |
| --- | --- |
| `/customerLogo` | obraz PNG ze ścieżki `CUSTOMER_LOGO_SOURCE` |
| `/customerDocumentPdf/{plik}` | dokument PDF z katalogu `ACCEPTATION_FILES_PATH` |

Pliki dokumentów BHP nazywamy kodem języka, np. `pl.pdf`, `en.pdf` i `ukr.pdf`.

## Wyszukanie transportu

Wysłanie formularza z numerem rejestracyjnym woła `ApolloService.getTransports`. Numer jest zamieniany na wielkie litery, a spacje są usuwane. Rezultat zależy od liczby znalezionych transportów.

| Wynik | Następny ekran |
| --- | --- |
| jeden transport | `/acceptConditions`, gdy BHP wymagane, w przeciwnym razie `/inputSms` |
| kilka transportów | `/selectTransport`, a przy `KIOSK_AUTO_SELECT_EARLIEST=true` kiosk obsługuje transport z najwcześniejszym oknem i pomija listę |
| brak transportów | `/validationFalse` z błędem `TRANSPORT_NOT_FOUND` |

Zasady, według których kiosk odrzuca i wybiera transporty, opisują sekcje "Filtrowanie transportów" i "Dwa zapytania i wybór transportu" na stronie [Integracja z Apollo i SMS](<https://docs.logintegra.com/infokiosk/integracja/index.md>).

## Błędy weryfikacji

Ekran `/validationFalse` dostaje typ błędu i pokazuje odpowiedni komunikat.

| Typ błędu | Przyczyna |
| --- | --- |
| `TRANSPORT_NOT_FOUND` | Apollo nie zwróciło transportu albo żaden nie ma okna czasowego w magazynach kiosku |
| `TRANSPORT_OUTSIDE_OF_INTERVAL` | Apollo odpowiedziało kodem 302 z opisem błędu |
| `DRIVER_TOO_EARLY` | koniec najbliższego okna czasowego jest późniejszy niż teraz plus `KIOSK_TIME_WINDOW_INTERVAL` godzin |
| `DRIVER_TOO_LATE` | początek najbliższego okna czasowego jest wcześniejszy niż teraz minus `KIOSK_TIME_WINDOW_INTERVAL` godzin |

W obu komunikatach o czasie kiosk pokazuje kierowcy okno czasowe, które znalazł. Po błędzie kierowca wraca na ekran startowy i próbuje ponownie.

## Kod SMS

Pierwsze wejście na `/inputSms` generuje kod i wysyła go przez mikroserwis SMS. Kod ma `KIOSK_SMS_CODE_LENGTH` znaków i składa się z wielkich liter oraz cyfr. Kolejne wejścia na ten adres w tej samej sesji nie wysyłają SMS ponownie.

Porównanie kodu nie rozróżnia wielkości liter. Po złym kodzie licznik prób rośnie, a kiosk pokazuje ekran kodu jeszcze raz. Gdy licznik osiągnie `KIOSK_MAX_NUMBER_OF_SMS_RETRIES`, kolejny zły kod kończy obsługę na `/validationFalse`.

Przy domyślnej wartości `1` kierowca ma więc dwie próby wpisania kodu.

## Potwierdzenie w Apollo

Poprawny kod uruchamia dwa wywołania do Apollo. Najpierw kiosk potwierdza status przyjazdu transportu. Jeśli kierowca zaakceptował dokument BHP, kiosk potwierdza też warunki.

Błąd potwierdzenia statusu przerywa obsługę i kieruje na `/error`. Błąd potwierdzenia warunków BHP trafia tylko do logu, a obsługa kończy się na `/end`.
