Generator dokumentów. Certyfikaty szkoleniowe wydawane seryjnie
01. Punkt wyjścia
Klient prowadzi szkolenia produktowe zakończone wydaniem certyfikatu każdemu uczestnikowi. Dokumenty wystawiane są w trzech wersjach językowych i muszą zawierać dane szkolenia, dane firmy uczestnika, unikalny numer oraz datę ważności.
Certyfikaty przygotowywane były ręcznie w PowerPoincie. Po każdym szkoleniu ktoś otwierał plik szablonu, podmieniał dane uczestnika, nadawał kolejny numer, eksportował dokument do PDF i wysyłał go w osobnej wiadomości. Przy grupie liczącej kilkanaście osób oznaczało to kilkanaście powtórzeń tej samej sekwencji czynności.
Proces oparty na ręcznej edycji pliku niósł ze sobą typowe dla siebie ryzyka. Numer nadawany był z pamięci lub z pomocniczej listy, więc powtórzenie albo pominięcie numeru zależało wyłącznie od uwagi osoby wystawiającej. Kolejne kopie szablonu zaczynały się od siebie różnić. Nie istniała też żadna ewidencja wysyłek: informacja o tym, komu i kiedy wysłano certyfikat, rozproszona była w skrzynce pocztowej, a wiadomość, która nie dotarła do adresata, po prostu ginęła.
02. Rozwiązanie
Zbudowaliśmy dedykowaną aplikację, która obejmuje pełny cykl życia dokumentu: od zaprojektowania szablonu, przez bazę odbiorców, po wygenerowany plik PDF i potwierdzoną wysyłkę.
Osoba obsługująca szkolenia przygotowuje szablon w edytorze z podglądem na żywo, wprowadza listę uczestników ręcznie lub importem z pliku CSV, a następnie uruchamia wysyłkę dla całej grupy. System nadaje numery, generuje dokumenty i wysyła je e-mailem, a wynik każdej operacji zapisuje w historii. Praca, która wcześniej rosła liniowo wraz z liczbą uczestników, przestała od niej zależeć.
03. Przebieg procesu
- Przygotowanie lub wybór szablonu certyfikatu.
- Wprowadzenie odbiorców ręcznie albo import listy z pliku CSV.
- Uruchomienie wysyłki dla wybranej grupy uczestników.
- Weryfikacja statusów i ewentualne ponowienie nieudanych wysyłek.
Jeden szablon jako źródło prawdy
Podgląd w edytorze i plik końcowy renderowane są z tego samego komponentu. Zmiana wprowadzona w szablonie jest natychmiast widoczna na ekranie i identyczna w wygenerowanym dokumencie. Nie istnieje osobna wersja robocza i osobna produkcyjna, więc wygląd certyfikatu nie ma jak się rozjechać niezależnie od tego, ile dokumentów zostało już wydanych.
Szablon obejmuje tytuł, podtytuł, nazwę szkolenia, logotyp, dane osoby podpisującej i stopkę. Etykiety przygotowane są w trzech wersjach językowych, a wzorzec numeracji oraz okres ważności definiuje się osobno dla każdego szablonu.
Bezpieczna numeracja przy wysyłce seryjnej
Numery przyznawane są przez licznik działający atomowo, co oznacza, że przy jednoczesnym generowaniu dokumentów dla całej grupy żaden numer nie zostanie powtórzony ani pominięty. Format numeru jest konfigurowalny i może zawierać znaczniki daty oraz sekwencję porządkową. Kontrola nad ciągłością numeracji przeszła z człowieka na system.
Import odbiorców i listy
Uczestników można dodawać pojedynczo lub wgrać plik CSV przez trzykrokowy kreator z mapowaniem kolumn. Zaimportowana grupa zapisywana jest jako lista, dzięki czemu kolejna wysyłka do tej samej grupy sprowadza się do jednego kliknięcia.
Kontrola nad wysyłką
Każdy dokument przechodzi przez statusy od utworzenia, przez wygenerowanie, po potwierdzone dostarczenie lub błąd. Nieudane wysyłki są sygnalizowane na pulpicie i można je ponowić bez generowania dokumentu od nowa. Dostępny jest również tryb bez wysyłki, w którym system przygotowuje wyłącznie pliki PDF do przekazania inną drogą.
Wykorzystane technologie
- Frontend: React 19, Vite 6, TailwindCSS, TanStack Router i Query, Radix UI, react-hook-form
- Backend: Node 22, Hono 4, TypeScript
- Baza danych: Prisma 6, SQLite
- Generowanie dokumentów: Puppeteer 24 z Chromium, render HTML z komponentów React
- Wysyłka: Nodemailer, SMTP
- Bezpieczeństwo: bcrypt, sesje w bazie, ciasteczko httpOnly, limit prób logowania
- Wdrożenie: Docker, nginx, certyfikat Let’s Encrypt
Aplikacja utrzymana jest w architekturze monorepo, w której typy, walidacja i komponent szablonu są współdzielone między frontendem a backendem. Jedna definicja walidacji obowiązuje po obu stronach, co eliminuje klasę błędów wynikających z rozjeżdżających się reguł.
04. Rezultaty
Wydanie certyfikatów dla całej grupy szkoleniowej sprowadza się do wyboru szablonu, wskazania listy uczestników i uruchomienia wysyłki. Czynności wykonywane wcześniej osobno dla każdego uczestnika realizowane są seryjnie, a czas obsługi szkolenia przestał zależeć od liczby osób w grupie.
Numeracja i spójność dokumentów przestały być kwestią czyjejś uwagi. Numery nadaje system, a wygląd certyfikatu wynika z jednego szablonu, nie z kolejnej kopii pliku.
Historia wszystkich wydanych dokumentów jest dostępna w jednym miejscu, razem ze statusem dostarczenia i możliwością ponownego wysłania. Nieudana wysyłka nie oznacza już utraty informacji o tym, że certyfikat nie dotarł do uczestnika.
Całość działa na lekkiej infrastrukturze: jeden serwer, kontenery Docker, baza plikowa. Utrzymanie systemu nie wymaga rozbudowanego zaplecza serwerowego ani administracji bazą danych.
