Dlaczego to nie jest zwykły cron
Automat wystawiający faktury wygląda na prostą robotę: co jakiś czas sprawdź, które pozycje harmonogramu dojrzały, i wystaw dokument. Pierwsza wersja takiego zadania działa. Problem pojawia się przy pierwszej zerwanej odpowiedzi HTTP.
Najgroźniejszy scenariusz to nie błąd aplikacji, tylko utracona odpowiedź. Żądanie dociera do systemu księgowego, faktura powstaje i idzie do KSeF, ale odpowiedź do nas nie wraca — timeout, restart kontenera, zerwane połączenie. Lokalnie widać porażkę. Ślepe ponowienie wystawia drugi dokument, którego nie da się wycofać jednym kliknięciem, bo jest już w rejestrze państwowym.
Trzy warstwy ochrony
- Atomowe przejęcie zadania. Zanim runner cokolwiek wystawi, jednym zapytaniem z warunkiem na statusie oznacza pozycję jako „w trakcie”. Dwa równoległe przebiegi nie przejmą tej samej pozycji, bo wygra tylko jeden zapis.
- Ograniczenia unikalności po obu stronach. Pozycja harmonogramu i wystawiona faktura mają wspólny klucz okresu rozliczeniowego, wymuszony przez bazę. Nawet gdyby logika zawiodła, baza odmówi zapisania drugiego dokumentu za ten sam etap.
- Rekoncyliacja przed każdym ponowieniem. Zanim runner ponowi nieudaną próbę, pyta system księgowy, czy dokument o tym opisie już istnieje — i jeśli tak, adoptuje go zamiast tworzyć nowy. Gdy rekoncyliacji nie da się wykonać, runner nie wystawia niczego i czeka.
Z tej ostatniej warstwy wynika nieoczywista konsekwencja dla każdego, kto dotknie tego kodu później: opis faktury jest kluczem wyszukiwania. Budowany jest tą samą funkcją przy tworzeniu i przy szukaniu, z identycznym przycinaniem długości. Rozjazd o jeden znak oznacza „nie znaleziono”, czyli duplikat w rejestrze. Ta zasada jest opisana w repozytorium nad samą funkcją, nie w osobnym dokumencie, którego nikt nie otworzy.
„Wystawione” znaczy coś więcej niż 200 OK
System księgowy potwierdza przyjęcie dokumentu od razu, ale numer referencyjny z KSeF przychodzi później. Dlatego osobny przebieg dopytuje o potwierdzenie i dopiero ono zamyka pozycję. Brak potwierdzenia po dwunastu godzinach generuje alert na skrzynkę — bo faktura, o której myślimy, że jest w KSeF, a której tam nie ma, to problem, który ujawni się dopiero przy kontroli.
Testy, bo inaczej nie można tego wdrożyć
Ścieżka ma zestaw szesnastu scenariuszy end-to-end uruchamianych na prawdziwej bazie z symulowanym systemem księgowym: zerwana odpowiedź w trakcie wystawiania, proces zabity między zapisem a potwierdzeniem, równoległe przebiegi tej samej pozycji, duplikat po stronie księgowości, niedostępna rekoncyliacja. Każda zmiana w tym obszarze przechodzi przez ten zestaw, zanim trafi na produkcję.
Efekt
Od wdrożenia mechanizm nie wygenerował ani jednego błędnego dokumentu. Operator przegląda wygenerowaną propozycję harmonogramu, zatwierdza, i wraca do tematu dopiero wtedy, gdy coś wymaga decyzji człowieka.