---
phase: 128-polkurier-shipment-service
plan: 01
type: execute
wave: 1
depends_on: []
files_modified:
- 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
autonomous: false
delegation: 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)
## AC-1: PolkurierApiClient — pelny kontrakt API
```gherkin
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
```gherkin
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
```gherkin
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: , status_raw: , description: }`
And `supports('polkurier')` zwraca true
```
## AC-4: UI prepare.php panel polkurier
```gherkin
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
```gherkin
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
```gherkin
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)
```
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/` (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 `` do `#carrierSelect` (linia ~103).
- Dolozyc panel `` z:
- `