Action Executor Servisi

Topoloji referansı: /projects/cinga/backend#sistem-işleyiş-akışı

Action Executor Servisi, Rule Servisi tarafından üretilen aksiyon taleplerini işleyen yürütme katmanıdır.

Bu servis yalnız mobil push değil; WhatsApp, e-posta, webhook ve benzeri çoklu kanal aksiyonlarını çalıştırır.

Execution Boundary Contract

• Rule Servisi bu katmana yalnız action.execute.requested.v1 talebi gönderir.
• Action Executor kanal bazlı aksiyonları yürütür.
• Cihaza gerçek downlink gerektiren adımlar Communication Servisi'ne devredilir.

Sorumluluk

• action.execute.requested.v1 eventini consume etmek
• action_plan_steps sırasına göre aksiyon adımlarını yürütmek
• Kanal bazlı gönderim yapmak (push/email/whatsapp/webhook/audit)
• Retry/backoff ve timeout yönetmek
• Başarı/fail sonuç eventleri üretmek
• Dead-letter (DLQ) akışını yönetmek

Desteklenen Kanal Tipleri (V1)

• push
• email
• whatsapp
• webhook
• audit

Hedef Kaynak Modeli (Recipient Directory)

Kime/nereden gönderim yapılacağı tek merkezde tutulmalıdır.

Önerilen tablolar:

recipient_profiles

Kolon	Tip	Not
id	bigint PK
device_id	varchar(21)	cihaz bazlı profil (opsiyonel)
name	varchar(100)	profil adı (Ops OnCall)
status	boolean	aktif/pasif
priority	integer	fallback sırası
created_at, updated_at	timestamptz

recipient_channels

Kolon	Tip	Not
id	bigint PK
profile_id	bigint FK	recipient_profiles.id
channel_type	varchar(32)	push/email/whatsapp/webhook
target	varchar(255)	token, telefon, email, URL
target_meta	jsonb	token platformu, webhook header vb
enabled	boolean	aktif/pasif
verify_status	varchar(16)	verified/pending/failed
created_at, updated_at	timestamptz

action_routes

Kolon	Tip	Not
id	bigint PK
action_plan_id	bigint FK	action_plans.id
step_order	integer
recipient_profile_id	bigint FK	recipient_profiles.id
channel_type	varchar(32)	route override için
enabled	boolean
created_at, updated_at	timestamptz

Karar sırası:

1. action_routes eşleşmesi
2. Profile içindeki priority sırası
3. Channel enabled + verify_status=verified filtresi

İşlem Akışı

Topic ve Event Standardı

• Topic:
  • cinga.action.requested
  • cinga.action.executed
  • cinga.action.failed
  • cinga.dlq.action
• Event:
  • action.execute.requested.v1
  • action.executed.v1
  • action.failed.v1

Hedef Çözümleme Örneği

Örnek:

• Rule tetikledi -> action_plan_id=21
• Step#1 channel_type=whatsapp
• action_routes -> recipient_profile_id=5
• recipient_channels tablosundan verified WhatsApp hedefi çekilir
• Gönderim bu hedefe yapılır

Aynı model push token, e-posta adresi ve webhook URL için de geçerlidir.

Timeout / Retry Kontratı (V1)

Kanal bazlı önerilen varsayılanlar:

• push: timeout 3s, retry 2
• whatsapp: timeout 8s, retry 1
• email: timeout 10s, retry 3
• webhook: timeout 5s, retry 3
• audit: timeout 2s, retry 0

Backoff: exponential (1s, 5s, 15s)

Dead-Letter Politikası

DLQ'ya düşme koşulları:

• retry limiti aşıldı
• non-retryable hata
• template render fatal hata

DLQ payload minimum alanlar:

• action_plan_id
• step_order
• channel_type
• error_code
• error_message
• retry_count
• failed_at

Event Örnekleri

action.executed.v1

{
  "event": "action.executed.v1",
  "meta": {
    "schema_version": 1,
    "trace_id": "act-9f3f...",
    "producer_service": "action-executor-service",
    "produced_at": "2026-03-12T20:55:10.100Z",
    "process_ms": 42
  },
  "context": {
    "device_id": "400000011D081B70",
    "stream_id": 9823412
  },
  "data": {
    "group_id": 12,
    "rule_id": 114,
    "action_plan_id": 21,
    "step_order": 1,
    "channel_type": "push",
    "delivery_status": "sent",
    "provider_message_id": "fcm:abc123"
  },
  "error": null
}

action.failed.v1

{
  "event": "action.failed.v1",
  "meta": {
    "schema_version": 1,
    "trace_id": "act-9f3f...",
    "producer_service": "action-executor-service",
    "produced_at": "2026-03-12T20:55:10.300Z",
    "process_ms": 58
  },
  "context": {
    "device_id": "400000011D081B70",
    "stream_id": 9823412
  },
  "data": {
    "group_id": 12,
    "rule_id": 114,
    "action_plan_id": 21,
    "step_order": 2,
    "channel_type": "email"
  },
  "error": {
    "failed_stage": "action_execute",
    "error_code": "SMTP_TIMEOUT",
    "error_message": "mail provider timeout",
    "retryable": true,
    "failed_at": "2026-03-12T20:55:10Z"
  }
}

Güvenlik ve Operasyon Notları

• Kanal credential’ları secret manager üzerinden çekilmelidir.
• PII içeren payload’lar log’da maskelenmelidir.
• Kanal adapter’ları circuit-breaker ile korunmalıdır.
• Aynı evaluation_key + step_order için idempotent teslimat uygulanmalıdır.

Servis Bazlı SLO Hedefleri (Öneri)

Metrik	Hedef
p95 action end-to-end	< 5s
delivery success rate	> 99.0%
dlq_rate	< 0.5%
critical action retry exhausted	< 0.1%

Çıktı

Action Executor Servisi çıktısı:

• Çoklu kanal aksiyon yürütme sonuçları
• Retry/DLQ görünürlüğü
• Rule tetiklerinin sahaya/insana ulaşan son adımı