update

.paul/docs/ARCHITECTURE.md

@@ -1,3 +1,94 @@
-# ARCHITECTURE
+# ARCHITECTURE
 
-> Struktura klas, modulow, przeplywow i zaleznosci w projekcie.
+## Zakres
+- Dokument opisuje aktualna architekture kodu (stan repo: 2026-04-18).
+- Zrodlem prawdy sa: `src/`, `routes/web.php`, `database/migrations/`.
+
+## Warstwy systemu
+- `Core`: bootstrap aplikacji, router, request/response, sesja, template, migrator, logger.
+- `Modules/*Controller`: obsluga requestow HTTP i walidacja wejscia.
+- `Modules/*Repository`: dostep do danych przez PDO/Medoo (prepared statements).
+- `Modules/*Service`: logika domenowa i integracje zewnetrzne.
+- `Cron`: runner, schedulery i handlery jobow okresowych.
+
+## Moduly domenowe
+- `Auth`: logowanie, wylogowanie, middleware sesyjne.
+- `Users`: zarzadzanie uzytkownikami panelu.
+- `Orders`: lista, szczegoly, statusy, platnosci reczne, preview, quick search.
+- `Shipments`: przygotowanie, tworzenie, status trackingu, etykiety, usuwanie, paczki reczne.
+- `Accounting`: paragony i eksport ksiegowy.
+- `Email`: wysylka i preview wiadomosci z resolverem zmiennych i zalacznikow.
+- `Automation`: reguly event-condition-action, historia wykonan.
+- `Settings`: konfiguracja statusow, integracji, cron, skrzynek, szablonow, drukowania, mapowan projektow.
+- `Printing`: API kolejkowania wydruku i klucze API dla klienta desktop.
+- `Cron`: synchronizacje integracji i zadania utrzymaniowe.
+- `Info`: endpoint diagnostyczny `/info`.
+
+## Kluczowe klasy i odpowiedzialnosci
+- `App\Core\Application`: bootstrap, dispatch requestu, opcjonalny web-cron z lockiem DB.
+- `App\Modules\Cron\CronRunner`: pobiera kolejke jobow z `cron_schedules/cron_jobs` i wykonuje handlery.
+- `App\Modules\Cron\CronHandlerFactory`: sklada zaleznosci i mapuje `job_type -> handler`.
+- `App\Modules\Orders\OrdersController`: flow UI zamowien + endpointy AJAX.
+- `App\Modules\Orders\OrdersRepository`: query listy/szczegolow zamowien, update statusow, activity log.
+- `App\Modules\Shipments\ShipmentController`: flow przesylek i etykiet.
+- `App\Modules\Shipments\ShipmentProviderRegistry`: wybor providera wysylki po `provider_code`.
+- `App\Modules\Printing\PrintApiController`: endpointy kolejki wydruku (session/api-key).
+- `App\Modules\Automation\AutomationService`: trigger eventow, ewaluacja warunkow, wykonanie akcji.
+- `App\Modules\Settings\ProjectMappingController`: CRUD mapowania produkt -> skrypt generacji projektu.
+
+## Integracje zewnetrzne
+- Allegro: OAuth, import zamowien, sync statusow push/pull, mapowania statusow i dostaw.
+- shopPRO: import zamowien, sync statusow push/pull, sync platnosci, mapowania statusow i dostaw.
+- Apaczka: konfiguracja API, tworzenie i tracking przesylek.
+- InPost: konfiguracja API, tworzenie i tracking przesylek.
+
+## Glowny przeplyw HTTP
+- Request -> `Router` -> middleware (`AuthMiddleware` lub `ApiKeyMiddleware`) -> Controller.
+- Controller waliduje dane i CSRF, wywoluje Repository/Service.
+- Response: HTML (widoki) albo JSON (endpointy AJAX/API).
+
+## Glowny przeplyw Cron
+- Trigger:
+- `GET /cron` (public token) lub web-cron w `Application::maybeRunCronOnWeb`.
+- `CronRunner::run(limit)` przetwarza aktywne zadania.
+- Obslugiwane joby:
+- `allegro_token_refresh`
+- `allegro_orders_import`
+- `allegro_status_sync`
+- `shoppro_orders_import`
+- `shoppro_order_status_sync`
+- `shoppro_payment_status_sync`
+- `shipment_tracking_sync`
+- `automation_history_cleanup`
+- `order_status_aged`
+
+## Automatyzacja
+- Triggerowana z wielu miejsc (m.in. zmiana statusu, przesylki, platnosci, wystawienie paragonu, cron age).
+- `AutomationService`:
+- wyszukuje aktywne reguly po `event_type`,
+- sprawdza warunki,
+- wykonuje akcje (`send_email`, `issue_receipt`, `update_shipment_status`, `update_order_status`),
+- zapisuje wynik do `automation_execution_logs`.
+
+## Printing
+- Panel tworzy job `print_jobs` przez `/api/print/jobs`.
+- Klient desktop pobiera pending joby przez API key.
+- Klient pobiera etykiete i zamyka job przez `/complete`.
+- Konfiguracja i zarzadzanie kluczami: `PrintSettingsController` + `print_api_keys`.
+
+## Projekt generation
+- `project_mappings` mapuje wzorzec nazwy produktu na `script_name` i `output_dir`.
+- `order_items.project_generated` i `project_generated_at` trzymaja status wygenerowania artefaktu.
+- UI konfiguracji: `/settings/project-mappings`.
+
+## Bezpieczenstwo
+- Session auth dla panelu.
+- API key auth dla zdalnego klienta druku.
+- CSRF dla POST w panelu.
+- Sekrety integracji szyfrowane przez `IntegrationSecretCipher`.
+
+## Zaleznosci miedzy modulami
+- `Orders` korzysta z `Automation`, `Email`, `Printing`, `Shipments`, `Settings`.
+- `Shipments` korzysta z `Orders`, `CompanySettings`, `Automation`.
+- `Cron` spina `Settings`, `Orders`, `Shipments`, `Automation`, `Email`.
+- `Automation` korzysta z `Orders`, `Email`, `Accounting`, `Shipments`.