Jacek Pyziak
98a0077204
- Kolorowe badge'e statusow dostawy w tabelach paczek (show.php + prepare.php) - Link sledzenia z carrier detection (InPost, Apaczka, Orlen, Allegro, Google fallback) - Sekcja Status dostawy w boksie Platnosc i wysylka - Ustawienie interwalu trackingu crona (5-120 min) w zakladce Ustawienia - Tekstowe mapowania statusow Apaczka API (NEW, CONFIRMED, etc.) - Fix: use-statements ApaczkaShipmentService (pre-existing bug) - Fix: pickup date normalization (next day po 16:00) - Fix: przycisk Pobierz etykiete (POST zamiast link do prepare) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
186 lines
7.8 KiB
Markdown
186 lines
7.8 KiB
Markdown
---
|
||
phase: 28-shipment-tracking-ui
|
||
plan: 01
|
||
subsystem: ui
|
||
tags: [delivery-status, tracking, badges, cron-settings, scss]
|
||
|
||
requires:
|
||
- phase: 27-shipment-tracking-backend
|
||
provides: delivery_status columns, DeliveryStatus class, ShipmentTrackingHandler cron
|
||
|
||
provides:
|
||
- Kolorowe badge'e statusów dostawy w UI (show.php + prepare.php)
|
||
- Link śledzenia przesyłki z carrier detection + Google fallback
|
||
- Sekcja "Status dostawy" w boksie Płatność i wysyłka
|
||
- Ustawienie interwału trackingu w UI crona (zakładka Ustawienia)
|
||
- Tekstowe mapowania statusów Apaczka API (NEW, CONFIRMED, etc.)
|
||
|
||
affects: []
|
||
|
||
tech-stack:
|
||
added: []
|
||
patterns:
|
||
- "content-tabs-nav pattern reused w cron.php (z allegro.php)"
|
||
- "Dual text+numeric status mapping w APACZKA_MAP"
|
||
|
||
key-files:
|
||
created:
|
||
- resources/scss/modules/_delivery-status.scss
|
||
modified:
|
||
- src/Modules/Shipments/DeliveryStatus.php
|
||
- src/Modules/Shipments/ApaczkaShipmentService.php
|
||
- src/Modules/Shipments/ShipmentPackageRepository.php
|
||
- src/Modules/Settings/CronSettingsController.php
|
||
- src/Modules/Cron/CronRepository.php
|
||
- resources/views/orders/show.php
|
||
- resources/views/shipments/prepare.php
|
||
- resources/views/settings/cron.php
|
||
- resources/scss/app.scss
|
||
- public/assets/css/app.css
|
||
|
||
key-decisions:
|
||
- "Google search jako fallback tracking URL gdy carrier nieznany"
|
||
- "carrier_delivery_method_mappings jako źródło carrier_id (nie pattern matching)"
|
||
- "Tekstowe mapowania Apaczka (API zwraca NEW/CONFIRMED, nie 0/1)"
|
||
- "Przesunięcie pickup na next day gdy po 16:00 (Apaczka API limit)"
|
||
- "Cron settings jako osobna zakładka (content-tabs-nav pattern)"
|
||
|
||
patterns-established:
|
||
- "Dual status mapping: numeryczne + tekstowe klucze w tej samej mapie"
|
||
|
||
duration: ~3h (z bugfixami)
|
||
started: 2026-03-23T19:00:00Z
|
||
completed: 2026-03-23T23:30:00Z
|
||
---
|
||
|
||
# Phase 28 Plan 01: Shipment Tracking UI + Settings Summary
|
||
|
||
**Badge'e statusów dostawy w UI, linki śledzenia z carrier detection, ustawienie interwału trackingu w cronie z zakładkowym layoutem.**
|
||
|
||
## Performance
|
||
|
||
| Metric | Value |
|
||
|--------|-------|
|
||
| Duration | ~3h (z bugfixami) |
|
||
| Started | 2026-03-23 19:00 |
|
||
| Completed | 2026-03-23 23:30 |
|
||
| Tasks | 3 completed + checkpoint |
|
||
| Files modified | 12 |
|
||
|
||
## Acceptance Criteria Results
|
||
|
||
| Criterion | Status | Notes |
|
||
|-----------|--------|-------|
|
||
| AC-1: Status dostawy w tabeli paczek (show.php) | Pass | Kolumna z badge + tooltip surowego statusu |
|
||
| AC-2: Status dostawy w tabeli paczek (prepare.php) | Pass | Analogicznie jak show.php |
|
||
| AC-3: Link śledzenia przesyłki | Pass | InPost, Apaczka, Orlen, Allegro + Google fallback |
|
||
| AC-4: Ustawienie interwału trackingu w cronie | Pass | Input 5–120 min w zakładce Ustawienia |
|
||
| AC-5: Info o śledzeniu w boksie Płatność i wysyłka | Pass | Badge + data ostatniej aktualizacji |
|
||
|
||
## Accomplishments
|
||
|
||
- Badge'e statusów dostawy z 10 kolorami, tooltip z surowym statusem API, link śledzenia z auto-detection przewoźnika
|
||
- Ustawienia crona przeorganizowane na zakładki (Ustawienia / Harmonogram), interwał trackingu konfigurowalny 5–120 min
|
||
- Naprawiono 7 bugów wykrytych podczas implementacji i testów
|
||
|
||
## Files Created/Modified
|
||
|
||
| File | Change | Purpose |
|
||
|------|--------|---------|
|
||
| `resources/scss/modules/_delivery-status.scss` | Created | Style badge'ów statusów dostawy (10 wariantów kolorystycznych) |
|
||
| `src/Modules/Shipments/DeliveryStatus.php` | Modified | trackingUrl() z carrier detection + Google fallback; tekstowe mapowania Apaczka |
|
||
| `src/Modules/Shipments/ApaczkaShipmentService.php` | Modified | Fix use-statements; pickup date normalization (next day po 16:00) |
|
||
| `src/Modules/Shipments/ShipmentPackageRepository.php` | Modified | resolveCarrierName() lookup z carrier_delivery_method_mappings |
|
||
| `src/Modules/Settings/CronSettingsController.php` | Modified | Przekazuje/zapisuje trackingIntervalMinutes |
|
||
| `src/Modules/Cron/CronRepository.php` | Modified | updateScheduleInterval() + getScheduleInterval() |
|
||
| `resources/views/orders/show.php` | Modified | Kolumna Status dostawy, badge, link, fix Pobierz etykietę |
|
||
| `resources/views/shipments/prepare.php` | Modified | Kolumna Status dostawy, badge, link |
|
||
| `resources/views/settings/cron.php` | Modified | Zakładki Ustawienia/Harmonogram; sekcja śledzenia przesyłek |
|
||
| `resources/scss/app.scss` | Modified | @use delivery-status |
|
||
| `public/assets/css/app.css` | Modified | Rebuilt z nowym SCSS |
|
||
| `database/migrations/20260323_000060_*` | Modified | Fix initial status values |
|
||
|
||
## Decisions Made
|
||
|
||
| Decision | Rationale | Impact |
|
||
|----------|-----------|--------|
|
||
| Google search jako fallback tracking URL | Gdy carrier_id nieznany — uniwersalne, zawsze działa | Każda przesyłka ma jakiś link śledzenia |
|
||
| carrier_delivery_method_mappings jako źródło carrier_id | API Apaczki nie zwraca usług; tabela mapowań konfigurowana przez usera | Poprawne URL-e dla Orlen, DPD etc. |
|
||
| Tekstowe mapowania Apaczka API | API zwraca "NEW"/"CONFIRMED" nie "0"/"1" jak w docs | Statusy mapują się poprawnie |
|
||
| Pickup przesunięcie na next day po 16:00 | Apaczka API odrzuca gdy MaxPickupDate < ReadyDate (teraz) | Tworzenie przesyłek działa o każdej porze |
|
||
| Cron settings jako osobna zakładka | User request — lepsze oddzielenie ustawień od harmonogramu | Czytelniejszy UI |
|
||
|
||
## Deviations from Plan
|
||
|
||
### Summary
|
||
|
||
| Type | Count | Impact |
|
||
|------|-------|--------|
|
||
| Auto-fixed | 7 | Niezbędne poprawki wykryte podczas testów |
|
||
| Scope additions | 1 | Zakładki w cron (user request) |
|
||
| Deferred | 0 | — |
|
||
|
||
**Total impact:** Niezbędne poprawki + 1 usprawnienie UX na życzenie użytkownika.
|
||
|
||
### Auto-fixed Issues
|
||
|
||
**1. Fix: use-statements ApaczkaShipmentService**
|
||
- **Found during:** Task 2 (testing)
|
||
- **Issue:** `use AppCorexceptionsShipmentException` — brak backslashy (pre-existing bug z fazy 07)
|
||
- **Fix:** Poprawiono na `use App\Core\Exceptions\ShipmentException` i `IntegrationConfigException`
|
||
|
||
**2. Fix: Przycisk Pobierz etykietę w show.php**
|
||
- **Found during:** Task 2
|
||
- **Issue:** Link do prepare zamiast bezpośredniego downloadu PDF
|
||
- **Fix:** Zmieniony na formularz POST z bezpośrednim downloadem
|
||
|
||
**3. Fix: delivery_status "delivered" → "confirmed"**
|
||
- **Found during:** Task 2
|
||
- **Issue:** Migracja błędnie ustawiała label_ready jako doręczona
|
||
- **Fix:** Naprawiono w DB (3 rows) i w pliku migracji
|
||
|
||
**4. Fix: carrier_id dla Apaczka**
|
||
- **Found during:** Task 2
|
||
- **Issue:** Puste carrier_id w shipment_packages
|
||
- **Fix:** Uzupełniono z carrier_delivery_method_mappings (13 rows); fallback w ApaczkaShipmentService
|
||
|
||
**5. Fix: Orlen Paczka URL**
|
||
- **Found during:** Task 2
|
||
- **Issue:** Niepoprawny URL śledzenia
|
||
- **Fix:** Poprawiono na `www.orlenpaczka.pl/sledz-paczke/?numer=`
|
||
|
||
**6. Fix: Tekstowe mapowania Apaczka API**
|
||
- **Found during:** Checkpoint Task 2
|
||
- **Issue:** API zwraca "NEW" ale mapa ma klucze "0","1" — status zawsze "unknown"
|
||
- **Fix:** Dodano 12 tekstowych kluczy do APACZKA_MAP i APACZKA_DESCRIPTIONS
|
||
|
||
**7. Fix: Apaczka pickup date/hours**
|
||
- **Found during:** Checkpoint Task 2
|
||
- **Issue:** Tworzenie przesyłki po 16:00 — Apaczka API error MaxPickupDate < ReadyDate
|
||
- **Fix:** Automatyczne przesunięcie na next business day gdy po 16:00
|
||
|
||
## Sonar Results
|
||
|
||
- 0 nowych unikalnych issues z kodu fazy 28
|
||
- 1x S1448 CronRepository (22 metod > 20) — dodane 2 metody, pre-existing pattern
|
||
- Pre-existing: S3776, S1142, S1192 na ApaczkaShipmentService, DeliveryStatus, cron.php
|
||
- Skill audit: sonar-scanner ✓
|
||
|
||
## Next Phase Readiness
|
||
|
||
**Ready:**
|
||
- System śledzenia przesyłek kompletny (backend + UI)
|
||
- Badge'e, linki, ustawienia crona działają
|
||
- Milestone v1.2 gotowy do zamknięcia
|
||
|
||
**Concerns:**
|
||
- CronRepository zbliża się do limitu metod (22/20) — rozważyć split w przyszłości
|
||
- Apaczka API docs vs rzeczywistość (tekst vs numeric) — monitorować
|
||
|
||
**Blockers:**
|
||
- Brak
|
||
|
||
---
|
||
*Phase: 28-shipment-tracking-ui, Plan: 01*
|
||
*Completed: 2026-03-23*
|