Inżynieria · ArbeitszeitCheck

Anatomia odbicia offline

30 października 2026 · Software by Design

12:07, brama budowy, brak zasięgu. Pracownik odbija wejście mimo to. Oto wszystko, przez co przechodzi to odbicie, zanim wyląduje w rejestrze czasu, i gdzie mogło pójść nie tak.

Minuta zero: telefon nie sięga serwera

Aplikacja mobilna nie ponawia na ślepo i nie udaje sukcesu. Odbicie trafia do szyfrowanej kolejki FIFO na urządzeniu, szyfrogram AES-GCM w AsyncStorage, klucz danych w SecureStore. Ten ostatni szczegół ma konkretny powód: SecureStore ogranicza wartości do około dwóch kilobajtów na Androidzie, więc oczywista konstrukcja (kolejka w SecureStore, koniec tematu) nigdy nie była dostępna. Sama kolejka ma limit 32 pozycji, ograniczony bufor, nie nieskończona obietnica. Optymistyczny status pokazuje pracownika jako „odbitego” od razu. Kolejka opróżnia się, gdy wróci zasięg.

Opróżnianie jest celowo drobiazgowe: aplikacja robi zrzut kolejki pod mutexem, wykonuje pracę sieciową poza blokadą, a potem scala wynik z powrotem, dzięki temu odbicie dodane do kolejki w trakcie opróżniania nie zostaje nadpisane przez scalenie. To klasa błędów, którą znajduje się tylko będąc paranoicznie ostrożnym wobec współbieżnych zapisów.

Odtworzenie: najpierw rezerwacja, potem mutacja

Gdy odbicie w końcu dociera do serwera, niesie dwie rzeczy, których zwykłe odbicie nie ma: clientRequestIdcodeoccurredAt i znacznik czasu payload_hashcodeoccurredAt. Serwer nie stosuje go od razu. Najpierw zapisuje wiersz rezerwacji„ten identyfikator żądania jest już mój, wynik w toku”. Dopiero potem mutuje rejestr czasu. Jeśli dwa retrysy się ścigają, drugi trafia na zajętą rezerwację i dostaje wynik pierwszej próby zamiast podwójnego odbicia.

Wiersz rezerwacji niesie failedcode, sha256 z akcji i jej znormalizowanych wejść. Ten sam identyfikator żądania z inną treścią odpowiada 409, nie cichym nadpisaniem: klient, który ponawia „odbij wejście” i przypadkiem wysyła „odbij wyjście”, dostaje błąd, który widać, a nie uszkodzone dane. Rezerwacje wiszące dłużej niż 300 sekund są przejmowane. Całe okno odtwarzania to siedem dni, po których zadanie porządkowe usuwa wiersze.

Czyj zegar się liczy

Zegary telefonów dryfują i można je celowo cofnąć, więc zgodność liczy się na code, moment, w którym pracownik faktycznie odbił, a nie na czasie dotarcia. Jak daleko serwer ufa temu znacznikowi, to ograniczone ustawienie administracyjne: konfigurowalny skew od 24 do 72 godzin wstecz i pięć minut w przód. Sufit jest celowy. Odbicie „z zeszłego czwartku” wymaga człowieka, który na nie spojrzy, a nie algorytmu, który mu uwierzy.

Ścieżka kiosku dostaje ten sam kontrakt z własnymi haczykami: szyfrowana pamięć podręczna kart NFC (TTL siedem dni, limit 500 pozycji), by terminal na korytarzu w piwnicy nadal otwierał właściwy ekran akcji podczas awarii, a udane opróżnienie zapisuje nowy status z powrotem w tej pamięci, inaczej następna awaria zaoferowałaby pracownikowi akcje, które już są błędne.

Czego wciąż brakuje, zapisane

Dwie luki. Odbicie, które pada na stałe, zostaje w kolejce z flagą code, użytkownik widzi toast, ale interfejsu ponowień per wiersz jeszcze nie ma. A stare wersje aplikacji, które nie znają nowych pól, po prostu odbijają tylko online. Nic się nie psuje, tylko tracą funkcję. Obie są zapisane w dokumencie decyzji, bo najgorszy rodzaj ograniczenia to ten, którego nikt nie udokumentował.

Pełna dokumentacja decyzji, włącznie z kolejnością blokad i zadaniem porządkowym, leży w repozytorium, które AGPL gwarantuje Państwu prawo do lektury. To druga połowa odpowiedzi tego wpisu: kolejka nie tylko jest zbudowana tak, by przetrwać martwą strefę, jest udokumentowana tak, by Państwo mogli to zweryfikować.