update

.paul/phases/66-allegro-delivery-tracking/66-01-SUMMARY.md

@@ -0,0 +1,96 @@
+---
+phase: 66-allegro-delivery-tracking
+plan: 01
+subsystem: shipments
+tags: [allegro, tracking, edge-api, delivery-status, cron]
+
+requires:
+  - phase: 27-shipment-tracking-backend
+    provides: ShipmentTrackingInterface, DeliveryStatus, ShipmentTrackingHandler
+
+provides:
+  - Allegro Delivery tracking via edge.allegro.pl API
+  - Edge API integration (no auth, public endpoint)
+  - Rate limiting for edge API requests (60s)
+
+affects: [allegro-tracking, delivery-status, cron-handler]
+
+tech-stack:
+  added: []
+  patterns: [edge-api-integration, rate-limited-cron]
+
+key-files:
+  created: []
+  modified:
+    - src/Modules/Shipments/AllegroTrackingService.php
+    - src/Modules/Shipments/DeliveryStatus.php
+    - src/Modules/Cron/ShipmentTrackingHandler.php
+
+key-decisions:
+  - "Edge API (edge.allegro.pl/ad/tracking) zamiast Allegro REST API (nie daje tracking statusów)"
+  - "Accept: application/vnd.allegro.internal.v1+json — wymagany nagłówek"
+  - "Provider allegro_edge osobny od allegro_wza w DeliveryStatus"
+  - "Rate limit 60s między requestami do edge API"
+
+patterns-established:
+  - "slugifyAllegroDescription() konwertuje opisy PL na slugi mapowalne na statusy"
+  - "Osobna metoda edgeApiRequest() bez Bearer token (publiczny endpoint)"
+
+duration: ~15min
+started: 2026-04-03T20:30:00Z
+completed: 2026-04-03T20:45:00Z
+---
+
+# Phase 66 Plan 01: Allegro Delivery Tracking — Core Integration
+
+**Integracja śledzenia przesyłek Allegro Delivery przez publiczne edge API — fetchAllegroEdgeStatus, mapowanie opisów PL na znormalizowane statusy, rate limiting 60s w cronie.**
+
+## Performance
+
+| Metric | Value |
+|--------|-------|
+| Duration | ~15min |
+| Tasks | 3 completed (delegated) |
+| Files modified | 3 |
+| Execution mode | Delegated auto (3 sub-agents) |
+
+## Acceptance Criteria Results
+
+| Criterion | Status | Notes |
+|-----------|--------|-------|
+| AC-1: Allegro Delivery tracking zwraca status | Pass | fetchAllegroEdgeStatus pobiera z edge API |
+| AC-2: Mapowanie opisów na statusy | Pass | slugify + ALLEGRO_EDGE_MAP |
+| AC-3: Rate limiting max 1 req/min | Pass | sleep() w ShipmentTrackingHandler |
+| AC-4: Fallback InPost nadal działa | Pass | Warunek carrier_id inpost/paczkomat bez zmian |
+
+## Accomplishments
+
+- AllegroTrackingService pobiera statusy z edge.allegro.pl/ad/tracking dla non-InPost przesyłek
+- DeliveryStatus ma provider 'allegro_edge' z mapą slugów i opisów PL
+- ShipmentTrackingHandler throttluje requesty do edge API (60s)
+
+## Files Created/Modified
+
+| File | Change | Purpose |
+|------|--------|---------|
+| `src/Modules/Shipments/DeliveryStatus.php` | Modified | ALLEGRO_EDGE_MAP, ALLEGRO_EDGE_DESCRIPTIONS, slugifyAllegroDescription() |
+| `src/Modules/Shipments/AllegroTrackingService.php` | Modified | fetchAllegroEdgeStatus(), edgeApiRequest() |
+| `src/Modules/Cron/ShipmentTrackingHandler.php` | Modified | Rate limiting 60s dla allegro_wza non-inpost |
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. Slug mismatch w mapie**
+- **Found during:** Orkiestrator verification
+- **Issue:** "Kurier przekazał przesyłkę do magazynu" → slug `przekazal_przesylke_do_magazynu` nie był w mapie (była `przekazana_do_magazynu`)
+- **Fix:** Dodano wariant do ALLEGRO_EDGE_MAP
+- **Verification:** Test 5/5 realnych opisów mapuje poprawnie
+
+## Next Phase Readiness
+
+**Ready:** Plan 66-02 rozszerza mapę i dodaje keyword fallback
+
+---
+*Phase: 66-allegro-delivery-tracking, Plan: 01*
+*Completed: 2026-04-03*