Calibration Servisi

Calibration Servisi, Stream Servisinden gelen stream.assembled.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.

Sorumluluk

• stream.assembled.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ışı

Hesap Kuralı

İşlem sırası:

1. CT dönüşümü (cihaz konfigürasyonu):
   • value_ct = raw_value * ct_ratio
2. Kalibrasyon kuralı (değişken bazlı):
   • calibrated_value = value * gain + offset

Not:

• Kural bulunmayan değişken kalibrasyonda pas geçilir.
• Çıkış veri setinde kalibrasyon uygulanmış ve uygulanmamış alanlar birlikte taşınabilir.

Kural Çözümleme Önceliği

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

Bu öncelik deterministic olmalıdır.

Değişken Bazlı Kalibrasyon Uygulaması

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

1. status = true olan kayıtlar filtrelenir.
2. Zaman penceresi kontrol edilir:
   • valid_from <= device_time
   • valid_to is null veya device_time <= valid_to
3. Cihaz özel kayıtlar global kayıtlara göre önceliklidir.
4. 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_input * 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:

1. Redis: device:{device_id}:detail
2. Redis miss ise DB fallback: devices tablosu (ct_ratio)
3. 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.

calibrations Tablo Şeması

Kolon	Tip	Not
id	bigint PK	Kayıt kimliği
device_id	varchar(21) FK	0 global kalibrasyon
variable_id	varchar(30) FK	Kalibre edilen değişken
gain	double precision	Çarpan
offset	double precision	Ofset
status	boolean	Aktif/pasif
priority	integer	İkincil sıralama
valid_from	timestamptz	Geçerlilik başlangıcı
valid_to	timestamptz	Geçerlilik bitişi
version	integer	Kural sürümü
create_time	timestamptz	Oluşturma zamanı
update_time	timestamptz	Güncelleme zamanı

Kalibrasyon Kural Cache Modeli

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

Çözümleme sırası:

1. Redis cihaz key'i: cal:{device_id}:latest
2. Redis global key'i: cal:0:latest
3. 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.ready.v1

{
  "event": "calibration.ready.v1",
  "meta": {
    "schema_version": 1,
    "trace_id": "9f3f...",
    "producer_service": "calibration-service",
    "produced_at": "2026-03-11T15:22:09.102Z",
    "process_ms": 14
  },
  "context": {
    "device_id": "400000011D081B70",
    "stream_id": 9823412,
    "device_time": "2026-03-11T15:22:06Z",
    "stream_time": "2026-03-11T15:22:09Z"
  },
  "data": {
    "calibration_version": 12,
    "calibrated": true,
    "warnings": [
      "CT_CONFIG_MISS"
    ]
  },
  "error": null
}

calibration.failed.v1

{
  "event": "calibration.failed.v1",
  "meta": {
    "schema_version": 1,
    "trace_id": "9f3f...",
    "producer_service": "calibration-service",
    "produced_at": "2026-03-11T15:22:09.140Z",
    "process_ms": 13
  },
  "context": {
    "device_id": "400000011D081B70",
    "stream_id": 9823412
  },
  "error": {
    "failed_stage": "calibration",
    "error_code": "CAL_RULE_MISS",
    "error_message": "calibration snapshot not found",
    "failed_at": "2026-03-11T15:22:09Z"
  }
}

Hata Kodları

• CAL_RULE_MISS
• CT_CONFIG_MISS
• CAL_SNAPSHOT_INVALID
• CALCULATION_ERROR

Redis Assembly Güncelleme ve Çıktı

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

1. Redis device_buffer:{device_id} içindeki assembly.payload_merged alanını kalibre değerlerle overwrite eder.
2. assembly.calibration meta bloğu güncellenir:
   • calibration_version
   • ct_ratio
   • calibrated_at
3. Ardından calibration.ready.v1 eventi üretilir.

Önerilen assembly kalibrasyon meta örneği:

{
  "assembly": {
    "payload_merged": {
      "IRMS_R": 0.812,
      "IRMS_S": 0.806
    },
    "calibration": {
      "calibration_version": 12,
      "ct_ratio": 200.0,
      "calibrated_at": "2026-03-12T12:10:02Z"
    }
  }
}

Çıktı

Calibration Servisinin çıktısı:

• Redis'te kalibre edilmiş assembly.payload_merged
• Kafka'da calibration.ready.v1 eventi

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