update

2026-04-04 18:20:13 +02:00
parent e95c4967d2
commit 7feda58a97
18 changed files with 845 additions and 325 deletions
--- a/.paul/phases/69-allegro-tracking-english-statuses/69-01-PLAN.md
+++ b/.paul/phases/69-allegro-tracking-english-statuses/69-01-PLAN.md
@@ -0,0 +1,172 @@
+---
+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>
--- a/.paul/phases/69-allegro-tracking-english-statuses/69-01-SUMMARY.md
+++ b/.paul/phases/69-allegro-tracking-english-statuses/69-01-SUMMARY.md
@@ -0,0 +1,48 @@
+---
+phase: 69-allegro-tracking-english-statuses
+plan: 01
+subsystem: shipments
+tags: [allegro, tracking, edge-api, status-mapping, hotfix]
+
+requires:
+  - phase: 66-allegro-delivery-tracking
+    provides: AllegroTrackingService edge API flow
+
+provides:
+  - EN status mapping for Allegro edge descriptions
+  - EN keyword fallback in DeliveryStatus guesser
+  - Unit tests for DeliveryStatus EN/PL normalization
+
+affects: [allegro-tracking, delivery-status, docs]
+
+key-files:
+  modified:
+    - src/Modules/Shipments/DeliveryStatus.php
+    - DOCS/DB_SCHEMA.md
+    - DOCS/ARCHITECTURE.md
+    - DOCS/TECH_CHANGELOG.md
+  created:
+    - tests/Unit/DeliveryStatusTest.php
+---
+
+# Phase 69 Plan 01: Allegro Tracking English Statuses
+
+Naprawiono przypadki, w ktorych statusy Allegro edge API w jezyku angielskim byly zapisywane jako `unknown`.
+
+## Outcome
+- `DeliveryStatus::slugifyAllegroDescription()` obsluguje prefiksy EN (`Parcel has been ...`, `Parcel is ...`, `Courier has ...`).
+- `ALLEGRO_EDGE_MAP` rozszerzono o slugi EN (m.in. `awaiting_pick_up`, `delivered`, `dispatched`, `released_for_delivery`).
+- `guessStatusFromDescription()` rozszerzono o fallback EN.
+- Dodano testy jednostkowe `DeliveryStatusTest` (4 testy, 7 asercji).
+
+## Verification
+- `php -l src/Modules/Shipments/DeliveryStatus.php` -> OK.
+- `phpunit --filter DeliveryStatusTest` -> OK (4/4).
+- Realny numer `A0046XFMG1`:
+  - `description=Parcel is awaiting pick-up`
+  - `slug=awaiting_pick_up`
+  - `normalized=ready_for_pickup`
+
+## Notes
+- Zmiana nie wymaga migracji DB.
+- Zaktualizowano dokumentacje techniczna (`DB_SCHEMA`, `ARCHITECTURE`, `TECH_CHANGELOG`).