Aplikacja mobilna technika — SerwisRun Mobile

Kompletny przewodnik po aplikacji mobilnej SerwisRun dla serwisantów. Dokument opisuje interfejs, przyciski stanu, pakiet offline, skanowanie materiałów i protokoły naprawy wypełniane w terenie.

Nowość 2026‑04‑17: Aplikacja została całkowicie przeprojektowana: niebieski header z datą/GPS, okrągłe akcje stanu, karta dyżuru, grid akcji 2x2 (START/STOP/PRZYJAZD/WYJAZD), Wirtualny Magazyn, skanowanie EAN i listy protokołów.

1 Przegląd — 5 zakładek TabBar

Po zalogowaniu technik trafia na ekran główny aplikacji mobilnej (/mobile). Na dole ekranu znajduje się pasek nawigacji z 5 zakładkami:

Auto-redirect: Użytkownik z rolą technician jest automatycznie przekierowywany do /mobile przy logowaniu (komponent TechnicianGate w App.tsx). Nie widzi desktopowego panelu.

2 Pulpit (ekran główny)

Elementy ekranu głównego (od góry do dołu)

1. Niebieski header:
   • Data i godzina (aktualizowane co sekundę)
   • Ikona lokalizacji + adres GPS (reverse‑geocoded z OpenStreetMap Nominatim)
   • Menu kropek (3 kropki) — dostęp do menu szybkiej nawigacji
2. Pasek szybkich akcji — 3 okrągłe kolorowe przyciski:
   • PRIV — jazda prywatna (fioletowy)
   • PAUZA — przerwa (żółty)
   • PALIWO — tankowanie (pomarańczowy)
3. Karta „Twój region" — informacja o dyżurnym technika dla Twojego oddziału; klikalna, rozwija się z listą wszystkich dyżurnych
4. Grid 2x2 akcji stanów:
   • START → STOP
   • PRZYJAZD ⇄ WYJAZD
5. Lista „Ostatnie wpisy" — aktywne operacje (tracking, tankowanie, jazda prywatna) + dzisiejsze konserwacje i interwencje
6. Bottom status bar — fedback wizualny akcji („Pobieranie lokalizacji…" na niebiesko, „Zapisano" na zielono, błąd na czerwono)

3 Karta dyżuru — „Twój region"

Co pokazuje karta?

Karta informuje, kto aktualnie pełni dyżur dla Twojego oddziału. Dyżur oznacza gotowość do przyjmowania pilnych zgłoszeń poza godzinami pracy.

Po rozwinięciu (kliknięcie strzałki) widzisz listę wszystkich aktywnych dyżurnych pogrupowanych według oddziałów (POZNAŃ, BYDGOSZCZ, itd.).

Akcje w karcie

Mechanizm PRZEJMIJ: Sekwencja atomowa: (1) POST /users/{target}/toggle-duty — wyłączenie dyżuru drugiego technika, (2) POST /users/{me}/toggle-duty — włączenie Twojego. System loguje zdarzenie w audicie.

4 Akcje stanu: START / STOP / PRZYJAZD / WYJAZD

Głównym elementem pulpitu jest grid 2x2 z czterema dużymi przyciskami akcji stanu. Przyciski są kontekstowo włączone/wyłączone w zależności od aktualnego stanu maszyny stanów.

Modal START — początek dnia pracy

Po rozpoczęciu pracy naciskasz START. Otwiera się modal:

• Wybierz Lokalizację — radio: DOM albo BIURO (skąd zaczynasz dzień)
• Numer Rejestracyjny — z wpisu pojazdu (auto-wypełniany z floty)
• Przebieg (km) — stan licznika na początku dnia
• Wyjazd Awaryjny — checkbox dla interwencji pilnych (priorytet w raportach)

Przycisk WYŚLIJ zapisuje transition z aktualnym GPS. System wie, że jesteś „w drodze" (TRAVELING).

Modal PRZYJAZD — na obiekcie

Po dojechaniu na obiekt naciskasz PRZYJAZD. System proponuje obiekt z listy dzisiejszych zleceń — możesz też wpisać dowolną nazwę (ad-hoc). Po zatwierdzeniu stan zmienia się na ON_SITE.

Modal WYJAZD — status zadania

Po zakończeniu prac na obiekcie naciskasz WYJAZD. Wybierasz status:

• Wykonane — zadanie zamknięte, naprawa skuteczna
• Do dalszej realizacji — potrzebna kolejna wizyta (np. brakujące części)

System przechodzi do stanu RETURNING — wracasz do bazy/domu.

Modal STOP — koniec dnia pracy

Naciskasz STOP na końcu dnia pracy. Wybierasz gdzie kończysz (DOM/BIURO), wpisujesz końcowy stan licznika. System przechodzi do IDLE. Raport dnia jest gotowy.

Kontekstowość: Przyciski są włączone tylko gdy akcja jest możliwa w aktualnym stanie. Np. STOP jest wyłączone gdy już jesteś w IDLE. PRZYJAZD działa tylko w stanie TRAVELING. System prowadzi Cię przez logiczną sekwencję.

5 Szybkie akcje: PRIV / PAUZA / PALIWO

Trzy okrągłe przyciski na górze ekranu dostępne są w każdym momencie — niezależnie od aktualnego stanu. Każdy jest toggle'em: pierwsze kliknięcie rozpoczyna, drugie kończy.

PRIV — jazda prywatna

Używasz gdy jedziesz prywatnie firmowym pojazdem. System rejestruje trip jako niepłatny (nie wlicza się do kosztów interwencji). Wymaga wpisania:

• Numeru rejestracyjnego
• Stanu licznika
• Celu (opcjonalnie — np. „wizyta u lekarza")

PAUZA — przerwa w pracy

Szybka rejestracja przerwy (obiad, kawa). Jedno kliknięcie rozpoczyna, kolejne kończy. System wstrzymuje tracking czasu pracy, ale zachowuje kontekst interwencji.

PALIWO — tankowanie

Rejestracja tankowania. Pola:

• Rodzaj Paliwa — ON (Diesel), PB (Benzyna), LPG, EV, Hybryda
• Ilość (Litry)
• Nr Rejestracyjny
• Stan Licznika (km)

Integracja z flotą: Wszystkie tankowania (refueling_logs) są powiązane z pojazdem i kierowcą. Generowanie raportów zużycia paliwa per pojazd, per technik — w module Flota na desktopie.

6 Zadania — lista interwencji

Zakładka Zadania wyświetla listę Twoich interwencji w 3 tabach:

• Dziś — zaplanowane na dzisiejszy dzień (statusy: assigned, acknowledged, traveling, on_site, working, in_progress, planned)
• Nadchodzące — przyszłe (draft, assigned, planned)
• Zakończone — zakończone (completed, closed)

Workflow interwencji

1. Dyspozytor przypisuje interwencję technikowi — status assigned, push notification
2. Technik potwierdza przyjęcie — przycisk „Potwierdź przyjęcie" → status acknowledged
3. Rozpoczęcie pracy — przycisk „Rozpocznij prace" → otwiera Timer Pracy (/mobile/interventions/:id/work)
4. Checklist zakresu prac — zadania do wykonania z polami „sprawne/usterka/pominięte"
5. Wypełnienie protokołu — przycisk „Wypełnij protokół" → Formularz offline
6. Zakończenie — przycisk „Zakończ i wyślij" → status completed, push do dyspozytora

Google Maps: W szczegółach interwencji dotknij adresu — otwiera się natywna nawigacja z trasą do obiektu. System preferuje współrzędne GPS z obiektu (latitude/longitude), fallback: adres tekstowy.

7 Wirtualny Magazyn

Zakładka Magazyn zawiera dwa taby:

MOJE NARZĘDZIA

Lista wszystkich materiałów i wyposażenia w Twoim osobistym magazynie technika. Każdy technik ma własny magazyn przypisany (warehouses.responsibleUserId = user.id).

CAŁY STAN

Lista wszystkich materiałów dostępnych w magazynach oddziału z niezerowym stanem. Przycisk POBIERZ obok każdego materiału tworzy dokument MM (przesunięcie międzymagazynowe) do Twojego magazynu technika.

Workflow pobrania

1. Technik wyszukuje materiał (po nazwie, typie lub EAN)
2. Kliknięcie POBIERZ → potwierdzenie dialogowe
3. Backend tworzy MM: POST /warehouses/documents z type=MM, source=oddział, target=magazyn technika, quantity=1
4. Stan natychmiast odświeżany w obu tabach
5. Materiał jest dostępny do użycia w protokole naprawy

Skan EAN w magazynie

Floating Action Button (+) w prawym dolnym rogu otwiera skaner EAN. Zeskanowany kod automatycznie wyszukuje materiał w magazynie.

Filozofia modelu: Technik to człowiek ruchomy — ma swój mały magazyn w samochodzie. „Pobierz" oznacza „wezmę z magazynu regionalnego do furgonetki". Zużycie rozliczane przez WZ po wypełnieniu protokołu.

8 Protokoły naprawy

Zakładka Protokoły wyświetla listę wszystkich protokołów w dwóch tabach:

Formularz protokołu offline

Formularz protokołu dostosowany do użycia w terenie:

1. Wykonane czynności — dla każdego zadania z checklisty:
   • Sprawne (zielony, ikona ✓) — zadanie wykonane, wszystko OK
   • Usterka (czerwony, ikona ⚠) — problem wykryty, wymaga uwagi
   • Pominięte (szary) — nie dotyczy, skip
   Plus pole „Uwagi" dla każdego zadania.
2. Zużyte materiały — lista z magazynu technika. Stepper do ustawienia ilości (+/-). Możliwość zeskanowania EAN kamery, aby dodać materiał do protokołu.
3. Zdjęcia dokumentacyjne — max 10 zdjęć, capture="environment" (tylna kamera smartfona), auto-compresja do 1920px JPEG 80%.
4. Podsumowanie — TextArea z opisem wykonanej naprawy. Przycisk „Generuj z AI" tworzy wstępny tekst.
5. Podpis klienta — imię i nazwisko + SignaturePad (podpis palcem) lub zdjęcie papierowego potwierdzenia.

Auto-save co 30 sekund

Formularz zapisuje się automatycznie co 30 sekund do IndexedDB (tabela protocolDrafts). Możesz zamknąć aplikację lub stracić zasięg — po powrocie szkic jest załadowany i możesz kontynuować.

Wysyłka protokołu

Przycisk „Zakończ i wyślij" → submit przez offline queue → endpoint PUT /interventions/:id z protocolFormData + completionSummary. Status interwencji zmienia się na completed. Dyspozytor otrzymuje push + SSE event.

Offline guarantee: Nawet bez internetu protokół trafia do kolejki (tabela pendingOperations). Po powrocie online auto-sync wyśle wszystkie zaległe operacje w kolejności naciśnięcia przycisku (clientTimestamp).

9 Skaner EAN

Zakładka Skaner to dedykowany ekran skanera kodów kreskowych EAN (i innych formatów: EAN-8, CODE_128, UPC_A, QR).

Funkcjonalność

• Ciągły skan — kamera aktywna, skanuje w pętli z cooldownem 1.5s
• Automatyczny lookup — po zeskanowaniu system pyta backend: najpierw o materiał (po EAN), potem o wyposażenie (po EAN lub nr ewidencyjnym)
• Wibracja — 200ms wibracji przy udanym skanie
• Koszyk zeskanowanych — lista ostatnich 50 pozycji z możliwością wyczyszczenia
• Oznaczenie typu: Materiał (niebieski), Wyposażenie (pomarańczowy), Nieznany (czerwony)

Integracja z protokołem

Zeskanowane materiały mogą być dodane do protokołu naprawy bezpośrednio z koszyka. Kliknij pozycję → „Dodaj do protokołu" → Stepper ilości.

Sprzęt: Skaner wykorzystuje bibliotekę html5-qrcode. Działa na wszystkich nowoczesnych smartfonach z tylną kamerą. Nie wymaga dodatkowego sprzętu (skaner USB). Opcjonalnie wspiera czytniki HID (USB/Bluetooth) przez pole EanInput.

10 Praca offline

Aplikacja zaprojektowana do pracy w trudnych warunkach (piwnica, teren wiejski, parkingi podziemne). Cała funkcjonalność działa offline.

Pakiet offline (Offline Package)

Przed wyjazdem na interwencję system pobiera pakiet offline — kompletne dane potrzebne do pracy bez internetu:

Kolejka operacji offline

Wszystkie operacje (start tracking, potwierdzenie statusu, submit protokołu, upload zdjęć) są kolejkowane w IndexedDB (tabela pendingOperations) i wysyłane po powrocie online:

• Timestampy — zapisywane w momencie naciśnięcia przycisku (clientTimestamp), nie synchronizacji
• Kolejność — FIFO, zachowana sekwencja działań
• Exponential backoff — 1s→2s→4s→8s→16s→30s, max 5 prób
• Background Sync API — system operacyjny wysyła pending operations nawet gdy aplikacja nie jest otwarta

Szyfrowanie danych offline

Wszystkie dane w IndexedDB są szyfrowane AES-256-GCM:

• Klucz generowany przez PBKDF2 z 100 000 iteracji
• Salt losowy per sesja
• Klucz pochodzi z tokena JWT sesji
• Po logoucie klucz usuwany → dane nie do odszyfrowania

Remote wipe

Administrator może zdalnie wyczyścić dane z konkretnego urządzenia (np. zgubionego telefonu):

1. Admin klika „Wymaż zdalnie" w panelu urządzeń
2. Web Push WIPE_DEVICE wysłany do Service Workera
3. SW czyści IndexedDB + caches + unregistruje się
4. Użytkownik zostaje wylogowany przy najbliższym kontakcie z internetem

11 Instalacja jako PWA

Aplikacja to Progressive Web App — można ją zainstalować na ekranie głównym smartfona bez sklepu z aplikacjami.

Android (Chrome)

1. Otwórz app.serwis.cloud/mobile w Chrome
2. Po 3 sekundach pojawi się niebieski banner „Zainstaluj aplikację"
3. Kliknij „Instaluj"
4. Ikona pojawi się na pulpicie Android

iOS (Safari)

1. Otwórz app.serwis.cloud/mobile w Safari
2. Kliknij ikonę „Udostępnij" (kwadrat ze strzałką)
3. Wybierz „Dodaj do ekranu głównego"
4. Potwierdź „Dodaj"

Co dostajesz po instalacji?

• Ikona na ekranie głównym — wygląda jak natywna aplikacja
• Pełny ekran — bez paska adresu Chrome/Safari
• Push notifications — powiadomienia o nowych interwencjach
• Offline — aplikacja działa bez internetu dzięki Service Worker
• Auto-aktualizacje — nowe wersje instalują się po restarcie aplikacji (cache PWA v4.0.0)

Bez App Store: Nie trzeba czekać na zatwierdzenie aktualizacji przez Apple/Google. Każda zmiana deployu na Railway jest od razu dostępna u wszystkich techników (po restarcie aplikacji).

12 Praktyczny workflow dnia

Typowy dzień technika z wykorzystaniem wszystkich funkcji aplikacji mobilnej: