Journey'ler (Faz 11)

Journey, kullanıcıyı bir tetikleyiciyle içeri alıp bekleme, koşul, dallanma ve gönderim adımlarından geçiren otomatik akıştır (OneSignal Journeys eşdeğeri). Tasarım kararları: docs/adr/0018-journey-motoru.md. Şema ve doğrulama: packages/shared/src/journeys.ts.

Yaşam döngüsüBağlantıyı kopyala

Düzenleme her zaman taslak sürüm üzerinde yapılır (PUT …/draft, PATCH …/nodes/:nodeId). publish taslağı yeni bir sürüm olarak yayınlar. Aktif run'lar girdikleri sürümde kalır (sürüm sabitleme); yeni girişler en son sürümü kullanır. Yayınlamadan önce yapısal ve anlamsal doğrulama çalışır; sorun varsa 400 ve details.issues döner.

Graf biçimiBağlantıyı kopyala

React Flow uyumludur:

{
  "nodes": [{ "id": "t", "type": "trigger", "position": { "x": 0, "y": 0 }, "data": { "trigger": { "kind": "event", "event_name": "signup" } } }],
  "edges": [{ "id": "e1", "source": "t", "target": "w", "sourceHandle": "next" }]
}

Kurallar:

• Tam olarak bir trigger düğümü olur ve döngü kurulamaz.
• Her düğüm tetikleyiciden erişilebilir olmalıdır.
• Her çıkış kolu (handle) en fazla bir kenara bağlanır; bağlanmamış kol, run'ın o noktada completed olması demektir.
• Sınırlar JOURNEY_LIMITS içindedir: en fazla 100 düğüm, 200 kenar ve 5 dal; bekleme 60 sn ile 365 gün arasıdır.

Düğüm türleriBağlantıyı kopyala

Mesaj olayları: sent, delivered, opened, clicked, failed, bounced, complained, unsubscribed.

Push → SMS yedeği örneği: send_push → wait_until [message (push düğümü, delivered), zaman aşımı 1 saat] → timeout kolu → send_sms.

Gönderim adımlarıBağlantıyı kopyala

• Her gönderim, source = journey ve journey_run_id alanlarıyla bir messages kaydı oluşturur. Gönderim normal teslimat hattından geçer, kampanya analitiği de bu kayıtla çalışır.
• Kullanıcının o kanalda aktif aboneliği yoksa adım skipped olur ve run devam eder.
• Sessiz saatler ve frekans sınırı uygulanır; settings.quiet_hours_exempt ve frequency_cap_exempt ile muaf tutulabilir.
• send_in_app, kullanıcıya süreli bir gösterim hakkı (in_app_journey_grants) verir. journey_only: true olan in-app mesajlar yalnızca bu hakkı olan kullanıcılara gösterilir.
• webhook düğümünün gövdesi Liquid ile yazılır; kapsamda user, journey, run ve context (giriş bağlamı) bulunur.
  • Gövde verilmezse varsayılan JSON gövde gönderilir: {type: "journey.webhook", journey_id, node_id, run_id, user, context}.
  • Her istek idempotency-key: <run_id>:<node_id> başlığını taşır.
  • SSRF koruması uygulanır.
  • Başarısız istek run'ı durdurmaz; sonuç adım istatistiğine yazılır.

Ayarlar (settings)Bağlantıyı kopyala

Yürütme ve güvenilirlikBağlantıyı kopyala

• Doğruluk kaynağı veritabanıdır. Her adım step_seq üzerinde iyimser kilitle sahiplenilir; aynı işin iki kez çalışması etkisizdir.
• Bekleyen run'lar next_action_at ile gecikmeli BullMQ işine bağlanır.
• Kurtarma: her 10 sn'de vadesi gelmiş run'lar taranır. Worker yeniden başlasa veya Redis işleri kaybolsa da run'lar devam eder.
• Segment ve takvim tetikleri: Redis kilidi altında her 60 sn'de taranır.
• Sinyaller: olaylar (/v1/.../events) tetik, çıkış kuralı, hedef ve wait_until koşullarını işler. Teslimat olayları da (delivered, clicked …) run'lara sinyal olarak gelir.
• Webhook olayları: journey.entered, journey.step_completed, journey.completed, journey.exited (webhooks.md).
• Saklama: biten run'lar teslimat saklama süresi (deliveries) dolunca silinir; süresi geçmiş in-app hakları da temizlenir. Kullanıcı silindiğinde kullanıcının run'ları ve hakları da silinir.

APIBağlantıyı kopyala

Dashboard (oturum) uçları internal/v1/apps/:appId/journeys/… altındadır. Public uçlar aynı yolları v1/apps/:appId/journeys/… altında sunar.

Run tetikleme yanıtı {entered, run, reason} biçimindedir. Giriş reddedilirse reason şu değerlerden biri olur: inactive, outside_schedule, re_entry, already_active, unknown_user.

SDK: Node hs.journeys.*, PHP $client->journeys() (sdk/node.md, sdk/php.md).

Örnek: kayıt → satın alma hatırlatmaBağlantıyı kopyala

trigger(event: signup) → wait(1 gün) → condition(event: purchase):

• yes kolu: exit
• no kolu: send_push → wait(3 gün) → send_email

Bu akış, zaman hızlandırmalı kabul testinde doğrulanır (apps/worker/src/__tests__/journeys.int.test.ts).