W połowie września w naszym programie księgowym pojawiła się faktura korygująca na 0,00 zł. Nikt jej nie chciał, nikt jej nie potrzebował, a mimo to została wystawiona, dostała numer i stanęła w kolejce do Krajowego Systemu e-Faktur. Kiedy spróbowaliśmy ją usunąć, program odpowiedział, że dokument oczekujący na wysyłkę do KSeF jest nieusuwalny. Został mail do biura obsługi z prośbą o zdjęcie go z kolejki i świadomość, że w rejestrze naszej spółki wisi papier, który powstał z jednej próbnej komendy.
To był trzeci taki przypadek w ciągu trzech dni. Najpierw testowa faktura VAT poszła do KSeF, choć miała tylko sprawdzić, czy proforma zamienia się w fakturę. Potem „test na sucho” z wycofaniem transakcji zostawił w bazie magazynu pozycję-widmo. Na koniec ta korekta. Prowadzę agencję automatyzacji dla małych i średnich firm, sam sprzedaję przez własny sklep internetowy i wszystko, co radzę klientom, najpierw testuję na sobie. Ten tekst jest o tym, ile kosztuje testowanie na produkcji, kiedy po drugiej stronie stoi urząd, i co zbudowaliśmy, żeby to się nie powtórzyło.
Spis treści
- Jak „pusty” zapis na próbę stał się prawdziwą korektą?
- Dlaczego test z wycofaniem transakcji zostawił w bazie widmo?
- Co łączyło te trzy wpadki?
- Jak testujemy automat faktur, skoro program księgowy nie ma piaskownicy?
- Po co człowiek zatwierdza pierwsze 10 faktur, skoro testy przeszły?
- Czego nadal nie da się przetestować?
- Jak sprawdzić, czy twój automat też testuje na żywym organizmie?
- Słownik pojęć
Jak „pusty” zapis na próbę stał się prawdziwą korektą?
Kontekst jest prozaiczny. W naszym sklepie hokejowym faktury wystawia panel magazynowy, który rozmawia z programem księgowym przez API. Pisałem już o tym, jak faktury wystawiają się u nas same i gdzie zostawiliśmy człowiekowi ostatnie kliknięcie. We wrześniu dokładaliśmy do tego korekty: klient anuluje opłacone zamówienie po wystawieniu faktury, więc potrzebna jest korekta do zera. Zanim napisze się taki moduł, trzeba wiedzieć, jakiej struktury danych oczekuje program po drugiej stronie.
Dokumentacja API była ogólnikowa. Kod u nas pisze agent AI pod moim nadzorem i zrobił to, co w takiej sytuacji robi każdy programista, którego znam: wysłał sondę. Prawdziwy identyfikator faktury jako dokumentu nadrzędnego, typ „korekta” i puste pozycje. Założenie było proste. Program odrzuci zapytanie bez pozycji, a w komunikacie błędu powie, czego mu brakuje. Tak działa większość systemów, z którymi pracowaliśmy.
Ten nie odrzucił. Odpowiedział „OK” i utworzył korektę o wartości 0,00 zł do istniejącej faktury. Dokument dostał numer w serii, został zaksięgowany i, ponieważ program wysyła do KSeF wsadowo, w ciągu kilku minut stanął w kolejce. Próba usunięcia zwróciła odmowę: dokument oczekujący na wysyłkę wsadową do KSeF jest nieusuwalny i niemodyfikowalny. Finansowo nic się nie stało, korekta zerowa niczego nie zmienia. Formalnie w rejestrze spółki jest faktura korygująca, która nie powinna istnieć, i prośba do biura obsługi programu, żeby ją zdjąć.
Dwa dni wcześniej było podobnie, tylko głośniej. Sprawdzaliśmy ścieżkę proforma → faktura VAT. Test zadziałał znakomicie: utworzył prawdziwą proformę, zamienił ją w prawdziwą fakturę VAT, a faktura poszła do kolejki KSeF. Usunąć się nie dało, dopóki nie anulowałem jej ręcznie w programie. Dopiero po anulowaniu dało się skasować fakturę, a na końcu proformę. Trzy kroki sprzątania po jednym kliknięciu „sprawdźmy, czy działa”. Szczerze? Przez chwilę miałem ochotę wyłączyć cały moduł faktur i wrócić do wystawiania ręcznie.
Dlaczego test z wycofaniem transakcji zostawił w bazie widmo?
Druga historia dotyczy nie programu księgowego, tylko naszej własnej bazy danych. I jest dla mnie bardziej pouczająca, bo tu nie było żadnego zewnętrznego systemu, na który można zrzucić winę.
Panel magazynowy stoi na SQLite. W połowie września dopinaliśmy do sprzedaży przez kasę rozliczanie kosztu własnego metodą FIFO. Trzeba było sprawdzić, czy sprzedaż z kasy zdejmuje stan i tworzy zapis kosztowy. Pomysł na „bezpieczny test” brzmiał rozsądnie: otwieramy transakcję, wołamy funkcję sprzedaży, patrzymy na wynik i wycofujemy wszystko jedną komendą. Baza wraca do stanu sprzed testu, nikt nic nie zauważa.
Baza nie wróciła. Po wycofaniu transakcji stan jednego z produktów pokazywał dwie sztuki zamiast trzech, a w tabeli ruchów magazynowych został zapis sprzedaży, której fizycznie nie było. Pozycja-widmo. Gdyby przeszła niezauważona, raport dla biura księgowego na koniec miesiąca pokazałby sprzedaż, do której nie ma paragonu, i niedobór sztuki na półce.
Co zatwierdzało zmiany za naszymi plecami
Przyczyna była w środku naszego kodu, nie w SQLite. Funkcje pomocnicze, których używa ścieżka sprzedaży, same zatwierdzają zmiany po każdej operacji. Tak zostały napisane, żeby żadna sprzedaż nie przepadła, gdy proces padnie w połowie. Z perspektywy sprzedaży przez kasę to zaleta. Z perspektywy „testu z wycofaniem” to oznacza, że moje wycofanie nie miało już czego wycofywać, bo każdy krok został zapisany na stałe sekundę wcześniej.
Następnego dnia ten sam błąd wrócił w innym przebraniu. Testowaliśmy tworzenie dokumentu wydania, znów z wycofaniem na końcu. Tym razem zmiany zatwierdził nie nasz kod, tylko sama biblioteka: funkcja, która przy starcie sprawdza, czy istnieją potrzebne tabele, wykonuje polecenie tworzenia tabel, a w SQLite takie polecenie zamyka otwartą transakcję i zapisuje wszystko, co było przed nim. Znów stan produktu spadł z trzech do dwóch, znów w bazie został testowy ruch z opisem „TEST”.
Oba widma wykryliśmy, bo po każdym teście czytaliśmy stan z bazy, zamiast ufać, że wycofanie zadziałało. Sprzątanie zajęło kilka minut: zrzut śladów do pliku, usunięcie zapisów oznaczonych identyfikatorem testu, przywrócenie stanu, ponowny odczyt. Ale „kilka minut” to łaskawa wersja. Gdyby test trafił na sobotni wieczór, a raport poszedł do księgowej w poniedziałek rano, mielibyśmy rozjazd między magazynem a dokumentami, którego nikt nie umiałby wyjaśnić.
Co łączyło te trzy wpadki?
Kiedy siedliśmy nad tym z agentem, który pisał ten kod, wspólny mianownik wyszedł od razu i był nieprzyjemny. Za każdym razem test opierał się na założeniu, że operacja się nie wykona. Program odrzuci puste pozycje. Wycofanie cofnie zapis. Proforma to nie faktura, więc nic nie pójdzie do urzędu. Żadne z tych założeń nie było sprawdzone. Każde brzmiało wiarygodnie i każde okazało się fałszywe w konkretnych warunkach.
To jest, moim zdaniem, najczęstszy błąd przy automatyzacji w małych firmach i popełniają go zarówno ludzie, jak i agenty AI. Zakładamy, że system zachowa się tak, jak zachowałby się rozsądny człowiek. Rozsądny księgowy, któremu podasz korektę bez pozycji, zapyta, o co ci chodzi. Program nie pyta. Program ma pole „pozycje”, pole jest puste, zapis przechodzi walidację, dokument powstaje. Automat jest dosłowny jak stażysta pierwszego dnia pracy, tylko ten stażysta nie zadaje pytań.
Druga rzecz, którą sobie wtedy powiedzieliśmy: skutek testu nie zależy od intencji testującego. Nieważne, że chcieliśmy tylko popatrzeć. Dla KSeF dokument wystawiony na próbę jest tak samo prawdziwy jak dokument wystawiony klientowi. Dla biura księgowego pozycja-widmo w raporcie jest tak samo prawdziwa jak sprzedaż z paragonem. W systemach, które mają skutki na zewnątrz, nie istnieje tryb „to tylko próba”, dopóki sam go nie zbudujesz.
Od tamtego tygodnia obowiązuje u nas zasada zapisana w rejestrze reguł, który czyta każdy nasz agent przed pracą: na produkcyjnej bazie „test na sucho” nie istnieje. Albo kopia, albo gotowe, przetestowane sprzątanie z identyfikatorem, po którym da się znaleźć każdy ślad. Druga reguła dotyczy programu księgowego wprost: nigdy nie wysyłamy do niego zapisu „żeby poznać kontrakt”, bo dokument powstaje nawet z pustymi danymi i idzie do KSeF.
Jak testujemy automat faktur, skoro program księgowy nie ma piaskownicy?
Tu dochodzimy do sedna problemu. Pod koniec września biuro księgowe potwierdziło, że każde zamówienie ze sklepu ma dostawać fakturę VAT. Przy kilkudziesięciu zamówieniach miesięcznie ręczne wystawianie to godziny pracy, więc powstał automat: zamówienie opłacone i wydane kurierowi dostaje fakturę w programie księgowym, program wysyła ją do KSeF, a po nadaniu numeru KSeF PDF wraca do sklepu i do klienta. Logika prosta. Jak to przetestować, skoro każdy prawdziwy zapis w programie księgowym to prawdziwy dokument w urzędzie?
Program, z którego korzystamy, nie ma środowiska testowego. Zapytaliśmy, sprawdziliśmy dokumentację, nie ma. Każda faktura wystawiona przez API to faktura w księgach spółki i w KSeF. Z punktu widzenia dostawcy to pewnie rozsądne, bo większość klientów klika w interfejsie i nie pisze własnych automatów. Z punktu widzenia firmy, która chce zautomatyzować fakturowanie, to oznacza, że trzeba zbudować własną piaskownicę.
Kopia bazy, atrapa programu, atrapa sklepu
Zbudowaliśmy ją z trzech elementów. Pierwszy to kopia bazy panelu, robiona na chwilę przed testem i kasowana po nim. Nie lokalna baza z wymyślonymi danymi, tylko wierna kopia produkcji: prawdziwe zamówienia, prawdziwi klienci, prawdziwe kwoty z kuponami rabatowymi i kosztami dostawy. Właśnie na takich danych wychodzą błędy, których nie wymyślisz przy biurku.
Drugi element to atrapa programu księgowego. Mały obiekt, który podstawia się pod funkcje rozmawiające z API i zamiast wysyłać zapytania, zapisuje je i zwraca odpowiedzi takie, jakich spodziewamy się od prawdziwego programu: identyfikator faktury, numer, po chwili numer KSeF. Dzięki temu test może sprawdzić, jaki dokładnie dokument automat chciał wystawić, pozycja po pozycji, bez wystawiania czegokolwiek. Trzeci element to atrapa kolejki sklepu, bo automat po wystawieniu faktury odsyła PDF do sklepu i test musi zobaczyć, że odsyła właściwy plik do właściwego zamówienia.
22, 25, 28. Skąd te liczby
Pierwsza wersja testu na kopii sprawdzała 22 scenariusze: zamówienie opłacone i wydane, zamówienie testowe (adres e-mail z domeny testowej, nazwisko zaczynające się od „Test”), zamówienie sprzed daty odcięcia, zamówienie z paragonem, zamówienie już zafakturowane, zamówienie scalone z innym, zamówienie w trybie podglądu kontra w trybie zatwierdzania. 22 z 22 przeszły.
Kilka godzin później doszły trzy kolejne, bo Artur, mój wspólnik, zapytał, co się stanie, gdy ktoś z zespołu wystawi fakturę ręcznie w programie, zanim automat zdąży. Dobre pytanie, na które pierwsza wersja nie miała odpowiedzi. Automat dostał funkcję, która przed wystawieniem szuka w programie faktury dla tego samego nabywcy na tę samą kwotę brutto albo z numerem zamówienia w opisie. Trafienie oznacza, że zamówienie ląduje w stanie „faktura ręczna w programie” i automat go nie dotyka. 25 z 25.
Dzień później biuro księgowe doprecyzowało dwie rzeczy: fakturę wystawiamy przy wysyłce, nie przy opłaceniu, a datą sprzedaży jest data wydania towaru, nie data złożenia zamówienia. Obie reguły weszły do kodu, do testu doszły trzy scenariusze. 28 z 28. Każda z tych liczb to konkretna rozmowa z człowiekiem, który wiedział coś, czego my nie wiedzieliśmy. Test rósł razem z wiedzą, nie wyprzedzał jej.
Pułapka, która omal nie zepsuła samego testu
Jedna rzecz z tej budowy warta jest osobnego akapitu, bo pokazuje, jak łatwo piaskownica po cichu przestaje być piaskownicą. Kod panelu szuka bazy w katalogu obok siebie. Kiedy skopiowaliśmy panel do katalogu tymczasowego, kopia panelu sama zaczęła czytać kopię bazy. Wygodne. Ale wystarczyłoby, żeby ktoś kiedyś przeniósł kopię panelu w inne miejsce albo ustawił zmienną środowiskową z adresem bazy, i test po cichu zacząłby pisać do produkcji, nadal raportując „28 z 28”.
Dlatego test ma na starcie twarde sprawdzenie ścieżki do bazy. Jeśli ścieżka nie zawiera katalogu tymczasowego, test przerywa pracę, zanim cokolwiek zapisze. Jedna linijka. Bez niej wszystko powyżej byłoby złudzeniem bezpieczeństwa, a złudzenie bezpieczeństwa jest gorsze niż jego brak, bo przestajesz patrzeć.
Po co człowiek zatwierdza pierwsze 10 faktur, skoro testy przeszły?
Bo atrapa programu księgowego odpowiada tak, jak my się spodziewamy, że odpowie prawdziwy program. A cała ta historia zaczęła się od tego, że prawdziwy program odpowiedział inaczej, niż się spodziewaliśmy. Test na kopii z atrapą sprawdza naszą logikę: czy automat wybiera właściwe zamówienia, liczy właściwe kwoty, pomija właściwe wyjątki. Nie sprawdza i nie może sprawdzić, jak zachowa się program księgowy i KSeF, bo pierwsza prawdziwa odpowiedź przyjdzie dopiero przy pierwszej prawdziwej fakturze.
Stąd warunek, który postawiłem przed włączeniem automatu: pierwsze 10 faktur zatwierdza człowiek. Automat działa w trybie „zatwierdzanie”. Przygotowuje fakturę, pokazuje ją w panelu obok zamówienia, pozycja po pozycji, z porównaniem kwoty faktury z kwotą zapłaconą, i czeka. Ktoś z zespołu patrzy, klika „zatwierdź” albo „odrzuć”. Dopiero po zatwierdzeniu zapis idzie do programu księgowego i dalej do KSeF. Jeśli faktura czeka dłużej niż dobę, dostaję alarm, żeby kolejka nie urosła po cichu.
Dziesięć to nie liczba z sufitu. Przy naszej skali to mniej więcej tydzień sprzedaży, czyli wystarczająco dużo, żeby przeszły przez automat różne typy zamówień: z kuponem, z darmową dostawą, z odbiorem osobistym, z firmowym NIP-em i bez. Jeśli przez dziesięć faktur program księgowy ani razu nie zaskoczy, przełączamy automat w tryb pełny. Jeśli zaskoczy, zaskoczy przy fakturze, na którą ktoś patrzył, a nie przy czterdziestej z rzędu w sobotnią noc.
Wyłącznik jest domyślnie wyłączony. Włącza go człowiek, świadomie, słowem „włącz”. Kiedy piszę ten tekst, automat nadal pracuje w trybie podglądu: pokazuje, co by wystawił, i nie wystawia nic. Między „testy przeszły” a „włączamy” jest jeszcze rozmowa z biurem księgowym o scenariuszu anulowania, i nie zamierzam jej skracać.
Czego nadal nie da się przetestować?
Uczciwie: korekty. Automat ma moduł korekty do zera dla zamówienia anulowanego po wystawieniu faktury. Ma tryb podglądu, który pokazuje, jak korekta by wyglądała, i działa poprawnie na kopii. Ale prawdziwy zapis korekty wymaga prawdziwej faktury z prawdziwym numerem KSeF, a każda taka korekta jest dokumentem nieusuwalnym. Nie da się jej „sprawdzić raz na próbę”. Wiemy to z września.
Decyzja jest więc taka, że moduł korekt ma osobny wyłącznik, również domyślnie wyłączony, a pierwsza prawdziwa korekta zostanie wykonana pod nadzorem, przy pierwszym prawdziwym anulowaniu, z człowiekiem patrzącym na ekran. Nie podoba mi się to. Wolałbym mieć test. Ale udawanie, że atrapa odpowie za urząd, byłoby dokładnie tym błędem, od którego zaczął się ten tekst.
Podobny wzorzec opisywałem przy kopii zapasowej, która skasowała się sama: są operacje, których nie da się przećwiczyć bez skutków, i wtedy jedyne, co zostaje, to zwolnić, podzielić na kroki i trzymać człowieka przy pierwszym przebiegu. Automatyzacja nie polega na usunięciu człowieka z procesu. Polega na tym, żeby człowiek patrzył tam, gdzie patrzenie ma sens, a nie na wszystko po trochu.
Jak sprawdzić, czy twój automat też testuje na żywym organizmie?
Jeśli masz w firmie automat, który dotyka faktur, płatności albo KSeF, albo dopiero go zamawiasz, zadaj wykonawcy pięć pytań. Odpowiedzi powiedzą ci więcej niż każda prezentacja.
- Gdzie był testowany? Jeśli odpowiedź brzmi „na waszym koncie, ale wszystko posprzątaliśmy”, dopytaj, co dokładnie zostało wystawione i czy poszło do KSeF. Dokumenty w kolejce wsadowej nie dają się usunąć, więc „posprzątaliśmy” ma granice.
- Czy program księgowy ma środowisko testowe? Większość popularnych w Polsce programów nie ma. Wtedy pytanie brzmi: z czego zbudowano piaskownicę i jak test pilnuje, żeby nie pisać do produkcji.
- Co się dzieje przy pierwszych fakturach? Tryb podglądu, tryb zatwierdzania, czy od razu pełny automat? Jeśli od razu pełny, zapytaj, kto zobaczy błąd pierwszy: wy czy klient.
- Jak wygląda sprzątanie po błędzie? Nie „czy jest”, tylko „pokaż”. Identyfikator testu w każdym zapisie, zrzut przed zmianą, procedura przywrócenia. Jeśli tego nie ma, każdy test jest ruletką.
- Czego nie da się przetestować? Uczciwy wykonawca wymieni przynajmniej jedną rzecz. Ten, który powie „wszystko przetestowane”, albo nie zna systemu, albo nie zna KSeF.
Dodam jedno z własnego podwórka. Jeśli kod pisze u ciebie agent AI, powyższe pytania są jeszcze ważniejsze, nie mniej. Agent zakłada tak samo jak człowiek, tylko szybciej i pewniej. Trzy wpadki z września zrobił agent, ale zasady, według których pracował, ustawiłem ja. Reguła „na żywej bazie nie ma próby” musiała trafić do jego instrukcji na piśmie, bo z samego doświadczenia nie wyciągnie jej na drugi dzień. Człowiek pamięta wstyd. Agent pamięta tylko to, co mu zapiszesz.
I ostatnia myśl, ta do zapamiętania. Program księgowy bez piaskownicy to nie wada, z którą trzeba się pogodzić. To informacja, że piaskownicę musisz zbudować sam, zanim napiszesz pierwszą linijkę automatu. Kopia bazy, atrapa po drugiej stronie, twarde sprawdzenie, że test pisze tam, gdzie ma pisać. Trzy rzeczy, jeden dzień pracy. Korekta na 0,00 zł w rejestrze spółki kosztowała nas więcej, choćby dlatego, że piszę o niej do dziś.
Słownik pojęć
- KSeF (Krajowy System e-Faktur) - państwowy system, przez który przechodzą faktury. Dokument, który do niego trafi, jest ostateczny. Nie da się go usunąć ani zmienić, można tylko wystawić do niego korektę, która też zostaje na stałe.
- Wysyłka wsadowa - tryb, w którym program księgowy zbiera wystawione faktury i wysyła je do KSeF paczkami co kilka minut. Dokument czekający w takiej kolejce jest już zablokowany przed usunięciem.
- Transakcja i wycofanie - mechanizm bazy danych, w którym grupę zmian można zapisać razem albo razem cofnąć. Wycofanie działa tylko wtedy, gdy żadna z funkcji po drodze nie zatwierdziła zmian sama.
- Atrapa (mock) - podstawiony w teście obiekt, który udaje prawdziwy system: przyjmuje zapytania, zapisuje je i odpowiada tak, jak spodziewamy się odpowiedzi prawdziwego systemu, bez wywoływania skutków.
- Tryb podglądu i tryb zatwierdzania - dwa stany automatu przed pełnym włączeniem. W podglądzie automat pokazuje, co by zrobił, i nic nie robi. W zatwierdzaniu przygotowuje dokument i czeka na kliknięcie człowieka.
Zanim włączysz automat, który dotyka KSeF
Jeśli budujesz albo zamawiasz automatyzację faktur i nie wiesz, jak ją bezpiecznie przetestować bez wystawiania prawdziwych dokumentów, napisz do mnie na [email protected]. Opowiem, jak wygląda nasza piaskownica z kopią bazy i atrapą programu księgowego, i które z pięciu pytań powyżej warto zadać twojemu wykonawcy jako pierwsze. Jak pracuję z firmami, opisałem osobno.
własnej firmie cybulski.ai JC


