Communication Servisi

Communication Servisi, otomasyon veya kullanıcı aksiyonlarından gelen komutları cihaza ileten downlink katmanıdır.

Execution Boundary Contract

• Communication Servisi yalnız cihaz downlink/ACK akışından sorumludur.
• Rule Servisi doğrudan cihaza komut göndermez.
• Action Executor'dan gelen komut adımları veya Automation istekleri burada gerçek iletime çevrilir.

Sorumluluk

• Komutları cihaz protokolüne çevirmek
• Cihaz downlink gönderimini yapmak
• ACK/NACK toplamak
• Timeout/retry yönetmek
• Komut denetim kaydı tutmak
• Komut güvenlik politikalarını uygulamak (auth, allowlist)

Girdiler

• action.execute.requested.v1 (komut tipi adımlar)
• automation.command.requested.v1

Çıktılar

• device.command.sent.v1
• device.command.acked.v1
• device.command.failed.v1

Komut Modeli

device_commands

Kolon	Tip	Not
id	bigint PK
device_id	varchar(21)
command_type	varchar(32)
command_payload	jsonb
source_type	varchar(16)	rule/automation/manual
source_ref_id	bigint	rule_id/job_id vb
status	varchar(16)	queued/sent/acked/failed
retry_count	integer
idempotency_key	varchar(128)
issued_at	timestamptz
acked_at	timestamptz
created_at, updated_at	timestamptz

Akış

Topic ve Event Standardı

• Topic:
  • cinga.device.command.sent
  • cinga.device.command.acked
  • cinga.device.command.failed
• Event:
  • device.command.sent.v1
  • device.command.acked.v1
  • device.command.failed.v1

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

Event Örnekleri

device.command.sent.v1

{
  "event": "device.command.sent.v1",
  "meta": {
    "schema_version": 1,
    "trace_id": "cmd-9f3f...",
    "producer_service": "communication-service",
    "produced_at": "2026-03-12T21:20:00.100Z",
    "process_ms": 11
  },
  "context": {
    "device_id": "400000011D081B70"
  },
  "data": {
    "command_id": 9122,
    "command_type": "PUMP_START",
    "source_type": "automation",
    "idempotency_key": "400000011D081B70:ab12:2026-03-12T21:20:00Z"
  },
  "error": null
}

device.command.acked.v1

{
  "event": "device.command.acked.v1",
  "meta": {
    "schema_version": 1,
    "trace_id": "cmd-9f3f...",
    "producer_service": "communication-service",
    "produced_at": "2026-03-12T21:20:01.030Z",
    "process_ms": 14
  },
  "context": {
    "device_id": "400000011D081B70"
  },
  "data": {
    "command_id": 9122,
    "ack_code": "OK",
    "rtt_ms": 930
  },
  "error": null
}

device.command.failed.v1

{
  "event": "device.command.failed.v1",
  "meta": {
    "schema_version": 1,
    "trace_id": "cmd-9f3f...",
    "producer_service": "communication-service",
    "produced_at": "2026-03-12T21:20:05.300Z",
    "process_ms": 20
  },
  "context": {
    "device_id": "400000011D081B70"
  },
  "data": {
    "command_id": 9122,
    "command_type": "PUMP_START",
    "retry_count": 3
  },
  "error": {
    "failed_stage": "device_downlink",
    "error_code": "COMMAND_ACK_TIMEOUT",
    "error_message": "device ack timeout",
    "retryable": false,
    "failed_at": "2026-03-12T21:20:05Z"
  }
}

Komut Politikası

• Timeout: 5s (öneri)
• Retry: 3
• Backoff: 1s, 5s, 15s
• Idempotency key: device_id + command_hash + issued_at
• Aynı cihaza command lock uygulanır

Güvenlik

• Komut tipleri allowlist ile sınırlandırılır
• Komut payload schema doğrulaması zorunludur
• Yetkisiz kaynaklardan gelen komutlar reddedilir (COMMAND_UNAUTHORIZED)
• Kritik komutlar için opsiyonel 2-adım onay akışı

SLO (Öneri)

Metrik	Hedef
p95 command dispatch	< 300ms
ack success rate	> 98%
duplicate command rate	< 0.1%
command timeout rate	< 1%

Çıktı

• Güvenli/izlenebilir cihaz downlink katmanı