# PAUL Handoff

**Date:** 2026-03-23
**Status:** paused — mid-APPLY Phase 28

---

## READ THIS FIRST

You have no prior context. This document tells you everything.

**Project:** orderPRO — wielokanałowe zarządzanie zamówieniami i przesyłkami
**Core value:** Sprzedawca obsługuje zamówienia ze wszystkich kanałów i nadaje przesyłki bez przełączania się między platformami.

---

## Current State

**Milestone:** v1.2 Śledzenie przesyłek
**Phase:** [2] of [2] — Shipment Tracking UI + Settings
**Plan:** 28-01 — APPLY in progress (Task 2 checkpoint pending, Task 3 not started)

**Loop Position:**
```
PLAN ──▶ APPLY ──▶ UNIFY
  ✓        ◐        ○     [APPLY mid-execution, checkpoint pending]
```

---

## What Was Done This Session

### Phase 27 — Shipment Tracking Backend (COMPLETE ✓)
- Migracja DB: 3 kolumny (delivery_status, delivery_status_raw, delivery_status_updated_at) + indeks
- DeliveryStatus class z mapowaniami statusów (30+ InPost, 11 Apaczka, 7 Allegro)
- ShipmentTrackingInterface + 3 implementacje (InpostTrackingService, ApaczkaTrackingService, AllegroTrackingService)
- ShipmentTrackingRegistry + ShipmentTrackingHandler cron (15 min interwał)
- CronHandlerFactory rozszerzony o shipment_tracking_sync
- Commit: `228c0e9`

### Phase 28 — Shipment Tracking UI (IN PROGRESS)
- Task 1 DONE: SCSS badge'e statusów + DeliveryStatus::trackingUrl() z carrier detection
- Task 2 PARTIALLY DONE: Badge'e w show.php i prepare.php, link śledzenia, boks Płatność i wysyłka
- Task 3 NOT STARTED: Ustawienia interwału crona

### Dodatkowe poprawki poza planem:
- **Fix: Przycisk Pobierz etykietę w show.php** — zmieniony z linku do prepare na formularz POST z bezpośrednim downloadem PDF
- **Fix: delivery_status "delivered" → "confirmed"** — migracja błędnie ustawiała label_ready jako doręczona; naprawiono w DB (3 rows) i w pliku migracji
- **Fix: carrier_id dla Apaczka** — uzupełniono z tabeli carrier_delivery_method_mappings (13 rows); dodano fallback w ApaczkaShipmentService
- **Fix: Orlen Paczka URL** — poprawiony na `www.orlenpaczka.pl/sledz-paczke/?numer=`
- **Fix: Google fallback** — gdy carrier nieznany, link śledzenia kieruje do Google search
- **Nowa metoda: ShipmentPackageRepository::resolveCarrierName()** — lookup carrier z carrier_delivery_method_mappings

---

## What's In Progress

- **Checkpoint Task 2** — user testuje UI badge'ów i linków śledzenia, jeszcze nie zatwierdził "approved"
- **Task 3** — ustawienia interwału trackingu w cronie — nie rozpoczęty

---

## What's Next

**Immediate:** Uzyskać checkpoint approval dla Task 2 (UI badge'y), potem wykonać Task 3 (cron interval settings)

**After that:**
1. Sonar scan + UNIFY Phase 28
2. PLAN Phase 29 — UI zarządzania mapowaniem statusów (user request)
3. Dodać fazę 29 do ROADMAP

---

## Decisions Made

| Decision | Rationale |
|----------|-----------|
| Google search jako fallback tracking URL | Gdy carrier_id nieznany — uniwersalne, zawsze działa |
| carrier_delivery_method_mappings jako źródło carrier_id | API Apaczki nie zwraca usług; tabela mapowań jest konfigurowana przez usera |
| Usunięto pattern matching po numerze śledzenia | Zawodne — 13-cyfrowy numer może być DPD, Orlen lub inny |
| Przycisk Pobierz w show.php zmieniony na POST form | Pre-existing bug — link do prepare zamiast bezpośredniego downloadu |

---

## Key Files

| File | Purpose |
|------|---------|
| `.paul/STATE.md` | Live project state |
| `.paul/ROADMAP.md` | Phase overview |
| `.paul/phases/28-shipment-tracking-ui/28-01-PLAN.md` | Current plan |
| `.paul/phases/27-shipment-tracking-backend/27-01-SUMMARY.md` | Phase 27 summary |
| `src/Modules/Shipments/DeliveryStatus.php` | Status mapping + trackingUrl() |
| `resources/views/orders/show.php` | Badge'e + link śledzenia w zamówieniu |
| `resources/views/shipments/prepare.php` | Badge'e + link śledzenia w przygotowaniu |
| `DOCS/SHIPMENT_TRACKING_STATUSES.md` | Dokumentacja statusów API |

---

## Modified Files (uncommitted)

- `src/Modules/Shipments/DeliveryStatus.php` — trackingUrl() z carrier detection + Google fallback
- `src/Modules/Shipments/ShipmentPackageRepository.php` — resolveCarrierName()
- `src/Modules/Shipments/ApaczkaShipmentService.php` — fallback carrier_id z mappings
- `resources/views/orders/show.php` — kolumna Status dostawy, badge, link, fix Pobierz
- `resources/views/shipments/prepare.php` — kolumna Status dostawy, badge, link
- `resources/scss/modules/_delivery-status.scss` — style badge'ów
- `resources/scss/app.scss` — @use delivery-status
- `public/assets/css/app.css` — rebuilt
- `database/migrations/20260323_000060_*` — fix initial status values

---

## Resume Instructions

1. Read `.paul/STATE.md` for latest position
2. Check this handoff file
3. Run `/paul:resume` or continue APPLY manually:
   - Get checkpoint approval for Task 2 (badge'e UI)
   - Execute Task 3 (cron interval settings in settings/cron.php)
   - Then sonar + `/paul:unify`

---

*Handoff created: 2026-03-23*