update

.paul/phases/102-apaczka-receiver-street-length/102-01-SUMMARY.md

@@ -0,0 +1,54 @@
+# Phase 102-01 — Apaczka Receiver Street Length
+
+**Status:** Complete
+**Date:** 2026-04-14
+
+## What Was Built
+
+Naprawiono blad HTTP 400 z API Apaczka: `receiver.street must be between 0 and 30` przy tworzeniu przesylki.
+
+### Strategia zalezna od typu uslugi
+
+- **Uslugi punktowe** (`receiver_point_id !== ''` — ORLEN Paczka, Paczkomat): auto-truncate street do 30 znakow przez `truncateStreetForPoint()` (mb_substr UTF-8 + rtrim).
+- **Uslugi kurierskie** (brak `receiver_point_id`): `assertStreetWithinCourierLimit()` rzuca `ShipmentException` z komunikatem po polsku zawierajacym dlugosc i pelna wartosc — operator skraca recznie, zeby nie uciac numeru domu/mieszkania.
+
+## Files Modified
+
+- `src/Modules/Shipments/ApaczkaShipmentService.php`
+  - `buildReceiverAddress()` — dodano gałąź zaleznie od `$receiverPointId`
+  - Nowe metody: `truncateStreetForPoint(string): string`, `assertStreetWithinCourierLimit(string): void`
+- `tests/Unit/ApaczkaShipmentServiceTest.php` (nowy plik, 8 test cases)
+
+## Decisions
+
+- **`ShipmentException` zamiast `ApaczkaApiException`** — klasa serwisu juz importuje `ShipmentException` i uzywa go spojnie. Dodawanie kolejnego typu bez powodu byloby niekonsystentne. Wyjatek propaguje przez `ShipmentController` do UI tak samo jak inne bledy przygotowania przesylki.
+- **Brak auto-fallback na line2** — prosciej i bezpieczniej wymusic recznie skrocenie przez operatora niz zgadywac, jak podzielic adres (ryzyko utraty informacji dla kuriera).
+
+## Tests
+
+```
+PHPUnit 11.5.55 — OK (8 tests, 15 assertions)
+```
+
+Test cases:
+1. `truncateStreetForPoint` — long value → ≤30 znakow, zaczyna sie od oryginalu
+2. `truncateStreetForPoint` — short value (Polna 5) → bez zmian
+3. `truncateStreetForPoint` — boundary 30 znakow → bez zmian
+4. `truncateStreetForPoint` — UTF-8 (polskie znaki) → mb_check_encoding OK
+5. `truncateStreetForPoint` — rtrim trailing space
+6. `assertStreetWithinCourierLimit` — short accept
+7. `assertStreetWithinCourierLimit` — boundary 30 accept
+8. `assertStreetWithinCourierLimit` — 42-znakowy adres → ShipmentException z "przekracza 30 znakow"
+
+## AC Status
+
+- [x] AC-1: Usluga punktowa + dlugi street → truncate do ≤30
+- [x] AC-2: Usluga kurierska + dlugi street → ShipmentException
+- [x] AC-3: Krotki street (<=30) → bez zmian
+- [x] AC-4: Boundary 30 → bez zmian
+- [x] AC-5: Unit testy zielone
+
+## Manual Re-test
+
+- Zamowienie 372 (Klaudia Florek-Mach, ORLEN Paczka, customer street 42 znaki): nalezy przetestowac w UI — oczekiwane: przesylka tworzona pomyslnie (sciezka point-truncate).
+- Zamowienie kurierskie z dlugim street: oczekiwane — widoczny komunikat walidacji z zachetą do skrócenia adresu.