Envelope: Heartbeat Servisi

Topic: qapu.heartbeat
DLQ: qapu.dlq.heartbeat
Producer: heartbeat-service

Heartbeat servisi, cihazlardan periyodik olarak gelen yaşam işareti mesajlarını işler, cihazın metriklerini günceller ve çevrimiçi/çevrimdışı durum geçişlerini tespit eder. Metrik güncellemede heartbeat.metrics.updated.v1, durum değişiminde heartbeat.status.changed.v1, işleme hatasında heartbeat.failed.v1 üretilir.

Event Envanteri

Event	Ne zaman üretilir?	Consumer	Amaç
heartbeat.metrics.updated.v1	Cihaz metrikleri (sinyal, batarya, sıcaklık vb.) güncellendiğinde	Observer, Dashboard	Cihaz sağlığı görünürlüğü
heartbeat.status.changed.v1	Cihazın çevrimiçi/çevrimdışı durumu değiştiğinde	Rule, Communication	Durum bazlı alarm ve bildirim
heartbeat.failed.v1	Heartbeat işleme sırasında hata oluştuğunda	Observer	Hata görünürlüğü

---

heartbeat.metrics.updated.v1

Özet

Başlık	Değer
Topic	qapu.heartbeat
Producer	heartbeat-service
Consumer	Observer, Dashboard
Tetikleyici	Cihazdan heartbeat mesajı alınıp başarıyla işlendiğinde
Kritiklik	Düşük/Orta — tanı ve izleme

Payload

{
  "event": "heartbeat.metrics.updated.v1",
  "meta": {
    "trace_id": "01a2b3c4d5e6f7g8h9i0",
    "producer_service": "heartbeat-service",
    "produced_at": "2026-03-11T15:30:01.200Z",
    "process_ms": 12
  },
  "context": {
    "device_id": "400000011D081B70",
    "raw_id": null,
    "stream_id": null,
    "device_time": "2026-03-11T15:30:00Z",
    "stream_time": "2026-03-11T15:30:01.200Z",
    "iccid": "8990000111111111111",
    "imei": "357042111111111",
    "firmware": "2.4.1"
  },
  "data": {
    "rssi_dbm": -72,
    "battery_mv": 3850,
    "board_temp_c": 42.3,
    "uptime_sec": 86400,
    "firmware_version": "2.4.1",
    "ip_address": "10.0.1.42"
  },
  "error": null
}

Alan Açıklamaları

Alan	Tip	Zorunlu	Açıklama
data.rssi_dbm	integer	Hayır	Sinyal gücü (dBm)
data.battery_mv	integer	Hayır	Batarya gerilimi (mV)
data.board_temp_c	number	Hayır	Kart sıcaklığı (°C)
data.uptime_sec	integer	Hayır	Son yeniden başlatmadan itibaren çalışma süresi (saniye)
data.firmware_version	string	Hayır	Cihazda çalışan firmware versiyonu
context.stream_id	integer|null	Hayır	Heartbeat üretim akışıyla ilişkili değilse null

---

heartbeat.status.changed.v1

Özet

Başlık	Değer
Topic	qapu.heartbeat
Producer	heartbeat-service
Consumer	Rule Servisi, Communication Servisi
Tetikleyici	Cihaz online→offline veya offline→online geçiş yaptığında
Kritiklik	Yüksek — cihaz kayıp durumu alarm üretebilir

Payload

{
  "event": "heartbeat.status.changed.v1",
  "meta": {
    "trace_id": "01a2b3c4d5e6f7g8h9i1",
    "producer_service": "heartbeat-service",
    "produced_at": "2026-03-11T16:15:05.000Z",
    "process_ms": 8
  },
  "context": {
    "device_id": "400000011D081B70",
    "raw_id": null,
    "stream_id": null,
    "device_time": null,
    "stream_time": "2026-03-11T16:15:05Z",
    "iccid": null,
    "imei": null,
    "firmware": null
  },
  "data": {
    "previous_status": "online",
    "current_status": "offline",
    "last_seen_at": "2026-03-11T15:30:01Z",
    "offline_duration_sec": null
  },
  "error": null
}

Alan Açıklamaları

Alan	Tip	Zorunlu	Açıklama
data.previous_status	string	Evet	online | offline | unknown
data.current_status	string	Evet	online | offline
data.last_seen_at	string (ISO 8601)	Evet	Son başarılı heartbeat zaman damgası
data.offline_duration_sec	integer|null	Hayır	Offline→online geçişinde ne kadar süre çevrimdışı kaldığı

---

heartbeat.failed.v1

Özet

Başlık	Değer
Topic	qapu.heartbeat
Producer	heartbeat-service
Consumer	Observer Servisi
Kritiklik	Düşük — işleme hatası; mesaj DLQ'ya da düşer

Payload

{
  "event": "heartbeat.failed.v1",
  "meta": {
    "trace_id": "01a2b3c4d5e6f7g8h9i2",
    "producer_service": "heartbeat-service",
    "produced_at": "2026-03-11T15:30:01.300Z",
    "process_ms": 5
  },
  "context": {
    "device_id": "400000011D081B70",
    "raw_id": null,
    "stream_id": null,
    "device_time": null,
    "stream_time": "2026-03-11T15:30:01.300Z",
    "iccid": null,
    "imei": null,
    "firmware": null
  },
    "device_time": null,
    "stream_time": "2026-03-11T15:30:01Z"
  },
  "data": {},
  "error": {
    "code": "HEARTBEAT_PARSE_ERROR",
    "message": "Missing required field: rssi_dbm",
    "stage": "message_parse",
    "retryable": false
  }
}