update

2026-04-07 20:32:43 +02:00
parent 1933c74395
commit 8fa9ca6439
45 changed files with 2974 additions and 3382 deletions
--- a/.paul/phases/77-cod-amount-fix/77-01-PLAN.md
+++ b/.paul/phases/77-cod-amount-fix/77-01-PLAN.md
@@ -0,0 +1,157 @@
+---
+phase: 77-cod-amount-fix
+plan: 01
+type: execute
+wave: 1
+depends_on: []
+files_modified:
+  - src/Core/Support/StringHelper.php
+  - src/Modules/Settings/ShopproOrderMapper.php
+  - resources/views/shipments/prepare.php
+  - resources/views/orders/show.php
+  - src/Modules/Orders/OrdersController.php
+autonomous: true
+---
+
+<objective>
+## Goal
+Naprawić automatyczne uzupełnianie kwoty pobrania (COD) przy generowaniu przesyłki dla zamówień spoza Allegro (shopPRO).
+
+## Purpose
+Zamówienia shopPRO z płatnością za pobraniem nie mają auto-wypełnionej kwoty COD w formularzu przesyłki, ponieważ pole `external_payment_type_id` zawiera wartość z shopPRO API (np. `"cod"`, `"pobranie"`), a nie Allegro-specyficzne `"CASH_ON_DELIVERY"`.
+
+## Output
+- Centralna metoda `StringHelper::isCodPayment()` zastępuje wszystkie hardcoded sprawdzenia
+- ShopproOrderMapper normalizuje typ płatności do `CASH_ON_DELIVERY` przy imporcie
+- Kwota pobrania auto-wypełnia się poprawnie dla zamówień z każdego źródła
+</objective>
+
+<context>
+## Project Context
+@.paul/PROJECT.md
+@.paul/ROADMAP.md
+@.paul/STATE.md
+
+## Source Files
+@src/Core/Support/StringHelper.php
+@src/Modules/Settings/ShopproOrderMapper.php
+@resources/views/shipments/prepare.php
+@resources/views/orders/show.php
+@src/Modules/Orders/OrdersController.php
+</context>
+
+<skills>
+No specialized flows configured — optional skills only.
+</skills>
+
+<acceptance_criteria>
+
+## AC-1: COD auto-fill dla zamówień shopPRO
+```gherkin
+Given zamówienie shopPRO z payment_method "cod" lub "pobranie" lub "za pobraniem"
+When użytkownik wchodzi na /orders/{id}/shipment/prepare
+Then pole "Pobranie" zawiera kwotę total_with_tax zamówienia
+And widoczny jest badge "ZA POBRANIEM"
+```
+
+## AC-2: COD auto-fill dla zamówień Allegro (regresja)
+```gherkin
+Given zamówienie Allegro z external_payment_type_id "CASH_ON_DELIVERY"
+When użytkownik wchodzi na /orders/{id}/shipment/prepare
+Then pole "Pobranie" zawiera kwotę total_with_tax zamówienia (bez zmian w zachowaniu)
+```
+
+## AC-3: Detekcja COD w widoku szczegółów zamówienia
+```gherkin
+Given zamówienie z dowolnym wariantem nazwy COD
+When użytkownik przegląda szczegóły zamówienia
+Then badge "Za pobraniem" wyświetla się poprawnie
+```
+
+</acceptance_criteria>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Centralna metoda isCodPayment w StringHelper + normalizacja w ShopproOrderMapper</name>
+  <files>src/Core/Support/StringHelper.php, src/Modules/Settings/ShopproOrderMapper.php</files>
+  <action>
+    1. W `StringHelper` dodaj statyczną metodę `isCodPayment(string $value): bool`:
+       - Normalizuj wartość: `strtoupper(trim($value))`
+       - Sprawdź czy pasuje do znanego zbioru: `CASH_ON_DELIVERY`, `COD`, `POBRANIE`, `ZA POBRANIEM`
+       - Zwróć true/false
+
+    2. W `ShopproOrderMapper::mapOrderAggregate()` (linia 139):
+       - Po odczytaniu `payment_method` ze ścieżek `['payment_method', 'payment.method', 'payments.method']`
+       - Jeśli odczytana wartość jest rozpoznawana jako COD (przez `StringHelper::isCodPayment()`), znormalizuj na `'CASH_ON_DELIVERY'`
+       - Dzięki temu nowe importy będą miały ujednolicony format
+
+    Nie zmieniaj kontraktu ShopproOrderMapper dla pozostałych pól.
+  </action>
+  <verify>
+    Przegląd kodu: metoda isCodPayment obsługuje min. 4 warianty; ShopproOrderMapper normalizuje COD.
+  </verify>
+  <done>AC-1 i AC-2 spełnione od strony danych — nowe importy mają ujednolicony format</done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Zamiana hardcoded sprawdzeń na StringHelper::isCodPayment</name>
+  <files>resources/views/shipments/prepare.php, resources/views/orders/show.php, src/Modules/Orders/OrdersController.php</files>
+  <action>
+    1. `resources/views/shipments/prepare.php` linia 41:
+       - Zamień: `strtoupper(trim(...)) === 'CASH_ON_DELIVERY'`
+       - Na: `\App\Core\Support\StringHelper::isCodPayment((string) ($orderRow['external_payment_type_id'] ?? ''))`
+
+    2. `src/Modules/Orders/OrdersController.php` linia 343:
+       - Zamień: `$isCod = $paymentType === 'CASH_ON_DELIVERY'`
+       - Na: `$isCod = StringHelper::isCodPayment($paymentType)`
+       - Upewnij się że `use App\Core\Support\StringHelper;` jest w importach
+
+    3. `resources/views/orders/show.php`:
+       - Znajdź wszystkie porównania z `'CASH_ON_DELIVERY'` (linie ~222, 228, 578, 678)
+       - Zamień na `\App\Core\Support\StringHelper::isCodPayment(...)`
+       - Zachowaj mapę wyświetlania nazw (array z 'CASH_ON_DELIVERY' => 'Za pobraniem' itp.) — dodaj warianty COD do mapy
+
+    Nie zmieniaj logiki wyświetlania ani formatowania — tylko warunek detekcji COD.
+  </action>
+  <verify>
+    Grep po codebase: brak hardcoded `=== 'CASH_ON_DELIVERY'` w plikach PHP poza testami i DOCS.
+    Widok shipment prepare: zamówienie shopPRO z pobraniem ma auto-wypełnioną kwotę.
+  </verify>
+  <done>AC-1, AC-2, AC-3 spełnione — detekcja COD działa dla wszystkich źródeł zamówień</done>
+</task>
+
+</tasks>
+
+<boundaries>
+
+## DO NOT CHANGE
+- src/Modules/Settings/AllegroOrderImportService.php (Allegro import działa poprawnie)
+- database/migrations/* (brak zmian schematu)
+- src/Modules/Shipments/ShipmentController.php (logika tworzenia przesyłki nie wymaga zmian)
+
+## SCOPE LIMITS
+- Nie aktualizujemy istniejących danych w bazie (istniejące zamówienia shopPRO z "cod" zachowają starą wartość — helper obsłuży je w runtime)
+- Nie dodajemy migracji
+- Nie zmieniamy API ani endpointów
+
+</boundaries>
+
+<verification>
+Before declaring plan complete:
+- [ ] `StringHelper::isCodPayment()` rozpoznaje: CASH_ON_DELIVERY, COD, POBRANIE, ZA POBRANIEM
+- [ ] ShopproOrderMapper normalizuje COD na 'CASH_ON_DELIVERY' przy nowych importach
+- [ ] Brak hardcoded `=== 'CASH_ON_DELIVERY'` w prepare.php, show.php, OrdersController.php
+- [ ] Formularz przesyłki auto-wypełnia kwotę COD dla zamówień shopPRO
+- [ ] Brak regresji: zamówienia Allegro nadal działają poprawnie
+</verification>
+
+<success_criteria>
+- Wszystkie 2 taski ukończone
+- Weryfikacja przeszła pomyślnie
+- Brak błędów PHP na stronach przygotowania przesyłki i szczegółów zamówienia
+</success_criteria>
+
+<output>
+After completion, create `.paul/phases/77-cod-amount-fix/77-01-SUMMARY.md`
+</output>
--- a/.paul/phases/77-cod-amount-fix/77-01-SUMMARY.md
+++ b/.paul/phases/77-cod-amount-fix/77-01-SUMMARY.md
@@ -0,0 +1,127 @@
+---
+phase: 77-cod-amount-fix
+plan: 01
+subsystem: shipments
+tags: [cod, payment, stringhelper, shoppro]
+
+requires:
+  - phase: none
+    provides: n/a
+provides:
+  - StringHelper::isCodPayment() — centralna detekcja platnosci COD
+  - Normalizacja COD w ShopproOrderMapper przy imporcie
+affects: []
+
+tech-stack:
+  added: []
+  patterns: [keyword-based COD detection via StringHelper]
+
+key-files:
+  created: []
+  modified:
+    - src/Core/Support/StringHelper.php
+    - src/Modules/Settings/ShopproOrderMapper.php
+    - resources/views/shipments/prepare.php
+    - resources/views/orders/show.php
+    - src/Modules/Orders/OrdersController.php
+
+key-decisions:
+  - "Keyword matching zamiast exact match — shopPRO wysyla pelne polskie nazwy metod platnosci"
+  - "Dwupoziomowa detekcja: exact match (COD_PAYMENT_TYPES) + keyword search (COD_PAYMENT_KEYWORDS)"
+
+patterns-established:
+  - "StringHelper::isCodPayment() jako jedyne miejsce detekcji COD w codebase"
+
+duration: 15min
+started: 2026-04-07T00:00:00Z
+completed: 2026-04-07T00:15:00Z
+---
+
+# Phase 77 Plan 01: COD Amount Fix Summary
+
+**Centralna detekcja platnosci COD (StringHelper::isCodPayment) z keyword matching dla shopPRO wartosci typu "Platnosc przy odbiorze"**
+
+## Performance
+
+| Metric | Value |
+|--------|-------|
+| Duration | ~15min |
+| Started | 2026-04-07 |
+| Completed | 2026-04-07 |
+| Tasks | 2 completed |
+| Files modified | 5 |
+
+## Acceptance Criteria Results
+
+| Criterion | Status | Notes |
+|-----------|--------|-------|
+| AC-1: COD auto-fill dla zamowien shopPRO | Pass | Testowane na zamowieniach 188/207 z wartoscia "Platnosc przy odbiorze" |
+| AC-2: COD auto-fill dla zamowien Allegro (regresja) | Pass | CASH_ON_DELIVERY nadal rozpoznawane przez exact match |
+| AC-3: Detekcja COD w widoku szczegulow zamowienia | Pass | Badge "Za pobraniem" wyswietla sie dla wszystkich wariantow COD |
+
+## Accomplishments
+
+- Centralna metoda `StringHelper::isCodPayment()` z dwupoziomowa detekcja: exact match na 4 warianty + keyword match na 3 frazy (PRZY ODBIORZE, POBRANIEM, POBRANIE)
+- Normalizacja COD na `CASH_ON_DELIVERY` w `ShopproOrderMapper` przy nowych importach
+- Eliminacja wszystkich hardcoded `=== 'CASH_ON_DELIVERY'` z kodu produkcyjnego (3 pliki)
+- Rozszerzenie map etykiet platnosci w `show.php` o warianty COD
+
+## Files Created/Modified
+
+| File | Change | Purpose |
+|------|--------|---------|
+| `src/Core/Support/StringHelper.php` | Modified | Dodano COD_PAYMENT_TYPES, COD_PAYMENT_KEYWORDS, isCodPayment() |
+| `src/Modules/Settings/ShopproOrderMapper.php` | Modified | normalizeCodPaymentType() + uzycie w mapOrderAggregate |
+| `resources/views/shipments/prepare.php` | Modified | Zamiana hardcoded na StringHelper::isCodPayment() |
+| `resources/views/orders/show.php` | Modified | Zamiana 2 sprawdzen + rozszerzenie map etykiet o warianty COD |
+| `src/Modules/Orders/OrdersController.php` | Modified | Zamiana hardcoded na StringHelper::isCodPayment() |
+
+## Decisions Made
+
+| Decision | Rationale | Impact |
+|----------|-----------|--------|
+| Keyword matching zamiast samego exact match | shopPRO wysyla pelne polskie nazwy np. "Platnosc przy odbiorze" — nie da sie przewidziec wszystkich wariantow | Odpornosc na nowe warianty nazw COD |
+| Dwupoziomowa detekcja (exact + keyword) | Exact match jest szybszy i pewniejszy dla znanych wartosci, keyword jako fallback | Brak false positives dla ONLINE/TRANSFER, elastycznosc dla COD |
+
+## Deviations from Plan
+
+### Summary
+
+| Type | Count | Impact |
+|------|-------|--------|
+| Auto-fixed | 1 | Kluczowe — bez tego fix nie dzialal |
+| Scope additions | 0 | - |
+| Deferred | 0 | - |
+
+**Total impact:** Konieczne rozszerzenie — plan zakladal 4 warianty exact match, rzeczywistosc wymagala keyword matching.
+
+### Auto-fixed Issues
+
+**1. Wartosc shopPRO to "Platnosc przy odbiorze" — nie ma w liscie exact match**
+- **Found during:** Weryfikacja po APPLY (user report)
+- **Issue:** Plan zakladal warianty "cod", "pobranie", "za pobraniem". Rzeczywista wartosc w DB to "Platnosc przy odbiorze"
+- **Fix:** Dodano COD_PAYMENT_KEYWORDS z keyword matching (str_contains) jako drugi poziom detekcji
+- **Files:** src/Core/Support/StringHelper.php, resources/views/orders/show.php
+- **Verification:** 9/9 unit testow przeszlo, w tym "Platnosc przy odbiorze" => true
+
+## Issues Encountered
+
+| Issue | Resolution |
+|-------|------------|
+| Poczatkowy fix nie dzialal — shopPRO wysyla "Platnosc przy odbiorze" nie "cod" | Sprawdzenie DB (orders WHERE id IN (188,207)), dodanie keyword matching |
+
+## Next Phase Readiness
+
+**Ready:**
+- StringHelper::isCodPayment() gotowy do uzycia w kolejnych miejscach
+- Nowe importy shopPRO beda mialy znormalizowane CASH_ON_DELIVERY
+
+**Concerns:**
+- Istniejace zamowienia w DB zachowuja oryginalna wartosc "Platnosc przy odbiorze" — helper obsluguje je w runtime, ale dane nie sa znormalizowane
+
+**Blockers:**
+- None
+
+---
+*Phase: 77-cod-amount-fix, Plan: 01*
+*Completed: 2026-04-07*