feat(v1.5): complete phases 40-43 workflow cleanup
This commit is contained in:
198
.paul/phases/42-automation-shipment-status-event/42-01-PLAN.md
Normal file
198
.paul/phases/42-automation-shipment-status-event/42-01-PLAN.md
Normal file
@@ -0,0 +1,198 @@
|
||||
---
|
||||
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>
|
||||
Reference in New Issue
Block a user