Calibration Servisi

Calibration Servisi, Stream Servisinden gelen stream.created.v1 eventini tüketip ham ölçüm değerlerini kalibrasyon kurallarına göre normalize eden mikroservistir.

Bu servis ham veriyi doğrudan DB segment tablolarına yazmaz. Çıktı olarak kalibre edilmiş veri setini bir sonraki katmana (Raw Writer) devreder.

Kanonik State Sozlesmesi

device_buffer alanlari, ownership ve stage gecisleri icin Device Buffer Redis Kaydi Sozlesmesi sayfasina bakiniz.

Sorumluluk

stream.created.v1 eventini consume etmek
Cihaz konfigürasyonundan CT oranını çözmek
Kalibrasyon kuralını (gain, offset) cihaz+global öncelikle çözmek
Değişken bazlı kalibrasyon uygulamak (kural yoksa pas geç)
Başarıda calibration.ready.v1, hatada calibration.failed.v1 üretmek

İşlem Akışı

Akış Diyagramı

Detaylı işlem akışı için Calibration Servisi Akış Diyagramı sayfasına bakınız.

Veri Katmanları Yazım Sırası

Calibration servisinde Redis, kural cache ve Kafka yazım sırasını görmek için Veri Katmanları Arası Yazım Sırası sayfasına bakınız.

Hesap Kuralı

İşlem sırası:

Aktiflik kontrolü:

Kalibrasyon uygulaması ilgili değişken için aktif değilse (kural yok veya kural status = false) değer olduğu gibi bırakılır; CT dönüşümü de uygulanmaz.

CT dönüşümü (cihaz konfigürasyonu):

value_ct = raw_value * ct_ratio

Kalibrasyon kuralı (değişken bazlı):

calibrated_value = value_ct * gain + offset

Not:

Kural bulunmayan değişken kalibrasyonda pas geçilir.
Çıkış veri setinde kalibrasyon uygulanmış ve uygulanmamış alanlar birlikte taşınabilir.
Yürütme sırası sabittir: önce CT, sonra diğer kalibrasyonlar.

Kural Çözümleme Önceliği

Cihaz özel kural (device_id = gerçek cihaz)
Global kural (device_id = '0')
Kural yoksa pas geç

Bu öncelik deterministic olmalıdır.

Önemli:

priority, CT dönüşümünün önüne geçmez; yalnız CT sonrası değişken kalibrasyonunda hangi aktif kuralın seçileceğini belirler.

Değişken Bazlı Kalibrasyon Uygulaması

Her değişken için uygulanacak kural aşağıdaki sırayla seçilir:

status = true olan kayıtlar filtrelenir.
Zaman penceresi kontrol edilir:
- valid_from <= device_time
- valid_to is null veya device_time <= valid_to
Cihaz özel kayıtlar global kayıtlara göre önceliklidir.
Aynı seviyede birden çok aday varsa:
- priority ASC uygulanır (küçük değer daha öncelikli)
- eşitlikte update_time en yeni olan seçilir.

Seçilen kural için uygulama:

value_calibrated = value_ct * gain + offset

Kural bulunamazsa ilgili değişken pas geçilir (orijinal değer korunur).

Not: priority sıralama yönü servis konfigürasyonunda sabitlenmelidir; V1'de tek bir yön kullanılır ve dokümana kilitlenir.

CT Ratio Çözümleme Kaynağı

CT ratio çözümleme zinciri:

Redis: device:{device_id}:detail
Redis miss ise DB fallback: devices tablosu (ct_ratio)
DB'den gelen değer Redis'e write-back edilir

Beklenen device detail örneği:

{
  "device_id": "400000011D081B70",
  "created_at": "2025-11-01T08:00:00Z",
  "last_data_at": "2026-03-12T12:10:00Z",
  "firmware": "1.0.7",
  "iccid": "8946120802005507363",
  "imei": "354485417650889",
  "ct_ratio": 200.0,
  "updated_at": "2026-03-12T12:10:00Z"
}

Not: ct_ratio bulunamazsa CT_CONFIG_MISS üretilir ve servis fallback olarak ct_ratio = 1 ile devam eder.

Kalibrasyon Data Modeli

Kalibrasyon şema detayları için data-model belgelerine bakınız:

Kalibrasyon Kural Cache Modeli

Kalibrasyon kural çözümleme Redis öncelikli, DB fallback çalışır.

Çözümleme sırası:

Redis cihaz key'i: cal:{device_id}:latest
Redis global key'i: cal:0:latest
Cache miss durumunda DB'den cihaz+global kuralları çöz, Redis'e write-back yap

Önerilen Redis gövdesi:

{
  "device_id": "400000011D081B70",
  "version": 12,
  "variables": {
    "IRMS_R": {
      "gain": 1.015,
      "offset": 0.002
    },
    "IRMS_S": {
      "gain": 1.014,
      "offset": 0.001
    },
    "IRMS_T": {
      "gain": 1.016,
      "offset": 0.003
    }
  },
  "updated_at": "2026-03-12T12:00:00Z"
}

Notlar:

Cihaz özel kural yoksa global (device_id='0') fallback uygulanır.
Kural güncellemesinde cache invalidation zorunludur.

Event Sözleşmeleri

Calibration Event Sözleşmeleri

calibration.ready.v1 ve calibration.failed.v1 dahil tüm event payload sözleşmeleri için Event Sözleşmeleri sayfasına bakınız.

Redis Buffer Güncelleme ve Çıktı

Kalibrasyon uygulandıktan sonra servis aşağıdaki adımları uygular:

Redis device_buffer:{device_id} içindeki buffers.measurements alanını kalibre değerlerle in-place overwrite eder.
Ardından calibration.ready.v1 eventi üretilir.

Kural:

device_buffer içinde kalibrasyon için yeni bir kayıt veya paralel buffer alanı açılmaz.
Sadece mevcut buffers.measurements içindeki ilgili ölçüm alanları güncellenir.

Device Buffer Flow

stream.created.v1 sonrasinda Calibration Servisinin device_buffer uzerinde olusturdugu ornek fixture:

Tum asamalari tek sayfada gormek icin Device Buffer Flow dokumanina bakiniz.

{
  "device_id": "64000000C466EF70",
  "device_time": "2026-04-13T11:18:09Z",
  "current_stage": "calibrated",
  "ingest": {
    "ingest_time": "2026-04-13T11:18:10Z",
    "is_valid": true,
    "raw_id": 2841023,
    "process_time_ms": 8
  },
  "stream": {
    "stream_id": 10248764,
    "stream_time": "2026-04-13T11:18:11Z",
    "process_time_ms": 13
  },
  "calibration": {
    "calibration_time": "2026-04-13T11:18:12Z",
    "process_time_ms": 11,
    "ct_ratio": 1,
    "vt_ratio": 1,
    "calibrated_value_count": 3
  },
  "buffers": {
    "measurements": {
      "VRMS_R": 220.006,
      "VRMS_S": 223.792,
      "VRMS_T": 221.671,
      "IRMS_R": 3.995,
      "IRMS_S": 4.073,
      "IRMS_T": 3.887,
      "IFUND_R": 3.999,
      "IFUND_S": 4.067,
      "IFUND_T": 3.863,
      "IPEAK_R": 6.012,
      "IPEAK_S": 6.246,
      "IPEAK_T": 5.925,
      "VFUND_R": 219.997,
      "VFUND_S": 223.793,
      "VFUND_T": 221.752,
      "P_R": 746.184,
      "P_S": 764.792,
      "P_T": 777.262,
      "Q_R": 467.521,
      "Q_S": 496.76,
      "Q_T": 360.724,
      "S_R": 879.551,
      "S_S": 911.181,
      "S_T": 861.344,
      "PF_R": 0.85,
      "PF_S": 0.84,
      "PF_T": 0.9,
      "AE_R": 62,
      "AE_S": 64,
      "AE_T": 65,
      "FQ": 49.98,
      "STOP": 36702270,
      "IHARM_R_3": 0.036,
      "IHARM_R_5": 0.059,
      "IHARM_R_7": 0.07,
      "IHARM_R_9": 0.004,
      "IHARM_S_3": 0.143,
      "IHARM_S_5": 0.093,
      "IHARM_S_7": 0.061,
      "IHARM_S_9": 0.008,
      "IHARM_T_3": 0.362,
      "IHARM_T_5": 0.105,
      "IHARM_T_7": 0.17,
      "IHARM_T_9": 0.055,
      "VHARM_R_3": 2.598,
      "VHARM_R_5": 0.951,
      "VHARM_R_7": 4.972,
      "VHARM_R_9": 0.205,
      "VHARM_S_3": 1.999,
      "VHARM_S_5": 4.082,
      "VHARM_S_7": 3.597,
      "VHARM_S_9": 0.537,
      "VHARM_T_3": 3.705,
      "VHARM_T_5": 4.228,
      "VHARM_T_7": 0.372,
      "VHARM_T_9": 0.92,
      "PCB_T": 22.95,
      "PCB_H": 48.34,
      "RSSI": 6,
      "STATUS": 1073741839
    },
    "synthesis": {},
    "window": {}
  },
  "device_metadata": {
    "device_id": "64000000C466EF70",
    "iccid": "899001190805082918",
    "firmware": "05.00.05",
    "device_type": "multi_function_meter"
  },
  "schema_version": 2,
  "state_version": 3
}

Bu dosya, bir sonraki adimda Raw Writer Servisine input olarak kullanilabilir.

Çıktı

Calibration Servisinin çıktısı:

Redis'te kalibre edilmiş buffers.measurements
Kafka'da calibration.ready.v1 eventi

Raw Writer Servisi bu eventi tüketerek ham segment tablolarına kalibre değerleri yazar.

Sık Sorulan Sorular

Calibration FAQ

Troubleshooting ve operasyonel sık sorular için Sık Sorulan Sorular sayfasına bakınız.

Sorumluluk​

İşlem Akışı​

Hesap Kuralı​

Kural Çözümleme Önceliği​

Değişken Bazlı Kalibrasyon Uygulaması​

CT Ratio Çözümleme Kaynağı​

Kalibrasyon Kural Cache Modeli​

Event Sözleşmeleri​

Redis Buffer Güncelleme ve Çıktı​

Çıktı​

Sık Sorulan Sorular​