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.