orderPRO/.paul/phases/49-automation-history-tab/49-01-PLAN.md

---
phase: 49-automation-history-tab
plan: 01
type: execute
wave: 1
depends_on: []
files_modified:
  - database/migrations/20260328_000072_create_automation_execution_logs_table.sql
  - src/Modules/Automation/AutomationExecutionLogRepository.php
  - src/Modules/Automation/AutomationRepository.php
  - src/Modules/Automation/AutomationService.php
  - src/Modules/Automation/AutomationController.php
  - resources/views/automation/form.php
  - public/assets/js/modules/automation-form.js
  - resources/views/automation/index.php
  - resources/scss/modules/_automation.scss
  - public/assets/css/app.css
  - src/Modules/Cron/CronHandlerFactory.php
  - src/Modules/Cron/AutomationHistoryCleanupHandler.php
  - routes/web.php
  - DOCS/DB_SCHEMA.md
  - DOCS/ARCHITECTURE.md
  - DOCS/TECH_CHANGELOG.md
autonomous: false
---

<objective>
## Goal
Rozdzielic ekran `/settings/automation` na dwa taby: `Ustawienia` (obecna lista i zarzadzanie regulami) oraz `Historia` (log wykonan automatyzacji z filtrami i paginacja), oraz dodac nowa akcje automatyzacji `zmien status zamowienia` z wyborem statusu docelowego.

## Purpose
Operator musi widziec kiedy i na jakim zamowieniu uruchomila sie automatyzacja (audyt) oraz miec mozliwosc automatycznej zmiany statusu zamowienia przez regule bez recznej ingerencji.

## Output
Nowa historia wykonan automatyzacji zapisywana w dedykowanej tabeli, UI historii w tabie `Historia` z filtrowaniem i paginacja, automatyczne czyszczenie wpisow starszych niz 30 dni oraz nowa akcja reguly `update_order_status` w formularzu automatyzacji.
</objective>

<context>
## Project Context
@.paul/PROJECT.md
@.paul/ROADMAP.md
@.paul/STATE.md
@DOCS/DB_SCHEMA.md
@DOCS/ARCHITECTURE.md

## Prior Work (only if genuinely needed)
@.paul/phases/16-automated-tasks/16-02-SUMMARY.md
@.paul/phases/47-shipment-created-automation/47-01-SUMMARY.md

## Source Files
@src/Modules/Automation/AutomationController.php
@src/Modules/Automation/AutomationRepository.php
@src/Modules/Automation/AutomationService.php
@resources/views/automation/form.php
@public/assets/js/modules/automation-form.js
@resources/views/automation/index.php
@resources/scss/modules/_automation.scss
@src/Modules/Cron/CronHandlerFactory.php
@src/Modules/Cron/CronRepository.php
@resources/views/settings/cron.php
@routes/web.php
</context>

<skills>
## Required Skills (from SPECIAL-FLOWS.md)

| Skill | Priority | When to Invoke | Loaded? |
|-------|----------|----------------|---------|
| `sonar-scanner` | required | Po APPLY, przed UNIFY | o |
| /frontend-design | optional | Przy dopracowaniu ukladu tabow i tabeli historii | 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
- [ ] /frontend-design (opcjonalnie)
- [ ] /code-review (opcjonalnie)

</skills>

<acceptance_criteria>

## AC-1: Zakladka automatyzacji ma dwa taby z rozdzielonym zakresem
```gherkin
Given uzytkownik otwiera `/settings/automation`
When laduje sie ekran
Then widzi tab `Ustawienia` z obecna lista regul i akcjami CRUD
And widzi tab `Historia` z lista wykonan automatyzacji
```

## AC-2: Historia pokazuje co, kiedy i dla jakiego zamowienia
```gherkin
Given regula automatyzacji zostala wywolana przez trigger
When wykonanie reguly zakonczy sie sukcesem lub bledem
Then system zapisuje wpis historii zawierajacy co najmniej: event_type, rule_id/rule_name, order_id, status wykonania i timestamp
And wpis jest widoczny w tabie `Historia`
```

## AC-3: Historia wspiera filtrowanie i paginacje
```gherkin
Given tab `Historia` zawiera wpisy z wielu regul i zdarzen
When uzytkownik uzyje filtrow (np. event, status, rule, order_id, zakres dat) i zmieni strone
Then widok pokazuje tylko pasujace rekordy
And paginacja zachowuje aktywne filtry
```

## AC-4: Wpisy starsze niz 30 dni sa usuwane automatycznie
```gherkin
Given historia zawiera wpisy starsze niz 30 dni
When uruchomi sie harmonogram czyszczenia
Then wpisy starsze niz 30 dni zostana usuniete
And nowsze wpisy pozostaja bez zmian
```

## AC-5: Dokumentacja odzwierciedla nowy kontrakt historii automatyzacji
```gherkin
Given wdrozono nowa tabele i flow zapisu historii automatyzacji
When zespol czyta dokumentacje techniczna
Then `DOCS/DB_SCHEMA.md`, `DOCS/ARCHITECTURE.md` i `DOCS/TECH_CHANGELOG.md` opisuja nowe elementy
```

## AC-6: Automatyzacja obsluguje akcje zmiany statusu zamowienia
```gherkin
Given uzytkownik tworzy lub edytuje regule na `/settings/automation/create`
When wybierze akcje `Zmien status zamowienia` i wskaze status docelowy
Then konfiguracja zapisuje sie poprawnie
And po triggerze reguly status zamowienia jest zmieniany na wskazany status
And aktualizacja statusu jest zapisana zgodnie z obecnym flow historii statusow/activity log
```

</acceptance_criteria>

<tasks>

<task type="auto">
  <name>Task 1: Dodaj model danych historii wykonania automatyzacji i retencje 30 dni</name>
  <files>database/migrations/20260328_000072_create_automation_execution_logs_table.sql, src/Modules/Automation/AutomationExecutionLogRepository.php, src/Modules/Cron/AutomationHistoryCleanupHandler.php, src/Modules/Cron/CronHandlerFactory.php</files>
  <action>
    Dodaj migracje tworzaca tabele historii wykonan automatyzacji (`automation_execution_logs`) z indeksami pod filtry i sortowanie po czasie.
    Dodaj repozytorium historii z metodami: insert wpisu wykonania, paginowane pobieranie z filtrami, count, purgeOlderThanDays(30).
    Dodaj handler crona do cyklicznego usuwania starych wpisow i podlacz go w `CronHandlerFactory`.
    Dodaj seed harmonogramu cleanup (`automation_history_cleanup`) tak, aby dzialal automatycznie bez recznej konfiguracji.
    Trzymaj sie medoo/prepared statements i bez laczenia SQL stringiem przez wartosci dynamiczne.
  </action>
  <verify>rg -n "automation_execution_logs|automation_history_cleanup|purgeOlderThanDays|AutomationHistoryCleanupHandler" database/migrations src/Modules/Automation src/Modules/Cron</verify>
  <done>AC-2 satisfied i AC-4 satisfied: dane historii sa zapisywane i maja automatyczna retencje 30 dni.</done>
</task>

<task type="auto">
  <name>Task 2: Rozszerz AutomationService i kontroler o zapis historii oraz endpoint listowania</name>
  <files>src/Modules/Automation/AutomationService.php, src/Modules/Automation/AutomationController.php, src/Modules/Automation/AutomationRepository.php, routes/web.php</files>
  <action>
    W `AutomationService::trigger` dodaj rejestracje wykonania per regula (co najmniej: event_type, rule_id, rule_name, order_id, result_status, result_message, executed_at), z logowaniem sukcesu i bledow bez zatrzymywania kolejnych regul.
    Rozszerz `AutomationController::index` o obsluge query filtrow i paginacji historii oraz przekazanie danych do widoku.
    Dodaj potrzebne metody repository do listowania filtrow pomocniczych (np. aktywne reguly/eventy) jesli sa potrzebne do UI.
    Zadbaj, aby filtry/paginacja historii nie ingerowaly w istniejaca liste regul i zachowaly kompatybilnosc obecnych akcji CRUD.
  </action>
  <verify>rg -n "execution log|history|history_page|history_filters|logExecution|automation history" src/Modules/Automation routes/web.php</verify>
  <done>AC-2 satisfied i AC-3 satisfied: backend dostarcza pelna historie z filtrowaniem i paginacja.</done>
</task>

<task type="auto">
  <name>Task 3: Dodaj akcje `update_order_status` do automatyzacji (backend + formularz)</name>
  <files>src/Modules/Automation/AutomationController.php, src/Modules/Automation/AutomationService.php, resources/views/automation/form.php, public/assets/js/modules/automation-form.js</files>
  <action>
    Rozszerz `ALLOWED_ACTION_TYPES` o nowa akcje `update_order_status` oraz walidacje konfiguracji tej akcji.
    W `AutomationService` dodaj wykonanie akcji aktualizacji statusu zamowienia przez istniejacy, centralny flow domenowy (z zachowaniem wpisu historii statusow i activity log).
    W formularzu automatyzacji dodaj nowa opcje akcji `Zmien status zamowienia` oraz selector statusu docelowego oparty o aktywne statusy orderPRO.
    Utrzymaj zgodnosc create/edit i dynamicznego JS dodajacego kolejne akcje.
  </action>
  <verify>rg -n "update_order_status|Zmien status zamowienia|order_status|action_type" src/Modules/Automation resources/views/automation public/assets/js/modules/automation-form.js</verify>
  <done>AC-6 satisfied: nowa akcja jest konfigurowalna i zmienia status zamowienia.</done>
</task>

<task type="auto">
  <name>Task 4: Zbuduj UI dwoch tabow (Ustawienia/Historia) i zaktualizuj dokumentacje</name>
  <files>resources/views/automation/index.php, resources/scss/modules/_automation.scss, public/assets/css/app.css, DOCS/DB_SCHEMA.md, DOCS/ARCHITECTURE.md, DOCS/TECH_CHANGELOG.md</files>
  <action>
    Przebuduj widok `/settings/automation` na taby zgodne ze stylem projektu (`content-tabs-nav` / `content-tab-panel`):
    - tab `Ustawienia`: zachowuje obecna liste regul i akcje,
    - tab `Historia`: tabela historii + formularz filtrow + paginacja.
    Zachowaj kompaktowy layout (male odstepy, duza gestosc informacji) i brak natywnych `alert()/confirm()`.
    Dodaj/uzupelnij style SCSS tylko w plikach SCSS, a nastepnie przebuduj CSS.
    Zaktualizuj dokumentacje techniczna o nowa tabele historii oraz nowa akcje `update_order_status`.
  </action>
  <verify>rg -n "content-tabs-nav|Historia|Ustawienia|automation history|30 dni|automation_execution_logs|update_order_status" resources/views/automation/index.php resources/scss/modules/_automation.scss DOCS/DB_SCHEMA.md DOCS/ARCHITECTURE.md DOCS/TECH_CHANGELOG.md</verify>
  <done>AC-1 satisfied i AC-5 satisfied: UI i dokumentacja sa zgodne z nowa funkcjonalnoscia.</done>
</task>

<task type="checkpoint:human-verify" gate="blocking">
  <what-built>Tab `Historia` na `/settings/automation` z filtrowaniem i paginacja, automatyczna retencja wpisow 30 dni oraz akcja `Zmien status zamowienia`.</what-built>
  <how-to-verify>
    1. Otworz: `https://orderpro.projectpro.pl/settings/automation`.
    2. Potwierdz obecnosc tabow: `Ustawienia` i `Historia`.
    3. W tabie `Historia` ustaw filtry (event, status, order ID lub zakres dat) i sprawdz czy lista oraz licznik/paginacja sa zgodne.
    4. Wywolaj testowo regule automatyzacji i potwierdz pojawienie sie nowego wpisu (co, kiedy, jakie zamowienie).
    5. W `Ustawienia > Zadania automatyczne > Dodaj zadanie` wybierz akcje `Zmien status zamowienia`, ustaw status docelowy i zapisz regule.
    6. Wyzwol regule i potwierdz realna zmiane statusu zamowienia na wybrany status.
    7. Potwierdz dzialanie cleanupu wpisow >30 dni (przez uruchomienie joba cron lub test na danych historycznych).
  </how-to-verify>
  <resume-signal>Type "approved" to continue, or describe issues to fix</resume-signal>
</task>

</tasks>

<boundaries>

## DO NOT CHANGE
- Logika tworzenia/edycji reguly automatyzacji poza koniecznymi zmianami pod nowe taby.
- Istniejace flow wysylki e-mail/paragonow/statusow przesylki poza dodaniem logowania wykonan.
- Istniejace flow zmiany statusu zamowienia poza rozszerzeniem go jako nowej akcji automatyzacji.
- Konfiguracja runtime DB host (`DB_HOST` pozostaje runtime; bez podpinania `DB_HOST_REMOTE`).

## SCOPE LIMITS
- Zakres dotyczy tylko ekranu `/settings/automation` i warstwy historii automatyzacji.
- Zakres obejmuje dodanie jednej nowej akcji automatyzacji: `update_order_status`.
- Bez zmian w innych ekranach ustawien.
- Bez dodatkowych funkcji biznesowych automatyzacji niezwi¹zanych z historia.

</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/AutomationRepository.php`
- [ ] `C:\xampp\php\php.exe -l src/Modules/Automation/AutomationExecutionLogRepository.php`
- [ ] `C:\xampp\php\php.exe -l src/Modules/Automation/AutomationService.php`
- [ ] `C:\xampp\php\php.exe -l src/Modules/Cron/CronHandlerFactory.php`
- [ ] `C:\xampp\php\php.exe -l src/Modules/Cron/AutomationHistoryCleanupHandler.php`
- [ ] `C:\xampp\php\php.exe -l resources/views/automation/form.php`
- [ ] `C:\xampp\php\php.exe -l resources/views/automation/index.php`
- [ ] Migracja wykonuje sie poprawnie i tworzy indeksy historii
- [ ] Test paginacji/filtrow historii przechodzi
- [ ] Test akcji `update_order_status` przechodzi (zapis + wykonanie + zmiana statusu)
- [ ] Test cleanupu wpisow >30 dni przechodzi
- [ ] Dokumentacja zaktualizowana (`DOCS/DB_SCHEMA.md`, `DOCS/ARCHITECTURE.md`, `DOCS/TECH_CHANGELOG.md`)
- [ ] All acceptance criteria met
</verification>

<success_criteria>
- `/settings/automation` ma dwa taby: `Ustawienia` i `Historia`.
- Historia pokazuje wykonania regul (co, kiedy, order) i ma filtry + paginacje.
- Akcja `Zmien status zamowienia` jest dostepna i poprawnie zmienia status na wybrany przez uzytkownika.
- Wpisy starsze niz 30 dni sa usuwane automatycznie.
- Dokumentacja techniczna odzwierciedla nowy model i przeplyw.
</success_criteria>

<output>
After completion, create `.paul/phases/49-automation-history-tab/49-01-SUMMARY.md`
</output>