# 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.
