Automation Servisi

Automation Servisi, planlanan zamanlarda cihazlara komut gönderimi için scheduler/orchestrator katmanıdır.

Sorumluluk

• Zamanlanmış görevleri (cron/interval) yönetmek
• Görev tetik anında komut isteği üretmek
• Çakışan komutları önlemek
• Retry/backoff yönetmek
• Görev yürütme geçmişi tutmak
• Manual trigger ve scheduled trigger akışını birleştirmek

Görev Modeli

automation_jobs

Kolon	Tip	Not
id	bigint PK
device_id	varchar(21)
name	varchar(100)
schedule_type	varchar(16)	cron/interval/once
schedule_expr	varchar(64)	cron veya interval tanımı
timezone	varchar(64)	varsayılan UTC
command_type	varchar(32)
command_payload	jsonb
enabled	boolean
priority	integer	çakışma çözümünde
valid_from, valid_to	timestamptz	aktiflik penceresi
last_run_at	timestamptz
next_run_at	timestamptz
created_at, updated_at	timestamptz

automation_job_runs

Kolon	Tip	Not
id	bigint PK
job_id	bigint FK	automation_jobs.id
scheduled_at	timestamptz
trigger_type	varchar(16)	scheduled/manual/retry
status	varchar(16)	queued/sent/acked/failed
idempotency_key	varchar(128)	job_id + scheduled_at
error_code	varchar(64)
error_message	text
created_at, updated_at	timestamptz

Akış

Topic ve Event Standardı

• Topic:
  • cinga.automation.command.requested
  • cinga.automation.job.completed
  • cinga.automation.job.failed
• Event:
  • automation.command.requested.v1
  • automation.job.completed.v1
  • automation.job.failed.v1

Not: Event payload standardı arşiv referansı: /projects/cinga/backend/architecture/event-envelope.

Event Örneği

automation.command.requested.v1

{
  "event": "automation.command.requested.v1",
  "meta": {
    "schema_version": 1,
    "trace_id": "auto-9f3f...",
    "producer_service": "automation-service",
    "produced_at": "2026-03-12T21:15:02.020Z",
    "process_ms": 8
  },
  "context": {
    "device_id": "400000011D081B70"
  },
  "data": {
    "job_id": 88,
    "run_id": 9122,
    "trigger_type": "scheduled",
    "command_type": "PUMP_START",
    "command_payload": {"duration_sec": 120},
    "scheduled_at": "2026-03-12T21:15:00Z",
    "idempotency_key": "88:2026-03-12T21:15:00Z"
  },
  "error": null
}

Çakışma ve Öncelik Kuralları

• Aynı cihaza eşzamanlı komut yok (device command lock).
• Manual trigger ile scheduled trigger çakışırsa manual öncelik.
• Aynı anda birden çok schedule tetiklenirse küçük priority değeri önce çalışır.
• Çalışamayan görev queued kalır, lock açılınca tekrar değerlendirilir.

Retry / Backoff Politikası

• Retryable hata durumunda exponential backoff (1m, 5m, 15m).
• Maksimum retry sayısı: 3 (öneri).
• Limit aşımında automation.job.failed.v1 üretilir.
• Aynı idempotency_key ile duplicate run açılmaz.

Güvenlik ve Operasyon

• Job create/update işlemleri yalnız admin/operator rolleriyle yapılır.
• Komut payload whitelist ile doğrulanır (command_type bazlı schema).
• Tüm job değişiklikleri audit log’a yazılır.
• Timezone karmaşasını önlemek için schedule hesapları UTC normalize edilir.

SLO (Öneri)

Metrik	Hedef
scheduler drift	< 5s
job dispatch success	> 99%
duplicate run rate	< 0.1%
p95 dispatch latency	< 200ms

Çıktı

• Planlı komut üretim hattı
• Çalışma geçmişi ve hata görünürlüğü