feat(shipments): add ShipmentProviderInterface and ShipmentProviderRegistry

- Introduced ShipmentProviderInterface to define the contract for shipment providers.
- Implemented ShipmentProviderRegistry to manage and retrieve shipment providers.
- Added a new tool for probing Apaczka order_send payload variants, enhancing debugging capabilities.

DOCS/TECH_CHANGELOG.md

@@ -1,6 +1,101 @@
 # Tech Changelog
 
 ## 2026-03-08
+- Poprawiono date podjazdu kuriera w payloadzie Apaczka:
+  - `pickup.date` dla trybu `COURIER` jest normalizowane tak, aby nie wypadal w niedziele (niedziela -> poniedzialek),
+  - `pickup.hours_to` jest ograniczane do `16:00` (wg limitu API), a okno godzinowe jest korygowane do poprawnej relacji `hours_from < hours_to`,
+  - eliminuje blad API `Field PickupLocation->MaxPickupDate cannot be set to Sunday`.
+- Dodano pole firmy `sender_contact_person` (osoba kontaktowa nadawcy):
+  - nowa migracja `20260308_000046_extend_company_settings_contact_person.sql`,
+  - UI `Ustawienia > Dane firmy` ma nowe pole `Osoba kontaktowa nadawcy`,
+  - `ApaczkaShipmentService` wysyla `contact_person` dla nadawcy z ustawien firmy.
+- Uzupelniono kontakt odbiorcy w payloadzie Apaczka:
+  - `ApaczkaShipmentService` wysyla `receiver.contact_person` (fallback na dane odbiorcy/klienta z zamowienia),
+  - eliminuje blad API: `Osoba kontaktowa nadawcy/odbiorcy: Pole jest wymagane`.
+- Dla tworzenia przesylek Apaczka dodano jawne pole `pickup.type` w payloadzie `order_send`:
+  - gdy podano `sender_point_id` ustawiane jest `SELF`,
+  - gdy brak punktu nadania i usluga dopuszcza odbior kurierem ustawiane jest `COURIER`.
+- Poprawiono obsluge punktow nadania/odbioru w payloadzie Apaczka:
+  - adres `sender` i `receiver` wysyla teraz komplet aliasow punktu (`point`, `foreign_address_id`, `point_id`),
+  - rozszerzono diagnostyke dla bledu API `Niepoprawny sposob nadania przesylki` o wskazowke dot. `sender_point_id` / doboru uslugi.
+- Wzmocniono fallback adresu odbiorcy dla przesylek punktowych Apaczka (Orlen/InPost):
+  - `ApaczkaShipmentService` probuje teraz dodatkowo uzupelnic adres punktu (`street`, `postal_code`, `city`) przez API `points` na podstawie `receiver_point_id`,
+  - jezeli zamowienie punktowe dalej nie ma kompletu danych adresowych, serwis uzupelnia techniczne minimum (`line1`, `city`, `postal_code`) zamiast blokowac tworzenie przesylki bledem walidacji lokalnej.
+- Ujednolicono i wzmocniono naglowki sekcji UI (`h2/h3/h4.section-title`) w widokach:
+  - naglowki sekcyjne maja teraz wyrazniejszy styl (akcent lewy, delikatne tlo, obramowanie),
+  - zmiana jest globalna (SCSS), obejmuje m.in. `Zamowienia > Przygotuj przesylke` oraz pozostale ekrany korzystajace z `section-title`.
+- Poprawiono fallback danych odbiorcy dla przesylek punktowych Apaczka (w tym Orlen Paczka):
+  - `ApaczkaShipmentService::buildReceiverAddress(...)` uzupelnia brakujace pola z wielu zrodel w kolejnosci:
+    - dane z formularza,
+    - adres `delivery` z zamowienia,
+    - dane punktu z `parcel_name` (`ulica`, `kod`, `miasto`),
+    - dane klienta (`name`, `phone`, `email`, `country`),
+  - adres ulicy sklada teraz `street_name + street_number`,
+  - naprawiono fallback `receiver_point_id` (uzywa `delivery.parcel_external_id`, usunieto bledne odwolanie do niezdefiniowanej zmiennej).
+- Poprawiono obsluge usunietych/nieosiagalnych etykiet Apaczka:
+  - gdy API zwraca `Label is not available for this order`, rekord paczki jest oznaczany jako `error` i zapisywany jest `error_message`,
+  - dzieki temu przycisk etykiety nie jest ponownie pokazywany dla tego rekordu.
+- Ujednolicono flow etykiet w `Zamowienia > Przygotuj przesylke` (dla wszystkich providerow):
+  - po statusie `created` etykieta jest generowana automatycznie przez cykliczne sprawdzanie statusu (backend probuje `downloadLabel`),
+  - UI nie pokazuje juz przycisku `Generuj etykiete`; do czasu gotowosci widoczny jest stan `Generowanie etykiety...`,
+  - przycisk `Pobierz` pojawia sie dopiero po zapisaniu pliku etykiety (`label_path`).
+- Uzgodniono payload `order_send` Apaczka z dokumentacja API v2:
+  - `ApaczkaShipmentService` wysyla teraz strukture `address.sender/receiver` + `shipment[]` (`dimension1/2/3`, `weight` w kg),
+  - `cod` jest przekazywany jako obiekt (`amount`, `currency`), a wartosc ubezpieczenia przez `shipment_value` + `shipment_currency`,
+  - punkty sa przekazywane jako `foreign_address_id` (z aliasami diagnostycznymi),
+  - naprawilo to blad wyceny dla zamowienia testowego `#21` (utworzenie przesylki zakonczone sukcesem).
+- Dodano techniczny skrypt diagnostyczny `tools/apaczka_probe_order.php`:
+  - wykonuje automatyczne proby `order_send` dla wskazanego zamowienia (bez klikania w UI),
+  - testuje kombinacje uslug i wariantow pol punktu, raportujac sukces/blad per proba.
+- Rozszerzono payload punktow w tworzeniu przesylki Apaczka:
+  - oprocz `point` przekazywane sa teraz aliasy `foreign_address_id` i `point_id` (dla odbiorcy i nadawcy),
+  - cel: kompatybilnosc z wariantami API wymagajacymi innej nazwy pola punktu.
+- Korekta walidacji punktu odbioru Apaczka:
+  - usunieto twarde blokowanie tworzenia przesylki na podstawie prefiksu punktu (`POP-`),
+  - informacja o prefiksie punktu pozostaje tylko jako sugestia diagnostyczna.
+- Poprawiono prefill danych odbiorcy na ekranie `Zamowienia > Przygotuj przesylke`:
+  - `ShipmentController` dla dostaw do punktu (`parcel_external_id`/`parcel_name`) ustawia `receiver_name` na dane klienta (`address_type=customer`),
+  - eliminuje przypadek podstawiania nazwy punktu/metody dostawy w polu `Imie i nazwisko`.
+- Poprawiono diagnostyke bledow tworzenia przesylki Apaczka:
+  - `ApaczkaShipmentService` przekazuje teraz `receiver_point_id` do payloadu `receiver.point` (oraz `sender_point_id` do `sender.point`),
+  - dodano walidacje wymagan uslugi na podstawie `service_structure` (np. wymagany punkt odbioru/nadania),
+  - dla bledu API `Brak wyceny dla podanych parametrów zamówienia` komunikat zawiera rozszerzona diagnostyke (service_id/nazwa/supplier, punkt odbioru/nadania, gabaryt/waga) i hint o niedopasowaniu uslugi do typu punktu.
+- Poprawiono import danych faktury z shopPRO:
+  - `ShopproOrdersSyncService` wykrywa fakture nie tylko po `is_invoice`/`invoice.required`, ale takze po danych firmowych (`firm_name`/`firm_nip`),
+  - `ShopproOrdersSyncService::mapAddresses(...)` zapisuje adres `invoice` (firma, NIP, adres) na podstawie pol `invoice`/`billing*`/`firm_*`,
+  - widok `orders/show` wyswietla teraz `company_name` i `company_tax_number` dla adresu faktury.
+- Fix prewyboru uslugi Apaczka na ekranie `Zamowienia > Przygotuj przesylke`:
+  - widok `resources/views/shipments/prepare.php` odczytuje ID uslugi Apaczka z fallbackiem `service_id -> id`,
+  - naprawia przypadek, gdy przewoznik (`Apaczka`) byl wybierany poprawnie, ale usluga dostawy pozostawala pusta mimo mapowania.
+- Poprawiono diagnostyke mapowania form dostawy na ekranie `Zamowienia > Przygotuj przesylke`:
+  - `ShipmentController` zwraca teraz komunikat diagnostyczny, gdy brak mapowania metody dostawy,
+  - komunikat rozroznia brak mapowan dla instancji `shopPRO` (`source_integration_id`) od braku mapowania konkretnej metody,
+  - widok `resources/views/shipments/prepare.php` wyswietla ten komunikat bezposrednio pod informacja o metodzie z zamowienia.
+- Poprawiono UX wyszukiwania w selectach mapowania form dostawy (zakladki `Formy dostawy`):
+  - `resources/views/settings/allegro.php` przeszlo z przebudowy opcji `<select>` na tryb bezpieczny (`focus first match` bez modyfikacji listy opcji),
+  - eliminuje przypadki „znikajacych” opcji i problem z wyborem uslugi po zmianie przewoznika na `Apaczka`,
+  - ujednolicono zachowanie z `resources/views/settings/shoppro.php`.
+- Poprawiono inicjalizacje stanu mapowania przewoznika (`allegro.php`, `shoppro.php`):
+  - dla niezamapowanych form domyslny przewoznik to teraz pusty wybor (zamiast `allegro`),
+  - panel uslugi (`Allegro/InPost/Apaczka/pusty`) jest synchronizowany na starcie z realna wartoscia selecta przewoznika (`showPanel(carrierSelect.value)`),
+  - usunieto pozostaly po refaktorze odwolanie do nieistniejacej zmiennej `$currentAllegroId` (zastapione `$currentMethodId`).
+- Dodano architekture provider-agnostic dla wysylek:
+  - nowy kontrakt `ShipmentProviderInterface`,
+  - nowy rejestr `ShipmentProviderRegistry`,
+  - `ShipmentController` wybiera providera dynamicznie (`allegro_wza` / `apaczka`) przy tworzeniu przesylki, sprawdzaniu statusu i pobieraniu etykiety.
+- Dodano integracje API Apaczka v2:
+  - nowy klient `App\Modules\Settings\ApaczkaApiClient` (`service_structure`, `order_send`, `order_details`, `waybill`, `points`),
+  - nowy serwis wysylkowy `App\Modules\Shipments\ApaczkaShipmentService`,
+  - rozszerzone `Ustawienia > Integracje > Apaczka` o pola `App ID`, `App Secret` oraz test polaczenia (`POST /settings/integrations/apaczka/test`).
+  - poprawiono format podpisu/requestu zgodnie z API v2 (`app_id:route:request_json:expires`, endpointy URL zamiast pola `method`), co naprawia blad testu polaczenia (`brak JSON`).
+- Dodano wspolny model mapowania form dostawy dla wielu providerow:
+  - nowa tabela `carrier_delivery_method_mappings` (migracja `20260308_000044_create_carrier_delivery_method_mappings_table.sql`),
+  - nowy repo `CarrierDeliveryMethodMappingRepository`,
+  - backfill danych z tabel legacy (`allegro_delivery_method_mappings`, `shoppro_delivery_method_mappings`),
+  - zakladki `Formy dostawy` w Allegro i shopPRO obsluguja mapowanie na `allegro_wza` i `apaczka`.
+- Dodano migracje `20260308_000045_extend_apaczka_credentials.sql`:
+  - rozszerzenie `apaczka_integration_settings` o `app_id` i `app_secret_encrypted`,
+  - migracja danych legacy sekretu z `api_key_encrypted`.
 - Dodano zakladke `Formy dostawy` dla integracji `shopPRO` (analogicznie do Allegro):
   - nowy endpoint `POST /settings/integrations/shoppro/delivery/save`,
   - mapowanie per instancja: forma dostawy shopPRO -> usluga dostawy Allegro/InPost WZA,