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

---
phase: 102-apaczka-receiver-street-length
plan: 01
type: execute
wave: 1
depends_on: []
files_modified:
  - src/Modules/Shipments/ApaczkaShipmentService.php
  - tests/Unit/Modules/Shipments/ApaczkaShipmentServiceTest.php
autonomous: true
delegation: off
---

<objective>
## Goal
Naprawic blad tworzenia przesylki Apaczka spowodowany przekroczeniem limitu 30 znakow w polu `receiver.street` (API Apaczka zwraca HTTP 400). Zachowanie zalezne od typu uslugi:
- **Uslugi punktowe (ORLEN Paczka, Paczkomat, punkty odbioru — `receiver_point_id` ustawione):** auto-truncate street do 30 znakow (street to etykieta punktu, nie realny adres dostarczenia).
- **Uslugi kurierskie (dostawa pod adres — brak `receiver_point_id`):** NIE obcinac automatycznie. Walidacja przed wywolaniem API: jesli street > 30, rzuc `ApaczkaApiException` z czytelnym komunikatem po polsku, zeby operator skorygowal adres recznie w formularzu.

## Purpose
Zamowienie OP/ID=372 (Klaudia Florek-Mach, `Ul. Generała Pilota Józefa Kowalskiego 6/1` = 42 znaki, ORLEN Paczka) blokuje tworzenie przesylki. Automatyczne obcinanie jest bezpieczne dla punktow odbioru (street jest tylko labelem), ale NIE dla kuriera — moglibysmy uciac numer domu/mieszkania i paczka trafilaby w zle miejsce.

## Output
- `ApaczkaShipmentService::buildReceiverAddress()` rozroznia tryby i stosuje wlasciwa strategie
- Dwa helpery: `truncateStreetForPoint()` i walidacja dla kuriera
- Unit testy pokrywajace oba scenariusze + edge cases
</objective>

<context>
## Project Context
@.paul/PROJECT.md
@.paul/ROADMAP.md
@.paul/STATE.md

## Source Files
@src/Modules/Shipments/ApaczkaShipmentService.php
@src/Core/Exceptions/ApaczkaApiException.php
</context>

<acceptance_criteria>

## AC-1: Usluga punktowa z dlugim street — auto-truncate
```gherkin
Given zamowienie z `receiver_point_id` = "POP-XYZ123" i street odbiorcy > 30 znakow (np. "Punkt odbioru POP-XYZ123 przy al. Jerozolimskich")
When ApaczkaShipmentService buduje receiver payload
Then receiver.line1 jest obcinane do 30 znakow (mb_substr + rtrim), request do API przechodzi
```

## AC-2: Usluga kurierska z dlugim street — walidacja + blad
```gherkin
Given zamowienie bez `receiver_point_id` i street > 30 znakow (np. "Ul. Generała Pilota Józefa Kowalskiego 6/1" = 42 znaki)
When ApaczkaShipmentService buduje receiver payload
Then rzucany jest ApaczkaApiException z komunikatem "Ulica odbiorcy przekracza 30 znakow (limit API Apaczka dla uslug kurierskich). Skroc adres recznie przed utworzeniem przesylki. Obecna wartosc: {N} znakow: {street}"
And request do API Apaczka NIE jest wykonywany
```

## AC-3: Krotki street — bez zmian (oba tryby)
```gherkin
Given street <= 30 znakow (np. "Polna 5")
When buduje receiver payload (usluga punktowa albo kurierska)
Then receiver.line1 = wartosc bez modyfikacji
```

## AC-4: Adres dokladnie 30 znakow — bez zmian
```gherkin
Given street o dlugosci dokladnie 30 znakow
When buduje receiver payload
Then receiver.line1 pozostaje 30 znakow, bez obcinania, bez wyjatku
```

## AC-5: Unit testy pokrywaja wszystkie AC
```gherkin
Given ApaczkaShipmentServiceTest
When uruchamiamy vendor/bin/phpunit --filter ApaczkaShipmentServiceTest
Then testy dla AC-1 (point truncate), AC-2 (courier throws), AC-3 (short passthrough), AC-4 (boundary 30) przechodza na zielono
```

</acceptance_criteria>

<tasks>

<task type="auto">
  <name>Task 1: Rozroznienie point vs courier w buildReceiverAddress + helpery</name>
  <files>src/Modules/Shipments/ApaczkaShipmentService.php</files>
  <action>
    W `buildReceiverAddress()` po wyliczeniu `$street` a przed wstawieniem do `$receiver['line1']`:

    1. Wyznacz tryb: `$isPointDelivery = $receiverPointId !== '';` (zmienna juz istnieje w metodzie).
    2. Zastosuj strategie zaleznie od trybu:
       - Point: `$street = $this->truncateStreetForPoint($street);`
       - Courier: `$this->assertStreetWithinCourierLimit($street);` (rzuca ApaczkaApiException jesli > 30)
    3. Dodaj dwie prywatne metody:

       ```php
       /**
        * Apaczka API: receiver.street limit 30 znakow.
        * Dla uslug punktowych (ORLEN/Paczkomat) street to etykieta punktu — obcinamy bezpiecznie.
        */
       private function truncateStreetForPoint(string $street): string
       {
           $street = trim($street);
           if (mb_strlen($street, 'UTF-8') <= 30) {
               return $street;
           }
           return rtrim(mb_substr($street, 0, 30, 'UTF-8'));
       }

       /**
        * Apaczka API: receiver.street limit 30 znakow.
        * Dla uslug kurierskich NIE obcinamy — ryzyko utraty numeru domu/mieszkania.
        * Operator musi skrocic adres recznie w formularzu.
        */
       private function assertStreetWithinCourierLimit(string $street): void
       {
           $length = mb_strlen($street, 'UTF-8');
           if ($length <= 30) {
               return;
           }
           throw new ApaczkaApiException(sprintf(
               'Ulica odbiorcy przekracza 30 znakow (limit API Apaczka dla uslug kurierskich). '
               . 'Skroc adres recznie przed utworzeniem przesylki. Obecna wartosc: %d znakow: "%s"',
               $length,
               $street
           ));
       }
       ```

    4. Uzyj `mb_strlen`/`mb_substr` z jawnym `'UTF-8'` (polskie znaki).
    5. Upewnij sie, ze `ApaczkaApiException` jest zaimportowane w `use`.

    Avoid:
    - `substr()`/`strlen()` bez `mb_` (psuje UTF-8)
    - Automatyczne obcinanie w trybie kuriera (ryzyko utraty numeru)
    - Modyfikacja innych pol odbiorcy
    - Zmiana sygnatury `buildReceiverAddress`
  </action>
  <verify>grep -nE "truncateStreetForPoint|assertStreetWithinCourierLimit|isPointDelivery" src/Modules/Shipments/ApaczkaShipmentService.php — widoczne wywolania + definicje</verify>
  <done>AC-1, AC-2, AC-3, AC-4 spelnione</done>
</task>

<task type="auto">
  <name>Task 2: Unit testy truncation point + walidacja courier</name>
  <files>tests/Unit/Modules/Shipments/ApaczkaShipmentServiceTest.php</files>
  <action>
    Dodaj/rozszerz testy pokrywajace logike street length:

    **Helper access:** Jesli `truncateStreetForPoint` / `assertStreetWithinCourierLimit` sa private — uzyj `ReflectionMethod::setAccessible(true)`.

    **Test cases:**
    1. `testTruncateStreetForPointShortensLongValue` — input 45 znakow → output mb_strlen = 30
    2. `testTruncateStreetForPointPreservesShortValue` — "Polna 5" → "Polna 5" bez zmian
    3. `testTruncateStreetForPointBoundary30` — 30 znakow → 30 znakow (bez zmian)
    4. `testTruncateStreetForPointUtf8Safe` — polskie znaki (35 znakow z ą/ę/ł) → mb_strlen = 30, bez uszkodzonych bajtow (sprawdz `mb_check_encoding($result, 'UTF-8')`)
    5. `testTruncateStreetForPointRtrimTrailingSpace` — gdy znak 30 to spacja, wynik bez koncowej spacji
    6. `testAssertStreetWithinCourierLimitAcceptsShort` — "Polna 5" → brak wyjatku
    7. `testAssertStreetWithinCourierLimitAcceptsBoundary30` — 30 znakow → brak wyjatku
    8. `testAssertStreetWithinCourierLimitRejectsLong` — "Ul. Generała Pilota Józefa Kowalskiego 6/1" (42 znaki) → `ApaczkaApiException` z komunikatem zawierajacym "przekracza 30 znakow" (PHPUnit `expectException` + `expectExceptionMessageMatches`)

    Uzyj `dg/bypass-finals` jesli klasa jest final.

    Avoid: integration testy (prawdziwe API), mockowanie calego flow order import.
  </action>
  <verify>vendor/bin/phpunit --filter ApaczkaShipmentServiceTest</verify>
  <done>AC-5 spelnione</done>
</task>

</tasks>

<boundaries>

## DO NOT CHANGE
- Pozostale pola receiver (name, city, postal_code, country_code, phone, email) — nie ruszac
- `buildSenderAddress` i sender logic — poza zakresem
- `validateServiceRequirements`, `resolvePointAddress`, `applyPointIdentifiers` — nie ruszac
- Struktura payloadu API Apaczka (klucze: line1, line2, city, postal_code, ...)
- Inne providery (InPost ShipX, Allegro WZA) — poza zakresem
- UI/formularz przygotowania przesylki — brak zmian w widokach i kontrolerze

## SCOPE LIMITS
- Tylko pole `receiver.street`/`line1` dla Apaczka
- Brak obslugi innych limitow dlugosci (name, city — jesli wystapia, osobne fazy)
- Brak automatycznego truncate w trybie kuriera (operator skraca recznie — celowa decyzja)
- Brak nowych komunikatow Flash/toast (blad przechodzi przez istniejacy kanal ApaczkaApiException -> ShipmentController)

</boundaries>

<verification>
Before declaring plan complete:
- [ ] vendor/bin/phpunit --filter ApaczkaShipmentServiceTest — zielone
- [ ] grep dla `truncateStreetForPoint` i `assertStreetWithinCourierLimit` zwraca definicje + wywolania w `buildReceiverAddress`
- [ ] Manualny re-test na zamowieniu 372 (ORLEN Paczka, 42-znakowy adres klienta) — tworzenie przesylki przechodzi (point truncate)
- [ ] Manualny re-test na zamowieniu z kurierem i adresem >30 znakow — widoczny bled walidacji ze zrozumialym komunikatem, brak wywolania API
- [ ] Wszystkie acceptance criteria spelnione
</verification>

<success_criteria>
- Usluga punktowa z dlugim street: przesylka tworzona pomyslnie (auto-truncate)
- Usluga kurierska z dlugim street: jasny komunikat dla operatora, brak ryzyka utraty numeru domu
- Krotkie adresy (<=30): obie sciezki bez zmian
- Unit testy pokrywaja 8 przypadkow
- Zero regresji w innych metodach serwisu
</success_criteria>

<output>
After completion, create `.paul/phases/102-apaczka-receiver-street-length/102-01-SUMMARY.md`
</output>