197 lines
8.4 KiB
Markdown
197 lines
8.4 KiB
Markdown
---
|
|
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>
|