update

2026-04-25 21:31:50 +02:00
parent 4931c55338
commit 4b998ea5be
16 changed files with 697 additions and 75 deletions
--- a/.paul/phases/107-automation-email-send-once/107-01-PLAN.md
+++ b/.paul/phases/107-automation-email-send-once/107-01-PLAN.md
@@ -0,0 +1,196 @@
+---
+phase: 107-automation-email-send-once
+plan: 01
+type: execute
+wave: 1
+depends_on: []
+files_modified:
+  - database/migrations/20260425_000102_create_automation_email_once_deliveries_table.sql
+  - src/Modules/Automation/AutomationController.php
+  - src/Modules/Automation/AutomationRepository.php
+  - src/Modules/Automation/AutomationService.php
+  - src/Modules/Automation/AutomationEmailOnceRepository.php
+  - resources/views/automation/form.php
+  - public/assets/js/modules/automation-form.js
+  - src/Modules/Cron/CronHandlerFactory.php
+  - tests/Unit/AutomationServiceTest.php
+  - .paul/docs/DB_SCHEMA.md
+  - .paul/docs/ARCHITECTURE.md
+  - .paul/docs/TECH_CHANGELOG.md
+autonomous: true
+delegation: off
+---
+
+<objective>
+## Goal
+Dodac w akcji automatyzacji `send_email` opcje "wyslij tylko raz na zamowienie", ktora gwarantuje, ze dla tej samej reguly i tego samego zamowienia ten sam mail nie zostanie wyslany ponownie przy kolejnych przebiegach crona.
+
+## Purpose
+Event `order.status_aged` jest uruchamiany cyklicznie. Bez mechanizmu idempotencji klient moze dostawac ten sam mail przy kazdym przebiegu. Potrzebujemy bezpiecznego "once per order", ale tylko tam, gdzie operator swiadomie zaznaczy taka opcje.
+
+## Output
+- Checkbox w konfiguracji akcji `Wyslij e-mail`: "Wyslij tylko raz dla tego zamowienia"
+- Trwale zapamietanie wysylki jednorazowej per `rule_id + action_id + order_id`
+- Logika wykonania, ktora pomija ponowna wysylke tylko dla akcji z wlaczonym checkboxem
+- Testy jednostkowe dla scenariusza jednorazowego i scenariusza domyslnego (wielokrotnego)
+</objective>
+
+<context>
+## Project Context
+@.paul/PROJECT.md
+@.paul/ROADMAP.md
+@.paul/STATE.md
+
+## Prior Work
+@.paul/phases/60-order-status-aged-event/60-01-SUMMARY.md
+
+## Source Files
+@src/Modules/Automation/AutomationController.php
+@src/Modules/Automation/AutomationRepository.php
+@src/Modules/Automation/AutomationService.php
+@src/Modules/Automation/OrderStatusAgedService.php
+@resources/views/automation/form.php
+@public/assets/js/modules/automation-form.js
+@src/Modules/Cron/CronHandlerFactory.php
+@database/migrations/20260318_000057_create_automation_tables.sql
+@database/migrations/20260328_000072_create_automation_execution_logs_table.sql
+</context>
+
+<skills>
+## Required Skills (from SPECIAL-FLOWS.md)
+
+| Skill | Priority | When to Invoke | Loaded? |
+|-------|----------|----------------|---------|
+| sonar-scanner (CLI) | required | Po APPLY, przed UNIFY | o |
+
+## Skill Invocation Checklist
+- [ ] sonar-scanner uruchomiony po wdrozeniu zmian
+</skills>
+
+<acceptance_criteria>
+
+## AC-1: Konfiguracja akcji e-mail ma opcje jednorazowej wysylki
+```gherkin
+Given operator tworzy lub edytuje zadanie automatyczne
+When wybierze akcje "Wyslij e-mail"
+Then widzi checkbox "Wyslij tylko raz dla tego zamowienia"
+And wartosc checkboxa zapisuje sie w action_config i wraca poprawnie po ponownej edycji reguly
+```
+
+## AC-2: Jednorazowa wysylka dziala per zamowienie
+```gherkin
+Given regula z eventem "order.status_aged" i akcja send_email z wlaczona opcja "wyslij tylko raz"
+And zamowienie pozostaje w tym samym statusie przez kolejne uruchomienia crona
+When cron wyzwoli te sama regule wielokrotnie dla tego samego zamowienia
+Then e-mail zostanie wyslany tylko podczas pierwszego udanego wykonania tej akcji
+And kolejne wykonania pominaja tylko te akcje e-mail, nie przerywajac pozostalych akcji reguly
+```
+
+## AC-3: Zachowanie domyslne pozostaje bez zmian
+```gherkin
+Given regula z akcja send_email bez zaznaczonej opcji "wyslij tylko raz"
+When event uruchomi regule wielokrotnie dla tego samego zamowienia
+Then e-mail moze byc wysylany wielokrotnie jak dotychczas
+```
+
+## AC-4: Oznaczenie "wyslano raz" powstaje tylko po sukcesie wysylki
+```gherkin
+Given pierwsza proba wysylki zakonczyla sie bledem
+When kolejny przebieg crona ponowi wykonanie
+Then system ponownie sprobuje wyslac e-mail
+And blokada jednorazowosci nie jest zapisana po nieudanej probie
+```
+
+</acceptance_criteria>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Dodac model danych jednorazowej wysylki i repozytorium idempotencji</name>
+  <files>database/migrations/20260425_000102_create_automation_email_once_deliveries_table.sql, src/Modules/Automation/AutomationEmailOnceRepository.php, src/Modules/Cron/CronHandlerFactory.php</files>
+  <action>
+    1. Dodac migracje tworzenia tabeli `automation_email_once_deliveries` z kolumnami:
+       - `id` (PK),
+       - `rule_id` (FK -> automation_rules.id),
+       - `action_id` (FK -> automation_actions.id),
+       - `order_id` (FK -> orders.id),
+       - `created_at`.
+    2. Dodac UNIQUE KEY na `(rule_id, action_id, order_id)` dla twardej deduplikacji.
+    3. Utworzyc `AutomationEmailOnceRepository` z metodami:
+       - `wasSent(int $ruleId, int $actionId, int $orderId): bool`
+       - `markSent(int $ruleId, int $actionId, int $orderId): void`
+    4. Podpiac repozytorium w `CronHandlerFactory` i konstruktorze `AutomationService`.
+  </action>
+  <verify>Uruchomienie migracji lokalnie konczy sie bez bledu, a tabela i indeks UNIQUE istnieja.</verify>
+  <done>AC-2 i AC-4 maja trwaly mechanizm danych.</done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Rozszerzyc konfiguracje akcji send_email o flage "send_once_per_order"</name>
+  <files>src/Modules/Automation/AutomationController.php, resources/views/automation/form.php, public/assets/js/modules/automation-form.js, src/Modules/Automation/AutomationRepository.php</files>
+  <action>
+    1. W `AutomationController::parseActionConfig()` dla `send_email` dodac bool `send_once_per_order` (0/1), domyslnie `0`.
+    2. W widoku formularza (`resources/views/automation/form.php`) dodac checkbox dla akcji e-mail:
+       `actions[idx][send_once_per_order]`.
+    3. W generatorze dynamicznym JS (`automation-form.js`) dodac ten sam checkbox przy dodawaniu nowej akcji e-mail.
+    4. Zachowac kompatybilnosc starych rekordow (brak pola = `false`).
+  </action>
+  <verify>Utworzenie i edycja reguly zapisuje/odczytuje checkbox poprawnie; brak regresji dla innych typow akcji.</verify>
+  <done>AC-1 i AC-3 sa spelnione po stronie konfiguracji.</done>
+</task>
+
+<task type="auto">
+  <name>Task 3: Wdrozyc wykonanie jednorazowe w AutomationService i testy</name>
+  <files>src/Modules/Automation/AutomationService.php, tests/Unit/AutomationServiceTest.php, .paul/docs/DB_SCHEMA.md, .paul/docs/ARCHITECTURE.md, .paul/docs/TECH_CHANGELOG.md</files>
+  <action>
+    1. W `AutomationService::executeActions()` przekazac `ruleId` i `actionId` do obslugi send_email.
+    2. W `handleSendEmail()`:
+       - odczytac `send_once_per_order`,
+       - gdy flaga aktywna: sprawdzic `wasSent(...)`; jesli true, pominac akcje e-mail,
+       - po udanej wysylce (bez wyjatku): zapisac `markSent(...)`.
+    3. Nie oznaczac jako wyslane przy bledzie wysylki (wyjatek -> brak `markSent`).
+    4. Dodac testy:
+       - `send_once_per_order=true` -> druga proba nie wywoluje `EmailSendingService::send`,
+       - `send_once_per_order=false` -> kolejne proby wysylaja dalej.
+    5. Zaktualizowac `.paul/docs/DB_SCHEMA.md`, `.paul/docs/ARCHITECTURE.md`, `.paul/docs/TECH_CHANGELOG.md`.
+  </action>
+  <verify>`php vendor/bin/phpunit tests/Unit/AutomationServiceTest.php` przechodzi; test reczny cron potwierdza pojedyncza wysylke dla zaznaczonej opcji.</verify>
+  <done>AC-2, AC-3, AC-4 sa spelnione end-to-end.</done>
+</task>
+
+</tasks>
+
+<boundaries>
+
+## DO NOT CHANGE
+- Logika eventow i warunkow automatyzacji niezwiązanych z `send_email`
+- Mechanizmy wysylki e-mail poza potrzebnym miejscem integracji w `AutomationService`
+- Runtime konfiguracji DB hostow (`DB_HOST` / `DB_HOST_REMOTE`)
+
+## SCOPE LIMITS
+- Brak nowych eventow automatyzacji
+- Brak zmian w harmonogramie crona `order_status_aged`
+- Brak zmian UI listy historii poza tym, co konieczne do konfiguracji checkboxa
+
+</boundaries>
+
+<verification>
+Before declaring plan complete:
+- [ ] Migracja tworzy tabele i UNIQUE KEY dla deduplikacji
+- [ ] Checkbox "wyslij tylko raz" dziala przy create/edit reguly
+- [ ] Dla `send_once_per_order=1` e-mail idzie tylko raz na zamowienie
+- [ ] Dla `send_once_per_order=0` zachowanie pozostaje bez zmian
+- [ ] `php vendor/bin/phpunit tests/Unit/AutomationServiceTest.php` przechodzi
+- [ ] Dokumentacja `.paul/docs/*` zaktualizowana
+</verification>
+
+<success_criteria>
+- Operator moze wlaczyc jednorazowa wysylke per zamowienie bez zmian kodu
+- Cron nie wysyla duplikatow dla tej samej jednorazowej akcji e-mail
+- Brak regresji istniejacych automatyzacji e-mail
+- Plan gotowy do uruchomienia przez `$paul-apply`
+</success_criteria>
+
+<output>
+After completion, create `.paul/phases/107-automation-email-send-once/107-01-SUMMARY.md`
+</output>