Wiki

Automations.md

@@ -0,0 +1,98 @@
+# Automations a Funnel
+
+## Přehled
+
+Automační systém reaguje na eventy a pohybuje kontakty mezi stavy (sloupci) v segmentu. Při přechodu do nového sloupce se spouštějí akce (email, webhook, tag...).
+
+```
+FunnelEvent
+    │
+    ▼
+RulesEngine.evaluate()
+    │
+    ├─ Projde FunnelRule záznamy pro aktivní segmenty kontaktu
+    ├─ Vyhodnotí podmínky (when_event, conditions)
+    └─ Pokud pravidlo platí → FunnelState přesune kontakt do target_column
+               │
+               ▼
+        RunFunnelActionsJob
+               │
+               ▼
+        FunnelAction → ActionRunner → Driver
+```
+
+## Klíčové třídy
+
+| Třída | Popis |
+|-------|-------|
+| `RulesEngine` | Vyhodnocuje pravidla pro daný event a kontakt |
+| `FunnelAssigner` | Přiřazuje kontakt do segmentu (vytváří FunnelState) |
+| `ActionRunner` | Spouští akce pro daný FunnelState |
+| `DriverFactory` | Vrací správný driver podle typu akce |
+
+## Modely
+
+### FunnelRule
+Pravidlo triggeru a přechodu.
+
+| Pole | Popis |
+|------|-------|
+| `segment_id` | Ke kterému segmentu patří |
+| `when_event` | Event který pravidlo triggeruje (např. `cart_upsert`) |
+| `conditions` | JSON podmínky (payload hodnoty, tagy...) |
+| `target_column_id` | Cílový sloupec po splnění pravidla |
+| `apply_once` | Aplikovat jen jednou na kontakt |
+| `priority` | Pořadí vyhodnocení |
+
+### FunnelAction
+Akce spouštěná při přechodu do sloupce.
+
+| Pole | Popis |
+|------|-------|
+| `segment_id` | Příslušný segment |
+| `column_id` | Sloupec který spouští akci |
+| `trigger` | `on_enter` / `on_exit` / `scheduled` |
+| `type` | Typ akce (viz níže) |
+| `config` | JSON konfigurace akce |
+| `throttle` | Omezení frekvence spuštění |
+
+### FunnelState
+Aktuální pozice kontaktu v segmentu.
+
+| Pole | Popis |
+|------|-------|
+| `contact_id` | Kontakt |
+| `segment_id` | Segment |
+| `column_id` | Aktuální sloupec |
+
+## Typy akcí (Drivers)
+
+| Typ | Driver | Popis |
+|-----|--------|-------|
+| `send_mail` | `SendMailDriver` | Odeslání emailu |
+| `set_tag` | `SetTagDriver` | Přidání tagu kontaktu |
+| `set_flag` | `SetFlagDriver` | Nastavení příznaku |
+| `move_to_column` | `MoveToColumnDriver` | Přesun do jiného sloupce |
+| `webhook` | `WebhookDriver` | HTTP webhook |
+| `slack` | `SlackDriver` | Slack notifikace |
+| `notify` | `NotifyDriver` | Interní notifikace |
+| `internal_note` | `InternalNoteDriver` | Poznámka ke kontaktu |
+| `smartemailing_sync` | `SmartEmailingAddToListDriver` | Přidání do SmartEmailing listu |
+| `smartemailing_add_tag` | `SmartEmailingAddTagDriver` | Tag v SmartEmailing |
+| `smartemailing_unsubscribe` | `SmartEmailingUnsubscribeDriver` | Odhlášení v SmartEmailing |
+
+## Placeholders v akcích
+
+`PlaceholderReplacer` nahrazuje `{{contact.email}}`, `{{contact.name}}` apod. v textech akcí.
+
+## Replay
+
+Command `FunnelReplaySegment` / job `ReplaySegmentAutomationsJob` přehraje eventy pro všechny kontakty v segmentu – užitečné při změně pravidel.
+
+## Inaktivita
+
+Command `FunnelEvaluateInactivity` / job `FunnelInactivityJob` spouští pravidla pro kontakty které dlouho nevykazovaly aktivitu.
+
+## Naplánované akce
+
+`FunnelScheduledAction` – akce naplánované do budoucnosti (např. "pošli email za 3 dny"). Zpracovává `RunScheduledFunnelActionJob`.