Window Event Sozlesmeleri

Bu sayfa Window Servisi tarafindan tuketilen/uretilen eventlerin payload sozlesmelerini, zorunlu alanlarini ve versiyonlama kurallarini toplu olarak verir.

Event Haritasi

Event	Ne zaman kullanilir?	Producer	Consumer	Amac
synth.ready.v1	Window akisinin tetiklenmesi icin tuketilir	Synthesis Servisi	Window Servisi	Islenecek stream baglamini almak
window.ready.v1	Window hesap + yazim tamamlandiginda uretilir	Window Servisi	Rule Servisi / API Projection	Window tabanli degerlendirmeyi tetiklemek
window.failed.v1	Window adimi teknik hatayla sonlandiginda uretilir	Window Servisi	Observer Servisi	Hata gorunurlugu ve yeniden gonderim orkestrasyonu

Ortak Envelope

Window eventleri asagidaki ortak zarf yapisini kullanir:

{
  "event": "<name>.v1",
  "meta": {
    "schema_version": 1,
    "trace_id": "9f3f...",
    "producer_service": "window-service",
    "produced_at": "2026-04-12T09:10:11.102Z",
    "process_ms": 22
  },
  "context": {
    "device_id": "400000011D081B70",
    "stream_id": 9823412,
    "device_time": "2026-04-12T09:10:08Z",
    "stream_time": "2026-04-12T09:10:11Z"
  },
  "data": {},
  "error": null
}

Input Event

synth.ready.v1

Window servisi bu eventi tetikleyici olarak tuketir.

Alan	Tip	Zorunlu	Aciklama
event	string	Evet	Sabit deger: synth.ready.v1
meta.schema_version	integer	Evet	Event sema surumu
meta.trace_id	string	Evet	Dagitik izleme kimligi
meta.producer_service	string	Evet	Beklenen deger: synthesis-service
meta.produced_at	datetime	Evet	Event uretim zamani
context.device_id	string	Evet	Cihaz kimligi
context.stream_id	integer	Evet	Islenecek stream kaydi
context.device_time	datetime	Evet	Cihaz zamani
context.stream_time	datetime	Evet	Stream zamani

window.ready.v1

Window hesaplamasi ve yazimlar tamamlandiginda uretilir.

Alanlar

Alan	Tip	Zorunlu	Aciklama
event	string	Evet	Sabit deger: window.ready.v1
meta.schema_version	integer	Evet	Event sema surumu
meta.trace_id	string	Evet	Dagitik izleme kimligi
meta.producer_service	string	Evet	Sabit deger: window-service
meta.produced_at	datetime	Evet	Event uretim zamani
meta.process_ms	integer	Evet	Islem suresi (ms)
context.device_id	string	Evet	Cihaz kimligi
context.stream_id	integer	Evet	Stream kaydi kimligi
data.tables_written[]	string[]	Evet	Yazilan tablo isimleri
data.finalized_windows[]	string[]	Hayir	Bu eventte finalize edilen pencere tipleri
data.calc_version	integer	Evet	Kullanilan hesaplama versiyonu
error	null	Evet	Basari eventinde daima null

Ornek

{
  "event": "window.ready.v1",
  "meta": {
    "schema_version": 1,
    "trace_id": "9f3f...",
    "producer_service": "window-service",
    "produced_at": "2026-04-12T09:10:11.182Z",
    "process_ms": 22
  },
  "context": {
    "device_id": "400000011D081B70",
    "stream_id": 9823412,
    "device_time": "2026-04-12T09:10:08Z",
    "stream_time": "2026-04-12T09:10:11Z"
  },
  "data": {
    "tables_written": [
      "windows_1d"
    ],
    "finalized_windows": [],
    "calc_version": 1
  },
  "error": null
}

window.failed.v1

Window adimi teknik nedenle tamamlanamadiginda uretilir.

Alanlar

Alan	Tip	Zorunlu	Aciklama
event	string	Evet	Sabit deger: window.failed.v1
meta.schema_version	integer	Evet	Event sema surumu
meta.trace_id	string	Evet	Dagitik izleme kimligi
meta.producer_service	string	Evet	Sabit deger: window-service
meta.produced_at	datetime	Evet	Event uretim zamani
meta.process_ms	integer	Evet	Hatanin olustugu ana kadar gecen sure
context.device_id	string	Evet	Cihaz kimligi
context.stream_id	integer	Evet	Stream kaydi kimligi
error.failed_stage	string	Evet	Pipeline asamasi (input_resolution, compute, persist, publish)
error.error_code	string	Evet	Makine okunur hata kodu
error.error_message	string	Evet	Insan okunur hata aciklamasi
error.retryable	boolean	Evet	Yeniden denenebilirlik bilgisi
error.failed_at	datetime	Evet	Hata olusum zamani

Ornek

{
  "event": "window.failed.v1",
  "meta": {
    "schema_version": 1,
    "trace_id": "9f3f...",
    "producer_service": "window-service",
    "produced_at": "2026-04-12T09:10:11.191Z",
    "process_ms": 24
  },
  "context": {
    "device_id": "400000011D081B70",
    "stream_id": 9823412
  },
  "error": {
    "failed_stage": "persist",
    "error_code": "WINDOW_DB_WRITE_FAIL",
    "error_message": "windows_1d upsert failed",
    "retryable": true,
    "failed_at": "2026-04-12T09:10:11Z"
  }
}

Retryable Karar Matrisi

• WINDOW_DB_WRITE_FAIL: true
• WINDOW_INPUT_TRANSIENT: true
• WINDOW_GRID_MISALIGNED: false
• WINDOW_POLICY_INVALID: false
• WINDOW_INPUT_MISSING: false

Observer Replay Akisi

• window.failed.v1 eventi Observer tarafindan consume edilir.
• Observer, yalniz islenmemis/hata almis kayitlari ele alir.
• Replay durumunda event ilgili zaman etiketi korunarak yeniden gonderilir.
• Window Servisi tarafinda tekrar isleme idempotent oldugu icin ayni pencere anahtari guvenle yeniden islenir.

Versiyonlama ve Geriye Donuk Uyumluluk

• Bu dokumanda aktif surum v1 ve meta.schema_version=1 kabul edilir.
• Geriye donuk uyumlu degisiklikler (optional alan ekleme) mevcut v1 altinda yapilir.
• Geriye donuk uyumsuz degisikliklerde yeni event surumu acilir (window.ready.v2, window.failed.v2).
• Tuketici servisler en az bir gecis periyodu boyunca v1 + v2 birlikte dinlemelidir.