System ewidencji PSZOK w Starym Sączu

Punkt Selektywnej Zbiórki Odpadów Komunalnych w Starym Sączu przez lata działał na papierze. Pracownik ręcznie wypełniał formularz, sprawdzał deklarację telefonicznie, a limity liczył w zeszycie.

Zbudowałem system ewidencji, który prowadzi pracownika przez całą wizytę mieszkańca, od wyszukania deklaracji do wydruku protokołu. Działa w sieci urzędu i korzysta z danych, które gmina już ma.

Panel pracownika

Pracownik loguje się kontem z intranetu urzędu, więc nie ma osobnych haseł do pamiętania. Na pulpicie widzi, ile przyjęć było dziś i w tym miesiącu, listę ostatnich wizyt z numerami protokołów i przycisk nowego przyjęcia.

System działa od maja 2026 roku. W samym październiku punkt obsłużył przez niego ponad 400 wizyt, a numeracja protokołów przekroczyła 2300.

Dane, których nie trzeba wpisywać drugi raz

Mieszkaniec może oddać odpady bezpłatnie, jeśli ma aktywną deklarację śmieciową. Ta informacja jest w systemie podatkowym urzędu. Zamiast budować kolejną kopię, system PSZOK czyta ją z intranetu na Directusie.

Osobny łącznik synchronizuje dane z programem dziedzinowym. Panel PSZOK nie ma do niego bezpośredniego dostępu, co ogranicza powierzchnię ataku do jednego, kontrolowanego miejsca.

Pracownik szuka właściciela deklaracji na trzy sposoby:

• po numerze PESEL z dowodu albo upoważnienia,
• po numerze punktu odbioru, także czytnikiem kodów kreskowych,
• po nazwisku i adresie.

Wyszukiwanie po PESEL idzie zapytaniem POST, więc numer nie trafia do adresu URL, historii przeglądarki ani logów serwera.

Limit, którego system świadomie nie liczy

Najciekawsza decyzja w tym projekcie dotyczyła limitów. Uchwała rady daje bezpłatnie 2,2 metra sześciennego odpadów budowlanych albo 20 worków 120 litrów. Problem w tym, że 20 takich worków to 2,4 metra sześciennego.

Do tego mieszkaniec raz przywozi worki, a raz gruz luzem. Każdy automat, który próbowałby to rozstrzygnąć, w którymś momencie pomyliłby się na niekorzyść mieszkańca albo gminy.

Dlatego system pokazuje pracownikowi historię wizyt z bieżącego roku i zostawia decyzję jemu. Nadwyżka jest zawsze ważona, a opłata liczy się od kilogramów według stawki z ustawień.

Jeden rodzaj odpadu może dać na protokole dwa wiersze: część bezpłatną w limicie i zważoną nadwyżkę. Dzięki temu mieszkaniec widzi czarno na białym, za co płaci.

Protokół w jednym kliknięciu

Po zapisie wizyta dostaje numer w formacie PSZOK/rok/kolejny numer, a licznik zeruje się co roku. Protokół generuje usługa PDF w intranecie urzędu, z szablonu odwzorowującego załącznik do regulaminu punktu.

• część pierwsza: dane właściciela deklaracji, osoby dostarczającej i lista odpadów z limitami,
• część druga, tylko przy nadwyżce: usługa dodatkowa z masą, stawką, kwotą i kwotą słownie,
• obie części na jednej stronie A4, z miejscem na podpisy,
• druk albo pobranie PDF prosto z karty wizyty.

Po zmianie wzoru system sam wygenerował brakujące protokoły z wcześniejszych wizyt, więc archiwum jest kompletne.

Drobiazgi, które robią różnicę na bramie

• upoważnienie dla innej osoby to jedno pole, a dane pełnomocnika zapisują się tylko wtedy, gdy są potrzebne,
• zdjęcia odpadów dołączone do wizyty, z podglądem, nawigacją strzałkami i pobieraniem,
• anulowanie wizyty przez 3 godziny od zapisu, jako oznaczenie, a nie kasowanie z bazy,
• dziennik zmian systemu widoczny w panelu, generowany z historii repozytorium.

Zaślepka strony bez wdrożenia

Gdy punkt jest nieczynny, na przykład w czasie inwentaryzacji albo awarii, pracownik może jednym przełącznikiem pokazać na stronie publicznej komunikat zamiast zwykłej treści. Edytor ma podświetlanie składni i podgląd na żywo, a zmiana działa od razu, bez wdrażania czegokolwiek.

RODO od pierwszego dnia

System przetwarza PESEL-e, imiona i adresy, więc zasady ochrony danych spisałem przed pierwszą linijką kodu. Pola wrażliwe nie trafiają do logów ani eksportów, a panel działa wyłącznie w sieci urzędu.

Klucze do usług zewnętrznych są w zmiennych środowiskowych, a nie w kodzie. Gdy któregoś brakuje, aplikacja zgłasza czytelny błąd zamiast działać po cichu bez zabezpieczenia.

Strona dla mieszkańców

Część publiczna pod adresem pszok.starysacz.org.pl to jedna strona z godzinami otwarcia, statusem punktu na żywo, listą frakcji i dokumentami do pobrania. Projekt strony przygotował Mateusz Duda, a ja wpiąłem ją w system jako statyczną stronę i utrzymuję.

Stack

• Astro w trybie SSR na Node.js, TypeScript,
• TailwindCSS v4 i Flowbite w panelu pracownika,
• Directus intranetu urzędu jako źródło danych i usługa PDF,
• monorepo pnpm ze wspólnym klientem Directusa dla części publicznej i systemowej,
• Docker, wdrożenie na serwerach urzędu.