Ana içeriğe geç

Device Detail

Bu sayfa, device:{device_id}:detail keyi icin V1 sozlesmesini tanimlar.

Ana hedef, cihazla ilgili gerekli operasyonel bilgileri tek key'de toplayip her istekte DB'ye gitmeden hizli cozmektir.

Dokuman Seti​

  • Genel omurga ve isletim mantigi: bu sayfa
  • Kanonik alan/ownerlik sozlesmesi: Device Detail Contract
  • Okuma/yazma/rebuild akis diyagrami: Device Detail Flow
  • Referans sema dosyasi: /project-qapu/services/redis/keyspace/device-detail/device-detail.schema.json

Key Pattern​

  • device:{device_id}:detail

Ornek:

  • device:400000011D081B70:detail

Owner Service​

  • Primary readers: Ingest, Stream, Calibration, Communication, Observer
  • Primary writer: Device lifecycle sahibi servis (API/Inventory)
  • Secondary writer: Read-through yapan servisler (cache miss sonrasinda DB fallback + write-back)

Kural: Bu key'in icerigi DB'deki cihaz kaydinin cache kopyasidir; authoritative kaynak daima DB'dir.

Cache Govdesi (V1)​

{
  "device_id": "400000011D081B70",
  "status": "active",
  "project_id": 120,
  "device_type": "multi_function_meter",
  "created_at": "2025-11-01T08:00:00Z",
  "last_data_at": "2026-03-12T12:10:00Z",
  "updated_at": "2026-03-12T12:10:00Z",
  "identity": {
    "firmware": "1.0.7",
    "iccid": "8946120802005507363",
    "imei": "354485417650889"
  },
  "calibration": {
    "ct_ratio": 200.0
  },
  "buffer_policy": {
    "stream_buffer_ttl_sec": 172800,
    "max_payload_bytes": 65535,
    "duplicate_window_sec": 120
  },
  "command_policy": {
    "default_timeout_ms": 20000,
    "max_retry": 3
  },
  "cache_meta": {
    "version": 18,
    "db_updated_at": "2026-03-12T12:10:00Z",
    "rebuilt_at": "2026-03-12T12:10:05Z"
  }
}

Not: ct_ratio kritik bir alandir, ancak bu key yalnizca kalibrasyon icin degil cihazin tum operasyon profili icin kullanilir.

Read / Write Paths​

Read Path​

  1. Servis key'i Redis'ten okur.
  2. Hit varsa gerekli alanlar dogrudan kullanilir (calibration, buffer_policy, identity vb.).
  3. Miss veya sema uyumsuzsa DB fallback calisir.

Write Path​

  1. Cihaz create/update/delete islemi DB'de tamamlanir.
  2. Ardindan key invalidate edilir veya yeni govde ile update edilir.
  3. Read-through yapan servislerde cache miss olursa DB'den yeniden olusturulup Redis'e write-back edilir.

CRUD Senkronizasyon Kurali​

Create​

  1. DB'ye cihaz kaydi acilir.
  2. device:{device_id}:detail key'i ilk govde ile yazilir.

Update​

  1. DB guncellemesi basarili olur.
  2. Key ya atomik update edilir ya da DEL edilip read-through rebuild'e birakilir.

Delete​

  1. DB'de cihaz pasif/silinmis duruma cekilir.
  2. Redis key aninda silinir.
  3. Sonraki okumada servisler DB durumuna gore "device inactive/not found" davranisina gecer.

Kural: Redis guncellemesi DB yazimindan once yapilamaz.

Write Order (DB -> Redis)​

Bu key icin yazim duzeni:

  1. Kalici kaynak DB'dir (devices ve iliskili cihaz detay kayitlari).
  2. Redis bu kaydin turetilmis cache kopyasidir.
  3. Redis hicbir durumda DB'nin yerine gecmez.

Kural: Redis'e yazim yalniz DB'den dogrulanmis degerle yapilir.

TTL ve Invalidation​

V1 onerisi:

  • TTL: 24h
  • Soft refresh penceresi: 30m

Invaliation tetikleri:

  1. Cihaz detayinda degisiklik (ozellikle ct_ratio, firmware, iccid, imei, buffer_policy) oldugunda key silinir veya guncellenir.
  2. Sema uyumsuz govde tespit edilirse key invalid edilir.
  3. Drift kontrolunde DB-Redis farki tespit edilirse key yeniden yazilir.
  4. Cihaz pasif/silinmis duruma geldiyse key zorunlu silinir.

Not: TTL degeri operasyonel davranisa gore degistirilebilir; ilke degismez: DB authoritative, Redis cache.

Failure ve Drift Senaryolari​

Senaryo A: Redis miss​

  • Beklenen davranis: DB fallback + write-back
  • Etki: Ilk istekte ek DB latency, sonraki isteklerde hizli yanit

Senaryo B: Redis down​

  • Beklenen davranis: DB fallback ile isleme devam
  • Etki: Performans duser ama dogruluk korunur

Senaryo C: Stale ct_ratio​

  • Beklenen davranis: Drift kontrolu ile tespit, key invalidate + rebuild
  • Etki: Kalibrasyon dogrulugu korunur

Senaryo D: Stale buffer_policy​

  • Beklenen davranis: Drift kontrolu ile tespit, key invalidate + rebuild
  • Etki: Ingest/observer tarafinda yanlis runtime davranisi onlenir

Senaryo E: Silinmis cihaz key'i Redis'te kaldi​

  • Beklenen davranis: Silme akisinda zorunlu DEL; kacan durumda ilk okumada DB not found -> key temizligi
  • Etki: Silinmis cihazin islenmesi engellenir

Reconciliation ve Rebuild​

Rebuild kaynaklari:

  1. devices ve iliskili cihaz detay kayitlari (authoritative)
  2. Cihaz envanter guncelleme akislarindan gelen yeni degerler

Rebuild adimlari:

  1. Redis key yoksa veya stale ise DB'den oku.
  2. Govdeyi normalize et (identity, calibration, buffer_policy, cache_meta).
  3. SETEX device:{device_id}:detail <ttl> ile yaz.

Gozlemlenebilirlik Metrikleri​

Asagidaki metrikler izlenmelidir:

  • device_detail_cache_hit_ratio
  • device_detail_cache_miss_total
  • device_detail_db_fallback_latency_ms
  • device_detail_cache_rebuild_total
  • device_detail_drift_detected_total
  • device_detail_invalidation_total
  • device_detail_stale_after_update_total

Alarm onerisi:

  • Cache hit ratio ani dusus
  • DB fallback latency surekli yukselis
  • Drift detected total ani artis

Kullanım Senaryolari​

1) Kalibrasyon ct_ratio cozumleme​

  • Redis device:{device_id}:detail -> hit
  • calibration.ct_ratio alinir ve value_ct = raw_value * ct_ratio uygulanir

2) Ingest veya Observer runtime policy kullanimi​

  • Redis device:{device_id}:detail -> hit
  • buffer_policy alanlari ile duplicate window/payload limiti/TTL davranisi uygulanir

3) Cache miss​

  • Redis miss -> DB fallback
  • Sonuc Redis'e write-back edilir

4) ct_ratio bulunamadi​

  • CT_CONFIG_MISS warning uretilir
  • Fallback olarak ct_ratio = 1 kullanilir
  • Key kalici sema bozuksa invalidate edilir

5) Device update sonrasi tutarlilik​

  • DB update tamamlanir
  • Key invalidate edilir veya guncellenir
  • Bir sonraki okumada key yeni govde ile olusur

Capraz Referanslar​

  • Calibration CT ratio zinciri: /projects/qapu/services/calibration
  • Calibration yazim sirasi: /projects/qapu/services/calibration/data-layer-write-order-chart
  • Redis ana prensipleri: /projects/qapu/services/redis