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