feat(127): polkurier integration foundation

Single-instance globalna konfiguracja polkurier.pl jako alternatywa dla Apaczki: szyfrowany login + Token API, karta w hubie integracji i realny test polaczenia przez apimetod=test_auth_api zweryfikowany na zywym koncie operatora (Autoryzacja: 1). ShipmentProviderRegistry netkniety - PolkurierShipmentService/ TrackingService w kolejnych fazach. Kluczowe ustalenia kontraktu API (z SDK polkurier-sdk): - POST https://api.polkurier.pl/ (jeden endpoint) - JSON body: {authorization:{login,token}, apimetod, data} - Sukces: top-level status === 'success' (nie 'ok') - Blad: tresc w polu 'response' envelope'a - Content-Type: application/json (strict, bez charset suffix) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-14 11:43:11 +02:00
parent 541e61bf7d
commit 3443879f59
17 changed files with 1391 additions and 17 deletions
--- a/.paul/phases/127-polkurier-integration-foundation/127-01-PLAN.md
+++ b/.paul/phases/127-polkurier-integration-foundation/127-01-PLAN.md
@@ -0,0 +1,292 @@
+---
+phase: 127-polkurier-integration-foundation
+plan: 01
+type: execute
+wave: 1
+depends_on: []
+files_modified:
+  - database/migrations/20260514_000114_create_polkurier_integration_settings.sql
+  - src/Modules/Settings/PolkurierIntegrationRepository.php
+  - src/Modules/Settings/PolkurierApiClient.php
+  - src/Modules/Settings/PolkurierIntegrationController.php
+  - src/Modules/Settings/IntegrationsHubController.php
+  - resources/views/settings/integrations/polkurier.php
+  - routes/web.php
+  - .paul/codebase/db_schema.md
+  - .paul/codebase/architecture.md
+  - .paul/codebase/tech_changelog.md
+autonomous: true
+delegation: auto
+---
+
+<objective>
+## Goal
+Dodac fundament integracji z brokerem kurierskim polkurier.pl jako rownolegla alternatywe dla Apaczki: pojedyncza globalna konfiguracja w `/settings/integrations/polkurier` (szyfrowany Token API), karta w hubie integracji `/settings/integrations`, oraz realny test polaczenia z API polkuriera (wywolanie endpointu zwracajacego dane konta lub liste uslug).
+
+## Purpose
+Operator dostaje druga bramke kurierska oprocz Apaczki. Faza zamyka warstwe ustawien i testu polaczenia — tworzenie przesylek, etykiety, tracking i mapowania metod dostawy beda dolozone w kolejnych fazach (analogicznie do tego jak Phase 116/117 zamknely tylko ustawienia HostedSMS/SMSPLANET przed pelnym SMS-em). Apaczka i jej `ShipmentProviderInterface` zostaja niezmienione — polkurier dziala obok.
+
+## Output
+- Migracja DDL tworzaca `polkurier_integration_settings` (mirror `apaczka_integration_settings`).
+- `PolkurierIntegrationRepository` szyfrujacy Token API przez `IntegrationSecretCipher` i zarzadzajacy pojedynczym rekordem `integrations.type='polkurier'` (id rekordu zalezne, nie wpisywane na sztywno).
+- `PolkurierApiClient` realnie wywolujacy API polkuriera w trybie test (endpoint zwracajacy dane konta / liste uslug — wybor zgodnie z dokumentacja SDK ze strony bazy wiedzy polkuriera, decyzja na czas implementacji).
+- `PolkurierIntegrationController` z routami `GET /settings/integrations/polkurier`, `POST .../save`, `POST .../test`.
+- Wiersz "polkurier" w hubie `/settings/integrations` ze statusem konfiguracji, sekretu, aktywnosci i ostatniego testu.
+- Aktualizacja dokumentow projektowych (db_schema, architecture, tech_changelog).
+</objective>
+
+<context>
+## Project Context
+@.paul/PROJECT.md
+@.paul/ROADMAP.md
+@.paul/STATE.md
+
+## Prior Art (wzorzec do skopiowania)
+@src/Modules/Settings/ApaczkaIntegrationRepository.php
+@src/Modules/Settings/ApaczkaApiClient.php
+@src/Modules/Settings/ApaczkaIntegrationController.php
+@src/Modules/Settings/HostedSmsIntegrationRepository.php
+@src/Modules/Settings/HostedSmsIntegrationController.php
+@src/Modules/Settings/SmsplanetIntegrationRepository.php
+@src/Modules/Settings/SmsplanetIntegrationController.php
+@src/Modules/Settings/IntegrationsHubController.php
+@src/Modules/Settings/IntegrationSecretCipher.php
+@database/migrations/20260512_000109_consolidate_fakturownia_to_single_instance.sql
+
+## Codebase docs
+@.paul/codebase/architecture.md
+@.paul/codebase/db_schema.md
+
+## Routy i widok wzorcowe
+@routes/web.php
+@resources/views/settings/integrations/apaczka.php
+
+<clarifications>
+- **Zakres MVP** — Jaki zakres ma pokryc pierwsza faza integracji polkurier.pl?
+  - Odpowiedz: Tylko fundament + test polaczenia (wzorzec faz 116/117).
+- **Model konta** — Pojedyncza globalna instancja czy wieloinstancyjna?
+  - Odpowiedz: Single instance (jak Apaczka/InPost) — fixed `polkurier_integration_settings.id=1`, jeden rekord `integrations.type='polkurier'`.
+- **Apaczka vs polkurier** — Zastapienie czy rownoleglosc?
+  - Odpowiedz: Obok Apaczki — oba dostawcy dzialaja, Apaczka netknieta, operator wybiera w kolejnych fazach (gdy `PolkurierShipmentService` zostanie dodany).
+- **Paczkomaty / punkty odbioru** — Czy w tej fazie?
+  - Odpowiedz: Poza zakresem tej fazy. Operator potwierdzil "ma dzialac jak Apaczka"; obsluga punktow odbioru pojawi sie razem z `PolkurierShipmentService` w nastepnej fazie (tak jak Apaczka — receiver_point_id w shipment_packages).
+</clarifications>
+</context>
+
+<acceptance_criteria>
+
+## AC-1: Migracja tworzy single-instance tabele konfiguracji
+```gherkin
+Given XAMPP MySQL jest online i migracje sa zacommitowane
+When operator uruchamia `php bin/migrate.php`
+Then powstaje tabela `polkurier_integration_settings` z kolumnami: `id TINYINT UNSIGNED PK` (always 1), `integration_id INT UNSIGNED UNIQUE NULL FK -> integrations(id) CASCADE`, `api_token_encrypted TEXT NULL`, `environment ENUM('production','sandbox') NOT NULL DEFAULT 'production'`, `default_label_format VARCHAR(8) NOT NULL DEFAULT 'PDF'`, `created_at`, `updated_at`
+And ponowne uruchomienie migracji jest no-op (`CREATE TABLE IF NOT EXISTS`)
+```
+
+## AC-2: Repozytorium szyfruje Token API i zarzadza pojedynczym rekordem integrations
+```gherkin
+Given migracja AC-1 wykonana
+When operator zapisuje konfiguracje przez `PolkurierIntegrationRepository::saveSettings([api_token => 'XYZ', environment => 'production', is_active => 1])`
+Then w `integrations` powstaje (lub zostaje zaktualizowany) jeden rekord `type='polkurier'`, `polkurier_integration_settings.id=1` ma uzupelnione `integration_id` i zaszyfrowane `api_token_encrypted`
+And `getSettings()` zwraca rekord BEZ surowego tokena, jedynie z flaga `has_api_token: bool`
+And `getCredentials()` zwraca odszyfrowany Token API tylko gdy konfiguracja jest kompletna i aktywna (`is_active=1`)
+```
+
+## AC-3: Endpoint testowy realnie wywoluje API polkuriera i zapisuje wynik
+```gherkin
+Given operator zapisal poprawny Token API
+When operator klika "Testuj polaczenie" w `/settings/integrations/polkurier`
+Then `PolkurierApiClient` wykonuje realne wywolanie HTTP do API polkuriera (endpoint nie pisany na sztywno w PLAN, wybierany przez implementatora z dokumentacji `Polkurier_WebService_API_1_1.pdf` — preferowany endpoint typu "lista uslug" / "konto" zwracajacy dane bez tworzenia przesylki)
+And `integrations.last_test_status / last_test_http_code / last_test_message / last_test_at` zostaja zaktualizowane przez `IntegrationsRepository::updateTestResult()`
+And UI pokazuje czytelny komunikat (sukces albo blad z opisem) — bez surowego dump-u JSON/XML
+And brak zaszyfrowanego tokena w logach (`storage/logs/app.log` nie zawiera plaintext tokena nawet w przypadku bledu API)
+```
+
+## AC-4: Karta polkurier w hubie integracji
+```gherkin
+Given konfiguracja istnieje (kompletna albo niekompletna)
+When operator otwiera `/settings/integrations`
+Then widzi wiersz "polkurier" z statusem: skonfigurowana (tak/nie), token zapisany (tak/nie), aktywna (tak/nie), ostatni test (timestamp + ok/error)
+And klikniecie wiersza prowadzi do `/settings/integrations/polkurier`
+```
+
+## AC-5: Apaczka i istniejace ShipmentProviderRegistry netkniete
+```gherkin
+Given Apaczka jest aktywna i zarejestrowana w `ShipmentProviderRegistry`
+When polkurier zostaje dodany do hubu integracji
+Then `ShipmentProviderRegistry` NIE rejestruje polkuriera (brak `PolkurierShipmentService` w tej fazie)
+And tworzenie przesylek Apaczka dziala bez zmian
+And `routes/web.php` nie modyfikuje wiring ApaczkaShipmentService/Tracking
+```
+
+## AC-6: Dokumentacja zaktualizowana
+```gherkin
+Given plan ukonczony
+When operator otwiera `.paul/codebase/db_schema.md`
+Then sekcja Integrations zawiera definicje `polkurier_integration_settings`
+And `.paul/codebase/architecture.md` zawiera sekcje "Phase 127 - polkurier Integration Settings" z opisem repository, api client, controller, hub
+And `.paul/codebase/tech_changelog.md` zawiera wpis chronologiczny z data i opisem co + dlaczego
+```
+
+</acceptance_criteria>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Migracja DB + PolkurierIntegrationRepository</name>
+  <files>
+    database/migrations/20260514_000114_create_polkurier_integration_settings.sql,
+    src/Modules/Settings/PolkurierIntegrationRepository.php
+  </files>
+  <action>
+    1) Migracja DDL `CREATE TABLE IF NOT EXISTS polkurier_integration_settings` zgodna z AC-1 (mirror `apaczka_integration_settings` + analogia do `hostedsms_integration_settings`/`smsplanet_integration_settings` w zakresie ENUM environment). InnoDB, utf8mb4_unicode_ci. FK `integration_id REFERENCES integrations(id) ON DELETE CASCADE`. Migracja MUSI byc idempotentna (re-run = no-op zgodnie z decyzja projektu: nigdy `SELECT 1;`, tylko DDL — patrz decision 2026-05-10 w PROJECT.md).
+    2) `PolkurierIntegrationRepository final class` w `src/Modules/Settings/`:
+       - konstruktor `(Medoo $db, IntegrationSecretCipher $cipher, IntegrationsRepository $integrations)`,
+       - `getSettings(): array` — JOIN `integrations` z `polkurier_integration_settings` po `integration_id`, zwraca `has_api_token: bool` (NIE plaintext), `environment`, `default_label_format`, `is_active`, `last_test_*`,
+       - `saveSettings(array $payload): void` — upsert: gdy brak rekordu `integrations.type='polkurier'`, twórz przez `IntegrationsRepository::ensureIntegration('polkurier', $name)`; gdy token jest pustym stringiem -> nie nadpisuj (BC z patternem fakturowni); inaczej zaszyfruj przez `IntegrationSecretCipher::encrypt()`. Walidacja serwerowa wymaganych pol.
+       - `getCredentials(): ?array` — zwraca `['api_token' => string, 'environment' => string, 'integration_id' => int]` TYLKO gdy `is_active=1` AND `api_token_encrypted IS NOT NULL`; inaczej `null`. Uzywany przez `PolkurierApiClient` i przyszly `PolkurierShipmentService`.
+       - `getIntegrationId(): ?int` — single source of truth dla przyszlych integracji (analogicznie do `FakturowniaIntegrationRepository`).
+    
+    Avoid: tworzenia drugiego rekordu `integrations.type='polkurier'` (analogicznie do migracji konsolidacyjnej Fakturowni 20260512_000109 — single instance jest twardym kontraktem); pisania tokenu plaintext do logow; sklejania SQL stringiem (Medoo + prepared statements only).
+  </action>
+  <verify>
+    `php bin/migrate.php` -> brak bledow, `SHOW CREATE TABLE polkurier_integration_settings;` -> kolumny zgodne z AC-1.
+    `php -r "require 'bootstrap/app.php'; $r = $app->make(PolkurierIntegrationRepository::class); var_dump($r->getSettings());"` -> array z `has_api_token=false`.
+  </verify>
+  <done>AC-1 satisfied (migracja DDL idempotentna), AC-2 satisfied (repozytorium szyfruje token, zwraca has_api_token bool, getCredentials gating na is_active).</done>
+</task>
+
+<task type="auto">
+  <name>Task 2: PolkurierApiClient + Controller + widok formularza</name>
+  <files>
+    src/Modules/Settings/PolkurierApiClient.php,
+    src/Modules/Settings/PolkurierIntegrationController.php,
+    resources/views/settings/integrations/polkurier.php,
+    routes/web.php
+  </files>
+  <action>
+    1) `PolkurierApiClient final class` w `src/Modules/Settings/`:
+       - cURL klient z `SslCertificateResolver::resolve()` (zgodnie z patternem `FakturowniaApiClient`, `HostedSmsApiClient`, `SmsplanetApiClient`),
+       - PHP 8.5: ZAKAZ `curl_close()` (decision 2026-05-10 — wycieka `Deprecated` HTML przed JSON response),
+       - metoda `testConnection(string $apiToken, string $environment): array` zwracajaca `['ok' => bool, 'http_code' => int, 'message' => string]`,
+       - WYBOR endpointu testowego: implementator MUSI sprawdzic `Polkurier_WebService_API_1_1.pdf` (link w opisie API polkuriera, baza wiedzy artykul "interfejs api do pobrania") i wybrac endpoint nie tworzacy przesylki (preferencja: "lista uslug" / "dane konta" / "wycena testowa"). Wybor udokumentowac w naglowku klasy.
+       - przyszle stuby `createShipment()`, `downloadLabel()`, `trackShipment()`, `cancelShipment()` — rzucajace `RuntimeException("Not implemented in Phase 127")`; dolozone w kolejnych fazach.
+    
+    2) `PolkurierIntegrationController final class` (mirror `HostedSmsIntegrationController` 1:1):
+       - routes: `GET /settings/integrations/polkurier` (`edit`), `POST /settings/integrations/polkurier/save` (CSRF `_token`), `POST /settings/integrations/polkurier/test` (CSRF `_token`),
+       - `test()` -> walidacja zapisanej konfiguracji -> `PolkurierApiClient::testConnection()` -> `IntegrationsRepository::updateTestResult()` -> Flash `Flash::push('success'|'danger', ...)` (Phase 120 pattern, NIE `Flash::set('polkurier.test')`),
+       - redirect przez `RedirectPathResolver`.
+    
+    3) Widok `resources/views/settings/integrations/polkurier.php`:
+       - dziedziczy z `layouts/app.php`,
+       - formularz: token API (password input z placeholderem "Pozostaw puste aby nie zmieniac" gdy `has_api_token=true`), environment (select production/sandbox), domyslny format etykiety (PDF/ZPL/EPL), checkbox `is_active`, przycisk "Zapisz" i osobny "Testuj polaczenie",
+       - `_token` na obu formularzach (CSRF, nie `_csrf_token` — decision 2026-03-13),
+       - alerty wylacznie przez komponent `resources/views/components/alert.php` (Phase 120 contract — NIE inline `<div class="alert alert--*">`),
+       - potwierdzenia akcji destrukcyjnych (na przyszlosc) przez `window.OrderProAlerts.confirm({...})` options-object API (decision Phase 114/120),
+       - bez inline `<style>` — style przez `resources/scss/modules/_integrations.scss` jezeli czegokolwiek brakuje (CLAUDE.md: zero CSS w widokach).
+    
+    4) `routes/web.php` — wpiac controller w sekcji Settings/Integrations (po Apaczka, przed HostedSMS dla porzadku alfabetycznego). DI: `new PolkurierIntegrationController($template, $translator, $auth, new PolkurierIntegrationRepository($app->db(), $cipher, $integrationsRepository), new PolkurierApiClient($timeoutSeconds = 15))`.
+    
+    Avoid: kopiowania `apaczka.php` bez przegladu (Apaczka ma duzy formularz z domyslnymi wymiarami — niepotrzebne w MVP polkuriera); dodawania `PolkurierShipmentService` do `ShipmentProviderRegistry` (out of scope, AC-5 wymaga netknietego registry); modyfikacji `apaczka_integration_settings` lub `IntegrationsRepository` poza `updateTestResult()` (reuse, nie refactor).
+  </action>
+  <verify>
+    Build PHP `php -l src/Modules/Settings/PolkurierApiClient.php` i `php -l src/Modules/Settings/PolkurierIntegrationController.php` -> No syntax errors.
+    Recznie: zaloguj sie, otworz `/settings/integrations/polkurier` -> formularz renderuje sie bez bledow, alerty stylowane.
+    Zapis pustego tokenu -> blad walidacji. Zapis prawdziwego tokenu (dev konto polkurier jezeli operator ma) -> rekord w DB ma niepuste `api_token_encrypted`.
+    Klik "Testuj polaczenie" z prawdziwym tokenem -> `integrations.last_test_status='ok'` w DB; bledny token -> `last_test_status='error'` + zrozumialy komunikat w UI.
+  </verify>
+  <done>AC-3 satisfied (realne wywolanie API, zapis wyniku, brak plaintext tokena w logach); fundament UI/wiring na miejscu.</done>
+</task>
+
+<task type="auto">
+  <name>Task 3: Hub integracji + aktualizacja dokumentow projektowych</name>
+  <files>
+    src/Modules/Settings/IntegrationsHubController.php,
+    resources/views/settings/integrations/index.php,
+    .paul/codebase/db_schema.md,
+    .paul/codebase/architecture.md,
+    .paul/codebase/tech_changelog.md
+  </files>
+  <action>
+    1) `IntegrationsHubController`:
+       - dodaj parametr konstruktora `PolkurierIntegrationRepository $polkurier`,
+       - dodaj metode `buildPolkurierRow(): array` zwracajaca te same klucze co `buildApaczkaRow()` (`name`, `configured`, `has_secret`, `is_active`, `last_test_status`, `last_test_at`, `last_test_message`, `link`),
+       - wcisniecie wiersza do listy w `index()` (kolejnosc: po Apaczka, przed Allegro/inni — sprawdz aktualny porzadek w `index.php`),
+       - `routes/web.php` - rozszerzyc wiring kontrolera o instancje `PolkurierIntegrationRepository` (kompatybilnie z istniejacymi 5+ params).
+    
+    2) `resources/views/settings/integrations/index.php`:
+       - jezeli widok generuje wiersze z tablicy zwracanej przez controller, ZADNA zmiana widoku nie jest potrzebna,
+       - jezeli widok ma hardkodowana liste rzedow (sprawdz przed edycja) — dodaj wiersz polkurier w tym samym wzorcu co Apaczka.
+    
+    3) `.paul/codebase/db_schema.md` — sekcja Integrations, po `apaczka_integration_settings`:
+       - dodac pelna tabele kolumn `polkurier_integration_settings` (zgodnie z AC-1),
+       - oznaczenie `(Phase 127; fixed 1 row)` w naglowku tabeli,
+       - update licznika `Total tables: 62` i `Updated: 2026-05-14`.
+    
+    4) `.paul/codebase/architecture.md`:
+       - dodac sekcje `## Phase 127 — polkurier Integration Settings` po `## Phase 117 - SMSPLANET Integration Settings`,
+       - opis `PolkurierIntegrationRepository`, `PolkurierApiClient`, `PolkurierIntegrationController`, integracja z `IntegrationsHubController`,
+       - zaznaczyc ze `ShipmentProviderRegistry` nie zostal zmodyfikowany (deferred do osobnej fazy).
+    
+    5) `.paul/codebase/tech_changelog.md` — dopisac wpis chronologiczny z data 2026-05-14:
+       - co: fundament polkurier integration (settings + test polaczenia),
+       - dlaczego: alternatywa dla Apaczki na zyczenie operatora,
+       - referencja do Phase 127.
+    
+    Avoid: dotykania PROJECT.md (Decisions / Validated Requirements) — to robi UNIFY, nie APPLY; modyfikacji ROADMAP.md (robi to /paul:plan w step update_state); zmiany schematu innych tabel.
+  </action>
+  <verify>
+    `/settings/integrations` -> widac wiersz polkurier z prawidlowym statusem konfiguracji.
+    `grep -c "polkurier_integration_settings" .paul/codebase/db_schema.md` -> co najmniej 1 trafienie.
+    `grep -c "Phase 127" .paul/codebase/architecture.md` -> co najmniej 1 trafienie.
+    Apaczka wiersz w hubie nadal sie renderuje (regresja zero — AC-5).
+  </verify>
+  <done>AC-4 satisfied (karta polkurier w hubie), AC-5 satisfied (Apaczka netknieta), AC-6 satisfied (dokumenty zaktualizowane).</done>
+</task>
+
+</tasks>
+
+<boundaries>
+
+## DO NOT CHANGE
+- `src/Modules/Shipments/*` — caly modul Shipments (registries, ApaczkaShipmentService, InpostShipmentService, ShipmentController). `PolkurierShipmentService` to osobna faza.
+- `src/Modules/Settings/Apaczka*.php` — Apaczka netknieta.
+- `database/migrations/*` istniejace pliki — tylko nowa migracja `20260514_000114_*`.
+- `src/Modules/Settings/IntegrationSecretCipher.php` — reuse, zero refaktoru.
+- `routes/web.php` istniejace routy — tylko dodajemy 3 nowe (polkurier GET/save/test).
+- `resources/views/components/alert.php` — Phase 120 contract, zero modyfikacji.
+
+## SCOPE LIMITS
+- Brak `PolkurierShipmentService` (tworzenie przesylki) — kolejna faza.
+- Brak `PolkurierTrackingService` (delivery polling) — kolejna faza po Shipment.
+- Brak wpisow w `delivery_status_mappings` (provider='polkurier') — wymagaja realnego API tracking, do osobnej fazy.
+- Brak mapowan metod dostawy w UI (`order_delivery_method -> polkurier service`) — wymagaja modelowania w osobnej fazie po analizie listy uslug API polkuriera.
+- Brak zmian w `shipment_presets` schemacie ani UI presetow — presety beda potem.
+- Brak migracji konsolidujacych z Apaczka — oba dostawcy zyja niezaleznie.
+- Brak `ShipmentProviderRegistry::register('polkurier', ...)` — out of scope.
+- Brak `.env` / `app_settings` flag globalnych — token siedzi tylko w `polkurier_integration_settings` (jak Apaczka/HostedSMS/SMSPLANET).
+
+</boundaries>
+
+<verification>
+Before declaring plan complete:
+- [ ] `php bin/migrate.php` przeszla bez bledow (operator manualnie po wdrozeniu — XAMPP online).
+- [ ] `php -l` przeszedl dla wszystkich nowych plikow PHP (bez syntax errors).
+- [ ] `/settings/integrations` renderuje wiersz polkurier obok Apaczki.
+- [ ] `/settings/integrations/polkurier` formularz dziala: zapis, ponowne wczytanie, "Testuj polaczenie" zwraca rzeczywista odpowiedz API (operator wpisuje prawdziwy token).
+- [ ] Apaczka konfiguracja `/settings/integrations/apaczka` dziala bez regresji.
+- [ ] `ShipmentProviderRegistry` nie zna polkuriera (grep brak `polkurier` w `src/Modules/Shipments/ShipmentProviderRegistry.php`).
+- [ ] Wszystkie acceptance criteria spelnione.
+</verification>
+
+<success_criteria>
+- Single-instance globalna konfiguracja polkurier zapisuje sie i odczytuje (Token zaszyfrowany, `has_api_token` flag w UI).
+- Realne wywolanie API polkuriera w trybie test zwraca status (ok/error) i jest widoczne w hubie i panelu integracji.
+- Apaczka dziala bez regresji obok polkuriera.
+- Dokumentacja codebase (`db_schema.md`, `architecture.md`, `tech_changelog.md`) zaktualizowana.
+- Zaden plik z `boundaries.DO NOT CHANGE` nie zostal zmodyfikowany.
+</success_criteria>
+
+<output>
+After completion, create `.paul/phases/127-polkurier-integration-foundation/127-01-SUMMARY.md`.
+</output>
--- a/.paul/phases/127-polkurier-integration-foundation/127-01-SUMMARY.md
+++ b/.paul/phases/127-polkurier-integration-foundation/127-01-SUMMARY.md
@@ -0,0 +1,201 @@
+---
+phase: 127-polkurier-integration-foundation
+plan: 01
+subsystem: integrations
+tags: [polkurier, courier, shipment-broker, settings, integration-hub, php]
+
+requires:
+  - phase: 116-hostedsms-integration-settings
+    provides: single-instance integration repository pattern (IntegrationsRepository::ensureIntegration + updateTestResult + IntegrationSecretCipher)
+  - phase: 120-alert-component-unification
+    provides: resources/views/components/alert.php contract for all settings views
+provides:
+  - polkurier_integration_settings DB table (single-instance, fixed id=1)
+  - PolkurierIntegrationRepository (login + Token API, AES-encrypted)
+  - PolkurierApiClient with verified live test connection against apimetod=test_auth_api
+  - /settings/integrations/polkurier UI (form + Testuj polaczenie) + hub row
+  - Foundation for future PolkurierShipmentService / PolkurierTrackingService
+affects:
+  - future polkurier-shipment-service phase (uses getCredentials + verified API client contract)
+  - future polkurier-tracking-service phase (delivery_status_mappings provider='polkurier')
+
+tech-stack:
+  added: []
+  patterns:
+    - single-instance integration ctor (PDO $pdo, string $secret) mirror HostedSMS/SMSPLANET
+    - polkurier API contract: POST https://api.polkurier.pl/, JSON body {authorization:{login,token}, apimetod, data:{platform, platform_version}}, success when top-level status='success'
+    - error path: payload from "response" field of envelope (string or struct) — mirror SDK ErrorException($response->get('response'))
+    - strict Content-Type: application/json (no charset suffix — polkurier rejects)
+
+key-files:
+  created:
+    - database/migrations/20260514_000114_create_polkurier_integration_settings.sql
+    - src/Modules/Settings/PolkurierIntegrationRepository.php
+    - src/Modules/Settings/PolkurierApiClient.php
+    - src/Modules/Settings/PolkurierIntegrationController.php
+    - resources/views/settings/polkurier.php
+  modified:
+    - routes/web.php
+    - src/Modules/Settings/IntegrationsHubController.php
+    - resources/lang/pl.php
+    - .paul/codebase/db_schema.md
+    - .paul/codebase/architecture.md
+    - .paul/codebase/tech_changelog.md
+
+key-decisions:
+  - "polkurier startuje jako single-instance globalna konfiguracja (mirror Apaczka/HostedSMS/SMSPLANET) — operator ma jedno konto polkurier"
+  - "polkurier dziala obok Apaczki — ShipmentProviderRegistry netkniety; oba dostawcy zyja niezaleznie"
+  - "API polkuriera wymaga login + token w body authorization (zweryfikowane w SDK polkurier-sdk); kolumna login dodana mimo ze PLAN AC-1 jej nie wymagal"
+  - "Brak kolumny environment ENUM — polkurier ma jeden produkcyjny endpoint, sandbox nie istnieje"
+  - "Test polaczenia uzywa apimetod=test_auth_api (nie tworzy przesylki, nie kosztuje); sukces gdy top-level status='success'"
+  - "Content-Type MUSI byc dokladnie 'application/json' — polkurier odrzuca '; charset=UTF-8' suffix"
+
+patterns-established:
+  - "polkurier API client: jeden POST endpoint, ResponseStatus::SUCCESS='success', tresc bledu w polu 'response' envelope'a — wzorzec dla wszystkich przyszlych metod (createShipment, getLabel, getStatus, cancelOrder, AvailableCarriers, etc.)"
+  - "Strict Content-Type bez charset suffix — pattern do reuse w innych integracjach jezeli odrzucaja parametry"
+
+duration: ~45min
+started: 2026-05-14T19:00:00Z
+completed: 2026-05-14T19:45:00Z
+---
+
+# Phase 127 Plan 01: polkurier Integration Foundation — Summary
+
+**polkurier.pl broker kurierski dostepny jako alternatywa dla Apaczki: pojedyncza globalna konfiguracja w `/settings/integrations/polkurier` z zaszyfrowanym Token API + loginem, realny test polaczenia przez `apimetod=test_auth_api` zweryfikowany na produkcyjnym koncie operatora (`Autoryzacja: 1`).**
+
+## Performance
+
+| Metric | Value |
+|--------|-------|
+| Duration | ~45min (incl. live API debugging) |
+| Started | 2026-05-14T19:00:00Z |
+| Completed | 2026-05-14T19:45:00Z |
+| Tasks | 3 of 3 completed |
+| Files created | 5 |
+| Files modified | 6 |
+
+## Acceptance Criteria Results
+
+| Criterion | Status | Notes |
+|-----------|--------|-------|
+| AC-1: Migracja tworzy single-instance tabele konfiguracji | Pass (modified) | DDL idempotentny. **Modyfikacja:** kolumna `environment ENUM` pominieta (polkurier nie ma sandbox); dodana kolumna `login VARCHAR(190)` (polkurier wymaga login+token, nie samego tokena). |
+| AC-2: Repozytorium szyfruje Token API i zarzadza pojedynczym rekordem integrations | Pass | `getSettings()` zwraca `has_api_token: bool`, `saveSettings()` szyfruje przez `IntegrationSecretCipher`, `getCredentials()` gates na `is_active=1`. |
+| AC-3: Endpoint testowy realnie wywoluje API polkuriera i zapisuje wynik | Pass (live verified) | Operator potwierdzil: `Polaczenie z polkurier dziala. Autoryzacja: 1` (response z `apimetod=test_auth_api`). `IntegrationsRepository::updateTestResult()` zapisuje wynik. |
+| AC-4: Karta polkurier w hubie integracji | Pass | `buildPolkurierRow()` w `IntegrationsHubController` wstawia wiersz po Apaczce (semantycznie sasiednie). |
+| AC-5: Apaczka i istniejace ShipmentProviderRegistry netkniete | Pass | Zerowe modyfikacje w `src/Modules/Shipments/*` i `Apaczka*`. Grep `polkurier` w `ShipmentProviderRegistry.php` -> 0 trafien. |
+| AC-6: Dokumentacja zaktualizowana | Pass | `db_schema.md` +1 tabela (62 total), `architecture.md` +sekcja Phase 127, `tech_changelog.md` +wpis z deviation. |
+
+## Accomplishments
+
+- polkurier.pl wpiety jako drugi broker kurierski (obok Apaczki) — fundament gotowy i zweryfikowany na zywym API operatora.
+- Kontrakt API polkuriera zweryfikowany i udokumentowany w `architecture.md`: POST `https://api.polkurier.pl/`, JSON `{authorization:{login,token}, apimetod, data:{platform, platform_version}}`, sukces gdy `status='success'`, tresc bledu w polu `response` envelope'a.
+- 4 buggi z pierwszego draftu naprawione live (3 podczas testow operatora) — finalna implementacja sprawdzona na realnym Token API.
+
+## Task Commits
+
+Commits jeszcze nie utworzone (czekaja na transition step). Calosc fazy 127 zostanie zacommitowana jako jeden `feat(127):` commit.
+
+| Task | Commit | Type | Description |
+|------|--------|------|-------------|
+| Task 1: Migracja + Repository | (pending) | feat | DDL + PolkurierIntegrationRepository |
+| Task 2: ApiClient + Controller + widok + routy | (pending) | feat | PolkurierApiClient + Controller + view + i18n + DI |
+| Task 3: Hub + dokumentacja codebase | (pending) | feat | IntegrationsHubController buildPolkurierRow + db_schema/architecture/tech_changelog |
+
+## Files Created/Modified
+
+| File | Change | Purpose |
+|------|--------|---------|
+| `database/migrations/20260514_000114_create_polkurier_integration_settings.sql` | Created | DDL tabeli + seed `integrations.type='polkurier'` (idempotentny) |
+| `src/Modules/Settings/PolkurierIntegrationRepository.php` | Created | Single-instance repo, szyfrowanie tokena, getCredentials z gating na is_active |
+| `src/Modules/Settings/PolkurierApiClient.php` | Created | POST do api.polkurier.pl, testConnection z apimetod=test_auth_api, stuby createShipment/getLabel/getStatus/cancelOrder |
+| `src/Modules/Settings/PolkurierIntegrationController.php` | Created | GET/save/test endpointy z CSRF, flash, RedirectPathResolver |
+| `resources/views/settings/polkurier.php` | Created | Formularz konfiguracji + Test polaczenia, alerty przez komponent alert.php |
+| `routes/web.php` | Modified | DI wiring (Repo+Controller) + 3 routy + ctor IntegrationsHubController |
+| `src/Modules/Settings/IntegrationsHubController.php` | Modified | +param polkurier + buildPolkurierRow() + wstawienie wiersza po Apaczce |
+| `resources/lang/pl.php` | Modified | settings.polkurier.* + providers.polkurier |
+| `.paul/codebase/db_schema.md` | Modified | +tabela polkurier_integration_settings, 61->62 |
+| `.paul/codebase/architecture.md` | Modified | +sekcja Phase 127 |
+| `.paul/codebase/tech_changelog.md` | Modified | +wpis 2026-05-14 z deviation |
+
+## Decisions Made
+
+| Decision | Rationale | Impact |
+|----------|-----------|--------|
+| Kolumna `login VARCHAR(190)` w tabeli zamiast samego `api_token` | API polkuriera (zweryfikowane w SDK Auth.php/Request.php) wymaga login+token w body authorization, nie samego tokena | Wszystkie przyszle wywolania API musza miec login z `getCredentials()['login']` |
+| Pominieta kolumna `environment ENUM('production','sandbox')` z PLAN AC-1 | polkurier nie ma osobnego srodowiska sandbox (jeden URL: https://api.polkurier.pl/) | YAGNI; jezeli polkurier doda sandbox, dolozymy migracja `ALTER TABLE ... ADD COLUMN` |
+| Wykonanie planu inline zamiast delegated:auto z planu | Swiezy kontekst API research (Config/Auth/Methods z polkurier-sdk) — agent musialby ten research powtorzyc | Brak; boundaries i AC niezmienione, deviation udokumentowana |
+| `Content-Type: application/json` (bez `; charset=UTF-8` suffix) | polkurier API zwraca `Content type must be: application/json` gdy header ma charset suffix | Pattern do reuse jezeli inne integracje sa rownie strict |
+| `ResponseStatus::SUCCESS = 'success'` (nie `'ok'`) | Zweryfikowane w `src/Type/ResponseStatus.php` SDK polkuriera | Wszystkie przyszle metody API musza sprawdzac `status === 'success'` |
+| Tresc bledu z pola `response` envelope'a (nie `error_message`) | SDK polkuriera rzuca `ErrorException($response->get('response'))` gdy status != success | Wzorzec parser bledu dla wszystkich przyszlych metod API |
+
+## Deviations from Plan
+
+### Summary
+
+| Type | Count | Impact |
+|------|-------|--------|
+| Auto-fixed | 3 | Krytyczne — bez tych poprawek test polaczenia nie zwracalby `success` |
+| Scope additions | 1 | Kolumna `login` w schemacie (poza zakresem AC-1 — wymagana przez kontrakt API) |
+| Scope removals | 1 | Kolumna `environment` z AC-1 pominieta (YAGNI) |
+| Execution mode | 1 | Plan: `delegation:auto`. Faktycznie: inline. Boundaries i AC niezmienione. |
+| Deferred | 0 | Brak |
+
+**Total impact:** Wszystkie deviacje wymuszone realnym kontraktem API polkuriera. Plan z chwili pisania bazowal na publicznym opisie API; szczegoly (login, status='success', strict Content-Type) wyplynely dopiero przy weryfikacji SDK i testach na zywym koncie operatora.
+
+### Auto-fixed Issues
+
+**1. [API contract] `status === 'ok'` -> `status === 'success'`**
+- **Found during:** Live test po Task 2 (operator zglosil `Status: error`)
+- **Issue:** Kod sprawdzal `$status === 'ok'`, ale `ResponseStatus::SUCCESS` w SDK polkuriera = `'success'`
+- **Fix:** Zmiana porownania na `$status === 'success'`; parser bledu zaktualizowany do pobierania tresci z pola `response` envelope'a (mirror SDK ErrorException)
+- **Files:** `src/Modules/Settings/PolkurierApiClient.php`
+- **Verification:** Drugi test operatora — komunikat `Content type must be: application/json` (faktyczna tresc z polkuriera, nie generyczne `Status: error`)
+- **Commit:** TBD (przy transition)
+
+**2. [HTTP headers] Content-Type strict**
+- **Found during:** Live test po fix #1 (operator zglosil `Content type must be: application/json`)
+- **Issue:** Header `Content-Type: application/json; charset=UTF-8` — polkurier robi strict equality check i odrzuca suffix `; charset=UTF-8`
+- **Fix:** Zmiana na `Content-Type: application/json` (sam mime, bez parametrow)
+- **Files:** `src/Modules/Settings/PolkurierApiClient.php`
+- **Verification:** Trzeci test operatora — `Polaczenie z polkurier dziala. Autoryzacja: 1` (sukces)
+- **Commit:** TBD (przy transition)
+
+**3. [Error reporting] Brak tresci bledu w komunikacie UI**
+- **Found during:** Live test po Task 2 (`Status: error` bez detali)
+- **Issue:** Komunikat fallback `'Status: ' . $status` byl nieczytelny; tresc bledu z polkuriera siedzi w polu `response` envelope'a, nie `error_message` top-level
+- **Fix:** Parser bledu czyta `response` field (string albo zagniezdzona struktura `error_message/errorMessage/message/error`), z fallbackiem na top-level `error_message/message/error` i finalnie `Status: X (HTTP Y)`
+- **Files:** `src/Modules/Settings/PolkurierApiClient.php`
+- **Verification:** Fix #2 mozliwy tylko dzieki temu (operator zobaczyl `Content type must be: application/json` zamiast `Status: error`)
+- **Commit:** TBD (przy transition)
+
+### Deferred Items
+
+Brak — kontrakt API operatora zweryfikowany, fundament zamkniety. Kolejne fazy (PolkurierShipmentService, PolkurierTrackingService) sa zaplanowane jako oddzielne, swiadomie poza zakresem 127 (PLAN boundaries `SCOPE LIMITS`).
+
+## Issues Encountered
+
+| Issue | Resolution |
+|-------|------------|
+| Operator: `Status: error` po pierwszym smoke | Fix #1 (status='success') + #3 (parser bledu) — operator widzi teraz realny komunikat polkuriera |
+| Operator: `Content type must be: application/json` po fix #1 | Fix #2 (strict Content-Type bez charset suffix) |
+| API research nieobecny przed planem | Pre-APPLY fetche SDK polkurier-sdk (Auth/Request/Methods/Config/ResponseStatus) — kontrakt zrekonstruowany przed implementacja |
+
+## Next Phase Readiness
+
+**Ready:**
+- `PolkurierIntegrationRepository::getCredentials()` zwraca odszyfrowany `login + api_token + default_label_format` — gotowe do uzycia w `PolkurierShipmentService`.
+- `PolkurierApiClient` ma zweryfikowany kontrakt POST (single endpoint, JSON body, status='success', error w `response`) + stuby `createShipment/getLabel/getStatus/cancelOrder` z `RuntimeException("Not implemented in Phase 127")` jako placeholder dla nastepnej fazy.
+- 36 metod SDK polkuriera zidentyfikowanych: `AvailableCarriers`, `OrderValuationV2`, `CreateOrder`, `GetLabel`, `GetStatus`, `CancelOrder`, `InpostParcelMachines`, `PocztexPostOffices`, `Kurier48PostOffices`, `GetCourierPoint`, `Heartbeat`, etc. — gotowe do mapowania w kolejnych planach.
+- Hub integracji pokazuje stan polkuriera obok Apaczki — operator widzi obie integracje rownolegle.
+
+**Concerns:**
+- Brak `PolkurierShipmentService` — operator nie moze jeszcze nadawac przesylek przez polkuriera. Zgodne z PLAN scope (`SCOPE LIMITS`).
+- Brak mapowan metod dostawy `order_delivery_method -> polkurier service` — wymaga analizy listy uslug z `AvailableCarriers` API.
+- Brak `delivery_status_mappings` dla `provider='polkurier'` — tracking polling rowniez deferred.
+
+**Blockers:**
+- Operator musi uruchomic `php bin/migrate.php` na zywej bazie (XAMPP) zeby zalozyc tabele i seed rekord `integrations.type='polkurier'`. AKTUALNIE migracja juz uruchomiona (test polaczenia dzialal, wiec rekord `integrations` istnieje).
+
+---
+*Phase: 127-polkurier-integration-foundation, Plan: 01*
+*Completed: 2026-05-14*