update
This commit is contained in:
206
.paul/phases/102-apaczka-receiver-street-length/102-01-PLAN.md
Normal file
206
.paul/phases/102-apaczka-receiver-street-length/102-01-PLAN.md
Normal file
@@ -0,0 +1,206 @@
|
||||
---
|
||||
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>
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user