InnerWeb
Przejdź do treści

Dobre praktyki kolejki offline w aplikacji terenowej

Inspektor na obchodzie traci zasięg w piwnicy, na dachu i w hali ze stalową konstrukcją, a zapisy z formularza nie mogą zginąć. Poniżej praktyki projektowania kolejki offline, dzięki której serwer nie dostaje duplikatów, a użytkownik widzi, co już dotarło, a co jeszcze czeka.

13 dni
domyślne czyszczenie rekordów idempotencji
Źródło: karta
4
stany zapisu widoczne dla użytkownika
Źródło: karta

Co kolejka offline robi w aplikacji webowej

Aplikacja webowa zapisuje nieudane zapytania modyfikujące dane (POST, PUT, PATCH) w kolejce IndexedDB przeglądarki, gdy nie ma sieci, i odtwarza je po jej powrocie. Użytkownik wypełnia formularz, naciska zapis i może pracować dalej, a aplikacja dostarczy dane później.

To rozwiązanie dla zadań, które nie mogą czekać na zasięg: obchód, kontrola, zgłoszenie, zdjęcie z usterką. Kolejka obsługuje także pliki i formularze, nie tylko proste dane tekstowe.

Siedem praktyk projektowych

Praktyki w kolejności, w jakiej zespół zazwyczaj podejmuje decyzje.

1. Każdemu zapytaniu daj klucz idempotencji

Każde zapytanie modyfikujące dostaje klucz idempotencji w nagłówku. Ponowne wysłanie po częściowej awarii sieci nie tworzy duplikatu po stronie serwera, bo serwer rozpoznaje klucz.

2. Serwer zapamiętuje tylko sukces

Serwer zapamiętuje wyniki zakończone sukcesem 2xx. Po błędzie 4xx lub 5xx klucz zostaje zwolniony, więc poprawione zapytanie można wysłać ponownie. Rekordy idempotencji czyści się po domyślnie 13 dniach.

3. Pokaż użytkownikowi stan kolejki

Stan zapisu jest widoczny: oczekuje, synchronizuje, błąd, wymagane logowanie. Inspektor, który widzi „oczekuje”, nie powtarza kontroli, a ten, który widzi „wymagane logowanie”, wie, co zrobić po powrocie do biura.

4. Ponawiaj z rosnącym opóźnieniem

Opóźnienia ponowień rosną wg ciągu Fibonacciego: 1, 2, 3, 5, 8, 13 s i dalej. Ciąg łagodniej niż podwajanie zwiększa przerwy, więc urządzenie szybko odzyskuje synchronizację po powrocie zasięgu, ale nie obciąża sieci przy długiej awarii.

5. Rozróżnij brak sieci od błędu logiki

Brak sieci to powód do ponowienia. Odpowiedź 4xx wymaga uwagi użytkownika, bo ponowienie tego samego zapytania da ten sam błąd. Kolejka pokazuje je jako błąd, a nie jako ciągłe oczekiwanie.

6. Ogranicz zawartość kolejki

Pliki i zdjęcia zajmują miejsce w pamięci przeglądarki. Ustal limit rozmiaru i rozdzielczości zdjęć w aplikacji terenowej, zanim pierwszy inspektor zapełni kolejkę na obchodzie.

7. Testuj z wyłączoną siecią i przerwanym łączem

Scenariusze testowe: tryb samolotowy w trakcie zapisu, zerwanie łącza w połowie wysyłki, sesja wygasła podczas pracy offline. Sprawdzaj, czy po powrocie sieci na serwerze jest dokładnie jeden rekord, a nie zero ani dwa.

Opóźnienia ponowień kolejki wg ciągu Fibonacciego

Opóźnienia ponowień kolejki wg ciągu FibonacciegoWykres słupkowy: opóźnienia kolejnych ponowień 1, 2, 3, 5, 8 i 13 sekund051015s1. próba: 1 s1 s1. próba2. próba: 2 s2 s2. próba3. próba: 3 s3 s3. próba4. próba: 5 s5 s4. próba5. próba: 8 s8 s5. próba6. próba: 13 s13 s6. próba
Źródło: Ciąg Fibonacciego opisany w dokumentacji funkcji kolejki offline

Przykładowe liczby do planowania

Kalkulacja przykładowa: inspektor wykonuje obchód 40 punktów, a przy każdym zapisuje formularz i zdjęcie. Gdy 8 z tych punktów leży poza zasięgiem, w kolejce czeka 8 formularzy i 8 zdjęć, które wysyłają się po powrocie sieci. Przy kluczach idempotencji ponowienie wysyłki nie zwiększy liczby rekordów powyżej 40.

Bez kluczy idempotencji ta sama sytuacja w razie przerwania wysyłki mogłaby dać dla części punktów dwa rekordy. To wystarczający powód, by klucz był standardem, a nie dodatkiem.

Czego kolejka offline nie robi

Kolejka nie zastępuje decyzji biznesowej o tym, co jest wiążące. Zapis wykonany offline ma czas urządzenia, więc dla ważnych zdarzeń (zezwolenie, odbiór pracy) warto pokazać użytkownikowi, że zapis jeszcze nie jest potwierdzony przez serwer. Dla alarmów o zagrożeniu życia lepiej użyć urządzenia z własnym łączem, takiego jak zegarek LoRa z bramką.

Lista kontrolna

Materiał wideo

Często zadawane pytania

Czy kolejka offline obsługuje zdjęcia i pliki?

Tak. Kolejka obsługuje także pliki i formularze, ale rozmiar trzeba ograniczyć, bo pamięć przeglądarki jest skończona.

Co, gdy serwer zwróci błąd 4xx?

Klucz zostaje zwolniony, a zapytanie trafia do stanu błędu. Użytkownik poprawia dane i wysyła ponownie, bez ryzyka duplikatu.

Jak długo serwer pamięta klucze idempotencji?

Domyślnie 13 dni, po czym rekordy są czyszczone. Zapytanie ponawiane po dłuższym czasie jest traktowane jak nowe.

Źródła

Przetestujmy pracę offline na Państwa obchodzie

Pokażemy kolejkę offline w aplikacji i wspólnie ułożymy scenariusze testowe dla obchodów w miejscach bez zasięgu. Zapraszamy do rozmowy.

Porozmawiajmy