DocFlow od środka — od danych i zdjęć do podpisanego protokołu i finalnego PDF

Problem: wypełnialny PDF to jeszcze nie proces

Najprostsza cyfryzacja protokołu to formularz PDF wypełniany na tablecie. Rozwiązuje problem papieru, ale nie problem procesu. Plik można zmienić po wysłaniu, zdjęcia trafiają osobno na telefon albo do komunikatora, numeracja zależy od pamięci biura, a o tym, czy protokół jest kompletny, decyduje uważność osoby, która go otwiera.

Protokół jako proces oznacza, że dokument ma stan, wymagane elementy i regułę zamknięcia. PDF jest wynikiem tego procesu, a nie miejscem, w którym proces się odbywa. Szerzej o tym podejściu piszemy na stronie cyfryzacja dokumentów.

Z czego składa się protokół

Z perspektywy użytkownika protokół w DocFlow to:

• Typ — wybierany z rejestru typów protokołów (m.in. instalacje PV, pompy ciepła, CO, kotły). Typy należą do pakietów branżowych włączanych dla organizacji.
• Numer — nadawany przy utworzeniu protokołu w formacie prefiks typu, rok i kolejny numer, na przykład PREFIKS-2026-0001. Licznik jest prowadzony osobno dla organizacji, typu i roku, a baza danych nie dopuszcza dwóch protokołów z tym samym numerem.
• Dane w sekcjach — m.in. dane inwestora, adres inwestycji, osoba sporządzająca i sekcje zależne od typu protokołu.
• Zdjęcia w slotach — każde zdjęcie ma swoje miejsce w protokole.
• Podpisy i zgody — wymagane do zamknięcia protokołu.
• Lokalizacja — opcjonalnie, tylko na żądanie użytkownika.

Dane formularza są przechowywane jako ustrukturyzowany dokument, bo każdy typ protokołu ma inne sekcje. Dzięki temu nowy wariant branżowy nie wymaga osobnej aplikacji — DocFlow i DocXpress działają na tym samym silniku, a markę wybiera ustawienie organizacji.

Stany protokołu

Protokół ma dwa stany: szkic i podpisany. Na liście protokołów widać je jako „Szkic” i „Podpisany”, a na finalnym PDF jako dokument sfinalizowany z oznaczeniem FINAL. Jedyną drogą ze szkicu do stanu podpisanego jest finalizacja — zwykła edycja nie może ustawić statusu „podpisany”, więc nie da się ominąć sprawdzenia podpisów, zgód i limitów planu.

Zdjęcia

Zdjęcia nie są załącznikiem do maila, tylko częścią protokołu. Kreator pokazuje sloty — wymagane albo opcjonalne — więc technik widzi, czego jeszcze brakuje. Zdjęcie jest zapisywane lokalnie przed wysyłką, a następnie trafia bezpośrednio do magazynu plików przez krótkotrwały adres wygenerowany przez API.

W obecnej wersji system przyjmuje:

• zdjęcia w formatach JPEG, PNG i WebP, do 8 MB każde,
• do 30 aktywnych zdjęć w protokole i do 6 w jednym slocie.

Po finalizacji dodawanie i usuwanie plików jest zablokowane, tak samo jak edycja danych.

Podpisy na ekranie

Inwestor i osoba wykonująca prace — zależnie od rodzaju protokołu instalator, serwisant, technik albo handlowiec — podpisują się palcem lub rysikiem na ekranie urządzenia. Podpis zapisywany jest jako obraz i trafia do protokołu oraz do PDF. Finalizacja sprawdza, czy są podpisy wszystkich wymaganych stron.

Podpis złożony na ekranie w DocFlow nie jest kwalifikowanym podpisem elektronicznym. Oznaczenie „podpisany elektronicznie” na finalnym PDF odnosi się do tego podpisu odręcznego złożonego na ekranie. Jeśli przepis albo umowa wymaga podpisu kwalifikowanego, potrzebna jest usługa, która go zapewnia — DocFlow jej nie zastępuje.

Finalizacja i blokada

Finalizacja to jedna operacja, która w kolejności:

1. sprawdza uprawnienia użytkownika i aktywność konta organizacji,
2. sprawdza limit protokołów wynikający z planu,
3. sprawdza wymagane pola — na przykład inwestora, adres inwestycji i osobę sporządzającą,
4. sprawdza wymagane podpisy i zgody, a zgody zapisuje razem z ich wersją,
5. zapisuje, kto i kiedy podpisał protokół,
6. generuje finalny PDF i zapisuje go w magazynie plików,
7. dopiero wtedy ustawia status „podpisany”.

Jeśli którykolwiek warunek nie jest spełniony, protokół zostaje szkicem, a użytkownik dostaje informację, czego brakuje. Po finalizacji system odrzuca każdą próbę zmiany danych, statusu albo dodania lub usunięcia pliku. Ponowna finalizacja również jest odrzucana.

PDF i weryfikacja dokumentu

Finalny PDF powstaje z danych protokołu na podstawie szablonu HTML. Zawiera logo organizacji, jeśli zostało ustawione, sekcję GPS, jeśli lokalizacja została pobrana, oraz sekcję weryfikacji z identyfikatorem dokumentu i kodem QR prowadzącym do strony weryfikacji.

• Wersje — PDF można wygenerować ponownie tylko dla podpisanego protokołu. Każde generowanie tworzy kolejną wersję pliku z tych samych, zablokowanych danych.
• Skrót pliku — dla każdego finalnego PDF zapisywany jest skrót SHA-256.
• Weryfikacja — na stronie weryfikacji można sprawdzić link z kodu QR albo wgrać plik PDF. System porównuje jego skrót z zapisanymi wersjami i odpowiada, czy dokument istnieje w systemie.

To sprawdzenie pozwala ustalić, czy plik jest identyczny z wersją wydaną przez system. Nie jest to pieczęć kwalifikowana ani podpis kwalifikowany, a sam PDF nie jest technicznie zabezpieczony przed modyfikacją — zmieniony plik po prostu nie przejdzie weryfikacji.

Po podpisaniu protokołu można pokazać kod QR, który prowadzi do pobrania finalnego PDF i jest ważny 24 godziny. Przy finalizacji można też zaznaczyć wysyłkę PDF e-mailem na podany adres. Wysyłka nie blokuje finalizacji: jeśli się nie uda, protokół i tak zostaje poprawnie zamknięty.

Role i dostęp

• Właściciel i administrator — pełny dostęp do protokołów organizacji.
• Technik — tworzy protokoły i widzi wyłącznie te, które sam utworzył. Próba otwarcia cudzego protokołu kończy się odpowiedzią „nie znaleziono”, więc system nie potwierdza nawet, że taki dokument istnieje.
• Podgląd — może przeglądać protokoły, ale nie może ich tworzyć, zmieniać, finalizować ani wysyłać.

Plan organizacji określa limity, m.in. liczby użytkowników i protokołów. System sprawdza limit przy tworzeniu protokołu i ponownie przy finalizacji.

Decyzje architektoniczne

• Next.js po stronie interfejsu i FastAPI po stronie API — reguły procesu (stany, blokada, uprawnienia, limity) są sprawdzane w API, a nie tylko w przeglądarce.
• PostgreSQL — protokoły, numeracja i pliki jako rekordy z ograniczeniami w bazie, a dane formularza jako dokument, którego struktura zależy od typu protokołu.
• Magazyn obiektów zgodny z S3 — zdjęcia, podpisy i finalne PDF-y są przechowywane poza bazą danych, a baza trzyma tylko ich opis i powiązanie z protokołem.
• WeasyPrint — PDF generowany z szablonu HTML, dzięki czemu wygląd dokumentu zmienia się w szablonie, a nie w kodzie każdego typu protokołu.

Czego DocFlow nie robi automatycznie

• Nie wypełnia protokołu za człowieka — treść, zdjęcia i podpisy zbiera technik na miejscu.
• Nie finalizuje sam — zamknięcie protokołu jest zawsze decyzją użytkownika.
• Nie śledzi lokalizacji — GPS jest pobierany wyłącznie po naciśnięciu przycisku.
• Nie wysyła maili bez decyzji — wysyłka PDF wymaga zaznaczenia i podania adresu.
• Nie składa podpisu kwalifikowanego — to wymagałoby zewnętrznej usługi zaufania.

Wnioski dla podobnych projektów

• Stan zamknięcia nie może być zwykłym polem do edycji. Jeśli status „podpisany” da się ustawić tak samo jak każde inne pole, reguły zamknięcia można obejść.
• Status zmienia się po wygenerowaniu dokumentu, nie przed. Inaczej powstają podpisane protokoły bez pliku.
• Numer nadawany przy utworzeniu pozwala odwołać się do dokumentu już w terenie, zanim zostanie zamknięty.
• Ograniczenia trzeba pisać wprost. Informacja, że podpis na ekranie nie jest kwalifikowany, jest częścią produktu, a nie przypisem.
• Jeden silnik dla wielu typów dokumentów wymaga elastycznego modelu danych, ale reguły wspólne dla wszystkich typów — stany, blokada, podpisy — muszą pozostać w jednym miejscu.

Opis wdrożenia znajdziesz w realizacji DocFlow, a szerszy kontekst przy automatyzacji procesów i oprogramowaniu dedykowanym. Jeśli Twoja firma prowadzi podobne protokoły, opisz proces w analizie procesu — odpowiemy, czy wystarczy gotowe narzędzie, czy warto zbudować własny proces dokumentowy.