orderPRO/.paul/phases/69-allegro-tracking-english-statuses/69-01-PLAN.md

phase, plan, type, wave, depends_on, files_modified, autonomous

phase	plan	type	wave	depends_on	files_modified	autonomous
69-allegro-tracking-english-statuses	01	execute	1		src/Modules/Shipments/DeliveryStatus.php src/Modules/Shipments/AllegroTrackingService.php tests/Unit/DeliveryStatusTest.php DOCS/DB_SCHEMA.md DOCS/ARCHITECTURE.md DOCS/TECH_CHANGELOG.md	true

## Goal Naprawic normalizacje statusow Allegro Delivery z edge API, aby angielskie opisy (np. `Parcel is awaiting pick-up`, `Parcel has been delivered`) nie konczyly jako `unknown`.

Purpose

Status dostawy w orderPRO musi byc wiarygodny dla obslugi zamowien i automatyzacji. Obecny fallback obsluguje glownie opisy PL i gubi realne statusy EN.

Output

• Rozszerzone mapowanie/fallback statusow w DeliveryStatus dla opisow EN z Allegro edge API.
• Lekki test jednostkowy dla normalizacji i fallbacku opisow Allegro.
• Aktualizacja dokumentacji technicznej (schema/architektura/changelog) po wdrozeniu hotfixu.

## Project Context @.paul/PROJECT.md @.paul/ROADMAP.md @.paul/STATE.md

Prior Work

@.paul/phases/66-allegro-delivery-tracking/66-01-SUMMARY.md @.paul/phases/66-allegro-delivery-tracking/66-02-SUMMARY.md

Source Files

@src/Modules/Shipments/DeliveryStatus.php @src/Modules/Shipments/AllegroTrackingService.php @src/Modules/Cron/ShipmentTrackingHandler.php @DOCS/DB_SCHEMA.md @DOCS/ARCHITECTURE.md @DOCS/TECH_CHANGELOG.md

## Required Skills (from SPECIAL-FLOWS.md)

Skill	Priority	When to Invoke	Loaded?
sonar-scanner	required	Po APPLY, przed UNIFY	o
/feature-dev	optional	Implementacja hotfixu trackingu	o
/code-review	optional	Przed UNIFY	o

BLOCKING: Required skills MUST be loaded before APPLY proceeds.

Skill Invocation Checklist

• sonar-scanner uruchomiony po APPLY
• (opcjonalnie) /feature-dev
• (opcjonalnie) /code-review

<acceptance_criteria>

AC-1: Angielskie statusy Allegro nie wracaja jako unknown

Given paczka `allegro_wza` otrzymuje z edge API opis po angielsku
When `AllegroTrackingService::fetchAllegroEdgeStatus()` normalizuje status
Then wynik `status` jest rozpoznany (np. `ready_for_pickup`, `delivered`)
And nie jest `unknown` dla znanych opisow EN

AC-2: Fallback nadal dziala dla opisow dotychczasowych

Given opisy statusow z mapy/sluga istniejacej w systemie (PL i dotychczasowe warianty)
When status jest normalizowany przez `DeliveryStatus`
Then wynik pozostaje zgodny z aktualnym kontraktem statusow
And nie ma regresji dla inpost/apaczka/allegro_wza

AC-3: Dokumentacja techniczna odzwierciedla hotfix

Given wdrozenie zmiany mapowania statusow Allegro edge
When aktualizacja kodu jest zakonczona
Then `DOCS/DB_SCHEMA.md`, `DOCS/ARCHITECTURE.md` i `DOCS/TECH_CHANGELOG.md` zawieraja wpis o tej zmianie
And wpisy jasno opisuja brak zmian schematu DB

</acceptance_criteria>

Task 1: Rozszerzyc normalizacje statusow EN dla Allegro edge src/Modules/Shipments/DeliveryStatus.php, src/Modules/Shipments/AllegroTrackingService.php Zaktualizuj `DeliveryStatus` tak, aby opisy EN z Allegro edge (w tym `Parcel is awaiting pick-up`, `Parcel has been delivered`) byly mapowane do statusow biznesowych. Dopuszczalne podejscia: rozszerzenie mapy slugow EN, poprawa `guessStatusFromDescription()` dla EN, lub oba. Zachowaj obecny kontrakt zwracanych statusow (`unknown|created|...`), bez zmiany interfejsu serwisu trackingu. Unikaj zmian w logice crona i bazie danych - to hotfix normalizacji. Manual check: uruchomic `DeliveryStatus::slugify/normalize/guess` dla statusow EN oraz sprawdzic, ze `Parcel is awaiting pick-up` -> `ready_for_pickup`, `Parcel has been delivered` -> `delivered`. AC-1 satisfied, AC-2 satisfied Task 2: Dodac test jednostkowy dla mapowania Allegro edge tests/Unit/DeliveryStatusTest.php Dodaj testy jednostkowe obejmujace co najmniej: - slug+normalize dla opisu EN z Allegro edge, - fallback `guessStatusFromDescription()` dla EN, - zachowanie bez regresji dla przykladowego statusu PL lub istniejacego sluga. Test ma byc szybki, bez dostepu do sieci i bez zaleznosci od bazy. `C:\\xampp\\php\\php.exe vendor\\bin\\phpunit --filter DeliveryStatusTest` przechodzi. AC-1 satisfied, AC-2 satisfied Task 3: Zaktualizowac dokumentacje techniczna po hotfixie DOCS/DB_SCHEMA.md, DOCS/ARCHITECTURE.md, DOCS/TECH_CHANGELOG.md Dodaj wpisy opisujace hotfix mapowania statusow Allegro edge (EN -> statusy biznesowe). W DB schema zaznacz jednoznacznie, ze zmiana nie modyfikuje tabel/kolumn/indeksow. W architekturze dopisz, jak dziala fallback EN w `DeliveryStatus`. W changelogu opisz co i dlaczego zostalo poprawione. Przeglad diffu dokumentacji: wszystkie 3 pliki zaktualizowane, opisy spojne z implementacja. AC-3 satisfied

DO NOT CHANGE

• database/migrations/* (brak zmian schematu)
• routing HTTP i kontrolery zamowien
• interfejsy API providerow wysylek poza normalizacja statusow Allegro edge

SCOPE LIMITS

• Zakres planu dotyczy tylko problemu statusow unknown dla opisow EN Allegro edge.
• Plan nie obejmuje cleanupu starych rekordow cron_jobs ze statusem processing.
• Plan nie obejmuje zmian UI poza efektem widocznego statusu po poprawnej normalizacji.

Before declaring plan complete: - [ ] `php -l` przechodzi dla zmienionych plikow PHP - [ ] `vendor/bin/phpunit --filter DeliveryStatusTest` przechodzi - [ ] Re-run diagnostyki na numerze `A0046XFMG1` zwraca status rozpoznany (nie `unknown`) - [ ] Dokumentacja (`DB_SCHEMA`, `ARCHITECTURE`, `TECH_CHANGELOG`) zaktualizowana - [ ] Wszystkie acceptance criteria spelnione

<success_criteria>

• Parcel is awaiting pick-up mapuje sie do ready_for_pickup
• Parcel has been delivered mapuje sie do delivered
• Brak regresji dla dotychczasowego flow normalizacji statusow
• Test jednostkowy dla normalizacji/fallbacku istnieje i przechodzi
• Dokumentacja techniczna jest aktualna </success_criteria>

After completion, create `.paul/phases/69-allegro-tracking-english-statuses/69-01-SUMMARY.md`