update

2026-04-19 00:10:58 +02:00
parent 42efc857de
commit 10cba24727
8 changed files with 446 additions and 2449 deletions
--- a/.paul/docs/API.md
+++ b/.paul/docs/API.md
@@ -1,3 +1,177 @@
-# API
+# API

-> Endpointy, kontrakty request/response, autentykacja.
+## Zakres
+- Dokument opisuje aktualne endpointy z `routes/web.php` (stan repo: 2026-04-18).
+- Runtime API jest oparte o sesje (`AuthMiddleware`) i CSRF dla formularzy.
+- Publiczny endpoint bez sesji: `GET /cron` (token w query lub segmencie sciezki).
+- API dla klienta drukowania uzywa `X-Api-Key` (`ApiKeyMiddleware`).
+
+## Uwierzytelnianie
+- Session auth: wszystkie trasy panelowe i wiekszosc tras `/api/*`.
+- API key auth: tylko zdalne kolejki druku.
+- CSRF: wszystkie trasy `POST` w panelu (`_token` w body).
+
+## Endpointy publiczne
+- `GET /health` - status aplikacji JSON.
+- `GET /info` - strona info.
+- `GET /cron?token=...` - uruchomienie crona przez HTTPS.
+- `GET /cron/{tokenValue}` - alternatywny wariant tokenu w sciezce.
+
+## Auth
+- `GET /login` - formularz logowania.
+- `POST /login` - logowanie.
+- `POST /logout` - wylogowanie.
+
+## Nawigacja i dashboard
+- `GET /` - redirect do `/settings/users` (zalogowany) albo `/login`.
+- `GET /users` - redirect do `/settings/users`.
+- `GET /orders` - redirect do `/orders/list`.
+- `GET /settings` - redirect do `/settings/users`.
+
+## Orders
+- `GET /orders/list` - lista zamowien; AJAX zwraca fragmenty HTML tabeli/panelu statusow.
+- `GET /orders/{id}` - szczegoly zamowienia.
+- `POST /orders/{id}/status` - zmiana statusu; obsluguje HTML i AJAX JSON.
+- `POST /orders/{id}/details/update` - update formy dostawy/platnosci.
+- `POST /orders/{id}/send-email` - wysylka e-mail z szablonu (JSON).
+- `POST /orders/{id}/email-preview` - preview e-maila (JSON: subject/body/attachments).
+- `POST /orders/{id}/payment/add` - reczne dodanie platnosci (JSON).
+- `GET /api/orders/search` - quick search (JSON).
+- `GET /api/orders/{id}/preview` - podglad mini karty zamowienia (HTML fragment).
+
+## Receipts i accounting
+- `GET /orders/{id}/receipt/create`
+- `POST /orders/{id}/receipt/store`
+- `GET /orders/{id}/receipt/{receiptId}`
+- `GET /orders/{id}/receipt/{receiptId}/print`
+- `GET /orders/{id}/receipt/{receiptId}/pdf`
+- `GET /accounting` - lista paragonow.
+- `POST /accounting/export` - eksport danych ksiegowych.
+
+## Shipments
+- `GET /orders/{id}/shipment/prepare`
+- `POST /orders/{id}/shipment/create`
+- `GET /orders/{id}/shipment/{packageId}/status`
+- `POST /orders/{id}/shipment/{packageId}/label`
+- `POST /orders/{id}/shipment/manual`
+- `POST /orders/{id}/shipment/{packageId}/delete`
+
+## Printing API
+- Session auth:
+- `POST /api/print/jobs` - dodanie zlecenia druku.
+- `GET /api/print/jobs/status` - statusy kolejek.
+- API key auth (`X-Api-Key`):
+- `GET /api/print/jobs/pending` - lista zadan `pending`.
+- `GET /api/print/jobs/{id}/download` - pobranie etykiety.
+- `POST /api/print/jobs/{id}/complete` - finalizacja zadania.
+
+## Settings: users i baza
+- `GET /settings/users`
+- `POST /settings/users`
+- `GET /settings/database`
+- `POST /settings/database/migrate`
+
+## Settings: statusy
+- `GET /settings/statuses`
+- `POST /settings/status-groups`
+- `POST /settings/status-groups/update`
+- `POST /settings/status-groups/delete`
+- `POST /settings/status-groups/reorder`
+- `POST /settings/statuses/create`
+- `POST /settings/statuses/update`
+- `POST /settings/statuses/delete`
+- `POST /settings/statuses/reorder`
+
+## Settings: cron i integracje
+- `GET /settings/cron`
+- `POST /settings/cron`
+- `GET /settings/integrations`
+
+## Settings: Allegro
+- `GET /settings/integrations/allegro`
+- `POST /settings/integrations/allegro/save`
+- `POST /settings/integrations/allegro/settings/save`
+- `POST /settings/integrations/allegro/oauth/start`
+- `GET /settings/integrations/allegro/oauth/callback`
+- `POST /settings/integrations/allegro/import-single`
+- `POST /settings/integrations/allegro/statuses/save`
+- `POST /settings/integrations/allegro/statuses/save-bulk`
+- `POST /settings/integrations/allegro/statuses/delete`
+- `POST /settings/integrations/allegro/statuses/save-pull`
+- `POST /settings/integrations/allegro/statuses/sync`
+- `POST /settings/integrations/allegro/delivery/save`
+
+## Settings: Apaczka / Inpost / shopPRO
+- `GET /settings/integrations/apaczka`
+- `POST /settings/integrations/apaczka/save`
+- `POST /settings/integrations/apaczka/test`
+- `GET /settings/integrations/inpost`
+- `POST /settings/integrations/inpost/save`
+- `GET /settings/integrations/shoppro`
+- `POST /settings/integrations/shoppro/save`
+- `POST /settings/integrations/shoppro/test`
+- `POST /settings/integrations/shoppro/statuses/save`
+- `POST /settings/integrations/shoppro/statuses/save-pull`
+- `POST /settings/integrations/shoppro/statuses/sync`
+- `POST /settings/integrations/shoppro/delivery/save`
+
+## Settings: firma, e-mail, automatyzacja, delivery mapping
+- `GET /settings/company`
+- `POST /settings/company/save`
+- `GET /settings/accounting`
+- `POST /settings/accounting/save`
+- `POST /settings/accounting/toggle`
+- `POST /settings/accounting/delete`
+- `GET /settings/email-mailboxes`
+- `POST /settings/email-mailboxes/save`
+- `POST /settings/email-mailboxes/delete`
+- `POST /settings/email-mailboxes/toggle`
+- `POST /settings/email-mailboxes/test`
+- `GET /settings/email-templates`
+- `GET /settings/email-templates/create`
+- `GET /settings/email-templates/edit`
+- `POST /settings/email-templates/save`
+- `POST /settings/email-templates/delete`
+- `POST /settings/email-templates/duplicate`
+- `POST /settings/email-templates/toggle`
+- `POST /settings/email-templates/preview`
+- `GET /settings/email-templates/variables`
+- `GET /settings/automation`
+- `GET /settings/automation/create`
+- `POST /settings/automation/store`
+- `GET /settings/automation/edit`
+- `POST /settings/automation/update`
+- `POST /settings/automation/delete`
+- `POST /settings/automation/duplicate`
+- `POST /settings/automation/toggle`
+- `GET /settings/delivery-status-mappings`
+- `POST /settings/delivery-status-mappings/save`
+- `POST /settings/delivery-status-mappings/save-bulk`
+- `POST /settings/delivery-status-mappings/reset`
+- `POST /settings/delivery-status-mappings/reset-all`
+
+## Settings: druk i mapowania projektow
+- `GET /settings/printing`
+- `POST /settings/printing/keys/create`
+- `POST /settings/printing/keys/{id}/delete`
+- `POST /settings/printing/jobs/delete`
+- `GET /settings/project-mappings`
+- `POST /settings/project-mappings`
+- `POST /settings/project-mappings/{id}/update`
+- `POST /settings/project-mappings/{id}/delete`
+- `POST /settings/project-mappings/{id}/toggle`
+
+## API shipment presets
+- `GET /api/shipment-presets`
+- `POST /api/shipment-presets`
+- `POST /api/shipment-presets/update`
+- `POST /api/shipment-presets/delete`
+
+## Kontrakty JSON (najwazniejsze)
+- `GET /health`: `{status, app, timestamp}`.
+- `GET /cron*`: `{ok, message, limit, timestamp}` albo blad `{ok:false, message, error?}`.
+- `POST /api/print/jobs`: tworzy rekord kolejki dla `package_id`; zwraca JSON statusu.
+- `GET /api/print/jobs/pending`: lista pending dla klienta desktop.
+- `POST /api/print/jobs/{id}/complete`: potwierdza wydruk, ustawia `completed`.
+- `GET /api/orders/search`: `{results:[...]}`.
+- `POST /orders/{id}/payment/add`: `{ok, payment_id, payment_status, total_paid}` lub blad.
--- a/.paul/docs/ARCHITECTURE.md
+++ b/.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`.
--- a/.paul/docs/DB_SCHEMA.md
+++ b/.paul/docs/DB_SCHEMA.md
@@ -1,3 +1,178 @@
-# DB_SCHEMA
+# DB_SCHEMA

-> Schemat bazy danych — tabele, kolumny, FK, indeksy.
+## Zakres i zrodlo prawdy
+- Schemat wynika z migracji SQL w `database/migrations`.
+- Dokument odzwierciedla stan repo na 2026-04-18 (migracje do `20260413_000100`).
+
+## Ostatnie istotne migracje
+- `20260413_000100_ensure_orders_delivery_payment_columns.sql`
+- `20260412_000099_add_requires_photo_to_project_mappings.sql`
+- `20260412_000098_rename_external_status_id_to_status_code.sql`
+- `20260412_000097_add_project_generation.sql`
+- `20260410_000081_add_remember_token_to_users.sql`
+- `20260408_000090_backfill_delivery_price.sql`
+- `20260407_000083_allegro_pull_status_mappings.sql`
+- `20260407_000080_backfill_personalization_message.sql`
+- `20260407_000079_pull_status_mappings.sql`
+- `20260407_000078_reverse_status_mapping_keys.sql`
+
+## Kompensacyjne migracje ensure_
+- `000038` - naprawa brakujacej tabeli `order_status_mappings`.
+- `000039` - uzupelnienie brakujacych kolumn fetch w `integrations`.
+- `000040` - seed/naprawa harmonogramu `shoppro_orders_import`.
+- `000041` - seed/naprawa harmonogramu `shoppro_order_status_sync` + direction.
+- `000042` - seed/naprawa `shoppro_payment_status_sync` + kolumny payment sync.
+- `000100` - kompensacja brakujacych kolumn `orders.payment_method` i `orders.delivery_method`.
+
+## Kluczowe tabele
+
+### users
+- Uzytkownicy panelu.
+- Wazne kolumny:
+- `id`, `email` (UNIQUE), `password_hash`, `remember_token` (od `000081`), `is_active`, `created_at`, `updated_at`.
+
+### orders
+- Glowna tabela zamowien (model neutralny wzgledem zrodla).
+- Wazne kolumny:
+- `id`, `source`, `integration_id`, `source_order_id`, `internal_order_number` (UNIQUE),
+- `status_code` (rename z `external_status_id` w `000098`),
+- `payment_status`, `total_paid`, `payment_method`,
+- `delivery_method`, `delivery_price` (dodane/backfill `000090`),
+- daty zrodlowe i techniczne, `payload_json`, `preferences_json`.
+- Wydajnosc:
+- indeksy na `source`, `status_code`, `ordered_at`, `(source, status_code)`.
+
+### order_items
+- Pozycje zamowienia.
+- Wazne kolumny:
+- `order_id`, `source_item_id`, `name`, `quantity`, `price_gross`, `media_url`, `payload_json`,
+- `personalization` (`000075`, backfill `000080`),
+- `project_generated`, `project_generated_at` (`000097`).
+
+### order_payments
+- Platnosci zamowien (import i reczne).
+- Wazne kolumny:
+- `order_id`, `source_payment_id`, `payment_type_id`, `payment_date`, `amount`, `currency`, `payload_json`.
+- Klucz unikalny:
+- `(order_id, source_payment_id)`.
+
+### order_status_history
+- Historia zmian statusow zamowienia.
+- Wazne kolumny:
+- `order_id`, `from_status_id`, `to_status_id`, `change_source`, `changed_by`, `changed_at`.
+
+### order_activity_log
+- Uniwersalny log aktywnosci (`status_change`, `payment`, `shipment`, `import`, itd.).
+- Wazne kolumny:
+- `order_id`, `event_type`, `summary`, `details_json`, `actor_type`, `actor_name`, `created_at`.
+
+### order_status_groups i order_statuses
+- Slownik statusow biznesowych i grup statusow.
+- Relacja:
+- `order_statuses.group_id -> order_status_groups.id` (`ON DELETE CASCADE`).
+
+### integrations
+- Bazowa tabela instancji integracji.
+- Wazne kolumny:
+- `type`, `name`, `base_url`, `api_key_encrypted`, `is_active`,
+- `orders_fetch_enabled`, `orders_fetch_start_date`,
+- `order_status_sync_direction`, `payment_sync_status_codes_json`,
+- pola diagnostyczne testu polaczenia.
+
+### integration_order_sync_state
+- Kursor synchronizacji per integracja.
+- Wazne kolumny:
+- `integration_id` (PK), `last_synced_order_updated_at`, `last_synced_source_order_id`,
+- `last_success_at`, `last_status_pushed_at`, `last_error`.
+
+### order_status_mappings
+- Mapowania push statusow dla shopPRO.
+- Po `000078` klucz unikalny:
+- `(integration_id, orderpro_status_code)`.
+- Dodatkowe indeksy:
+- `(integration_id, shoppro_status_code)`.
+
+### order_status_pull_mappings
+- Dedykowane mapowanie pull shopPRO -> orderPRO (`000079`).
+- Klucz unikalny:
+- `(integration_id, shoppro_status_code)`.
+
+### allegro_order_status_mappings
+- Mapowania statusow Allegro dla kierunku push.
+- Po `000078` klucz unikalny:
+- `orderpro_status_code`.
+- Indeks lookup:
+- `allegro_status_code`.
+
+### allegro_order_status_pull_mappings
+- Dedykowane mapowanie pull Allegro -> orderPRO (`000083`).
+- Klucz unikalny:
+- `allegro_status_code`.
+
+### allegro_integration_settings
+- OAuth i tokeny Allegro per srodowisko/integracja.
+- Wazne kolumny:
+- `integration_id` (UNIQUE FK), `environment`, `client_id`, `client_secret_encrypted`,
+- `redirect_uri`, `access_token_encrypted`, `refresh_token_encrypted`, `token_expires_at`,
+- `orders_fetch_enabled`, `orders_fetch_start_date`.
+
+### apaczka_integration_settings i inpost_integration_settings
+- Ustawienia providerow wysylek, powiazane 1:1 z `integrations` przez `integration_id`.
+
+### company_settings
+- Dane firmy/nadawcy, parametry domyslnych paczek i pola ksiegowe.
+
+### receipt_configs, receipts, receipt_number_counters
+- Konfiguracja numeracji, wystawione paragony i liczniki numerow.
+
+### email_mailboxes, email_templates, email_logs
+- Skrzynki SMTP, szablony i log wysylki.
+
+### automation_rules, automation_conditions, automation_actions, automation_execution_logs
+- Definicje regul i historia ich wykonan.
+
+### shipment_packages
+- Rekordy przesylek i etykiet.
+- Wazne kolumny trackingowe (od `000060`):
+- `delivery_status`, `delivery_status_raw`, `delivery_status_updated_at`.
+
+### delivery_status_mappings
+- Mapowanie statusow przewoznikow na status biznesowy (`provider + raw_status` UNIQUE).
+
+### carrier_delivery_method_mappings
+- Wspolne mapowanie form dostawy na providerow wysylki.
+
+### shipment_presets
+- Presety nadania wykorzystywane przez API presetow przesylek.
+
+### print_api_keys
+- Klucze API dla klienta desktop druku.
+- Kolumny:
+- `key_hash` (UNIQUE), `key_prefix`, `is_active`, `last_used_at`.
+
+### print_jobs
+- Kolejka wydruku etykiet.
+- Kolumny:
+- `order_id`, `package_id`, `label_path`, `status`, `created_by`, `created_at`, `completed_at`.
+
+### project_mappings
+- Mapowanie produktu na skrypt generujacy projekt (`000097`).
+- Wazne kolumny:
+- `product_name_pattern`, `script_name`, `output_dir`, `requires_photo` (`000099`), `is_active`.
+
+## Harmonogram cron (cron_schedules)
+- Wykorzystywane typy jobow:
+- `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`
+
+## Notatki kompatybilnosci
+- Migracje `ensure_` i `000100` sa idempotentne i kompensuja roznice miedzy srodowiskami.
+- Rename `orders.external_status_id -> status_code` wymaga, aby nowe query i dokumentacja uzywaly tylko `status_code`.
+- `delivery_price` jest backfillowane z JSON payloadow importu (Allegro/shopPRO).