orderPRO/.paul/phases/47-shipment-created-automation/47-01-PLAN.md

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

phase	plan	type	wave	depends_on	files_modified	autonomous
47-shipment-created-automation	01	execute	1		src/Modules/Automation/AutomationController.php src/Modules/Automation/AutomationService.php src/Modules/Cron/CronHandlerFactory.php src/Modules/Shipments/ShipmentController.php src/Modules/Shipments/ShipmentPackageRepository.php resources/views/automation/form.php public/assets/js/modules/automation-form.js resources/views/automation/index.php DOCS/ARCHITECTURE.md DOCS/TECH_CHANGELOG.md DOCS/todo.md	false

## Goal Dodac nowe zdarzenie automatyzacji `shipment.created`, ktore uruchamia sie od razu po utworzeniu przesylki w zamowieniu, oraz dodac nowa akcje automatyzacji `update_shipment_status` (UI: "Zmiana statusu przesylki").

Purpose

Operator ma moc budowania automatyzacji natychmiast po wygenerowaniu przesylki (bez czekania na cron tracking) i moze reakcja reguly zmieniac status przesylki zgodnie z procesem operacyjnym firmy.

Output

Kompletne rozszerzenie automatyzacji o:

• event shipment.created (natychmiastowy trigger),
• action update_shipment_status,
• konfiguracje w formularzu automatyzacji,
• aktualna dokumentacje techniczna.

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

Prior Work (only if genuinely needed)

@.paul/phases/42-automation-shipment-status-event/42-01-PLAN.md @.paul/phases/42-automation-shipment-status-event/42-01-SUMMARY.md @.paul/phases/26-manual-tracking-number/26-01-SUMMARY.md @.paul/phases/27-shipment-tracking-backend/27-01-SUMMARY.md

Source Files

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

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

Skill	Priority	When to Invoke	Loaded?
sonar-scanner	required	Po APPLY, przed UNIFY	o
/feature-dev	optional	Przed wdrazaniem nowej funkcjonalnosci	o
/code-review	optional	Po APPLY, przed UNIFY	o

BLOCKING: Required skills MUST be loaded before APPLY proceeds.

Skill Invocation Checklist

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

<acceptance_criteria>

AC-1: Event "Utworzenie przesylki" uruchamia sie natychmiast po sukcesie utworzenia

Given istnieje aktywna regula automatyzacji z eventem `shipment.created`
When uzytkownik utworzy przesylke dla zamowienia (provider API lub recznie)
Then system wywola AutomationService trigger w tym samym flow requestu
And nie wymaga to oczekiwania na cron `shipment_tracking_sync`

AC-2: Nowa akcja "Zmiana statusu przesylki" jest konfigurowalna i walidowana

Given uzytkownik tworzy/edytuje regule automatyzacji
When dodaje akcje "Zmiana statusu przesylki"
Then moze wskazac docelowy status przesylki z dozwolonej listy
And zapis nie przechodzi dla nieprawidlowej konfiguracji akcji

AC-3: Akcja poprawnie aktualizuje status przesylki i nie powoduje petli

Given regula uruchamia akcje `update_shipment_status`
When akcja jest wykonana dla zamowienia z paczka
Then status paczki zostaje zaktualizowany tylko przy realnej zmianie
And system nie wchodzi w nieskonczone petle triggerow automatyzacji

AC-4: UI i dokumentacja sa spójne z nowymi elementami automatyzacji

Given wdrozenie nowego eventu i akcji
When uzytkownik otworzy formularz automatyzacji
Then widzi event "Utworzenie przesylki" i akcje "Zmiana statusu przesylki"
And ARCHITECTURE/TECH_CHANGELOG/todo opisuja zakres i ograniczenia implementacji

</acceptance_criteria>

Task 1: Dodaj event `shipment.created` i natychmiastowy trigger po utworzeniu przesylki src/Modules/Automation/AutomationController.php, src/Modules/Shipments/ShipmentController.php, src/Modules/Automation/AutomationService.php Rozszerz ALLOWED_EVENTS i etykiety UI o `shipment.created` ("Utworzenie przesylki"). W `ShipmentController::create()` i `ShipmentController::createManual()` po potwierdzonym utworzeniu paczki wywolaj `AutomationService->trigger('shipment.created', orderId, context)`. Context powinien zawierac co najmniej: package_id, provider, tracking_number (jezeli dostepny), package_status. Unikaj triggera w sciezkach bledu tworzenia przesylki. rg -n "shipment\.created|trigger\('shipment\.created'|Utworzenie przesylki" src/Modules/Automation src/Modules/Shipments resources/views/automation AC-1 satisfied: event jest dostepny i odpalany od razu po utworzeniu przesylki. Task 2: Dodaj akcje `update_shipment_status` i wykonanie backend src/Modules/Automation/AutomationController.php, src/Modules/Automation/AutomationService.php, src/Modules/Shipments/ShipmentPackageRepository.php, src/Modules/Cron/CronHandlerFactory.php Dodaj nowy typ akcji do walidacji i parsera konfiguracji: `update_shipment_status`. Konfiguracja akcji: docelowy status dostawy (`delivery_status`) z tej samej mapy statusow biznesowych co warunki shipment_status. W `AutomationService` dodaj handler akcji, ktory wyszukuje docelowa paczke (z context package_id lub fallback: najnowsza aktywna paczka zamowienia) i wykonuje aktualizacje statusu tylko przy realnej zmianie. Dodaj zabezpieczenie anty-petla: nie emituj kolejnego eventu przy braku zmiany; przy zmianie oznacz context zrodla automatyzacji i respektuj chain dedup. Zaktualizuj factory DI, by serwis automatyzacji mial dostep do repo paczek. rg -n "update_shipment_status|handleUpdateShipmentStatus|delivery_status|ALLOWED_ACTION_TYPES" src/Modules/Automation src/Modules/Shipments src/Modules/Cron AC-2 satisfied i AC-3 satisfied: akcja jest walidowana, wykonuje realna zmiane i nie petli sie. Task 3: Rozszerz formularz automatyzacji oraz dokumentacje techniczna resources/views/automation/form.php, public/assets/js/modules/automation-form.js, resources/views/automation/index.php, DOCS/ARCHITECTURE.md, DOCS/TECH_CHANGELOG.md, DOCS/todo.md Dodaj opcje akcji "Zmiana statusu przesylki" do formularza oraz dynamiczny config (wybor statusu). Zapewnij zgodnosc renderu create/edit i JS add-row. Zaktualizuj dokumentacje: nowy event natychmiastowy i nowa akcja, z opisem kontekstu oraz ograniczen. Dodaj/uzupelnij wpis w `DOCS/todo.md` dla nowego zakresu (zamkniecie po wdrozeniu). rg -n "shipment\.created|Zmiana statusu przesylki|update_shipment_status" resources/views/automation public/assets/js/modules/automation-form.js DOCS/ARCHITECTURE.md DOCS/TECH_CHANGELOG.md DOCS/todo.md AC-4 satisfied: UI i dokumentacja sa spójne z wdrozonym zakresem. Nowy natychmiastowy event `shipment.created` oraz nowa akcja automatyzacji `update_shipment_status`. 1. Otworz: Ustawienia > Zadania automatyczne > Dodaj zadanie. 2. Sprawdz event "Utworzenie przesylki" i akcje "Zmiana statusu przesylki". 3. Utworz regule: event `shipment.created`, warunek integracji, akcja zmiany statusu przesylki. 4. Utworz przesylke z poziomu zamowienia i potwierdz, ze regula wykonala sie od razu (bez cron). 5. Potwierdz, ze ponowne odpalenie bez realnej zmiany statusu nie generuje petli. Type "approved" to continue, or describe issues to fix

DO NOT CHANGE

• database/migrations/* (brak zmian schematu w tej fazie)
• Logika eventu receipt.created i istniejace akcje poza wymaganym rozszerzeniem
• Moduly niezwiazane z automatyzacja i przesylkami

SCOPE LIMITS

• Tylko nowe zdarzenie i nowa akcja w module automatyzacji.
• Bez przebudowy calego silnika cron/tracking.
• Bez zmian UX poza formularzem i listowaniem automatyzacji.

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/Shipments/ShipmentController.php` - [ ] `C:\xampp\php\php.exe -l src/Modules/Shipments/ShipmentPackageRepository.php` - [ ] `C:\xampp\php\php.exe -l src/Modules/Cron/CronHandlerFactory.php` - [ ] `C:\xampp\php\php.exe -l resources/views/automation/form.php` - [ ] `C:\xampp\php\php.exe -l resources/views/automation/index.php` - [ ] Manual checkpoint wykonany (event dziala od razu + akcja statusu) - [ ] Dokumentacja zaktualizowana (`DOCS/ARCHITECTURE.md`, `DOCS/TECH_CHANGELOG.md`, `DOCS/todo.md`) - [ ] All acceptance criteria met

<success_criteria>

• Event shipment.created uruchamia automatyzacje natychmiast po utworzeniu przesylki.
• Akcja update_shipment_status jest dostepna, walidowana i dziala przewidywalnie.
• Brak petli automatyzacji przy ponownych wywolaniach bez zmiany statusu.
• Dokumentacja techniczna odzwierciedla nowy kontrakt event/action. </success_criteria>

After completion, create `.paul/phases/47-shipment-created-automation/47-01-SUMMARY.md`