Moduły wspierające — Magazyn, HR/Kadry, Flota

Przewodnik po trzech modułach wspierających procesy operacyjne: Magazyn materiałów i obiegu dokumentów, HR (Kadry) z ewidencją pracowników oraz Flota pojazdów serwisowych.

Wersja 1.1·Opublikowano: 2026-05-08

Konwencja: Każdy moduł posiada dedykowaną stronę z listą + DetailPanel (zakładki), kreator 4‑5 fazowy dla nowych rekordów oraz pełną integrację z obiegiem dokumentów (cloud storage, audit log).

Spis treści

Magazyn materiałów i obieg dokumentów
Partie FIFO i rezerwacje
Dokumenty PZ / WZ / MM / INW
Potwierdzenie odbioru podpisem (mobile)
HR / Kadry — pracownicy, nieobecności, badania
Flota pojazdów serwisowych
Dokumenty, transfery, przejazdy

1 Magazyn materiałów i obieg dokumentów

Lista magazynow dane zanonimizowane.

Material w detailPanel dane zanonimizowane — zdjecia, dostawcy, partie FIFO.

Moduł Magazyn wspiera pełen obieg materiałów: od zakupu (PZ z faktury zakupowej lub zamówienia), przez transfery między magazynami (MM), aż po wydanie na protokół serwisowy (WZ) i fakturę końcową.

Docelowy łańcuch obiegu

Kosztorys → ZATWIERDZENIE → Zamówienie → PZ → MM do technika → WZ do protokołu → ZUŻYTY → Faktura → ZAFAKTUROWANY

Struktura magazynów

Typ magazynu	Przeznaczenie	Odpowiedzialny
`central`	Magazyn centralny oddziału — zakupy hurtowe, zasoby strategiczne	Magazynier / kierownik
`technician`	Magazyn technika — samochód/biurko; materiały „na trasie"	Konkretny technik (`responsible_user_id`)
`branch`	Magazyn oddziału — pośredni poziom	Kierownik oddziału

Każdy magazyn ma przypisany oddział (branch_id) — filtrowanie RBAC działa automatycznie. Techników nie widzą magazynów innych oddziałów.

2 Partie FIFO i rezerwacje

Tabela `material_batches` — śledzenie dostaw

Każde PZ tworzy partię materiału z unikalnymi danymi:

Cena zakupu — rzeczywista z faktury
Dostawca (supplier_id)
Data zakupu — baza dla FIFO
Pozostała ilość (remaining_quantity)
Powiązanie z fakturą zakupu i PZ

Konsumpcja FIFO przy potwierdzeniu WZ

Gdy technik wydaje materiał (potwierdzenie WZ), system konsumuje od najstarszej partii:

SELECT batches WHERE material_id = ? AND remaining_quantity > 0 ORDER BY purchase_date ASC
Dekrementacja remaining_quantity aż do pokrycia całej ilości
Zapis do batch_consumptions — audit trail: który WZ zjadł którą partię
Aktualizacja ceny pozycji WZ wg średniej ważonej (przy mieszanych partiach)

Korzyść biznesowa: Rachunek zysków i strat oblicza się precyzyjnie na podstawie rzeczywistych kosztów zakupu, a nie średniej „katalogowej".

Rezerwacje (`material_reservations`)

System automatycznie rezerwuje materiały przy zatwierdzeniu kosztorysu, aby zapobiec podwójnemu wydaniu:

Zdarzenie	Akcja
Zatwierdzenie kosztorysu (klient akceptuje)	`reserveMaterials()` — `warehouse_stock.reserved_quantity += qty`, status `active`
Odrzucenie / anulowanie kosztorysu	`releaseReservation()` — `reserved_quantity -= qty`, status `released`
Potwierdzenie WZ z pozycji kosztorysu	`consumeReservation()` — status `consumed`

Przed zatwierdzeniem kosztorysu frontend wywołuje GET /api/cost-estimates/:id/check-availability. Jeśli brakuje materiałów, użytkownik widzi ostrzeżenie z listą braków.

3 Dokumenty PZ / WZ / MM / INW

Zamowienia do dostawcow dane zanonimizowane.

Ewidencja wyposazenia dane zanonimizowane.

Typ	Nazwa pełna	Opis	Akcja bazodanowa
`PZ`	Przyjęcie zewnętrzne	Przyjęcie materiału od dostawcy (z faktury zakupu)	+ stan magazynu, nowa partia
`WZ`	Wydanie zewnętrzne	Wydanie do protokołu / klienta	− stan, konsumpcja FIFO
`MM`	Międzymagazynowe	Transfer między magazynami firmy	− źródło, + cel
`INW`	Inwentaryzacja	Korekta stanu po spisie z natury	± stan, protokół różnic
`PRZM`	Protokół zużycia	Materiały instalacyjne rozliczane okresowo	− stan technika

Przepływ dokumentu

draft → confirmed (stan magazynu się zmienia) → [optional: cancelled]

Dokument w statusie draft nie wpływa na stan. Dopiero confirmDocument aktualizuje warehouse_stock i tworzy/konsumuje partie.

Numeracja

Format: {TYP}-{ROK}-{NUMER_5_CYFR} — np. PZ-2026-00042. Numeracja per typ + rok (warehouse_document_sequence), zerowanie na przełomie roku.

4 Potwierdzenie odbioru podpisem (mobile)

Nowość 2026‑04‑17: Dokumenty MM tworzone z aplikacji mobilnej przy pobieraniu materiałów/wyposażenia do magazynu technika są potwierdzane podpisem odbiorcy. Podpis zapisywany jako base64 PNG w kolumnach recipient_signature, recipient_signed_at, recipient_name (migracja 222).

Flow w aplikacji mobilnej

Technik w module „Wirtualny Magazyn" (/mobile/warehouse) wybiera zakładkę CAŁY STAN
Wyszukuje materiał i klika przycisk POBIERZ
Otwiera się Popup z nazwą materiału, docelowym magazynem i polem podpisu
Technik podpisuje ekran palcem (canvas)
Klika Potwierdź odbiór
Backend tworzy dokument MM z polami:
- recipient_signature — base64 PNG
- recipient_signed_at — aktualny czas
- recipient_name — imię i nazwisko technika (auto z sesji)
Toast: „Odebrano i potwierdzono podpisem"

Analogiczny mechanizm jak przy protokole konserwacji/naprawy — audyt każdego ruchu materiału z podpisem odbiorcy.

5 HR / Kadry — pracownicy, nieobecności, badania

Kadry — lista pracownikow. dane osobowe zanonimizowane

DetailPanel pracownika, 6 zakladek. dane osobowe zanonimizowane

Uzytkownicy systemu — kolumna Kadry. dane osobowe zanonimizowane

Moduł HR zarządza wszystkimi pracownikami firmy niezależnie od tego, czy mają konto użytkownika w systemie (rola admin / client / demo może, ale nie musi być pracownikiem).

Architektura — Users vs Employees

Kluczowa separacja: employees = wszyscy pracownicy firmy (pełna kadra); users = konta logowania (subset). Powiązane przez users.employee_id.

Widok /hr wyświetla wyłącznie rekordy z tabeli employees
Widok /users wyświetla konta + kolumnę „Kadry" z tagiem „Powiązany/Niepowiązany"
Avatary są zawsze ze zdjęcia pracownika (pole employees.avatar_base64) — jedno źródło prawdy

Zakładki DetailPanel w module Kadry (6)

Zakładka	Zawartość
Dane osobowe	Imię, nazwisko, PESEL, data urodzenia, kontakt, adres, zdjęcie ID‑photo (350x450)
Nieobecności	20 typów wg polskiego Kodeksu Pracy (urlop wypoczynkowy, L4, opieka art.188, szkolenie, delegacja...)
Certyfikaty	SEP, UDT, manufacturer, BHP — analiza skanu przez AI (vision), ekstrakcja daty ważności
Dokumenty pracownicze	Upload skanów do cloud storage `SerwisRun/Kadry/{Imię Nazwisko}/`
Badania lekarskie	Typ badania, data, data ważności, wynik
Metadane	Utworzono, zaktualizowano, kto

Typy zatrudnienia (`employees.employment_type`)

full_time — Pełny etat
part_time — Niepełny etat
contract — Umowa o pracę na czas określony
civil_contract — Umowa cywilnoprawna (zlecenie/dzieło)

Zdjęcie pracownika

Przy uploadzie przez POST /api/employees/:id/photo serwer (sharp):

Crop do proporcji dowodowych 350x450 z białym tłem
Tworzy miniaturkę 150x150 → zapis do employees.avatar_base64
Pełne zdjęcie na OneDrive: SerwisRun/Kadry/{firstName} {lastName}/{firstName}_{lastName}.jpg

Kreator pracownika (wizard 4‑fazowy)

Trasa: /hr/wizard. Fazy: Dane osobowe → Zatrudnienie → Kontakt i notatki → Podsumowanie. Navigation guard + draft saving (klucz hr w draftStore).

6 Flota pojazdów serwisowych

Flota pojazdow. numery rejestracyjne i dane zanonimizowane

DetailPanel pojazdu, 4 zakladki. dane zanonimizowane

Moduł Flota ewidencjonuje wszystkie pojazdy firmowe używane przez techników — z pełną historią przejazdów, dokumentów i przekazań.

Dane pojazdu (`service_vehicles`)

Pole	Opis
`registration_number` / `plate_number`	Numer rejestracyjny
`vin`	Numer VIN
`type`	Typ: van, bus, car, truck...
`fuel_type`	petrol / diesel / lpg / electric / hybrid
`tank_capacity`	Pojemność zbiornika (do kalkulacji tankowań)
`branch_id`	Oddział bazowy
`assigned_user_id`	Aktualnie przypisany technik
`insurance_expiry_date`	Data wygaśnięcia OC/AC
`next_inspection_date`	Data następnego przeglądu

Zakładki DetailPanel (4)

Dane — rejestracja, VIN, typ, paliwo, ubezpieczenie, przegląd, oddział, technik
Przejazdy — historia z vehicle_trips: data, start/koniec lokalizacji, kilometry, cel (powiązanie z konserwacją/zleceniem), koszt
Dokumenty — vehicle_documents: dowód rejestracyjny, polisa OC, badanie techniczne. Cloud storage: SerwisRun/Samochody/{nr_rejestracyjny}/
Transfery — vehicle_transfers: kto od kogo do kogo przekazał, kilometry przy przekazaniu, notatki o stanie

Integracja z aplikacją mobilną

Pojazd jest integralnym elementem aplikacji mobilnej technika:

START / STOP — wymagany wybór pojazdu (numer rejestracyjny) + stan licznika (km)
PALIWO — w Modal: wybór pojazdu, litry, koszt, typ paliwa → zapis do refueling_logs z GPS
PRIV — jazda prywatna: wybór pojazdu + cel (opcjonalnie) → private_trips

System automatycznie koreluje każdy przejazd (vehicle_trips) z konkretną konserwacją/zleceniem serwisowym, co pozwala liczyć rzeczywisty koszt dojazdu na podstawie spalania pojazdu, a nie tylko stawki kilometrowej.

Kreator pojazdu (wizard 4‑fazowy)

Trasa: /fleet/wizard. Fazy: Dane pojazdu → Przypisanie → Dokumenty → Podsumowanie.

7 Dokumenty, transfery, przejazdy

Cloud storage — struktura folderów

Moduł	Ścieżka
Kadry (zdjęcia, skany umów)	`SerwisRun/Kadry/{Imię Nazwisko}/`
Samochody (dokumenty)	`SerwisRun/Samochody/{nr_rejestracyjny}/`
Wyposażenie	`SerwisRun/Obiekty-Materiały/Wyposazenie/{kategoria}`
Materiały	`SerwisRun/Obiekty-Materiały/Materialy/{kategoria}`

Abstrakcja cloudStorage.service.ts przełącza między Google Drive, OneDrive lub S3 wg konfiguracji w Ustawieniach → Integracje.

Audit trail

Każda akcja CRUD w tych modułach loguje się do audit_logs przez HOF withAuditLog. Widok /audit-logs pokazuje pełną historię z możliwością filtrowania per encja, akcja, użytkownik.

D Dostawcy

Modul Dostawcy (/suppliers) ewidencjonuje dostawcow. Integracja z API MF (Biala Lista VAT) + Delta-Poznan.

Dostawcy — lista. NIP i dane zanonimizowane

DetailPanel dostawcy + badge statusu VAT z MF. dane zanonimizowane