---
phase: 69-allegro-tracking-english-statuses
plan: 01
type: execute
wave: 1
depends_on: []
files_modified:
- 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
autonomous: 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`
## AC-1: Angielskie statusy Allegro nie wracaja jako unknown
```gherkin
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
```gherkin
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
```gherkin
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
```
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
- `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