Automatizace — N8N-style workflow engine

Vizuální editor automatizací věrný N8N. Workflow = graf uzlů propojených hranami; data protékají jako pole items (JSON). Model i ovládání kopírují N8N: multi-output větve (IF má true/false, Switch N výstupů), výrazy {{ $json.pole }}, smyčky po dávkách, per-uzel izolace chyb a log každého běhu s daty pro panely vstupu/výstupu.

Po zapnutí pluginu přibude v adminu Pluginy → Automatizace.

Architektura (proč „plugin")

Cílem plugin balíčku je nebobtnat binárku ani admin.wasm:

• Čisté jádro (automation-core/ crate) — typy grafu, výrazy, podmínky, katalog uzlů, čisté transformace a validace + topologické pořadí. Kompiluje se nativně do API i do wasm fasády → jediný zdroj pravdy, žádný type drift.
• Engine (api/src/automation/) — orchestrace běhu (graf + smyčky), akční uzly s IO (e-mail/HTTP/log), čekání, dispatch doménových událostí. Žije v jádru API (rozhodnutí: „prostě v jádru"), ale je za runtime vypínačem (Nastavení → Funkce → automation).
• Editor — thin JS canvas (admin/static/automation-editor/) hostovaný v adminu přes <iframe>. Katalog uzlů, počty portů, validaci grafu i náhled výrazů volá přes wasm fasádu automation-core-js (stejný vzor jako wave-core-js) → nula bajtů navíc v admin.wasm (Leptos bundlu).

Plugin je tedy deklarativní descriptor — Riplet nikdy nespouští jeho kód (viz docs/plugins.md). Chování je v jádru, tady je metadata + dokumentace.

Typy uzlů

Typ	Kategorie	Vstupy	Výstupy	Popis
trigger.event	trigger	0	1	Doménová událost (inquiry.created, form.submitted, subscriber.confirmed)
trigger.schedule	trigger	0	1	Interval v minutách (scheduler)
trigger.webhook	trigger	0	1	POST /api/automation/webhook/{path}
trigger.manual	trigger	0	1	Jen ruční spuštění z editoru
logic.if	logic	1	2 (true/false)	Rozvětvení podle podmínek
logic.filter	logic	1	1	Propustí jen items splňující podmínky
logic.switch	logic	1	N (dle pravidel)	Routing do víc výstupů, volitelný fallback
logic.merge	logic	2	1	Append / spojení podle pořadí / podle klíče / výběr větve
logic.wait	logic	1	1	Pauza (strop 300 s)
logic.split_batches	logic	1	2 (loop/done)	Dávkování se smyčkou (N8N „Loop Over Items")
transform.set	transform	1	1	Nastaví/přepíše pole z výrazů
transform.code	transform	1	1	JSON šablona s výrazy (žádný JS runtime)
transform.aggregate	transform	1	1	Sloučí proud do jednoho itemu
transform.datetime	transform	1	1	Formátování / posun data a času
transform.sort	transform	1	1	Řazení podle polí
transform.limit	transform	1	1	Prvních/posledních N items
transform.remove_duplicates	transform	1	1	Odstranění duplicit
core.noop	transform	1	1	Průchozí (spojka větví)
core.sticky	note	0	0	Poznámka na plátně (engine ignoruje)
action.email	action	1	1	Zařadí e-mail do fronty
action.http_request	action	1	1	HTTP volání (opt-in, SSRF guard)
action.log	action	1	1	Zápis do tracing + audit logu

Uzel lze vypnout (disabled) — zůstane v grafu i s hranami, ale při běhu jen propustí data dál (N8N „deactivate").

Smyčky

logic.split_batches je jediný uzel, do kterého smí vést zpětná hrana: tělo smyčky se vrací na jeho vstup, uzel vydá další dávku a po vyčerpání pošle nasbíraná data na výstup done. Validace takovou hranu nepovažuje za cyklus (validate::back_edges), editor ji kreslí čárkovaně. Počet iterací je zastropován (1000) a vnořené smyčky podporované nejsou.

Výrazy

Textová pole podporují {{ … }} vsuvky (bezpečná podmnožina, žádný JS runtime):

• {{ $json }} / {{ $json.contact.email }} / {{ $json["a"]["b"] }} — aktuální item
• {{ $node["Název"].json.pole }} — výstup pojmenovaného uzlu
• {{ $now }} (RFC3339) / {{ $today }} (YYYY-MM-DD)
• literály: "text", čísla, true/false/null
• Celé pole = jediný {{ výraz }} → zachová typ; jinak string interpolace. Vedoucí = značí výrazové pole (jako v N8N).

Editor u každého výrazového pole ukazuje živý náhled vyhodnocený stejnou funkcí, kterou použije engine (automation_core::expr přes wasm) — náhled tedy nemůže lhát.

Editor

• Plátno — tečkovaná mřížka, posun tažením, zoom kolečkem, přichycení do mřížky (Alt vypíná), minimapa, ovládání přiblížení.
• Uzly — čtvercové dlaždice s ikonou a názvem pod nimi, hover toolbar (spustit krok, vypnout, duplikovat, smazat), odznak s počtem items posledního běhu a počtem iterací.
• Hrany — bezier s tlačítky „vložit uzel doprostřed" a „smazat", popisky větví (ano/ne, smyčka/hotovo).
• Přidání uzlu — Tab, „+" vpravo nahoře, „+" na volném výstupu nebo puštění hrany do prázdna; panel má fulltext a ovládá se šipkami.
• Detail uzlu (NDV) — dvojklik: VSTUP │ PARAMETRY │ VÝSTUP, data v pohledech Tabulka / JSON / Schéma, tlačítko „Spustit krok" (běh se zastaví po tomto uzlu, navazující akce se nevykonají).
• Exekuce — záložka se seznamem běhů; klik na uzel přenese data běhu na plátno.
• Ostatní — undo/redo, výběr rámečkem, kopírovat/vložit, kontextové menu, poznámky (sticky notes), klávesové zkratky.

Texty editoru jsou i18n (admin/i18n/*.json, klíče auto.*); jazyk a motiv předává admin v query parametrech iframu.

Bezpečnost

• Runtime vypínač — vypnutá funkce automation (Nastavení → Funkce) NIKDY nespustí žádné workflow (event, plán ani webhook).
• HTTP uzel opt-in — site_settings.automation.allow_http (default false). SSRF guard blokuje loopback/privátní rozsahy (IPv4 i IPv6, včetně IPv4-mapped), jen http/https, redirecty se nenásledují.
• Žádný JS runtime — „Code" uzel je JSON šablona s výrazy, ne interpret.
• Per-uzel izolace — chyba akce neblokuje ostatní větve a je vidět v logu exekucí i v audit logu.
• Validace grafu — cykly, viset. hrany a neplatné porty se odmítnou při uložení i před během.
• Limity běhu — 1000 iterací smyčky, 300 s čekání, vzorek dat v logu ořezaný (20 items na větev / 32 kB na uzel).

Instalace / ověření

Plugin se instaluje z katalogu: Admin → Pluginy → Dostupné → Instalovat. Ověřit balíček ze zdrojů jde i ručně:

sh registry/plugins/automation/run.sh

Skript jen validuje balíček (JSON manifest). Funkce samotná je vestavěná v jádru — zapne se v Admin → Nastavení → Funkce, položka menu se objeví po zapnutí pluginu v Admin → Pluginy.