orderPRO/.paul/phases/42-automation-shipment-status-event/42-01-PLAN.md

phase, plan, type, wave, depends_on, files_modified, autonomous

phase	plan	type	wave	depends_on	files_modified	autonomous
42-automation-shipment-status-event	01	execute	1		src/Modules/Automation/AutomationController.php src/Modules/Automation/AutomationService.php src/Modules/Cron/ShipmentTrackingHandler.php src/Modules/Cron/CronHandlerFactory.php src/Modules/Automation/AutomationRepository.php resources/views/automation/form.php resources/views/automation/index.php public/assets/js/modules/automation-form.js DOCS/ARCHITECTURE.md DOCS/TECH_CHANGELOG.md DOCS/todo.md	false

## Goal Zrealizowac punkt 42 z `DOCS/todo.md`: dodac nowe zdarzenie automatyzacji dla zmiany statusu przesylki oraz nowe warunki filtrowania po statusach przesylek (zarejestrowana, do odbioru, nadana w punkcie, odebrana, anulowana, nieodebrana, odebrana-zwrot), z weryfikacja jakie statusy sa technicznie dostepne.

Purpose

Uzytkownik ma miec mozliwosc budowania automatycznych regu³ opartych o realny status dostawy, a nie tylko zdarzenie paragonu. To domyka workflow post-shipping i pozwala reagowac na sytuacje kurierskie.

Output

Nowe zdarzenie shipment.status_changed, nowe warunki reguly dla statusow przesylki, trigger uruchamiany po zmianie statusu w trackerze, oraz dokumentacja mapowania statusow dostepnych vs oczekiwanych biznesowo.

## Project Context @.paul/PROJECT.md @.paul/ROADMAP.md @.paul/STATE.md @DOCS/todo.md @DOCS/ARCHITECTURE.md @DOCS/DB_SCHEMA.md

Prior Work (only if genuinely needed)

@.paul/phases/16-automated-tasks/16-02-SUMMARY.md @.paul/phases/27-shipment-tracking-backend/27-01-SUMMARY.md @.paul/phases/29-delivery-status-mapping-ui/29-01-SUMMARY.md

Source Files

@src/Modules/Automation/AutomationController.php @src/Modules/Automation/AutomationService.php @src/Modules/Cron/ShipmentTrackingHandler.php @src/Modules/Cron/CronHandlerFactory.php @src/Modules/Automation/AutomationRepository.php @resources/views/automation/form.php @resources/views/automation/index.php @public/assets/js/modules/automation-form.js @src/Modules/Shipments/DeliveryStatus.php

## Required Skills (from SPECIAL-FLOWS.md)

Skill	Priority	When to Invoke	Loaded?
sonar-scanner	required	Po APPLY, przed UNIFY	o
/code-review	optional	Po implementacji, przed UNIFY	o

BLOCKING: Required skills MUST be loaded before APPLY proceeds.

Skill Invocation Checklist

• sonar-scanner uruchomiony po APPLY
• /code-review (opcjonalnie)

<acceptance_criteria>

AC-1: Dostepne jest nowe zdarzenie automatyzacji statusu przesylki

Given uzytkownik tworzy/edytuje zadanie automatyczne
When wybiera zdarzenie
Then moze wybrac `shipment.status_changed`
And reguly dla tego zdarzenia sa zapisywane i odczytywane poprawnie

AC-2: Dostepne sa warunki filtrowania po statusie przesylki

Given uzytkownik konfiguruje warunki reguly dla `shipment.status_changed`
When wybiera statusy przesylek
Then moze wskazac statusy biznesowe odpowiadajace wymaganiom z punktu 42
And system waliduje i stosuje te warunki podczas uruchamiania automatyzacji

AC-3: Trigger dziala po realnej zmianie statusu trackingu

Given cron tracking aktualizuje status paczki
When `delivery_status` zmienia wartosc
Then uruchamiane jest `automationService->trigger('shipment.status_changed', orderId, context)`
And reguly uruchamiaja akcje tylko gdy warunki statusu sa spelnione

AC-4: Statusy z punktu 42 sa zweryfikowane i udokumentowane

Given wdrozenie punktu 42
When sprawdzane sa dokumenty techniczne
Then ARCHITECTURE/TECH_CHANGELOG opisuja mapowanie statusow "biznesowych" do statusow technicznie obslugiwanych
And punkt 42 w DOCS/todo.md jest oznaczony jako wykonany

</acceptance_criteria>

Task 1: Rozszerz model automatyzacji o event i condition statusu przesylki src/Modules/Automation/AutomationController.php, src/Modules/Automation/AutomationService.php, src/Modules/Automation/AutomationRepository.php, resources/views/automation/form.php, public/assets/js/modules/automation-form.js, resources/views/automation/index.php Dodaj event `shipment.status_changed` do listy dozwolonych zdarzen i etykiet formularza/listy. Dodaj nowy typ warunku (np. `shipment_status`) z konfiguracja wielokrotnego wyboru statusow. W `AutomationService` rozszerz ewaluacje warunkow o porownanie statusu z kontekstu triggera (dla eventu shipment). Zachowaj kompatybilnosc istniejacych regul `receipt.created`. rg -n "shipment\.status_changed|shipment_status|ALLOWED_EVENTS|ALLOWED_CONDITION_TYPES" src/Modules/Automation resources/views/automation public/assets/js/modules/automation-form.js AC-1 satisfied i AC-2 satisfied: event + warunki sa dostepne i walidowane. Task 2: Podlacz trigger automatyzacji do zmian statusu trackingu src/Modules/Cron/ShipmentTrackingHandler.php, src/Modules/Cron/CronHandlerFactory.php, src/Modules/Automation/AutomationService.php W `ShipmentTrackingHandler` porownuj status przed/po aktualizacji i uruchamiaj automatyzacje tylko przy realnej zmianie. Przekaz do triggera kontekst: package_id, provider, delivery_status, delivery_status_raw, previous_status. Zaktualizuj fabryke crona (`CronHandlerFactory`) tak, aby `ShipmentTrackingHandler` mial dostep do `AutomationService`. Unikaj podwojnych triggerow dla tej samej paczki i tej samej wartosci statusu. rg -n "shipment\.status_changed|trigger\(|previous_status|delivery_status_raw|CronHandlerFactory" src/Modules/Cron src/Modules/Automation AC-3 satisfied: reguly odpalaja sie po zmianie statusu przesylki. Task 3: Udokumentuj mapowanie statusow biznesowych i zamknij TODO 42 DOCS/ARCHITECTURE.md, DOCS/TECH_CHANGELOG.md, DOCS/todo.md Opisz mapowanie statusow wymaganych biznesowo z punktu 42 do statusow obslugiwanych technicznie (normalized/raw). Jesli ktorys status nie ma 1:1 mapowania, zapisz jawnie przyjety odpowiednik i ograniczenie. Oznacz punkt 42 jako wykonany. rg -n "shipment\.status_changed|status przesylki|42\." DOCS/ARCHITECTURE.md DOCS/TECH_CHANGELOG.md DOCS/todo.md AC-4 satisfied: statusy i ograniczenia sa transparentnie opisane. Nowe zdarzenie automatyzacji dla zmiany statusu przesylki i warunki filtrowania po statusach. 1. Otworz `Ustawienia > Zadania automatyczne > Dodaj zadanie`. 2. Sprawdz, ze na liscie zdarzen jest `shipment.status_changed` (z czytelna etykieta). 3. Dodaj warunek statusu przesylki i zapisz regule. 4. Wymus trigger statusu (np. uruchom cron tracking dla testowej paczki). 5. Zweryfikuj, ze akcja reguly uruchomila sie tylko dla wybranych statusow. Type "approved" to continue, or describe issues to fix

DO NOT CHANGE

• database/migrations/* (zakladamy wykorzystanie istniejacego modelu JSON condition_value)
• Istniejace akcje automatyzacji poza koniecznym rozszerzeniem
• UI innych modulow niz settings/automation

SCOPE LIMITS

• Zakres dotyczy eventu i warunkow dla statusu przesylki.
• Bez dodawania nowych typow akcji automatyzacji.
• Bez przebudowy calego tracking engine.

Before declaring plan complete: - [ ] `C:\xampp\php\php.exe -l src/Modules/Automation/AutomationController.php` - [ ] `C:\xampp\php\php.exe -l src/Modules/Automation/AutomationService.php` - [ ] `C:\xampp\php\php.exe -l src/Modules/Cron/ShipmentTrackingHandler.php` - [ ] `C:\xampp\php\php.exe -l src/Modules/Cron/CronHandlerFactory.php` - [ ] `C:\xampp\php\php.exe -l src/Modules/Automation/AutomationRepository.php` - [ ] Manual verification checkpoint wykonany - [ ] Dokumentacja (`DOCS/ARCHITECTURE.md`, `DOCS/TECH_CHANGELOG.md`, `DOCS/todo.md`) zaktualizowana - [ ] All acceptance criteria met

<success_criteria>

• Uzytkownik moze tworzyc reguly reagujace na zmiane statusu przesylki
• Warunki statusowe dzialaja przewidywalnie i bez falszywych triggerow
• Punkt 42 jest zamkniety z pelna dokumentacja mapowania statusow </success_criteria>

After completion, create `.paul/phases/42-automation-shipment-status-event/42-01-SUMMARY.md`