How poulcuzz/ksef-import works
Typ projektu i cel (z plików + README)
To lekka aplikacja webowa (single-page UI + PHP backend) służąca do importowania (w praktyce eksportu z KSeF i pobrania) faktur z Krajowego Systemu e‑Faktur w kilku krokach.
• Frontend: statyczne index.html + styles.css + app.js (formularz, wywołania API, pobranie ZIP do przeglądarki).
• Backend: api.php jako pojedynczy entrypoint (router po parametrze action=), logika w src/**.
• Integracja zewnętrzna: komunikacja z KSeF API (różne środowiska demo/test/prod).
• Bezpieczeństwo: autoryzacja tokenem lub certyfikatem, szyfrowanie RSA-OAEP + AES-256, obsługa kluczy i decrypt pliku ZIP.
• Stan/artefakty lokalne: logi w logs/, pliki tymczasowe w temp/, cache kluczy w src/**/keys_cache.
Wniosek do diagramu: to nie jest mikroserwis ani rozbudowany system; to monolit PHP + statyczny front z wyraźnymi modułami: API Actions, Auth, Export, HTTP client, Logger.
Jak czytać strukturę i jak ją przełożyć na architekturę (mapowanie katalogów → komponenty)
Najważniejsze elementy do narysowania wynikają bezpośrednio z folderów w src:
Warstwa API (routing + actions)
• api.php – HTTP entrypoint; wybiera akcję na podstawie action=... i metody (GET/POST).
• src/Api/Actions/*Action.php – kontrolery/handlery dla endpointów:
• StartExportAction.php (w README endpoint start_import; nazewnictwo w kodzie sugeruje eksport KSeF)
• StartImportWithCertificateAction.php
• CheckStatusAction.php
• DownloadAction.php
• src/Api/ErrorHandler.php – centralna obsługa błędów i czytelne komunikaty.
• src/Api/Helpers.php – utilsy (walidacje/formatowanie/odpowiedzi).
Na diagramie: pokaż api.php jako “API Gateway/Router” → strzałki do “Actions”.
Warstwa orchestration / service
• src/KsefService.php – prawdopodobnie główny serwis spinający: auth → wywołanie KSeF → przygotowanie pobrania → logowanie.
Na diagramie: “KsefService (Application Service)” jako centralny komponent, do którego wołają Actions.
Auth (strategie autoryzacji + szyfrowanie tokena)
• src/Auth/AuthenticatorInterface.php – kontrakt strategii.
• src/Auth/KsefAuthenticator.php – autoryzacja tokenem.
• src/Auth/CertificateAuthenticator.php – autoryzacja certyfikatem/XAdES.
• src/Auth/TokenEncryptor.php – szyfrowanie (RSA-OAEP + AES-256).
• Cache kluczy (w README): src/Auth/keys_cache/* (np. token_key_demo.pem).
Na diagramie: “Auth Module” z dwoma wariantami (Token vs Certificate) + komponent “TokenEncryptor/KeyCache”.
Export / Download (obsługa szyfrowania plików i ZIP)
• src/Export/KsefExporter.php – logika eksportu z KSeF (inicjacja, status, pobranie).
• src/Export/EncryptionHandler.php – metadane szyfrowania/klucze sesyjne.
• src/Export/FileDecryptor.php – deszyfracja pobranego pliku.
• src/Export/ExporterInterface.php – kontrakt.
• Cache kluczy (w README): src/Export/keys_cache/public_key_*.pem
• last_export_encryption.json (w README) – stan szyfrowania ostatniego eksportu (ważne dla “download”).
Na diagramie: “Export Module” + “Local encryption metadata store (last_export_encryption.json)”.
HTTP client (integracja z KSeF)
• src/Http/KsefClient.php – klient HTTP (curl) do KSeF API.
Na diagramie: “KsefClient” → strzałka do zewnętrznego “KSeF API (demo/test/prod)”.
Logowanie i pliki
• src/Logger/JsonLogger.php, LoggerInterface.php – logowanie operacji API do plików.
• logs/ – persystencja logów.
• temp/ – pliki tymczasowe (i .htaccess sugeruje ochronę przed bezpośrednim listingiem/pobraniem).
Na diagramie: “File System Storage” z podziałem na logs/ i temp/.
Browser (UI)
2. Static Web Assets: index.html, app.js, styles.css (serwowane przez PHP built-in albo Apache/Nginx)
PHP Backend
• api.php router
• Actions
• KsefService
• moduły: Auth, Export, Http, Logger
Local File Storage
• temp/ (ZIP i/lub zaszyfrowane pliki)
• logs/ (JSON logi)
• keys_cache/ i last_export_encryption.json (stan/klucze)
Relacje / przepływy (strzałki z opisem)
Narysuj przynajmniej 4 główne przepływy odpowiadające endpointom:
Start import (token)
Browser → POST api.php?action=start_import → StartExportAction/StartImportAction → KsefService
→ KsefAuthenticator + TokenEncryptor (RSA/AES, klucze)
→ KsefClient → KSeF API
→ zapis: last_export_encryption.json / pliki w temp/ (jeśli już pobiera)
→ JsonLogger → logs/
Start import (certificate)
Browser → POST api.php?action=start_import_certificate → StartImportWithCertificateAction
→ CertificateAuthenticator → KsefClient → KSeF API → logi/stan jak wyżej
Check status
Browser → GET api.php?action=check_status → CheckStatusAction
→ KsefService → KsefClient → KSeF API → status → Browser
(+ logowanie)
Download ZIP
Browser → GET api.php?action=download → DownloadAction
→ KsefService / KsefExporter (pobranie pliku) → KsefClient → KSeF API
→ EncryptionHandler + FileDecryptor (jeśli dotyczy)
→ zapis w temp/ (opcjonalnie)
→ odpowiedź: streaming ZIP do Browser
(+ logowanie)
Wzorce/zasady architektoniczne, które warto nazwać na diagramie
• Front–Back separation: statyczny UI i API w PHP.
• Single entrypoint + Action handlers: api.php jako router, Actions jako kontrolery.
• Strategy pattern dla auth: AuthenticatorInterface + KsefAuthenticator + CertificateAuthenticator.
• Ports & adapters / interface-first: ExporterInterface, LoggerInterface (łatwiejsza podmiana implementacji).
• Integration boundary: KsefClient jako adapter do zewnętrznego KSeF.
Dodaj etykiety typu “Strategy”, “Adapter”, “Service” przy komponentach — dla principal-level czytelności.
System Context (1 slajd)
• Użytkownik / Przeglądarka
• System “KSeF Import”
• Zewnętrzny “KSeF API”
• Lokalny filesystem (można jako część systemu)
Container + Component (1–2 slajdy)
• Container: Browser UI, PHP Backend, File Storage, External KSeF
• Component (wewnątrz backendu): api.php, Actions, KsefService, Auth, Export, KsefClient, Logger
To wystarcza, żeby uchwycić realną architekturę bez “overengineering”.
Wybierz “start_import → check_status → download” jako jeden scenariusz i narysuj sekwencję:
Browser → api.php → Action → KsefService → Auth → KsefClient → KSeF
… potem status … potem download (z decrypt/stream).
Sekwencja często daje większą “prawdziwość” niż statyczny obrazek.
Elementy, które masz obowiązkowo umieścić (czytelność + precyzja)
• Czytelne etykiety komponentów z nazwami zgodnymi z repo:
• api.php, KsefService, KsefClient, JsonLogger, KsefAuthenticator, CertificateAuthenticator, KsefExporter, FileDecryptor, EncryptionHandler
• Strzałki kierunkowe z podpisami protokołu/danych:
• “HTTP (GET/POST)”
• “KSeF REST API via curl”
• “RSA-OAEP + AES-256 (token/file encryption)”
• “ZIP stream to browser”
• Kolor/kształt wg typu (proponowana legenda):
• Prostokąty: moduły aplikacji (Actions/Services)
• Cylindry: storage/stan (logs/, temp/, last_export_encryption.json)
• Chmura: zewnętrzny system (KSeF)
• Inny kolor dla “Security/Crypto” (Auth/Encryptor)
Co dodatkowo doprecyzować na diagramie (żeby był “maksymalnie komponentowy”)
Ponieważ prosisz o “jak najwięcej komponentów”, rozbij backend na logiczne klocki zamiast jednego bloku:
• api.php (Router)
• Api\Actions\* (4 osobne boxy)
• Api\ErrorHandler
• KsefService
• Auth:
• AuthenticatorInterface (jako adnotacja)
• KsefAuthenticator
• CertificateAuthenticator
• TokenEncryptor
• keys_cache (jako storage)
• Export:
• KsefExporter
• EncryptionHandler
• FileDecryptor
• last_export_encryption.json (storage)
• Http\KsefClient
• Logger\JsonLogger → logs/
• temp/ (z adnotacją: pliki tymczasowe/ZIP, zabezpieczone .htaccess)
Gotowy “szkielet” układu diagramu (jak to rozmieścić)
Układ lewo→prawo (czytelny data-flow):
• Left: Browser (UI)
• Center: PHP Backend (api.php + komponenty)
• Right: KSeF API (external)
• Bottom (pod backendem): File storage (temp/, logs/, caches)
To naturalnie pokazuje: UI → API → integracja → pliki/logi → odpowiedź do UI.