---
phase: 42-automation-shipment-status-event
plan: 01
type: execute
wave: 1
depends_on: []
files_modified:
  - 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
autonomous: false
---

<objective>
## 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.
</objective>

<context>
## 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
</context>

<skills>
## 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)
</skills>

<acceptance_criteria>

## AC-1: Dostepne jest nowe zdarzenie automatyzacji statusu przesylki
```gherkin
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
```gherkin
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
```gherkin
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
```gherkin
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>

<tasks>

<task type="auto">
  <name>Task 1: Rozszerz model automatyzacji o event i condition statusu przesylki</name>
  <files>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</files>
  <action>
    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`.
  </action>
  <verify>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</verify>
  <done>AC-1 satisfied i AC-2 satisfied: event + warunki sa dostepne i walidowane.</done>
</task>

<task type="auto">
  <name>Task 2: Podlacz trigger automatyzacji do zmian statusu trackingu</name>
  <files>src/Modules/Cron/ShipmentTrackingHandler.php, src/Modules/Cron/CronHandlerFactory.php, src/Modules/Automation/AutomationService.php</files>
  <action>
    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.
  </action>
  <verify>rg -n "shipment\.status_changed|trigger\(|previous_status|delivery_status_raw|CronHandlerFactory" src/Modules/Cron src/Modules/Automation</verify>
  <done>AC-3 satisfied: reguly odpalaja sie po zmianie statusu przesylki.</done>
</task>

<task type="auto">
  <name>Task 3: Udokumentuj mapowanie statusow biznesowych i zamknij TODO 42</name>
  <files>DOCS/ARCHITECTURE.md, DOCS/TECH_CHANGELOG.md, DOCS/todo.md</files>
  <action>
    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.
  </action>
  <verify>rg -n "shipment\.status_changed|status przesylki|42\." DOCS/ARCHITECTURE.md DOCS/TECH_CHANGELOG.md DOCS/todo.md</verify>
  <done>AC-4 satisfied: statusy i ograniczenia sa transparentnie opisane.</done>
</task>

<task type="checkpoint:human-verify" gate="blocking">
  <what-built>Nowe zdarzenie automatyzacji dla zmiany statusu przesylki i warunki filtrowania po statusach.</what-built>
  <how-to-verify>
    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.
  </how-to-verify>
  <resume-signal>Type "approved" to continue, or describe issues to fix</resume-signal>
</task>

</tasks>

<boundaries>

## 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.

</boundaries>

<verification>
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
</verification>

<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>

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