Schedulery, które pilnują obiegu dokumentów

Za automatyzację odpowiada proces exksef.Scheduler. Web pozostaje miejscem pracy operatora, a scheduler działa jako oddzielny host z własnym logiem, konfiguracją, walidacją zależności i cyklem życia. Przy starcie proces ładuje wspólne adaptery KSeF, Pekao Connect, pocztę, SMS, push, repozytoria i use case'y używane również przez aplikację webową.

Takie rozdzielenie ma praktyczne znaczenie. Zadania okresowe nie wykonują się w kontekście kliknięcia użytkownika, nie blokują strony i nie zależą od tego, czy ktoś ma otwartą przeglądarkę. Jednocześnie nie powstaje drugi świat logiki: scheduler korzysta z tych samych reguł domenowych, walidatorów, dispatcherów i repozytoriów co web.

Silnik CronSchedulerService pracuje minutowo. Po starcie zapisuje heartbeat, czeka do pełnej minuty, pobiera włączone zadania z bazy, sprawdza ich wyrażenia CRON i uruchamia tylko te przebiegi, których zaplanowany tick nie został jeszcze wykonany. Nieznane zadania są pomijane z ostrzeżeniem, a błędne wyrażenie CRON nie zatrzymuje procesu.

Domyślne zadania są seedowane do tabeli harmonogramu z nazwą techniczną, nazwą widoczną w panelu, domyślnym CRON-em i konfiguracją JSON. Wszystkie startują jako wyłączone, więc administrator świadomie uruchamia automatyzację dopiero po przygotowaniu tokenów, odbiorców powiadomień i ustawień integracji.

Stałe zadania systemowe

• KSeF - pobieranie faktur pobiera faktury przychodzące z zakresu od ostatniej synchronizacji, zapisuje XML, dodaje nowych sprzedawców do kolejki kontrahentów, wykrywa automatycznie opłacone dokumenty i może wysłać e-mail, SMS oraz push do aplikacji mobilnej.

• Raport - dzienny raport płatności zbiera płatności i faktury wymagające uwagi w bieżącym tygodniu. Płatności już opłacone są pomijane, a faktury z istniejącą płatnością nie dublują się w drugiej części raportu.

• Cykliczne - wykonanie płatności tworzy należne płatności z definicji cyklicznych, przesuwa harmonogram i raportuje wykonane, dezaktywowane oraz błędne pozycje.

• Cykliczne - wykonanie faktur generuje faktury sprzedażowe z definicji cyklicznych, raportuje wystawione dokumenty i nie wysyła pustych powiadomień, gdy nic nie było do zrobienia.

• KSeF - wsadowa wysyłka sprzedażowych bierze faktury sprzedażowe w statusie gotowym do wysyłki, wysyła paczkę do KSeF i zapisuje wynik: przyjęte, odrzucone, wysłane oraz numer sesji.

• KSeF - sprawdzanie statusów sprzedażowych odświeża faktury wysłane do KSeF, synchronizuje UPO i XML dla zaakceptowanych faktur oraz próbuje wyrównać przypadki duplikatów odrzuconych przez KSeF.

• Płatności - powiadomienie o przeterminowanych znajduje zaakceptowane faktury sprzedażowe po terminie, liczy łączną zaległość i najstarsze opóźnienie, a następnie wysyła raport do operatora.

• Płatności - powiadomienie kontrahentów obsługuje przypomnienia przed terminem i wezwania po terminie. Ma ochronę antyspamową, zapisuje historię wysyłki oraz pomija kontrahentów bez danych kontaktowych zamiast wywracać cały przebieg.

Zadania Pekao Connect

Joby Pekao Connect pojawiają się tylko wtedy, gdy integracja bankowa jest włączona. Dzięki temu instalacja bez Pekao nie dostaje martwych pozycji w harmonogramie.

• Pekao Connect - wysyłka płatności do banku przetwarza kolejkę QueuedForBank przez wspólny dispatcher przelewów. Wynik rozróżnia płatności wysłane, czekające na autoryzację, odrzucone, pominięte i błędne.

• Pekao Connect - statusy płatności odpytuje bank po pain.002 dla płatności wysłanych lub czekających na autoryzację, żeby szybciej wykryć odrzucenia i statusy wykonania.

• Pekao Connect - synchronizacja transakcji pobiera przyrostowy raport camt.052 i przez jeden matcher domyka debety jako opłacone płatności oraz kredyty jako wpłaty do faktur sprzedażowych. Niedopasowane wpłaty trafiają do reakcji operatora.

W administracji zakładka harmonogramu pokazuje nazwę zadania, CRON, przełącznik włączenia, ostatnie uruchomienie, wynik oraz akcje zapisu i konfiguracji. Operator techniczny nie uruchamia tu jobów ręcznie. Ta strona służy do ustawienia rytmu pracy i parametrów, a wykonanie pozostaje po stronie procesu schedulera.

Każde zadanie może mieć własny dialog konfiguracji. Joby KSeF wymagają użytkownika z tokenem KSeF, joby raportowe mają odbiorców e-mail/SMS, a Pekao Connect używa ustawień bankowych i kursora transakcji tam, gdzie jest to potrzebne. UI nie udaje, że wszystkie automatyzacje mają ten sam formularz.

Czas ostatniego przebiegu jest prezentowany w czasie lokalnym aplikacji, a nie jako surowe UTC. To ważne dla operatora, bo historia ma odpowiadać temu, co faktycznie widać w pracy firmy: kiedy pobrano faktury, kiedy poszła paczka do KSeF, kiedy bank zwrócił status i kiedy wysłano powiadomienia.

Każde wykonanie zadania kończy się wynikiem Completed, Skipped albo Failed. To celowe rozróżnienie. Brak płatności do wysyłki, brak faktur do raportu albo wyłączona integracja Pekao Connect nie są awarią aplikacji. Z kolei błąd pobrania raportu, problem z tokenem czy brak konfiguracji trafiają do czytelnego komunikatu i historii.

Po zakończeniu scheduler zapisuje LastRunAtUtc, status powodzenia i ewentualny komunikat błędu na samym zadaniu. Równolegle dopisuje rekord do jednolitego logu biznesowego z nazwą joba, nazwą źródłową, czasem startu i końca, statusem, podsumowaniem, szczegółami oraz metrykami JSON.

Dzięki temu administracja widzi zarówno szybki stan ostatniego przebiegu, jak i pełniejszą historię: ile faktur pobrano z KSeF, ile płatności utworzono z cyklicznych reguł, ile faktur wysłano do KSeF, ile przelewów przyjęło Pekao, ile pozycji odrzucono oraz co wymagało reakcji operatora.

Najważniejsze decyzje w schedulerze dotyczą nie samego wywołania co kilka minut, ale ograniczenia ryzyka.

• Świadome włączanie sprawia, że nowe zadania nie zaczynają działać po migracji bez decyzji administratora.

• Idempotentny seed po nazwie technicznej joba zapobiega dublowaniu harmonogramu przy kolejnych startach procesu.

• Heartbeat niezależny od zadań pozwala webowi pokazać, czy proces żyje nawet wtedy, gdy wszystkie joby są wyłączone.

• Scope per wykonanie izoluje zależności, repozytoria i transakcje dla konkretnego przebiegu.

• Wspólne use case'y ograniczają rozjazd między ręczną akcją z weba i automatem działającym w tle.

• Warunkowa rejestracja Pekao Connect usuwa z procesu bankowe joby, gdy integracja nie jest aktywna.

• Powiadomienia tylko przy sensownych zdarzeniach chronią operatora przed pustymi raportami i informacyjnym szumem.

Schedulery są dobrym przykładem tego, że ExKSeF nie jest tylko zestawem ekranów CRUD. System ma procesy długotrwałe, integracje z zewnętrznymi usługami, zadania zależne od czasu, diagnostykę, retry przez kolejny cykl, osobne kanały powiadomień i wspólną warstwę domenową dla weba oraz pracy w tle.

W praktyce oznacza to umiejętność budowania aplikacji operacyjnej: takiej, która nie tylko przyjmuje kliknięcia użytkownika, ale pilnuje obiegu dokumentów przez całą dobę, zostawia ślad audytowy i potrafi bezpiecznie wrócić do pracy po błędzie konfiguracji, braku tokena, odrzuceniu przez bank albo chwilowej niedostępności integracji.