orderPRO/.paul/phases/104-apaczka-weekend-delivery/104-01-SUMMARY.md

---
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*