Envelope: FOTA Servisi

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

FOTA (Firmware Over-The-Air) servisi, cihazlara kablosuz olarak firmware güncellemesi gönderir. Cihaz firmware dosyasını başarıyla indirip doğruladığında firmware.download.completed.v1, hata durumunda firmware.download.failed.v1 üretilir.

:::caution Fiziksel Etki FOTA eventleri cihaz yeniden başlatma sürecini tetikler. Bu eventleri izleyen servisler cihazın geçici olarak çevrimdışı kalacağını göz önünde bulundurmalıdır. :::

Event Envanteri

Event	Ne zaman üretilir?	Consumer	Amaç
firmware.download.completed.v1	Cihaz firmware'i başarıyla indirip bütünlük doğrulaması geçtiğinde	Heartbeat, Ledger	Flash ve yeniden başlatma beklentisi
firmware.download.failed.v1	İndirme veya doğrulama hata verdiğinde	Observer	Hata görünürlüğü ve retry kararı

---

firmware.download.completed.v1

Özet

Başlık	Değer
Topic	qapu.fota
Producer	fota-service
Consumer	Heartbeat Servisi, Ledger Servisi
Tetikleyici	Cihazdan indirme tamamlandı + CRC doğrulama başarılı bildirimi alındığında
Kritiklik	Yüksek — cihaz yakında yeniden başlayacak

Payload

{
  "event": "firmware.download.completed.v1",
  "meta": {
    "trace_id": "01a2b3c4d5e6f7g8h9i0",
    "producer_service": "fota-service",
    "produced_at": "2026-03-11T17:05:30.000Z",
    "process_ms": 12500
  },
  "context": {
    "device_id": "400000011D081B70",
    "raw_id": null,
    "stream_id": null,
    "device_time": "2026-03-11T17:05:29Z",
    "stream_time": "2026-03-11T17:05:30.000Z",
    "iccid": null,
    "imei": null,
    "firmware": "2.4.0"
  },
  "data": {
    "fota_job_id": "fota_job_441",
    "firmware_version": "2.5.0",
    "firmware_size_bytes": 262144,
    "crc32": "A3F7B21C",
    "download_duration_ms": 12490,
    "device_action": "reboot_scheduled"
  },
  "error": null
}

Alan Açıklamaları

Alan	Tip	Zorunlu	Açıklama
data.fota_job_id	string	Evet	FOTA işinin benzersiz tanımlayıcısı
data.firmware_version	string	Evet	İndirilen firmware sürümü
data.firmware_size_bytes	integer	Hayır	Firmware dosya boyutu (bayt)
data.crc32	string	Evet	Bütünlük doğrulama özeti
data.device_action	string	Evet	reboot_scheduled | reboot_manual — yeniden başlatma türü

---

firmware.download.failed.v1

Özet

Başlık	Değer
Topic	qapu.fota
Producer	fota-service
Consumer	Observer Servisi
Kritiklik	Yüksek — güncelleme iptal edildi; Observer retry/eskalasyon kararı verir

Payload

{
  "event": "firmware.download.failed.v1",
  "meta": {
    "trace_id": "f1e2...",
    "producer_service": "fota-service",
    "produced_at": "2026-03-11T17:05:35.200Z",
    "process_ms": 15200
  },
  "context": {
    "device_id": "400000011D081B70",
    "raw_id": null,
    "stream_id": null,
    "device_time": "2026-03-11T17:05:34Z",
    "stream_time": "2026-03-11T17:05:35.200Z",
    "iccid": null,
    "imei": null,
    "firmware": "2.4.0"
  },
  "data": {
    "fota_job_id": "fota_job_441",
    "firmware_version": "2.5.0",
    "attempt": 2
  },
  "error": {
    "code": "FOTA_CRC_MISMATCH",
    "message": "CRC32 mismatch after download. Expected A3F7B21C, got D9041EAB",
    "stage": "crc_verification",
    "retryable": true
  }
}

Alan Açıklamaları

Alan	Tip	Zorunlu	Açıklama
data.attempt	integer	Hayır	Bu eventı üreten indirme denemesi sayısı
error.code	string	Evet	FOTA_CRC_MISMATCH | FOTA_TRANSFER_TIMEOUT | FOTA_STORAGE_FULL
error.retryable	boolean	Evet	FOTA_CRC_MISMATCH ve FOTA_TRANSFER_TIMEOUT için true