Trigerite käsiraamat

Mootoris on kaks eraldiseisvat trigeri-süsteemi, mida kergesti segi aetakse:

• Mootori sisemised trigerid — öised tuvastajad, mis toidavad soovitus-konveierit. Need EI saada ise midagi; nende väljund muutub rec_-soovitusteks ja rec_active_triggers väljaks (vt Smaily mallid).
• Mootori käivitatavad automatsioonid — väiksem alamhulk trigereid, mille saad pluginas/adminis sisse lülitada, et mootor ise kontakti sinu Smaily automatsiooni enrollikäivitaks (Smaily mallid → mootori käivitatavad automatsioonid annab kasutus-juhendi; see leht annab täpsed numbrid).

See leht on numbrite allikas: iga lävend, aken ja cooldown on kontrollitud otse koodist (lib/engine/triggers/, lib/automations/, sektoripakkide triggers.yaml), mitte spetsifikatsiooni-kavatsusest. Kus mootor lubab rohkem, kui ta täna teeb, on see siin selgelt kirjas.

Kuidas trigerid öisesse ahelasse sobituvad#

Kõik ajad on Europe/Tallinn serveri-graafiku järgi:

Mootori sisemised trigerid (soovituste taga)#

Need kümme detektorit on koodis olemas (lib/engine/triggers/index.ts). Kas ja millise sektoripaki puhul üks neist päriselt kandidaate tekitab, otsustab sektoripaki triggers.yaml status-väli — sama detektor-kood teenindab kõiki sektoreid, aga iga pakk lülitab endale sobivad trigerid sisse.

Fashion ja Alcohol pakid on sisustatud, aga ühtki tenant'i nende peal veel ei jookse, seega praktikas nende trigerid midagi ei tuvasta. Travel ja Consumer Electronics on endiselt stub-pakid (manifest + tühi edges.yaml, CLAUDE.md §1) ilma triggers.yaml failita.

Kategooria-ostu järelsoovitus — purchase_in_category#

Käivitub kliendi kategooria-ostu põhjal cross-sell/taastäitumis/avastus- soovitustega. Ei nõua korduvostu — käivitub juba esimesest ostust selles kategoorias (erinevalt cadence_window_reached-ist, mis nõuab vähemalt 3 kordusostu).

• Käivitub, kui: kliendil on lõpetatud/töötlemisel tellimus kategoorias C viimase window_days päeva jooksul. Üks kandidaat per (klient, kategooria); ankur-toode = kategooria viimati ostetud SKU (viigi puhul suurima reasummaga).
• Aken: 30 päeva (Pet, FMCG) / 45 päeva (Beauty).
• Cooldown: 14 päeva (Pet, FMCG) / 21 päeva (Beauty, Fashion, Alcohol) — sama klient+kategooria ei käivita enne uuesti.

Taastäitumise aken — cadence_window_reached#

Käivitub, kui korduvtoode hakkab kliendi ENDA ostu-rütmi järgi otsa saama.

• Käivitub, kui: now >= ennustatud_järgmine_ost − 15% × mediaan-intervall (puhver-tegur 0,85) JA kliendil on vähemalt 3 kinnitatud kordusostu sama toote/toote-pere kohta (n_observations >= 3) JA ostu-rütmi usaldus ≥ 0,5.
• Cooldown: 14 päeva (Pet, Beauty, Alcohol) / 7 päeva (FMCG) / 30 päeva (Fashion) — toote-pere-teadlik: kui sama pere mõni teine variant sai soovituse hiljuti, ei käivitu see toote jaoks uuesti (variandivahetus ei tekita topelt-kirja).
• Tuvastuse cooldown: 5 päeva kliendi+toote kohta, loetuna selle trigeri eelmisest kandidaadist. Taastäitumise aken püsib avatud nädalaid, seega ilma selleta tuvastataks sama toode iga öö uuesti; teise toote otsa saamist see ei puuduta — see käivitub samal ööl.
• Ostu-rütmi andmed (mediaan-intervall, tarbimiskiiruse tegur, usaldus) arvutatakse 03:30 kalibratsioonis, enne 04:00 trigerite-tuvastust.

Korvist loobumine — cart_abandonment (väljas)#

Detektori kood on olemas ja töökorras (24-72h aken pärast korvi-lingi klikki, cooldown 7 päeva), aga Pet-pakis on staatus stub — ta EI tuvasta täna ühtki kandidaati üheski sektoris. Põhjus: ükski edges_universal reegel ei kanna trigger_type='cart_abandonment'-i — kirjutamata edge tähendaks "soovita kogu kataloogi"; selleks, et pakkuda "1 turvaline kaaslane", on vaja korvi SISU, mis eeldab sirvimis-jälgimise Variant B-d (backlog, vt CLAUDE.md §14.2).

Tagasivõidetud klikkija — dormant_to_clicker#

Käivitub, kui kaua vaikinud klient näitab värsket elumärki (avamine või klikk) — tagasivõitmise hetk.

• Käivitub, kui (kaks juhtu, VÕI):
  1. klient on ikka veel dormant-seisundis, on olnud seal ≥60 päeva, JA on viimase 7 päeva jooksul kirja avanud või klõpsanud (katab avamise-põhise ärkamise, sest kaasatuse öine cron lülitab seisundit ümber ainult KLIKI peale, mitte avamise peale);
  2. klient on 03:00 crooniga äsja (viimase 8 päeva jooksul) tõusnud seisundisse won_back_recent JA on viimase 7 päeva jooksul kirja avanud või klõpsanud (see on tänane elav rada — cron on kliendi juba "päästnud", enne kui trigerite-tuvastus jõuab kohale).
• Cooldown: 30 päeva kõigis viies populeeritud sektoripakis, loetuna selle trigeri eelmisest kandidaadist.
• Kaks katset, siis stopp: "katse" on üks selle trigeri kandidaat, mille öine väljastus päriselt ära kasutas, loetuna kliendi viimasest ostust alates. Pärast kahte klient enam kandidaadiks ei kvalifitseeru, kuni ta uuesti ostab — vastus tagasivõitmisele on ost, ja ost nullib ka loenduri. Värske KLIKK loendurit ei nulli: trigger käivitubki kliki peale, seega kliki-nullimine tähendaks, et piir ei rakendu kunagi kellelegi. Piiri täis saanud klient saab oma üheksa soovitust endiselt kätte, lihtsalt ilma järjekordse "tule tagasi" pakkumiseta.
• Ankur-toode soovituste jaoks: kliendi enim ostetud toode (tõestatud lemmik, mitte uudistoode).

Ostu poolest lapsed, aga avab kirju — purchase_lapsed_opener (ainult Fashion)#

dormant_to_clicker-i teine pool: too räägib KIRJADE vaikusest ja lõpeb klikiga. See siin räägib kliendist, kes lõpetas ostmise, aga avab endiselt kirju — moerõivastes on see tüüpiline lapsed klient, ja kliki nõudmine hoidis tagasivõitmise ukse peaaegu kõigi ees kinni.

• Käivitub, kui: ostu pole 180 päeva JA kiri on avatud viimase 30 päeva jooksul JA kliendil on alla kahe vastuseta katse (vt allpool).
• Ankur: täpselt ÜKS kategooria — kliendi enim alles jäetud toode ja selle kategooria. Tagasivõitmine jääb selle kategooria sisse.
• Kaks katset, siis stopp (sama loendur mis dormant_to_clicker-il ülal): "katse" on üks selle trigeri kandidaat, mille öine väljastus päriselt ära kasutas, loetuna kliendi viimasest ostust alates. Pärast kahte klient enam kandidaadiks ei kvalifitseeru. Eraldi "kas vastati" kontrolli pole: vastus tagasivõitmisele on ost, mis nii lõpetab 180-päevase lapse kui nullib loenduri.
• Cooldown: 60 päeva.
• Ainult Fashion-pakk deklareerib selle; teistes pakkides pole trigerit defineeritud, seega detektor ei tagasta neile midagi.

Elufaasi üleminek — life_stage_transition_due (ainult lemmikloomapood)#

Käivitub, kui lemmiklooma vanus ületab elufaasi piiri: kutsikas/kassipoeg → täiskasvanu 12 kuu vanuselt; täiskasvanu → senior (koer 7 aastat / 84 kuud, kass 11 aastat / 132 kuud).

• Käivitub, kui: customers.inferred_attributes.pet_age_months on teada JA jääb vahemikku [lävend, lävend + 1) kuud (30-päevane tagasivaateaken, öine cron tabab ülemineku alati) JA kliendil EI ole sama liigi jaoks noore-elufaasi (kassipoeg/kutsikas) ostu ja täiskasvanu/seenior-ostu, mis jäävad teineteisest 6 kuu sisse — kõva konfliktilüliti, mis välistab trigeri tõenäolise mitme-lemmiku või kingituse-ostu majapidamise puhul, kus vanuse-põhine üleminek saadaks vale elufaasi kirja.
• Cooldown: 365 päeva, loetuna selle trigeri eelmisest kandidaadist (elufaasi üleminek juhtub korra elus). Sama cooldown hoiab ära selle, et kuu laiune vanuse-aken tekitaks kandidaadi igal ööl.
• Kust vanus tuleb, usalduse järjekorras:
  1. Registreerimise sünnikuupäev — plugina registreerimisväli, mille klient ise täidab. Täpne, aga peaaegu ükski pood ei kogu seda.
  2. Ostu-ankruga vanuse-ajajoon (PRO-1569) — kliendi ESIMENE kassipoja/kutsika toote ost käivitab kella ja lemmikut käsitletakse sel hetkel vastsündinuna. Nii saadud vanus on teadlikult alahinnang (lemmik oli selle toidu ostmise ajal juba mõni nädal või kuu vana), seega üleminek jõuab pigem hiljaks kui liiga vara — see on "aeg toitu vahetada" kirja jaoks ohutu suund. Kella võib käivitada AINULT noore-elufaasi ost: ainult täiskasvanutoitu ostnud klient ei saa vanust üldse, sest "12 kuud vana" eeldus võltsiks tal ülemineku kohe esimese tellimuse pealt. Hilisem täiskasvanu/seenior-ost käivitab kella uuesti sellest ostust, nii et järgmist piiri mõõdetakse nähtud üleminekust. Sünnikuupäev võidab alati, kui see olemas on.
• Aus staatus: ajajoonega käivitub trigger päris klientidele, aga ainult neile vähestele, kelle ostud kannavad elufaasi-silti — pood, mille tootenimed ei ütle kunagi "kitten" või "puppy", ei anna siin ikka midagi.

Esmakordne ost kategoorias — category_first_purchase (väljas Pet'is)#

Käivitub kliendi ESIMESE ostu peale terves kategooria-peres (nt esimene skincare-toode) — onboarding-hetk.

• Käivitub, kui: kategooria-pere esimene-eales ost toimus viimase window_days jooksul JA kliendil pole varasemat ostu samas peres.
• Aken: 45 päeva (Beauty) / 30 päeva (FMCG).
• Cooldown: 60 päeva (Beauty) / 45 päeva (FMCG).
• Pet-pakis staatus stub — Pet-tenantidel see trigger ei käivitu.

Laoseisu muutus — stock_status_change#

Käivitub, kui toode, mida klient usaldusväärselt korduvalt ostab (ostu-rütmi n_observations >= 3), on otsa saanud, kadunud kataloogist või muutunud mitte-soovitatavaks — vajab asendustoote soovitust.

• Käivitub, kui: kliendi ostu-rütmi SKU on kas kataloogist kadunud, in_stock = false VÕI recommendable = false.
• Cooldown: 30 päeva (Beauty) / 21 päeva (FMCG) / 30 päeva (Pet).
• Pet-pakis staatus active (PRO-1479, 2026-07-20) — detektor oli juba olemas ja Pet'i edges.yaml viitas talle juba, aga trigger-kirje triggers.yaml'is puudus üldse, mistõttu see vaikimisi kunagi ei käivitunud. Nüüd aktiivne — sama universaalne detektor mis Beauty/FMCG.

Korv jääb tasuta tarnest napilt alla — aov_below_free_shipping_threshold (väljas Pet'is)#

Käivitub, kui kliendi tüüpiline korv jääb poe tasuta-tarne lävest kuni lubatud vahemiku võrra alla — väike lisatoode võib lünga sulgeda.

• Eeldus: tenant_settings.free_shipping_threshold peab olema seadistatud; kui lävendit pole, trigger vaikimisi ei käivitu kellelegi.
• Käivitub, kui: kliendi viimaste tellimuste keskmine (window_days jooksul) jääb vahemikku [lävend − max_gap, lävend).
• Aken / max vahe: 60 päeva / 25€ (Beauty); 60 päeva / 20€ (FMCG).
• Cooldown: 30 päeva (Beauty) / 21 päeva (FMCG).
• Pet-pakis staatus stub — Pet-tenantidel ei käivitu.

Hooajaline aken — seasonal_window_open (väljas Pet'is)#

Käivitub, kui kalendris on avatud hooajaline aken (nt päikesekaitse-hooaeg, külmetushaiguste hooaeg, kingitus-hooaeg) JA klient sobib akna kõlblikkus-reegliga.

• Käivitub, kui: jooksev kuu kuulub akna kuude nimekirja JA klient vastab akna kõlblikkus-tingimusele — kas "ostis varem, mitte hiljuti" (ost lookback_days sees, aga mitte viimase recent_days jooksul) või "ostis tagasivaate sees" (mistahes ost akna kategooria-prefiksist lookback_days sees).
• Näited: Beauty spf_season (aprill-august, "ostis varem, mitte hiljuti", 120p mitte-hiljuti/455p tagasivaade); FMCG cold_flu_season (oktoober-veebruar); mõlemal sektoril gift_season (november-detsember).
• Cooldown: 75 päeva (Beauty) / 60 päeva (FMCG) — üks hooaja-seeria hooaja kohta.
• Pet-pakis staatus stub — Pet-tenantidel ei käivitu.

Kavandatud, kood veel puudub#

Kolm trigerit on Pet-paki triggers.yaml-is kirjeldatud kui placeholder-kontseptsioonid ilma töötava detektorita (lib/engine/triggers/ kaustas neile faili pole, ACTIVE_DETECTORS kaardis neid pole) — ära oota, et need täna kandidaate tekitaksid:

Mootori käivitatavad automatsioonid (kirja saatmine)#

Automatsiooni-trigerid on väiksem alamhulk (praegu 5) ülaltoodud detektoritest, mille saab siduda Smaily automatsiooni-workflow'ga — mootor enrollib kontakti, workflow saadab kirja. Mudel: seadistus pluginas/adminis, täitmine mootoris, sisu Smailys (autoritatiivne kood: lib/automations/catalog.ts + lib/automations/fire.ts).

Üks neist viiest, laoseisu taastumine, ei tule üldse üheltki ülaltoodud üheksast öisest detektorist — vt allpool olevast tabelist, kuidas seda tegelikult tuvastatakse.

Kandidaadi värskuse nõue#

Öine automatsiooni-käivitus (05:15) kasutab AINULT viimase 24 tunni jooksul tuvastatud kandidaate (trigger_candidates.detected_at) — eilne või vanem kandidaat, mille automatsiooniks ei jõutud kasutada, jääb automatsiooni-teelt maha (soovituste teele see siiski jõuab, see aken kehtib ainult kirja-saatmise poolel). Laoseisu taastumine on ainuke erand: eraldi cron jookseb iga 15 minuti tagant (fire-back-in-stock) ja kutsub sama käivitus-loogikat 30-minutilise värskuse-aknaga — nii jõuab selle trigeri tuvastuselt saatmiseni ~15-30 minutit, mitte kuni ööpäev.

Sisse-lülituse jada (iga kandidaat läbib täpselt selles järjekorras)#

1. Fail-closed: kui tenant'i konfiguratsiooni pole VÕI enabled=false, kogu tenant jäetakse vahele (ei logita kliendi-kaupa, mahu tõttu) — aktiveerimata trigger ei käivita KUNAGI.
2. Loobunud klient (opted_out=true) — jäetakse vahele igal rajal.
3. Kõrvalejäetud võrdlusgrupp (holdout_arm='holdout') — jäetakse alati vahele, enne muid kontrolle (kaitseb juurdekasvu mõõtmist).
4. Sünki-skoop: kontaktil peab olema e-post, ta peab olema Smaily listis (in_smaily=true) ja mitte loobunud (smaily_unsubscribed ei tohi olla tõene) — muidu jäetakse vahele.
5. Test-režiim: kui sees, käivituvad AINULT test_emails nimekirja aadressid; kõik teised jäetakse vahele.
6. Cooldown: kui sama trigeriga on sellel kliendil pending või fired rida cooldown_days sees, jäetakse vahele.
7. Päevalimiit: kui tänane fired-arv selle trigeri kohta on juba daily_cap-i täis, jäetakse vahele.
8. Workflow ACTIVE kontroll: kui Smailys pole vastavat automatsiooni- ID-d ACTIVE-nimekirjas, jäetakse vahele (INACTIVE workflow annab Smailylt ikkagi 101 OK, aga kirja ei saada — vaikne lõks, mida see samm väldib).

Ühekordsus: pending-rida kirjutatakse automation_fires tabelisse ENNE Smaily kõnet; kui kõne krahhib, jääb pending rida seisma ja loetakse cooldown'i sisse — kordusjooks ei saada topelt-kirja. failed staatus EI blokeeri järgmist ööd (parem üks päev hiljem kui mitte kunagi).

Lisaks: tenant-tasandi lukustus (contact_sync_enabled=false, nt migratsiooni-freeze ajal) välistab kogu tenant'i automatsioonidest — sama lipp, mis peatab kontaktisünki.

Konfiguratsiooni piirid#

Viis praegu saadaolevat automatsiooni-trigerit#

Neli neist on sisuliselt universaalsed (mehhanism ei sõltu sektorist, sisu tuleb sektoripakist); elufaasi-trigger on koodis sektorile piiratud (scope: ['pet'] failis lib/automations/catalog.ts), sest lävendid tulevad Pet-paki triggers.yaml-ist — teine sektoripakk peaks defineerima oma lävendid või jätma trigeri kasutamata.

Iga trigeri kirjeldus, retsept ja aktiveerimis-sammud (test-režiim → päris aktiveerimine) on kirjas Smaily mallid → mootori käivitatavad automatsioonid. Kui sul on operaatori-ligipääs, on käivituste/skip'ide detailne seire ja debug-tabel operaatori runbook'is "Automaatikate aktiveerimine ja seire".

Laoseisu taastumine — kuidas seda tegelikult tuvastatakse (PRO-1376)#

Erinevalt teistest neljast pole laoseisu taastumisel öist detektorit. See on sündmuspõhine: iga kataloogi-sisestus (nii plugina tavaline sünk KUI admin CSV-taasüleslaadimine) võrdleb iga SKU laoseisu varasemaga. false → true üleminek loetakse alles siis, kui toode on olnud laost otsas vähemalt 30 minutit (debounce, mis filtreerib välja sama-päevase tühjaks-müügi-ja-kohese-taastäitumise vilkumise ning täis-resünki ajal tekkiva riknenud-loenduse müra) — kvalifitseeruvad signaalid kogunevad väikeses sisemises tabelis.

Eraldi cron (fire-back-in-stock, iga 15 minuti tagant) siis:

1. Ehitab huviringi selle taastäitunud SKU jaoks — v1 kasutab kahte mootorist otse tuletatavat signaali, veel ilma e-poe ootenimekirjata: toote varasemad ostjad (180-päevane tagasivaade) ja kliendid, kes vaatasid seda SKU-d, kui see oli otsas (30-päevane tagasivaade product_view sündmustele, seal, kus lehitsemis-jälgimine on poe jaoks juhtmestatud).
2. Käivitab täpselt sama sisse-lülituse jada kaudu, mis on kirjeldatud ülal — kõrvalejäetud võrdlusgrupp, sünki-skoop, test-režiim, cooldown, päevalimiit, workflow ACTIVE — ilma eranditeta.

Üks päris erinevus teisest neljast: ülaltoodud kliendi-tasandi cooldown ei ole SKU-teadlik (seda pole võimalik toote kaupa piirata ilma andmemudeli muudatuseta), seega klient, keda teavitati ühest taastäitunud tootest, ei saa teadet TEISE taastäitunud toote kohta enne, kui tema seadistatud cooldown_days on möödas. Eraldi, SKU-põhine kontroll kandidaadi-loomise hetkel (30-päevane aken) takistab lisaks SAMA toote korduvat teavitust samale kliendile, kui laoseis vilgub aja jooksul korduvalt sisse-välja.

Nagu teised neli, on see vaikimisi väljas — ühelgi tenant'il pole back_in_stock täna sisse lülitatud; miski ei käivitu enne, kui kaupmees lülitab selle sisse sama seadistuse kaudu, mida iga teine trigger kasutab.

Sama signaal toidab nüüd ka soovitusi (PRO-1566): alates Pet-paki versioonist 1.3.0 annab taastäitumise-kandidaat lisaks kliendi öises top-9-s slot'i täpselt sellele tootele, mis lattu tagasi tuli (laost-otsas asendusreegli peegelpilt — soovitud toode, mitte kompromiss). See pool ei vaja sisselülitamist ega saada ise midagi: see muudab ainult seda, millised tooted öösel kliendi rec_1..9_* väljadele jõuavad. Kaks tarbijat ei sega teineteist — automaatika loeb kandidaadi 30-minutilist värskusakent, öine väljastus tembeldab kandidaadi töödelduks, ja kumbki samm ei mõjuta teist.

Kust rohkem lugeda#

• Smaily mallid ja väljad — kuidas rec_active_triggers ja automatsioonid praktikas kirja panna.
• KKK ja tõrkeotsing — kui miski trigeri käitumises tundub vale.

Viimati uuendatud: 2026-07-29