199 lines
8.5 KiB
Markdown
199 lines
8.5 KiB
Markdown
---
|
|
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>
|