Dokumentacja Techniczna: Architektura Faktur i Integracja KSeF

Dokument opisuje architekturę systemu fakturowania oraz przepływ danych w integracji z Krajowym Systemem e-Faktur (KSeF) na platformie EnterSlot. Skupia się na relacyjnych strukturach danych, akcjach serwerowych oraz asynchronicznym procesie synchronizacji API.

1. Architektura Danych Finansowych

Struktura bazy danych opiera się na wydajnym modelu relacyjnym z centralną encją faktur i powiązanymi pozycjami, uwzględniając rygorystyczne wymogi integracji z Ministerstwem Finansów:

• Relacja Główna (1:N): Główny podmiot faktury przechowywany jest w ustrukturyzowanej tabeli, a poszczególne pozycje (usługi/produkty) są z nią ściśle powiązane kluczem obcym, wspierającym integralność kaskadową (Cascade Deletion).
• Zarządzanie Korektami: Logika faktur korygujących realizowana jest poprzez bezpieczne samozłączenia (Self-Joins), które wskazują na fakturę pierwotną. Weryfikacja po stronie serwera rygorystycznie wymaga, aby korygowany dokument posiadał już nadany i zatwierdzony docelowy numer KSeF.
• Kryptografia w Multi-Tenancy: Globalne parametry fakturowania oraz wrażliwe tokeny uwierzytelniające dla środowisk KSeF (produkcyjnych i testowych) są szyfrowane na poziomie bazy danych, zapewniając pełną izolację konfiguracji w modelu wielodostępnym (Multi-Tenant).

2. Budowanie i Generowanie Faktur

Zarządzanie cyklem życia dokumentu (CRUD) oraz generowanie jego fizycznej reprezentacji opiera się na architekturze rozproszonej:

• Mutacje Danych (Server Actions): Logika biznesowa centralizuje operacje mutacji (tworzenie, korekty, usuwanie) za pomocą bezpiecznych akcji serwerowych (Next.js Server Actions). Akcje te bezpośrednio i transakcyjnie modyfikują tabele bazy danych, po czym wyzwalają odświeżenie pamięci podręcznej (Cache Revalidation).
• Dynamiczne Generowanie PDF: Konwersja do formatu PDF jest obsługiwana przez dedykowane, autoryzowane endpointy API. Moduł generujący w locie rysuje struktury tabelaryczne, osadza statusy wizualne oraz kryptograficzne kody QR wymagane do weryfikacji. Zabezpieczenia backendowe blokują generowanie pliku PDF dla dokumentów B2B, dopóki nie uzyskają one zatwierdzonego statusu w KSeF.

3. Proces i Cykl Życia KSeF (Przepływ Asynchroniczny)

Architektura integracji z Ministerstwem Finansów bazuje na niezawodnym wzorcu "Fire & Forget" połączonym z asynchronicznym pollingiem statusów. Eliminuje to problem blokowania interfejsu użytkownika podczas komunikacji z powolnymi bramkami urzędowymi.

Etap 1: Budowa i Szyfrowanie (Pre-processing)

Proces przygotowania dokumentu przed opuszczeniem serwera:

• Budowa Schemy XML: Moduł systemowy transformuje dane do restrykcyjnej schemy FA(2). Przeprowadza rygorystyczną normalizację stawek VAT, mapuje węzły i agreguje sumy kontrolne, aby spełnić matematyczne wymogi walidatorów MF.
• Utrwalenie i Niezmienność: Wygenerowany ładunek XML (payload) jest zapisywany w bazie, a jego kryptograficzny skrót (SHA-256) gwarantuje absolutną niezmienność dokumentu po autoryzacji.
• Ochrona Tokenów: Surowe tokeny autoryzacyjne są odszyfrowywane wyłącznie w pamięci operacyjnej (w czasie rzeczywistym) za pomocą bezpiecznego algorytmu symetrycznego AES-256-GCM.

Etap 2: Wysyłka (Sesja Interaktywna)

Dedykowany serwis mikro-architektoniczny odpowiada za dostarczenie paczki do bramki Ministerstwa:

• Logika realizuje pełny, wieloetapowy proces autoryzacji: pobiera Challenge, szyfruje token kluczem publicznym Ministerstwa, uwierzytelnia JWT i otwiera bezpieczną sesję interaktywną.
• Zawartość XML jest szyfrowana w locie generowanym jednorazowo kluczem symetrycznym AES, który z kolei jest szyfrowany asymetrycznie i dołączany do nagłówków żądania (Envelope Encryption).
• Po udanym zgłoszeniu paczki, stan dokumentu ulega mutacji na "przetwarzany", a główny wątek aplikacji zostaje natychmiast zwolniony.

Etap 3: Asynchroniczna Weryfikacja i UPO (Cron Polling)

Kluczowy proces gwarantujący ostateczną finalizację dokumentu realizowany przez procesy w tle:

• Asynchroniczny Polling: Izolowane skrypty (Cron Jobs) cyklicznie odpytują bazę danych, wykorzystując do tego wysoce zoptymalizowane indeksy B-Tree, w poszukiwaniu faktur oczekujących na zatwierdzenie.
• Walidacja Statusu: Dla każdego rekordu wysyłane jest zautoryzowane zapytanie do środowiska Ministerstwa Finansów.
• Obsługa Sukcesu: Gdy faktura zostaje zatwierdzona, system wyodrębnia docelowy numer KSeF i bezpiecznie pobiera Urzędowe Poświadczenie Odbioru (UPO) w formacie XML dekodowanym z Base64.
• Obsługa Wyjątków: W przypadku odrzucenia dokumentu (np. błędy strukturalne, nieprawidłowy NIP), status przechodzi w stan błędu, a precyzyjne komunikaty wyjątków z API MF logowane są w celach diagnostycznych.
• Dystrybucja Dowodów: Pliki UPO są serwowane użytkownikom poprzez zabezpieczone endpointy API z restrykcyjną warstwą kontroli dostępu.