Device Buffer Redis Kaydi Sozlesmesi

Bu sayfa, Ingest ile Window arasinda tasinan device_buffer:{device_id} kaydinin tek kanonik referansidir.

Amac, ayni alanin farkli sayfalarda farkli adla veya farkli anlamla anlatilmasini engellemektir.

Kapsam

Bu sozlesme su asamalar icin gecerlidir:

1. Ingest
2. Stream
3. Calibration
4. Raw Writer
5. Synthesis
6. Window

Not: Bu sayfa state kontratini tanimlar. Event payload sozlesmeleri, Kafka topic kurallari ve DB tablo kolonlari ilgili servis sayfalarinda tutulur.

Kanonik Yapi

device_buffer:{device_id} icin hedef JSON yapisi asagidaki gibidir:

{
  "device_id": "400000011D081B70",
  "device_time": "2026-03-12T09:49:58Z",
  "current_stage": "synthesized",
  "ingest": {
    "ingest_time": "2026-03-12T09:50:00Z",
    "is_valid": true,
    "raw_id": 1840021,
    "process_time_ms": 9
  },
  "stream": {
    "stream_id": 9823412,
    "stream_time": "2026-03-12T09:50:01Z",
    "process_time_ms": 11
  },
  "calibration": {
    "calibration_time": "2026-03-12T09:50:02Z",
    "process_time_ms": 12,
    "ct_ratio": 20,
    "calibrated_value_count": 3
  },
  "raw_writer": {
    "write_time": "2026-03-12T09:50:03Z",
    "process_time_ms": 13,
    "table_write_counts": {
      "measurements_voltage": 1,
      "measurements_current": 1,
      "measurements_power": 1,
      "measurements_energy": 1,
      "measurements_device": 1,
      "measurements_register": 1
    }
  },
  "synthesis": {
    "synthesis_time": "2026-03-12T09:50:04Z",
    "process_time_ms": 14,
    "synthesized_variable_count": 2
  },
  "buffers": {
    "measurements": {
      "STATUS": 1073741824,
      "VRMS_R": 229.63,
      "IRMS_R": 252.572,
      "B_IV": 3.02,
      "RSSI": 28
    },
    "synthesis": {
      "VRMS_A": 229.553,
      "IRMS_A": 248.582
    },
    "window": {}
  },
  "schema_version": 1,
  "state_version": 5
}

Tasarim Ilkeleri

1. device_buffer tek bir cihaz icin ortak calisma state'idir.
2. buffers.* alanlari veri payload'i tasir.
3. Kok seviyedeki servis bloklari islem metadatasi tasir.
4. Her servis yalniz sahip oldugu blogu yazar.
5. Asagidaki alanlar append-only degil, son guncel state'i temsil eder:
   • current_stage
   • buffers.measurements
   • buffers.synthesis
   • buffers.window
6. state_version her basarili state mutasyonunda artar.

Alan Gruplari

1) Kimlik ve zaman

Alan	Tip	Zorunlu	Aciklama
device_id	string	Evet	Redis key ile uyumlu cihaz kimligi
device_time	datetime	Evet	Cihazin urettigi olcum zamani
current_stage	string	Evet	State'in pipeline icindeki son basarili asamasi
schema_version	integer	Evet	Device buffer sema surumu
state_version	integer	Evet	Her guncellemede artan state sayaci

2) Servis metadata bloklari

Blok	Producer	Amac
ingest	Ingest	Kabul sonucu, raw kayit referansi, sure
stream	Stream	stream_id, stream zamani, sure
calibration	Calibration	Kalibrasyon uygulama ozeti
raw_writer	Raw Writer	DB yazim zamani ve tablo bazli yazim sayilari
synthesis	Synthesis	Sentez calistirma ozeti

3) Payload buffer bloklari

Blok	Producer	Amac
buffers.measurements	Ingest, Calibration	Canonical measurement payload; Calibration bunu in-place gunceller
buffers.synthesis	Synthesis	Turetilmis metrikler
buffers.window	Window	Pencere ve finalize state'i

Ownership Matrisi

Alan / Blok	Ingest	Stream	Calibration	Raw Writer	Synthesis	Window
device_id	Yazar	Okur	Okur	Okur	Okur	Okur
device_time	Yazar	Okur	Okur	Okur	Okur	Okur
current_stage	Yazar	Gunceller	Gunceller	Gunceller	Gunceller	Gunceller
ingest.*	Yazar	Okur	Okur	Okur	Okur	Okur
stream.*	Okur	Yazar	Okur	Okur	Okur	Okur
calibration.*	Okur	Okur	Yazar	Okur	Okur	Okur
raw_writer.*	Okur	Okur	Okur	Yazar	Okur	Okur
synthesis.*	Okur	Okur	Okur	Okur	Yazar	Okur
buffers.measurements	Yazar	Okur	Gunceller	Okur	Okur	Okur
buffers.synthesis	Okur	Okur	Okur	Okur	Yazar	Okur
buffers.window	Okur	Okur	Okur	Okur	Okur	Yazar
schema_version	Yazar	Okur	Okur	Okur	Okur	Okur
state_version	Yazar	Gunceller	Gunceller	Gunceller	Gunceller	Gunceller

Kural:

• Bir servis, sahip olmadigi kok bloga yeni alan eklememelidir.
• Bir servis, kendinden onceki blogun semantik anlamini degistirmemelidir.
• Yeni payload alanlari once bu sayfada tanimlanmadan servis dokumanina eklenmemelidir.

Stage Gecisleri

Onceki durum	Event / islem	Sonraki durum
yok	Ingest kabul	ingested
ingested	Stream kaydi olustu	streamed
streamed	Kalibrasyon tamamlandi	calibrated
calibrated	Raw Writer DB yazimi tamamlandi	raw_persisted
raw_persisted	Sentez tamamlandi	synthesized
synthesized	Window guncellendi	windowed

Kural:

• current_stage yalniz basarili geciste ilerler.
• Failed event uretmek stage'i ilerletmez.
• Retry ayni stage uzerinden tekrar calisabilir.

Guncelleme Kurallari

Ingest

• device_buffer kaydini ilk olusturan servistir.
• buffers.measurements icine canonical payload'i yazar.
• ingest blogunu doldurur.

Stream

• stream blogunu yazar.
• current_stage = streamed yapar.
• state_version artirir.

Calibration

• Yeni bir measurement buffer acmaz.
• buffers.measurements icindeki ilgili alanlari in-place gunceller.
• calibration blogunu yazar.

Raw Writer

• buffers.measurements kaynagini okur.
• DB yazim ozetini raw_writer bloguna yazar.
• Basarili durumda current_stage = raw_persisted yapar.

Synthesis

• buffers.measurements ve gerekli kalici kaynaklardan girdi cozer.
• Sonuclari buffers.synthesis alanina yazar.
• synthesis blogunu yazar.

Window

• buffers.window alanini gunceller.
• Gerekirse finalizasyon state'i ekler.

Bilincli Olarak Kullanilmayan Alanlar

Asagidaki alan adlari bu kontratin disindadir ve yeni dokumanda kullanilmamalidir:

• raw_buffer
• synth_buffer
• window_buffer
• raw_last
• device_buffer.raw
• device_buffer.device
• redis_stream_refreshed

Ornek Fixture Zinciri

Bu sozlesmenin asama bazli ornekleri her servis sayfasinda inline gosterilmektedir:

• Ingest sonrasi fixture
• Stream sonrasi fixture
• Calibration sonrasi fixture
• Raw Writer sonrasi fixture
• Synthesis sonrasi fixture

Kullanim Kurali

Bu sayfadan sonra bir servis dokumaninda device_buffer anlatilacaksa:

1. Buradaki alan adlari aynen kullanilmali.
2. Yeni alan gerekiyorsa once bu sayfa guncellenmeli.
3. Servis sayfasi sadece kendi sahip oldugu alanlari anlatmali.
4. Tam state ornegi kopyalanmak yerine bu sayfaya link verilmelidir.

Dogrulama

Bu sozlesmenin fixture dosyalariyla uyumlu kalmasi icin JSON Schema dogrulamasi zorunludur.

• Schema dosyasi: /project-qapu/services/redis/schemas/device-buffer.schema.json
• Dogrulama scripti: /scripts/validate_device_buffer_fixtures.mjs
• Komut: npm run validate:device-buffer

Bu komut asagidaki fixture zincirini tek seferde dogrular:

1. ingest
2. stream
3. calibration
4. raw-writer
5. synthesis