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

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

<objective>
## 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.
</objective>

<context>
## 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
</context>

<skills>
## 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`

</skills>

<acceptance_criteria>

## 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
```

</acceptance_criteria>

<tasks>

<task type="auto">
  <name>Task 1: Rozszerzyc normalizacje statusow EN dla Allegro edge</name>
  <files>src/Modules/Shipments/DeliveryStatus.php, src/Modules/Shipments/AllegroTrackingService.php</files>
  <action>
    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.
  </action>
  <verify>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`.</verify>
  <done>AC-1 satisfied, AC-2 satisfied</done>
</task>

<task type="auto">
  <name>Task 2: Dodac test jednostkowy dla mapowania Allegro edge</name>
  <files>tests/Unit/DeliveryStatusTest.php</files>
  <action>
    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.
  </action>
  <verify>`C:\\xampp\\php\\php.exe vendor\\bin\\phpunit --filter DeliveryStatusTest` przechodzi.</verify>
  <done>AC-1 satisfied, AC-2 satisfied</done>
</task>

<task type="auto">
  <name>Task 3: Zaktualizowac dokumentacje techniczna po hotfixie</name>
  <files>DOCS/DB_SCHEMA.md, DOCS/ARCHITECTURE.md, DOCS/TECH_CHANGELOG.md</files>
  <action>
    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.
  </action>
  <verify>Przeglad diffu dokumentacji: wszystkie 3 pliki zaktualizowane, opisy spojne z implementacja.</verify>
  <done>AC-3 satisfied</done>
</task>

</tasks>

<boundaries>

## 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.

</boundaries>

<verification>
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
</verification>

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

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