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

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

• AC-1: Usluga punktowa + dlugi street → truncate do ≤30
• AC-2: Usluga kurierska + dlugi street → ShipmentException
• AC-3: Krotki street (<=30) → bez zmian
• AC-4: Boundary 30 → bez zmian
• 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.