update

.paul/docs/ARCHITECTURE.md

@@ -29,9 +29,10 @@
 - `App\Core\Application`: bootstrap, dispatch requestu, opcjonalny web-cron z lockiem DB.
 - `App\Modules\Cron\CronRunner`: pobiera kolejke jobow z `cron_schedules/cron_jobs` i wykonuje handlery.
 - `App\Modules\Cron\CronHandlerFactory`: sklada zaleznosci i mapuje `job_type -> handler`.
-- `App\Modules\Orders\OrdersController`: flow UI zamowien + endpointy AJAX.
-- `App\Modules\Orders\OrdersRepository`: query listy/szczegolow zamowien, update statusow, activity log.
+- `App\Modules\Orders\OrdersController`: flow UI zamowien + endpointy AJAX; `buildCustomerRiskInfo/composeCustomerRiskText` skladaja alert klienta ze zwrotami do widoku `orders/show`.
+- `App\Modules\Orders\OrdersRepository`: query listy/szczegolow zamowien, update statusow, activity log; `customerReturnedCountSubquerySql` generuje correlated subquery dopasowujaca historyczne zamowienia klienta po email/phone/name z paczka `returned` (self-exclusion).
 - `App\Modules\Shipments\ShipmentController`: flow przesylek i etykiet.
+- `App\Modules\Shipments\ShipmentPackageRepository`: CRUD paczek + `findReturnedByCustomer(customer, excludeOrderId)` zwraca liste zwroconych paczek klienta dla bannera ryzyka w szczegolach zamowienia.
 - `App\Modules\Shipments\ShipmentProviderRegistry`: wybor providera wysylki po `provider_code`.
 - `App\Modules\Printing\PrintApiController`: endpointy kolejki wydruku (session/api-key).
 - `App\Modules\Automation\AutomationService`: trigger eventow, ewaluacja warunkow, wykonanie akcji.
@@ -85,6 +86,16 @@
 - wykonuje akcje (`send_email`, `issue_receipt`, `update_shipment_status`, `update_order_status`),
 - zapisuje wynik do `automation_execution_logs`.
 
+## Shipment tracking — mapowanie statusow kuriera
+- `ShipmentTrackingHandler` (job `shipment_tracking_sync`) iteruje po aktywnych paczkach i pobiera status z API przewoznika (`Inpost/Apaczka/AllegroTrackingService`).
+- Serwisy zwracaja `{status, status_raw, description}`, gdzie `status` pochodzi z `DeliveryStatus::normalize($provider, $raw)` (hardcoded PROVIDER_MAPS).
+- Handler na starcie wczytuje overrides z `delivery_status_mappings` (raz per uruchomienie) i po kazdym wyniku stosuje `DeliveryStatus::normalizeWithOverrides()` — pozwala to przypisac nowe raw statusy kuriera przez UI bez zmian w kodzie.
+- Strona `/settings/delivery-status-mappings`:
+  - Pokazuje defaulty + overrides + sekcje „Niezmapowane statusy wykryte w systemie" (distinct raw statusy z `shipment_packages` nie wystepujace w defaultach ani overrides).
+  - Bulk form zapisuje do `delivery_status_mappings` (override = normalized inny niz default LUB raw nie ma defaultu).
+  - Badge w sidebar pokazuje sumaryczna liczbe niezmapowanych statusow (`DeliveryStatusMappingRepository::countAllUnmappedForBadge`).
+- Przy zmianie normalized status (previous != new) handler wywoluje `automation.trigger('shipment.status_changed', ...)`.
+
 ## Printing
 - Panel tworzy job `print_jobs` przez `/api/print/jobs`.
 - Klient desktop pobiera pending joby przez API key.

.paul/docs/TECH_CHANGELOG.md

@@ -2,6 +2,65 @@
 
 > Chronologiczny log zmian technicznych — co i dlaczego.
 
+## 2026-04-22 - Alert klienta z historia zwrotow (Phase 106)
+
+**Powod**: Operator wysylkowy nie widzial wczesniej, ze kupujacy juz raz nie odebral przesylki (`delivery_status='returned'`) zanim wyslal kolejna paczke — generowalo to kolejne koszty wysylki i magazynowania.
+
+**Zmiany**:
+- `src/Modules/Orders/OrdersRepository.php`:
+  - nowa metoda prywatna `customerReturnedCountSubquerySql(orderAlias, addressAlias)` — generuje correlated subquery zliczajaca inne zamowienia klienta biezacego wiersza z paczka `returned`.
+  - `buildListSql()` — dodana kolumna `customer_returned_count` (EXISTS-style COUNT DISTINCT) do SELECT listy zamowien.
+  - `transformOrderRow()` — przekazuje `customer_returned_count` do wiersza.
+  - `findDetails()` — JOIN `order_addresses` typu customer + subquery `customer_returned_count`; zwraca rowniez `buyer_email`, `buyer_phone`, `buyer_name` w `$order`.
+- `src/Modules/Shipments/ShipmentPackageRepository.php`:
+  - nowa metoda `findReturnedByCustomer(array customer, int excludeOrderId, int limit=10)` — lista zwroconych paczek klienta (match OR: email lower+trim, phone tylko cyfry >=6, name lower+trim), sortowana po dacie malejaco.
+- `src/Modules/Orders/OrdersController.php`:
+  - `toTableRow()` — dodano badge `zwroty: N` w kolumnie buyer + klasa `is-risk-return` na `<tr>` gdy `customer_returned_count >= 1` (kompozycja z klasa aged orders z Phase 101).
+  - `show()` — oblicza `$customerRiskInfo` i przekazuje do widoku.
+  - nowe metody prywatne: `buildCustomerRiskInfo(order, orderId)`, `composeCustomerRiskText(count, email, phone, name)` — budowa tresci alertu zaleznie od dostepnosci pol (phone+email / email / phone / name).
+- `resources/views/orders/show.php` — banner `customer-risk-banner` u samej gory karty szczegolow (pod naglowkiem, nad flash messages i status change), z `<details>` rozwijajacym liste zamowien ze zwrotem (order_id, data, tracking, provider).
+- `resources/scss/modules/_customer-risk-alert.scss` (nowy modul):
+  - `.customer-risk-banner` + `__icon`, `__body`, `__text`, `__list`, `__table` — czerwony banner z pastelowym tlem i lewym paskiem 4px.
+  - `.risk-return-badge` — maly inline badge przy buyer name.
+  - `tr.is-risk-return` — lewy pasek wiersza w tabeli zamowien.
+- `resources/scss/app.scss` — `@use "modules/customer-risk-alert"`.
+- `public/assets/css/app.css` — rebuild przez `npm run build:css`.
+
+**Wymagania**:
+- MySQL 8.0+ (REGEXP_REPLACE w subquery matching phone).
+- Wynik licznika wyliczany on-the-fly (brak migracji DB, brak materializacji). Indeksy na `order_addresses(order_id, address_type)` i `shipment_packages(order_id, delivery_status)` sugerowane jesli lista zamowien przekroczy ~50k wierszy — zglosic w kolejnym planie.
+
+**Anti-fraud/false positive**:
+- Self-exclusion: `sp.order_id != o.id` — biezace zamowienie nie wlicza sie do licznika.
+- Minimum phone length 6 cyfr — eliminuje match na "", "+48", krotkich fragmentach.
+- OR matching po email/phone/name moze dac fałszywe pozytywy dla popularnych imion; swiadome odstepstwo (user wymagal szerokiego matchingu).
+
+## 2026-04-22 - Mapowanie statusow dostawy: wykrywanie niezmapowanych + runtime overrides
+
+**Powod**: zamowienia (np. OP000000357, OP000000638) pokazywaly `delivery_status=unknown`, mimo ze apaczka API zwracala `RETURNED_TO_SHIPPER`. UI `/settings/delivery-status-mappings` pokazywalo wylacznie statusy obecne w defaultach kodu — nowe raw statusy kuriera nie mialy gdzie zostac przypisane bez zmiany kodu.
+
+**Faza A — quick fix (defaulty + backfill)**:
+- `src/Modules/Shipments/DeliveryStatus.php`: dodano 3 brakujace mapowania:
+  - apaczka `RETURNED_TO_SHIPPER` -> `returned`
+  - apaczka `PICKUP` -> `in_transit`
+  - allegro_wza `collected_from_sender` -> `in_transit`
+- `database/migrations/20260422_000101_backfill_delivery_status_unknowns.sql`: backfill 11 paczek (3 + 7 + 1). Bez trigger `shipment.status_changed` (backfill starych rekordow, nie runtime event).
+
+**Faza B — rozwiazanie systemowe**:
+- `DeliveryStatusMappingRepository::listUnmappedRawStatuses(provider, knownKeys)` — zwraca raw statusy z `shipment_packages` ktore nie wystepuja w defaultach ani overrides DB; z licznikiem paczek i ostatnim wystapieniem.
+- `DeliveryStatusMappingController::index` — przekazuje `unmappedRawStatuses` do widoku; rowniez wlacza do listy overrides, ktore nie maja odpowiadajacego defaultu (user moze dodac completely custom raw statusy).
+- `resources/views/settings/delivery-status-mappings.php` — nowa sekcja „Niezmapowane statusy wykryte w systemie (N)" z form submit do `save-bulk`. Pomaranczowy akcent aby wyroznic od defaultow.
+- `ShipmentTrackingHandler` — dostal `?DeliveryStatusMappingRepository` w konstruktorze; po kazdym `service->getDeliveryStatus()` wywoluje `DeliveryStatus::normalizeWithOverrides(provider, raw, overrides)` jesli overrides istnieja. Dzieki temu override z UI dziala runtime bez zmian kodu.
+- `CronHandlerFactory` — przekazuje `DeliveryStatusMappingRepository` do `ShipmentTrackingHandler`.
+
+**Faza C — badge w menu**:
+- `Application` — dodano statyczny holder `self::$instance` + `Application::instance()`, aby layout mial dostep do kontenera.
+- `DeliveryStatusMappingRepository::countAllUnmappedForBadge()` — zlicza niezmapowane raw statusy dla wszystkich providerow UI (inpost, apaczka, allegro_wza); cache per-request.
+- `resources/views/layouts/app.php` — badge pomaranczowy przy linku „Mapowanie statusow dostawy" z liczba niezmapowanych statusow (jesli > 0). Try/catch — brak badge'a nie psuje layoutu.
+- `resources/scss/app.scss` — klasa `.sidebar__badge`.
+
+**Efekt**: user nie musi modyfikowac kodu przy kazdym nowym statusie kuriera. Badge sygnalizuje pojawienie sie nieznanych statusow; sekcja na stronie mapowan pozwala przypisac je do znormalizowanych kategorii. Cron po nastepnym tick'u automatycznie przeliczy istniejace paczki zgodnie z override.
+
 ## 2026-04-19 - Statystyki zamowien (menu + raport dzienny)
 
 - Dodano nowy modul `Statistics`: