Project-Pro/orderPRO
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
567e888664552ef9156a913ead4dd4c4d831abf0
orderPRO/.paul/phases/104-apaczka-weekend-delivery/104-01-SUMMARY.md
Jacek Pyziak 567e888664 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

8.7 KiB
Raw Blame History

phase, plan, subsystem, tags, requires, provides, affects, tech-stack, key-files, key-decisions, patterns-established, duration, started, completed
phase plan subsystem tags requires provides affects tech-stack key-files key-decisions patterns-established duration started completed
104-apaczka-weekend-delivery 01 shipments
apaczka
inpost
paczkomat
weekend-delivery
php
shipment-form
phase provides
102-apaczka-receiver-street-length stabilna obsluga uslug paczkomatowych Apaczki (truncate/assert dla street)
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
presety przesylek
automatyzacja shipment.created
kolejne opcje API Apaczki
added patterns
Stala OPTION_KEYS jako mapa pole_formularza => api_option_id (rozszerzalne)
buildOptionsPayload(array $formData): array — pojedyncza odpowiedzialnosc, filter_var FILTER_VALIDATE_BOOL
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
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
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)
~35min 2026-04-17T00:00:00Z 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 , 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 , 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

Reference in New Issue View Git Blame Copy Permalink