feat(104-apaczka-weekend-delivery): Apaczka Paczka w Weekend dla paczkomatow InPost

Phase 104 complete: - Backend: ApaczkaShipmentService::buildOptionsPayload() mapuje weekend_delivery -> option[19] = 1 w payloadzie API Apaczka v2 - Stala OPTION_KEYS jako rozszerzalne mapowanie pole formularza -> id opcji Apaczki - Frontend: checkbox "Dostawa w weekend (sobota)" w prepare.php widoczny tylko dla supplier=INPOST + paczkomat (door_to_point=1 lub point_to_point=1) - JS toggle oparty na atrybutach data-supplier/data-paczkomat z resetem stanu - 3 nowe testy jednostkowe pokrywajace mapowanie buildOptionsPayload (phpunit OK 11/11) - Hotfix integracyjny po UAT: ShipmentController::create() nie przekazywal pola weekend_delivery z requestu do formData providera (root cause: reczna lista pol w controllerze) - Dokumentacja zaktualizowana (DOCS/ARCHITECTURE.md, DOCS/TECH_CHANGELOG.md) DEFER-104-01: rozwazyc test integracyjny pelnego flow controller -> service lub refactor na request->all(). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-17 09:03:44 +02:00
parent 3d61d3b2df
commit 567e888664
13 changed files with 538 additions and 12 deletions
--- a/.paul/phases/104-apaczka-weekend-delivery/104-01-PLAN.md
+++ b/.paul/phases/104-apaczka-weekend-delivery/104-01-PLAN.md
@@ -0,0 +1,210 @@
+---
+phase: 104-apaczka-weekend-delivery
+plan: 01
+type: execute
+wave: 1
+depends_on: []
+files_modified:
+  - src/Modules/Shipments/ApaczkaShipmentService.php
+  - resources/views/shipments/prepare.php
+  - tests/Unit/ApaczkaShipmentServiceTest.php
+  - DOCS/ARCHITECTURE.md
+  - DOCS/TECH_CHANGELOG.md
+autonomous: true
+delegation: auto
+---
+
+<objective>
+## Goal
+Dodac w formularzu przygotowania przesylki Apaczka opcjonalny checkbox "Dostawa w weekend (sobota)" dla uslug paczkomatowych InPost. Po zaznaczeniu wysylka tworzona przez API Apaczki dostaje opcje dodatkowa `option[19] = 1`, ktora wlacza usluge "Paczka w Weekend" (sobotnia dostawa do paczkomatu).
+
+## Purpose
+Operator chce miec mozliwosc wyboru dostawy w weekend dla zamowien paczkomatowych bez wchodzenia recznie na panel Apaczka. Funkcja jest dostepna w API Apaczki (option ID `19` = "dostawa w sobotę" wg `service_structure` / dokumentacji v2).
+
+## Output
+- Backend: ApaczkaShipmentService buduje pole `option` w payloadzie API gdy uzytkownik zaznaczyl weekend.
+- Frontend: prepare.php pokazuje checkbox tylko dla uslug Apaczki o supplier=INPOST i flagach paczkomatowych (door_to_point lub point_to_point).
+- Test jednostkowy potwierdza poprawne mapowanie pola formularza na klucz `option[19]` w payloadzie.
+- Aktualizacja DOCS/ARCHITECTURE.md i DOCS/TECH_CHANGELOG.md.
+</objective>
+
+<context>
+## Project Context
+@.paul/PROJECT.md
+@.paul/ROADMAP.md
+@.paul/STATE.md
+
+## Source Files
+@src/Modules/Shipments/ApaczkaShipmentService.php
+@resources/views/shipments/prepare.php
+@tests/Unit/ApaczkaShipmentServiceTest.php
+@src/Modules/Settings/ApaczkaApiClient.php
+
+## API Reference (Apaczka v2)
+- Endpoint: `POST https://www.apaczka.pl/api/v2/order_send/`
+- Payload `option`: tablica klucz=>1, gdzie klucze pochodza z `service_structure.response.options`.
+- Klucz `19` = "dostawa w sobote" (InPost Paczka w Weekend).
+- Cut-off InPost dla Paczki w Weekend: czwartek 20:00 - piatek 18:00. Jezeli API odrzuci request poza tym oknem, blad propagujemy do UI bez specjalnej obslugi.
+</context>
+
+<acceptance_criteria>
+
+## AC-1: Checkbox widoczny tylko dla paczkomatow Apaczka InPost
+```gherkin
+Given operator otwiera formularz `Przygotuj przesylke` dla zamowienia
+When wybiera przewoznika `Apaczka` i usluge o supplier=INPOST z flaga door_to_point=1 lub point_to_point=1
+Then widzi checkbox "Dostawa w weekend (sobota)" pod sekcja Apaczki
+And checkbox jest domyslnie odznaczony
+
+Given operator wybiera usluge Apaczki bez paczkomatu (np. kurier door-to-door)
+When przelacza usluge w selekcie
+Then checkbox "Dostawa w weekend" znika z UI i jego stan jest resetowany do `unchecked`
+```
+
+## AC-2: Zaznaczony checkbox dodaje option[19]=1 do payloadu API
+```gherkin
+Given formData zawiera `weekend_delivery=1` oraz wybrana usluge Apaczki paczkomatowej
+When ApaczkaShipmentService::createShipment buduje apiPayload
+Then payload zawiera klucz `option` => `[19 => 1]`
+And payload jest zapisany w `shipment_packages.payload_json`
+
+Given formData NIE zawiera `weekend_delivery` (lub `weekend_delivery=0`)
+When ApaczkaShipmentService::createShipment buduje apiPayload
+Then payload NIE zawiera klucza `option` (lub jest pusta tablica) — zachowanie identyczne z dzisiejszym
+```
+
+## AC-3: Test jednostkowy pokrywa mapowanie pola formularza
+```gherkin
+Given ApaczkaShipmentServiceTest wywoluje prywatna metode `buildOptionsPayload(array $formData)`
+When przekazuje `['weekend_delivery' => '1']`
+Then metoda zwraca `[19 => 1]`
+
+When przekazuje `['weekend_delivery' => '0']` lub `[]`
+Then metoda zwraca `[]`
+```
+
+</acceptance_criteria>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Backend — buildOptionsPayload + integracja z payloadem API</name>
+  <files>src/Modules/Shipments/ApaczkaShipmentService.php</files>
+  <action>
+    1. Dodac prywatna metode `buildOptionsPayload(array $formData): array` zwracajaca tablice opcji do `option` w payloadzie API.
+       - Akceptowane wejscie: `weekend_delivery` (string '0'/'1' lub bool) — kiedy truthy, dodaj `19 => 1`.
+       - Metoda ma byc rozszerzalna — pojedyncza tablica mapowania `'weekend_delivery' => 19` w stale klasy `OPTION_KEYS`.
+       - Zwroc pusta tablice gdy nie ma zadnych aktywnych opcji.
+    2. W `createShipment()`:
+       - Po zbudowaniu `$apiPayload` (przed `pickup`) wywolaj `$options = $this->buildOptionsPayload($formData);`.
+       - Jezeli `$options !== []`, ustaw `$apiPayload['option'] = $options;`.
+       - NIE dodawaj klucza `option` gdy tablica jest pusta — kompatybilnosc z istniejacym payloadem.
+    3. Zachowac istniejace zachowanie dla pozostalych pol (insurance, COD, pickup) bez zmian.
+
+    Avoid: nie dodawac twardo `option[19] = 1` poza kontrolka uzytkownika; nie wprowadzac toggle'a tylko po stronie UI bez parowania z backendem.
+  </action>
+  <verify>
+    - PHP syntax: `php -l src/Modules/Shipments/ApaczkaShipmentService.php`
+    - Reflection: w testach widzialne sa nowe metody `buildOptionsPayload` i stala `OPTION_KEYS`.
+  </verify>
+  <done>AC-2 satisfied: payload zawiera `option[19]=1` tylko gdy weekend_delivery=1.</done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Frontend — checkbox "Dostawa w weekend" w prepare.php z toggle JS</name>
+  <files>resources/views/shipments/prepare.php</files>
+  <action>
+    1. W panelu `#shipment-apaczka-panel` (po `#shipment-apaczka-select`, przed zamknieciem panelu Apaczki) dodac blok:
+       ```html
+       <div id="shipment-apaczka-weekend-wrap" class="mt-2" style="display:none">
+         <label class="checkbox-inline">
+           <input type="checkbox" name="weekend_delivery" id="shipment-apaczka-weekend" value="1">
+           Dostawa w weekend (sobota)
+         </label>
+         <div class="muted" style="font-size:12px">Dostepne dla paczkomatow InPost. Etykiety mozna generowac od czwartku 20:00 do piatku 18:00.</div>
+       </div>
+       ```
+    2. W petli `<?php foreach ($apaczkaSvcList as $aSvc): ?>` dodac do `<option>` dwa atrybuty data:
+       - `data-supplier="<?= $e(strtoupper(trim((string) ($aSvc['supplier'] ?? '')))) ?>"`
+       - `data-paczkomat="<?= ((int)($aSvc['door_to_point'] ?? 0) === 1 || (int)($aSvc['point_to_point'] ?? 0) === 1) ? '1' : '0' ?>"`
+    3. W bloku JS `if (apaczkaSelect)` po zakonczeniu funkcji `syncApaczkaFields` dodac kontrole widocznosci checkboxa:
+       - Pobrac `var weekendWrap = document.getElementById('shipment-apaczka-weekend-wrap');` i `var weekendInput = document.getElementById('shipment-apaczka-weekend');`.
+       - Stworzyc funkcje `toggleWeekendOption()` ktora czyta `data-supplier` i `data-paczkomat` z aktualnie wybranego `<option>`. Pokazuje wrap gdy `supplier === 'INPOST' && paczkomat === '1'`. W przeciwnym wypadku ukrywa wrap i ustawia `weekendInput.checked = false`.
+       - Wywolac `toggleWeekendOption()` po kazdej zmianie selektu Apaczki (`apaczkaSelect.addEventListener('change', toggleWeekendOption)`) oraz po zmianie przewoznika (w istniejacym `carrierSelect.addEventListener('change', ...)` dodac wywolanie po reset).
+       - Wywolac toggle takze przy starcie skryptu (`toggleWeekendOption();`) zeby wlasciwie obsluzyc preselekcje.
+    4. Upewnic sie, ze przy przelaczeniu na innego przewoznika `weekendInput.checked = false`.
+
+    Avoid: stylow inline w widoku poza minimum (`display:none` na wrapperze) — pelne style kompaktowe i tak juz istnieja w SCSS dla `checkbox-inline`. Nie duplikuj wspolnych komponentow.
+  </action>
+  <verify>
+    - Otworzyc `/orders/{id}/prepare`, wybrac Apaczke i usluge paczkomatowa InPost — checkbox widoczny.
+    - Przelaczyc na usluge kurierska — checkbox znika i jest odznaczony.
+    - Przelaczyc na innego przewoznika (Allegro/InPost) — checkbox niewidoczny.
+  </verify>
+  <done>AC-1 satisfied: checkbox pojawia sie tylko dla Apaczka+InPost+paczkomat.</done>
+</task>
+
+<task type="auto">
+  <name>Task 3: Test jednostkowy buildOptionsPayload + dokumentacja</name>
+  <files>tests/Unit/ApaczkaShipmentServiceTest.php, DOCS/ARCHITECTURE.md, DOCS/TECH_CHANGELOG.md</files>
+  <action>
+    1. W `tests/Unit/ApaczkaShipmentServiceTest.php`:
+       - Dodac prywatny helper `invokeBuildOptions(array $formData): array` analogiczny do `invokeTruncate` (ReflectionMethod na `buildOptionsPayload`, accessible).
+       - Dodac trzy testy:
+         - `testBuildOptionsPayloadWeekendEnabled` — `['weekend_delivery' => '1']` zwraca `[19 => 1]`.
+         - `testBuildOptionsPayloadWeekendDisabled` — `['weekend_delivery' => '0']` zwraca `[]`.
+         - `testBuildOptionsPayloadEmptyForm` — `[]` zwraca `[]`.
+    2. W `DOCS/ARCHITECTURE.md` zaktualizowac sekcje opisujaca `App\Modules\Shipments\ApaczkaShipmentService` (lub dodac nowy wpis):
+       - Wymienic nowa metode `buildOptionsPayload`.
+       - Opisac, ze pole `weekend_delivery` w formularzu mapuje na `option[19]` w payloadzie API Apaczki.
+    3. W `DOCS/TECH_CHANGELOG.md` dopisac wpis na koncu z dzisiejsza data:
+       - Tytul: `Apaczka weekend delivery option`.
+       - Tresc: krotki opis (1-3 zdania) o nowym checkboxie i mapowaniu na option[19].
+
+    Avoid: zmieniania istniejacych testow `truncateStreetForPoint` / `assertStreetWithinCourierLimit` — nowe testy dodawane na koncu klasy.
+  </action>
+  <verify>
+    - `php vendor/bin/phpunit --filter ApaczkaShipmentServiceTest` — wszystkie testy zielone.
+    - `git diff --stat DOCS/` pokazuje 2 pliki zmienione (ARCHITECTURE.md, TECH_CHANGELOG.md).
+  </verify>
+  <done>AC-3 satisfied: testy potwierdzaja mapowanie + dokumentacja zaktualizowana.</done>
+</task>
+
+</tasks>
+
+<boundaries>
+
+## DO NOT CHANGE
+- `ApaczkaApiClient.php` — komunikacja z API juz wspiera dowolny payload `order`, nie wymaga zmian.
+- `ShipmentPackageRepository.php` — schema `payload_json` przyjmie nowe pole bez migracji.
+- Logika pickup/COD/insurance w `ApaczkaShipmentService::createShipment` — nie modyfikujemy.
+- Mapowania presetow przesylek (`shipment_presets`) — pozostaja bez zmian; weekend_delivery jest swiadomym wyborem operatora przed wyslaniem.
+
+## SCOPE LIMITS
+- Brak osobnej kolumny w `shipment_packages` na flage weekendu — zapisujemy tylko w `payload_json` (debug + powtarzalnosc).
+- Brak walidacji okna czasowego (czwartek 20:00 - piatek 18:00) po stronie aplikacji — zaufanie do API Apaczki/InPost.
+- Brak nowej kolumny w bazie / migracji.
+- Brak rozszerzenia presetow przesylek o ta opcje (mozliwa kolejna faza).
+- Brak aktywacji checkboxa dla innych supplierow (UPS/POCZTA) — tylko InPost wg dokumentacji "Paczka w Weekend".
+</boundaries>
+
+<verification>
+Before declaring plan complete:
+- [ ] `php -l src/Modules/Shipments/ApaczkaShipmentService.php` zwraca `No syntax errors detected`.
+- [ ] `php vendor/bin/phpunit --filter ApaczkaShipmentServiceTest` przechodzi (5+ testow).
+- [ ] Manualne UAT: utworzenie przesylki Apaczka InPost paczkomat z zaznaczonym checkboxem — payload w `shipment_packages.payload_json` zawiera `"option":{"19":1}`.
+- [ ] Manualne UAT: utworzenie tej samej przesylki bez checkboxa — payload bez klucza `option`.
+- [ ] Wszystkie acceptance criteria spelnione.
+</verification>
+
+<success_criteria>
+- Checkbox "Dostawa w weekend (sobota)" widoczny dla uslug Apaczki o supplier=INPOST i fladze paczkomatowej.
+- Backend mapuje `weekend_delivery=1` na `option[19] = 1` w payloadzie API.
+- Testy jednostkowe potwierdzaja mapowanie i braku regresji.
+- Dokumentacja (DOCS/ARCHITECTURE.md, DOCS/TECH_CHANGELOG.md) zaktualizowana.
+- Zero zmian w bazie danych ani API klienta.
+</success_criteria>
+
+<output>
+After completion, create `.paul/phases/104-apaczka-weekend-delivery/104-01-SUMMARY.md`
+</output>
--- a/.paul/phases/104-apaczka-weekend-delivery/104-01-SUMMARY.md
+++ b/.paul/phases/104-apaczka-weekend-delivery/104-01-SUMMARY.md
@@ -0,0 +1,150 @@
+---
+phase: 104-apaczka-weekend-delivery
+plan: 01
+subsystem: shipments
+tags: [apaczka, inpost, paczkomat, weekend-delivery, php, shipment-form]
+
+requires:
+  - phase: 102-apaczka-receiver-street-length
+    provides: stabilna obsluga uslug paczkomatowych Apaczki (truncate/assert dla street)
+provides:
+  - checkbox "Dostawa w weekend (sobota)" w formularzu prepare.php dla Apaczki+InPost paczkomat
+  - mapowanie pole formularza weekend_delivery -> option[19] = 1 w payloadzie API Apaczki
+  - prywatna metoda ApaczkaShipmentService::buildOptionsPayload + stala OPTION_KEYS
+affects: [presety przesylek, automatyzacja shipment.created, kolejne opcje API Apaczki]
+
+tech-stack:
+  added: []
+  patterns:
+    - "Stala OPTION_KEYS jako mapa pole_formularza => api_option_id (rozszerzalne)"
+    - "buildOptionsPayload(array $formData): array — pojedyncza odpowiedzialnosc, filter_var FILTER_VALIDATE_BOOL"
+
+key-files:
+  created: []
+  modified:
+    - src/Modules/Shipments/ApaczkaShipmentService.php
+    - src/Modules/Shipments/ShipmentController.php
+    - resources/views/shipments/prepare.php
+    - tests/Unit/ApaczkaShipmentServiceTest.php
+    - DOCS/ARCHITECTURE.md
+    - DOCS/TECH_CHANGELOG.md
+
+key-decisions:
+  - "Klucz API Apaczki dla soboty to staly numer 19 (z service_structure.options); zaszyty w stalej OPTION_KEYS"
+  - "Brak walidacji okna czasowego Paczki w Weekend (czw 20:00 - pt 18:00) po stronie aplikacji — zaufanie do API"
+  - "Brak osobnej kolumny w shipment_packages — flaga zapisywana wylacznie w payload_json"
+  - "Checkbox widoczny tylko dla supplier=INPOST i paczkomat (door_to_point=1 lub point_to_point=1) — minimalizacja blednych aktywacji"
+
+patterns-established:
+  - "Rozszerzalne mapowanie pole formularza -> id opcji Apaczki w prywatnej stalej (kolejne opcje to 1 linia w OPTION_KEYS)"
+  - "Frontend toggle JS na podstawie data-* atrybutow z <option> selektu uslug (data-supplier, data-paczkomat)"
+
+duration: ~35min
+started: 2026-04-17T00:00:00Z
+completed: 2026-04-17T00:35:00Z
+---
+
+# Phase 104 Plan 01: Apaczka Weekend Delivery Summary
+
+**Dodano opcjonalna usluge "Paczka w Weekend" dla przesylek Apaczki paczkomatowych InPost — checkbox w formularzu mapowany na `option[19]=1` w payloadzie `order_send` API Apaczki v2.**
+
+## Performance
+
+| Metric | Value |
+|--------|-------|
+| Duration | ~35min |
+| Started | 2026-04-17T00:00:00Z |
+| Completed | 2026-04-17T00:35:00Z |
+| Tasks | 3/3 completed |
+| Files modified | 5 |
+
+## Acceptance Criteria Results
+
+| Criterion | Status | Notes |
+|-----------|--------|-------|
+| AC-1: Checkbox widoczny tylko dla paczkomatow Apaczka InPost | Pass | Toggle JS sprawdza `data-supplier=INPOST` + `data-paczkomat=1`; reset stanu przy zmianie uslugi/przewoznika |
+| AC-2: Zaznaczony checkbox dodaje option[19]=1 do payloadu | Pass | `createShipment` warunkowo wstrzykuje `$apiPayload['option']` tylko gdy tablica niepusta; brak regresji dla scenariusza bez opcji |
+| AC-3: Test jednostkowy pokrywa mapowanie pola formularza | Pass | 3 nowe testy (`testBuildOptionsPayloadWeekendEnabled/Disabled/EmptyForm`) zielone |
+
+## Accomplishments
+
+- Operator moze wlaczac dostawe w weekend dla Apaczki InPost paczkomat bez wchodzenia recznie na panel apaczka.pl.
+- Backend i frontend skonsolidowane wokol jednego kontraktu (`weekend_delivery` -> `option[19]`), z testami pokrywajacymi mapping.
+- Wzorzec `OPTION_KEYS` przygotowuje grunt pod kolejne opcje Apaczki (np. `25` = dostawa w godzinach, `58` = ostroznie, `31` = SMS) — przyszle dodanie to 1 linia w stalej + 1 wpis w UI.
+
+## Task Commits
+
+| Task | Commit | Type | Description |
+|------|--------|------|-------------|
+| Task 1: Backend buildOptionsPayload + integracja w createShipment | (pending phase commit) | feat | Stala OPTION_KEYS + metoda + warunkowe `option` w payloadzie |
+| Task 2: Frontend checkbox "Dostawa w weekend" + toggle JS | (pending phase commit) | feat | HTML checkbox, data-* atrybuty na <option>, JS toggleWeekendOption |
+| Task 3: Testy jednostkowe + dokumentacja | (pending phase commit) | test+docs | 3 testy PHPUnit, ARCHITECTURE.md, TECH_CHANGELOG.md |
+
+Atomowe commity per task pominiete — zmiany trafia w pojedynczym commicie fazowym `feat(104-apaczka-weekend-delivery): ...` w transition-phase.
+
+## Files Created/Modified
+
+| File | Change | Purpose |
+|------|--------|---------|
+| `src/Modules/Shipments/ApaczkaShipmentService.php` | Modified (+31) | Stala `OPTION_KEYS`, metoda `buildOptionsPayload`, integracja w `createShipment` |
+| `src/Modules/Shipments/ShipmentController.php` | Modified (+1, hotfix) | Przekazanie pola `weekend_delivery` z requestu do `formData` providera |
+| `resources/views/shipments/prepare.php` | Modified (+31) | Checkbox `weekend_delivery`, atrybuty data-* na <option>, JS toggle |
+| `tests/Unit/ApaczkaShipmentServiceTest.php` | Modified (+29) | Helper `invokeBuildOptions` + 3 nowe testy |
+| `DOCS/ARCHITECTURE.md` | Modified (+1) | Wpis o `buildOptionsPayload` w sekcji `POST /orders/{id}/shipment/create` |
+| `DOCS/TECH_CHANGELOG.md` | Modified (+8) | Wpis Phase 104 z opisem zmian, mapowania i testow |
+
+## Decisions Made
+
+| Decision | Rationale | Impact |
+|----------|-----------|--------|
+| Stale id opcji `19` zaszyte w stalej PHP (nie pobierane dynamicznie z service_structure) | Apaczka traktuje numery opcji jako kontrakt API; dynamiczne wyszukiwanie po nazwie byloby krucha (lokalizacja, slowotworstwo). Stala = jasny kontrakt | Przy ewentualnej zmianie ID po stronie API — jedno miejsce do aktualizacji |
+| Brak walidacji okna "Paczka w Weekend" (czw 20:00 - pt 18:00) | API Apaczki/InPost zwraca jasny blad poza tym oknem; replikacja logiki po stronie klienta = ryzyko driftu | Operator widzi blad z API; brak false-positive blokady |
+| Checkbox tylko dla supplier=INPOST | Dokumentacja Apaczki "Paczka w Weekend" wskazuje InPost jako jedynego supplera; UPS/POCZTA nie maja tej uslugi | Inne suppliery nie zobacza checkboxa |
+| Brak rozszerzenia presetow przesylek o flage weekendu | Decyzja swiadoma — operator wlacza weekend swiadomie per-przesylke; preset moglby utrwalic kosztowniejsza opcje | Mozliwa kolejna faza (preset advanced options) |
+
+## Deviations from Plan
+
+### Summary
+
+| Type | Count | Impact |
+|------|-------|--------|
+| Auto-fixed | 1 | Hotfix integracyjny w ShipmentController (UAT wykryl, ze checkbox nie skutkowal) |
+| Scope additions | 0 | n/a |
+| Deferred | 1 | Test integracyjny pelnego flow (controller -> service) — logged below |
+
+**Total impact:** Plan dostarczyl wartosc; bug integracyjny wykryty podczas UAT i zalataniem 1-linii.
+
+### Auto-fixed Issues
+
+**1. [Integration bug] Pole weekend_delivery nie bylo przekazywane z requestu do formData providera**
+- **Found during:** UAT po zamknieciu plan-loop (operator zaznaczyl checkbox, etykieta wygenerowana bez option[19])
+- **Issue:** `ShipmentController::create()` (linie 182-207) buduje `$formData` poprzez recznie wymieniona liste pol z requestu. Nowe pole `weekend_delivery` nie zostalo dodane do listy, wiec `ApaczkaShipmentService::buildOptionsPayload()` dostawal tablice bez tego klucza i zwracal pusta tablice opcji.
+- **Fix:** Dodano linie 207: `'weekend_delivery' => (string) $request->input('weekend_delivery', '')`.
+- **Files:** `src/Modules/Shipments/ShipmentController.php` (+1)
+- **Verification:** Operator powtorzyl UAT z UI po fixie — przesylka utworzona z opcja Paczka w Weekend.
+- **Root cause planu:** Test jednostkowy `ApaczkaShipmentServiceTest::testBuildOptionsPayload*` testowal metode przez Reflection (omijajac kontroler). Plan 104-01 nie wymagal testu integracyjnego pelnego flow.
+
+### Deferred Items
+
+- **DEFER-104-01:** Brak testu integracyjnego pokrywajacego pelny flow `ShipmentController::create()` → `ApaczkaShipmentService::createShipment()`. Aktualne testy jednostkowe nie zlapalyby brakujacego pola w formData. Mozliwe rozwiazania: (a) refactor `ShipmentController::create()` na przekazywanie `$request->all()` zamiast recznej listy pol (eliminuje cala klase bugow); (b) test integracyjny z mock'owanym `ProviderRegistry`. Sugerowana ewentualna kolejna faza housekeeping.
+
+## Issues Encountered
+
+| Issue | Resolution |
+|-------|------------|
+| TECH_CHANGELOG.md ma konwencje newest-at-top, ale plan instruowal "na koncu pliku" | Zastosowano explicit instrukcje planu (na koncu pliku); konwencja moze byc znormalizowana w przyszlej fazie housekeeping |
+
+## Next Phase Readiness
+
+**Ready:**
+- Wzorzec `OPTION_KEYS` gotowy do rozszerzenia o kolejne opcje Apaczki (25=dostawa w godzinach, 58=ostroznie, 31=SMS, 11=ROD).
+- Frontend toggle JS oparty na `data-supplier`/`data-paczkomat` mozna powtorzyc dla innych przewoznikow.
+
+**Concerns:**
+- Dokumentacja Apaczka API v2 nie precyzuje na poziomie service_structure jakie opcje sa dostepne dla konkretnej uslugi — w razie wprowadzenia kolejnych opcji warto rozwazyc walidacje przy wyborze uslugi.
+
+**Blockers:** None
+
+---
+*Phase: 104-apaczka-weekend-delivery, Plan: 01*
+*Completed: 2026-04-17*