orderPRO/.paul/phases/128-polkurier-shipment-service/128-01-PLAN.md

phase, plan, type, wave, depends_on, files_modified, autonomous, delegation

phase	plan	type	wave	depends_on	files_modified	autonomous	delegation
128-polkurier-shipment-service	01	execute	1		src/Modules/Settings/PolkurierApiClient.php src/Modules/Shipments/PolkurierShipmentService.php src/Modules/Shipments/PolkurierTrackingService.php src/Modules/Shipments/ShipmentController.php src/Modules/Shipments/DeliveryStatus.php src/Modules/Cron/CronHandlerFactory.php routes/web.php resources/views/shipments/prepare.php database/migrations/20260514_000115_seed_polkurier_delivery_status_mappings.sql .paul/codebase/architecture.md .paul/codebase/db_schema.md .paul/codebase/tech_changelog.md	false	off

## Goal Dostarczyc pelna integracje wysylkowa polkurier.pl: tworzenie paczek (createOrder), pobieranie etykiet (getLabel), tracking statusow przesylek (getStatus) oraz UI do nadawania paczek w `/orders/{id}/shipment/prepare` z dynamiczna lista przewoznikow z polkuriera i obsluga punktow odbioru (Paczkomaty InPost, ORLEN, Pocztex, Kurier48). Weryfikacja na zywych zamowieniach #114 i #115 z manualnym anulowaniem po teście.

Purpose

Phase 127 dostarczyl fundament (settings + test_auth_api). Bez ShipmentService polkurier jest "wystawiony w hubie integracji ale niedzialajacy". Operator chce realnie nadawac paczki przez polkurier obok Apaczki — wspolny use case (DPD, UPS, GLS, InPost) z lepszymi cenami.

Output

• 2 nowe klasy w src/Modules/Shipments/ (PolkurierShipmentService, PolkurierTrackingService) implementujace odpowiednio ShipmentProviderInterface i ShipmentTrackingInterface
• Rozszerzony PolkurierApiClient z 6 nowymi metodami API
• Nowy panel "polkurier" w prepare.php + przelacznik JS
• Migracja seedujaca delivery_status_mappings (provider='polkurier')
• Architektura/schema/changelog zaktualizowane
• 2 paczki utworzone na zywym koncie polkurier (#114 i #115), zweryfikowane, recznie anulowane przez operatora

- **Zakres fazy** — Co dostarczamy w Phase 128? → Odpowiedz: Pelny zakres: ShipmentService + TrackingService + UI prepare + delivery_status_mappings (jedna duza faza zamiast dwoch). - **Uslugi UI** — Jak prezentujemy uslugi polkurier w UI prepare? → Odpowiedz: Dynamiczna lista z API polkuriera (`get_available_carriers` lub odpowiednia metoda) — analog `ApaczkaApiClient::getServiceStructure`. - **Paczkomaty** — Czy obslugujemy paczkomaty/punkty odbioru w Phase 128? → Odpowiedz: Pelne wsparcie wszystkich punktow (InpostParcelMachines, PocztexPostOffices, Kurier48PostOffices, ewentualnie ORLEN). - **Tryb testu** — Jak testujemy na #114/#115? → Odpowiedz: Realny createOrder na zywym koncie + manualny cancelOrder po weryfikacji przez operatora w panelu polkurier (live test, ale bez wysylki).

Project Context

@.paul/PROJECT.md @.paul/ROADMAP.md @.paul/STATE.md @.paul/codebase/architecture.md @.paul/codebase/db_schema.md

Prior Work

@.paul/phases/127-polkurier-integration-foundation/127-01-SUMMARY.md

Source Files (wzorzec Apaczka)

@src/Modules/Shipments/ApaczkaShipmentService.php @src/Modules/Shipments/ApaczkaTrackingService.php @src/Modules/Settings/ApaczkaApiClient.php @src/Modules/Shipments/ShipmentProviderInterface.php @src/Modules/Shipments/ShipmentTrackingInterface.php @src/Modules/Shipments/ShipmentProviderRegistry.php @src/Modules/Settings/PolkurierApiClient.php @src/Modules/Settings/PolkurierIntegrationRepository.php @src/Modules/Shipments/ShipmentController.php @src/Modules/Cron/CronHandlerFactory.php @resources/views/shipments/prepare.php @routes/web.php

External Reference

• Oficjalne polkurier SDK: https://github.com/Polkurier/polkurier-sdk (zweryfikowany kontrakt API w Phase 127)
• Klucze apimetod w SDK: test_auth_api, new_order, get_label, get_status, cancel_order, get_available_carriers, get_parcel_machines, get_post_offices, get_carrier_info (do potwierdzenia per SDK)

<acceptance_criteria>

AC-1: PolkurierApiClient — pelny kontrakt API

Given globalna konfiguracja polkurier jest aktywna i token zwery (Phase 127)
When backend wywoluje `PolkurierApiClient::getAvailableCarriers()` z poprawnymi credentials
Then klient zwraca tablice przewoznikow (DPD/UPS/GLS/InPost/Pocztex…) z polami: `carrier_id`, `name`, `service_code`, `supports_pickup_point` (bool), `weight_limits`, `cod_supported`
And `createShipment($payload)` zwraca tablice `{order_id: string, tracking_number: string, label_url: ?string, raw: array}` przy `status='success'`
And `getLabel($orderId, $format)` zwraca binarna zawartosc etykiety (PDF/ZPL/EPL zaleznie od `default_label_format`)
And `getStatus($orderId)` zwraca tablice `{status_code, status_name, status_date}`
And `cancelOrder($orderId)` zwraca `{ok: bool, message: string}`
And kazda metoda przy `status != 'success'` rzuca `RuntimeException` z trescia z pola `response`

AC-2: PolkurierShipmentService implementuje ShipmentProviderInterface

Given `PolkurierShipmentService` jest zarejestrowany w `ShipmentProviderRegistry` jako `code()='polkurier'`
When `createShipment(int $orderId, array $formData)` jest wywolane z danymi zamowienia #114 lub #115
Then service buduje payload polkurier (sender z `company_settings`, receiver z order_addresses, paczka z formData), woła `PolkurierApiClient::createShipment()`, zapisuje wynik do `shipment_packages` (provider='polkurier', tracking_number, label_path po pobraniu, payload_json)
And `downloadLabel($packageId, $storagePath)` pobiera plik etykiety i aktualizuje `shipment_packages.label_path`
And `checkCreationStatus($packageId)` zwraca aktualny stan z `shipment_packages` (sync vs `getStatus()` API)
And `getDeliveryServices()` zwraca cache'owana liste przewoznikow z `getAvailableCarriers()` (per-request)

AC-3: PolkurierTrackingService cron tracking

Given paczka z `provider='polkurier'` i `tracking_number` istnieje w `shipment_packages`
When `ShipmentTrackingHandler` (cron) wywoluje `PolkurierTrackingService::getDeliveryStatus($package)`
Then service woła `PolkurierApiClient::getStatus()`, parsuje surowy status i mapuje przez `delivery_status_mappings(provider='polkurier')` na znormalizowany status z `delivery_statuses`
And zwraca `{status: <normalized>, status_raw: <polkurier_code>, description: <polkurier_label>}`
And `supports('polkurier')` zwraca true

AC-4: UI prepare.php panel polkurier

Given operator wszedl na `/orders/115/shipment/prepare`
When wybiera "polkurier" z dropdowna przewoznika
Then JS pokazuje panel `#shipment-polkurier-panel` z dynamicznym selectem uslug (zaladowanym z `getAvailableCarriers`)
And dla uslug `supports_pickup_point=true` pojawia sie selektor punktu odbioru z listą punktów odpowiedniego typu (InPost/Pocztex/Kurier48/ORLEN)
And ukryty input `provider_code` ustawia sie na `polkurier`
And submit formularza tworzy paczke przez `ShipmentController::store()` -> `ShipmentProviderRegistry::get('polkurier')->createShipment()`

AC-5: delivery_status_mappings + /settings/delivery-statuses

Given migracja `20260514_000115_seed_polkurier_delivery_status_mappings.sql` wykonana
When operator otwiera `/settings/delivery-statuses` (tab 'mapping')
Then widoczne sa wpisy `provider='polkurier'` z surowymi statusami polkuriera mapowanymi na znormalizowane statusy z `delivery_statuses` (np. `nowa_paczka` -> `registered`, `w_doreczeniu` -> `out_for_delivery`, `doreczone` -> `delivered`, `anulowane` -> `cancelled`)
And `DeliveryStatus::trackingUrl('polkurier', $tracking, $carrierId)` zwraca poprawny link sledzenia (URL polkuriera lub bezposrednio przewoznika)

AC-6: Live test na zamowieniach #114 i #115

Given operator ma aktywne konto polkurier (Phase 127 test "Autoryzacja: 1")
When operator nadaje paczki na #114 i #115 przez nowy panel UI
Then dla obu zamowien `shipment_packages` zawiera wiersz `provider='polkurier'`, `status='created'`, niepusty `tracking_number`, sciezke `label_path` do pobranej etykiety
And operator widzi etykiety jako PDF w `/orders/{id}` zakladka Przesylki
And operator recznie anuluje obie paczki w panelu polkurier.pl po weryfikacji (poza zakresem kodu — manualna akcja w UI polkuriera)

</acceptance_criteria>

Task 1: PolkurierApiClient — implementacja pelnego kontraktu API src/Modules/Settings/PolkurierApiClient.php Zastapic stuby `createShipment/getLabel/getStatus/cancelOrder` realnymi implementacjami i dodac `getAvailableCarriers`, `getParcelMachines`, `getPostOffices`.

Wspolny helper `private function call(string $apimetod, array $data, string $login, string $apiToken): array`:
  - Buduje payload `{authorization: {login, token}, apimetod, data}`.
  - Wykorzystuje istniejacy `postJson()` (Phase 127).
  - Parsuje envelope: jezeli `status === 'success'` zwraca `$decoded['response']` (array). W przeciwnym razie rzuca `RuntimeException` z trescia `response` (string albo zserializowany JSON).
  - PHP 8.5: NIE wywolywac `curl_close()`.

Metody publiczne:
  - `createShipment(string $login, string $apiToken, array $payload): array` — apimetod `new_order` (sprawdzic dokladna nazwe w SDK polkurier-sdk/src/Api). Zwraca `{order_id, tracking_number, raw}`.
  - `getLabel(string $login, string $apiToken, string $orderId, string $format): string` — apimetod `get_label`, format=PDF/ZPL/EPL. Zwraca surowa zawartosc base64-decoded jezeli polkurier zwraca base64; w przeciwnym razie binarny stream. Sprawdzic odpowiedz API.
  - `getStatus(string $login, string $apiToken, string $orderId): array` — apimetod `get_status`. Zwraca `{status_code, status_name, status_date, raw}`.
  - `cancelOrder(string $login, string $apiToken, string $orderId): array` — apimetod `cancel_order`. (NIE bedzie wywolywana w Phase 128 — operator anuluje w UI polkuriera, ale metoda dostepna dla przyszlych planow.)
  - `getAvailableCarriers(string $login, string $apiToken): array` — apimetod `get_available_carriers` (potwierdzic w SDK; mozliwe alternatywy: `get_carriers`, `get_services`). Zwraca liste przewoznikow.
  - `getParcelMachines(string $login, string $apiToken, string $type, ?string $postalCode = null): array` — apimetod `get_parcel_machines`. type=InPost/Pocztex/Kurier48/ORLEN.
  - `getPostOffices(string $login, string $apiToken, string $type): array` — apimetod `get_post_offices` (jezeli polkurier rozdziela).

UWAGA: dokladne nazwy `apimetod` zweryfikowac wzgledem `polkurier-sdk` (https://github.com/Polkurier/polkurier-sdk) — pliki `src/Api/*Api.php`. Jezeli nazwa rozna od zakladanej, dostosowac stale prywatne (`private const APIMETOD_NEW_ORDER = '...'` itp.).

Avoid: hardcodowane mapowanie statusow (zostawiamy `DeliveryStatusMappingRepository`), zmiany w `testConnection()` (dziala od Phase 127), wprowadzania `Content-Type: application/json; charset=UTF-8` (polkurier odrzuca — zachowac dokladnie `application/json`).

1. `php -l src/Modules/Settings/PolkurierApiClient.php` (no syntax errors). 2. Operator wywoluje przyszly smoke test: `php bin/smoke-polkurier.php` (skrypt z Task 4) — pierwszy crash wskaze brakujace pole. 3. Rzut `RuntimeException` zawiera tresc z pola `response` (nie `status: error`). AC-1 satisfied: wszystkie 7 metod publicznych zaimplementowane wzorem `testConnection()`; envelope `{status, response}` parsowany jednolicie; bledy rzucane z trescia z `response`. Task 2: PolkurierShipmentService + PolkurierTrackingService src/Modules/Shipments/PolkurierShipmentService.php, src/Modules/Shipments/PolkurierTrackingService.php, src/Modules/Shipments/DeliveryStatus.php **PolkurierShipmentService** — `final class implements ShipmentProviderInterface`, wzorzec `ApaczkaShipmentService` (1044 LOC, ale polkurier prostszy — ~500-700 LOC):

Konstruktor (manualny DI, mirror Apaczki):
  - `PolkurierIntegrationRepository $integrationRepository`
  - `PolkurierApiClient $apiClient`
  - `ShipmentPackageRepository $packages`
  - `CompanySettingsRepository $companySettings`
  - `OrdersRepository $ordersRepository`

Metody:
  - `code(): string` -> `'polkurier'`.
  - `getDeliveryServices(): array` — `getCredentials()` -> `$apiClient->getAvailableCarriers()`. Cache per-request (`private ?array $servicesCache = null`).
  - `createShipment(int $orderId, array $formData): array`:
      1. `findDetails($orderId)` z OrdersRepository; throw `ShipmentException` gdy null.
      2. `requireCredentials()` -> `[$login, $token]` z `PolkurierIntegrationRepository::getCredentials()`; throw `IntegrationConfigException` gdy null.
      3. Sender z `CompanySettingsRepository::getSenderAddress()` + walidacja (`validateSenderAddress`).
      4. Receiver z `order_addresses` (delivery type), normalizacja telefonu/postal_code.
      5. Wybor uslugi z `$formData['service_code']` lub `$formData['carrier_id']`.
      6. Wymiary/waga z formData (z domyslnymi z `company_settings.default_package_*`).
      7. Punkt odbioru: jezeli `$formData['receiver_point_id']` niepuste -> wstawiamy w payload polkuriera (klucz zaleznie od SDK).
      8. COD/insurance z formData.
      9. `$apiClient->createShipment($login, $token, $payload)` -> `{order_id, tracking_number, ...}`.
      10. `$packages->insert([...])` z `provider='polkurier'`, `command_id=order_id`, `tracking_number`, `status='created'`, `payload_json=zserializowany_payload`.
      11. Synchroniczne pobranie etykiety przez `downloadLabel($packageId, $storagePath)` — analog Apaczki, ktora pobiera label do `storage/labels/`.
      12. Zwroc `['package_id' => ..., 'tracking_number' => ..., 'label_path' => ...]`.
  - `checkCreationStatus(int $packageId): array` — fetch z `shipment_packages`; jezeli `status='draft'` -> pingnij `getStatus()` API i zaktualizuj.
  - `downloadLabel(int $packageId, string $storagePath): array` — `$apiClient->getLabel($login, $token, $orderId, $package['label_format'] ?? 'PDF')`; zapisz do `$storagePath/polkurier_{packageId}.pdf` (lub `.zpl`); update `shipment_packages.label_path`.

**PolkurierTrackingService** — `final class implements ShipmentTrackingInterface`:
  - `supports(string $provider): bool` -> `strtolower($provider) === 'polkurier'`.
  - `getDeliveryStatus(array $package): ?array`:
      1. `requireCredentials()`; zwroc null gdy konfiguracja nieaktywna (cron nie powinien rzucac, tylko skipowac).
      2. `$apiClient->getStatus($login, $token, $package['command_id'])`.
      3. Mapuj `status_code` przez `DeliveryStatusMappingRepository::findNormalized('polkurier', $rawStatus)`.
      4. Fallback `unknown` gdy brak mapowania (analog Apaczki).
      5. Zwroc `['status' => $normalized, 'status_raw' => $rawStatus, 'description' => $statusName]`.

**DeliveryStatus.php** — dolozyc obsluge providera `polkurier` w `trackingUrl(string $provider, string $tracking, string $carrierId): string`:
  - Polkurier deleguje do przewoznika docelowego — `carrierId` mowi nam ktory. Fallback URL `https://polkurier.pl/sledzenie/<tracking>` (jezeli polkurier ma taki) lub URL przewoznika docelowego z istniejacych branch-ow (`inpost`, `dpd`, etc.). MVP: zwroc URL bazowy polkurier + tracking_number.

Avoid:
  - Hardcodowania URL tracking polkuriera bez weryfikacji (sprawdzic w panelu polkurier lub SDK).
  - Pobierania etykiety w osobnym requeście jezeli polkurier zwraca `label_base64` w odpowiedzi createShipment (parsowac i zapisywac od razu).
  - Throwowania w `PolkurierTrackingService::getDeliveryStatus` przy braku credentials — cron musi byc odporny.

1. `php -l src/Modules/Shipments/PolkurierShipmentService.php` i `PolkurierTrackingService.php`. 2. Manualnie: po Task 3 wejdz na `/orders/114/shipment/prepare`, wybierz polkurier — dropdown zwraca przewoznikow z API. AC-2 i AC-3 satisfied: oba serwisy implementuja interfejsy, integruja z `PolkurierApiClient`, `ShipmentPackageRepository` i `DeliveryStatusMappingRepository`. Kontrakt Phase 127 (single global config, `is_active=1` guard) zachowany. Task 3: Wiring + UI prepare.php panel polkurier routes/web.php, src/Modules/Shipments/ShipmentController.php, src/Modules/Cron/CronHandlerFactory.php, resources/views/shipments/prepare.php **routes/web.php**: - W `$shipmentProviderRegistry = new ShipmentProviderRegistry([...])` (linia ~474) dolozyc `new PolkurierShipmentService($polkurierIntegrationRepository, new PolkurierApiClient(), $shipmentPackageRepository, $companySettingsRepository, new OrdersRepository(...))`. - Dolozyc `use App\Modules\Shipments\PolkurierShipmentService;` w nagłowku.

**CronHandlerFactory.php** (linia ~166-169):
  - W tablicy trackerow dolozyc `new PolkurierTrackingService($polkurierIntegrationRepository, $polkurierApiClient, $deliveryStatusMappingRepository)`.
  - Dolozyc `use App\Modules\Shipments\PolkurierTrackingService;` i `use App\Modules\Settings\PolkurierIntegrationRepository;`/`PolkurierApiClient;`.

**ShipmentController.php**:
  - Wstrzyknac `PolkurierShipmentService $polkurierService` (lub uzywac z registry).
  - W `prepare()` przekazac do widoku `$polkurierServices = $polkurierService->getDeliveryServices()` (try/catch — empty array on failure).

**resources/views/shipments/prepare.php** — wzorzec panelu Apaczki (linie 172-216):
  - Dolozyc `<option value="polkurier">polkurier</option>` do `#carrierSelect` (linia ~103).
  - Dolozyc panel `<div id="shipment-polkurier-panel">` z:
      - `<select id="shipment-polkurier-service-select">` wypelniony `$polkurierServices` (carrier_id, name).
      - Conditional pickup point picker (`<select id="shipment-polkurier-point-select">`) widoczny gdy wybrana usluga ma `supports_pickup_point=true`. Lista punktow ladowana AJAX-em z nowego endpointu `/shipments/polkurier/points?type=InPost&postal=XX-XXX` (dodac route + metoda w `ShipmentController`).
      - Hidden input `name="service_code"` aktualizowany przez JS na podstawie selecta.
  - JS (linie ~580-650): dodac `polkurierSelect`/`polkurierPanel`/`polkurierPointSelect`; toggle widocznosci paneli; ustaw `providerInput.value = 'polkurier'` gdy carrier='polkurier'.

Avoid:
  - Powielania logiki Apaczki — uzyc tych samych helperow JS gdzie sie da.
  - Hardcodowania listy punktow w widoku — wszystko z API polkuriera przez AJAX.

1. `/orders/114/shipment/prepare` — dropdown przewoznika ma "polkurier"; po wyborze pokazuje panel. 2. Select uslug ma realne wartosci z polkuriera. 3. `php -l routes/web.php` i `CronHandlerFactory.php`. AC-4 satisfied: panel polkurier widoczny w prepare.php, integracja z registry, cron tracker zarejestrowany. Live test polkurier ShipmentService na zamowieniach #114 i #115. Operator nadaje paczki przez nowy panel UI, weryfikuje wynik, recznie anuluje w panelu polkurier po weryfikacji. 1. XAMPP MySQL online + cron disabled (zeby tracking nie zaczal pingowac przed weryfikacja). 2. Otworz `/orders/114/shipment/prepare`: - Wybierz "polkurier" w dropdownie. - Wybierz usluge kuriera (np. DPD Standard albo InPost Kurier). - Uzupelnij wymiary/wage; potwierdz adres odbiorcy. - Submit. 3. Sprawdz redirect na `/orders/114` -> zakladka Przesylki: - Wiersz `provider=polkurier`, niepusty `tracking_number`, link "Pobierz etykiete" otwiera PDF. 4. Powtorz dla zamowienia #115 — ten raz z usluga paczkomatowa (InPost Paczkomat); selektor punktu pokazuje liste paczkomatow z API. 5. Otworz panel polkurier.pl manualnie -> zobacz utworzone paczki. 6. Anuluj obie paczki w panelu polkurier (manualna akcja). 7. Zglos wynik: "OK" jezeli paczki utworzone i etykiety pobrane, "issues" z opisem co nie dziala. Type "approved" to continue with delivery_status_mappings seed, or describe issues to fix Task 4: Migracja seed delivery_status_mappings + weryfikacja /settings/delivery-statuses database/migrations/20260514_000115_seed_polkurier_delivery_status_mappings.sql Stworzyc migracje seedujaca `delivery_status_mappings` (provider='polkurier') na podstawie REALNYCH statusow zwracanych przez API polkurier w Task 1 (operator po live tescie zna konkretne `status_code` z `getStatus`).

Baseline mapowan (do dostrojenia po live tescie):
  - `nowa` / `przyjete` / `oczekuje` -> `registered`
  - `wydrukowane` / `przygotowanie` -> `label_printed` (jezeli istnieje w `delivery_statuses` — sprawdzic w Phase 108)
  - `nadane` / `w_dostawie` / `w_doreczeniu` -> `in_transit` lub `out_for_delivery`
  - `doreczone` / `odebrane` -> `delivered`
  - `zwrocone` -> `returned`
  - `anulowane` -> `cancelled`
  - `niedoreczone` / `blad_doreczenia` -> `delivery_failed` lub `unknown` (zaleznie od `delivery_statuses`)

Migracja musi byc idempotentna: `INSERT INTO delivery_status_mappings (provider, raw_status, normalized_status, description) VALUES (...) ON DUPLICATE KEY UPDATE normalized_status = VALUES(normalized_status), description = VALUES(description);`.

Uruchom `php bin/migrate.php` po zatwierdzeniu mapowan.

Otworz `/settings/delivery-statuses?tab=mapping` -> potwierdz widocznosc wpisow provider='polkurier'.

Avoid:
  - Seedu na bazie przypuszczen — uzyj statusow ZAOBSERWOWANYCH w live tescie z Task checkpoint.
  - Tworzenia nowych wpisow w `delivery_statuses` (jezeli polkurier zwraca status ktorego nie ma — dodaj rownolegly INSERT do tej migracji albo osobna migracje).

1. `php bin/migrate.php` zwraca success. 2. `SELECT COUNT(*) FROM delivery_status_mappings WHERE provider='polkurier'` >= 6. 3. `/settings/delivery-statuses?tab=mapping` pokazuje wiersze polkurier. 4. Ponowne uruchomienie migracji = no-op (idempotencja). AC-5 satisfied: mapowania wpisane do DB, widoczne w UI, idempotentne. Task 5: Aktualizacja dokumentacji codebase .paul/codebase/architecture.md, .paul/codebase/db_schema.md, .paul/codebase/tech_changelog.md **architecture.md** — dolozyc sekcje "Phase 128 — polkurier ShipmentService + Tracking" pod sekcja Phase 127: - PolkurierApiClient — pelna lista 7 publicznych metod z apimetod-ami. - PolkurierShipmentService — kontrakt ShipmentProviderInterface, lista pol payloadu, integracja z `getAvailableCarriers`. - PolkurierTrackingService — kontrakt ShipmentTrackingInterface, mapowanie statusow. - Wiring w `ShipmentProviderRegistry` i `CronHandlerFactory`. - UI prepare.php panel polkurier — selector uslug + pickup point ajax.

**db_schema.md** — dolozyc seed mapping rows w sekcji "delivery_status_mappings":
  - Wymienic mapowania `provider='polkurier'` z migracji.

**tech_changelog.md** — wpis z data 2026-05-14 (lub data wdrozenia):
  - "Phase 128 (polkurier ShipmentService): pelna implementacja API client (createShipment/getLabel/getStatus/cancelOrder/getAvailableCarriers/getParcelMachines/getPostOffices), PolkurierShipmentService implementing ShipmentProviderInterface, PolkurierTrackingService, UI panel w prepare.php, seed delivery_status_mappings."

Avoid: kopiowania kodu do dokumentacji (zostawic referencje sciezek + 1-2 zdania kontraktu).

Manualnie przegladnac diff `.paul/codebase/*.md` — wpisy obecne, formatowanie spojne z Phase 127. Dokumentacja zaktualizowana zgodnie z CLAUDE.md (sekcja "Utrwalanie stalych wymagan").

DO NOT CHANGE

• src/Modules/Settings/PolkurierIntegrationRepository.php — Phase 127, kontrakt stabilny.
• src/Modules/Settings/PolkurierApiClient::testConnection() — Phase 127, zweryfikowany na zywym koncie ("Autoryzacja: 1").
• apaczka_integration_settings, ApaczkaShipmentService, ApaczkaTrackingService — Apaczka dziala niezaleznie obok polkuriera.
• database/migrations/20260514_000114_create_polkurier_integration_settings.sql (Phase 127).
• ShipmentProviderInterface i ShipmentTrackingInterface — kontrakty stabilne (nie dolozyc/zmienic metod).
• Reszta paneli w prepare.php (allegro/inpost/apaczka) — tylko dolozenie nowego panelu polkurier obok.

SCOPE LIMITS

• BEZ implementacji OrderValuationV2 (wycena przed nadaniem) — odlozone na osobna faze.
• BEZ presetow przesylek dla polkuriera (shipment_presets.provider_code='polkurier') — operator moze ich uzywac dopiero jak panel polkurier dziala; presety w osobnej fazie.
• BEZ widoku CLI smoke test scriptu (bin/smoke-polkurier.php) — testujemy w realnym UI na #114/#115.
• BEZ event automatyzacji shipment.created zmian — to zdarzenie juz emitowane jednolicie z ShipmentController::store() dla wszystkich providerow.
• BEZ idempotencji createShipment (double-POST guard) — jak w Apaczce, brak retry guard w MVP.
• BEZ refaktoringu wspolnego kodu Apaczka/polkurier (buildReceiverAddress, validateSenderAddress itp.) — kopiujemy wzorzec, deduplikacja w osobnym planie.

Before declaring plan complete: - [ ] `php -l` przechodzi dla wszystkich zmienionych plikow PHP - [ ] Migracja `20260514_000115_*.sql` wykonana, ponowne uruchomienie = no-op - [ ] Operator potwierdzil checkpoint: 2 paczki utworzone na #114 i #115, etykiety pobrane, manualnie anulowane w panelu polkurier - [ ] `/settings/delivery-statuses?tab=mapping` pokazuje wpisy provider='polkurier' - [ ] `/orders/{id}/shipment/prepare` panel polkurier widoczny i funkcjonalny - [ ] Cron tracking nie crashuje (sprawdzic `storage/logs/app.log` po jednym przebiegu) - [ ] Dokumentacja `.paul/codebase/*.md` zaktualizowana - [ ] Wszystkie AC-1..AC-6 spelnione

<success_criteria>

• Operator moze nadawac paczki przez polkurier z poziomu /orders/{id}/shipment/prepare w 4 trybach: kurier door-to-door, paczkomat InPost, punkt Pocztex/Kurier48, ORLEN.
• Tracking polkurier dziala w cronie i aktualizuje shipment_packages.delivery_status przez delivery_status_mappings.
• Live test na #114 i #115 zakonczony sukcesem (paczki utworzone, etykiety pobrane, recznie anulowane).
• Zaden istniejacy provider (Apaczka/InPost/Allegro WZA) nie regresuje. </success_criteria>

After completion, create `.paul/phases/128-polkurier-shipment-service/128-01-SUMMARY.md`