Raw Writer Servisi

Raw Writer Servisi, calibration.ready.v1 eventini tüketip kalibre edilmiş verileri ham segment tablolarına kalıcı olarak yazan mikroservistir.

Bu servis sentez hesaplaması yapmaz; yalnızca normalize/kalibre veriyi doğru tabloya, doğru stream_id ile yazar ve bir sonraki katmanı tetikler.

Sorumluluk

• calibration.ready.v1 eventini consume etmek
• Redis device_buffer:{device_id}.assembly.payload_merged içinden kalibre veri setini okumak
• Veriyi segment bazında doğru tablolarına dağıtmak
• Yazım tutarlılığını stream_id üzerinden korumak (idempotent upsert)
• Başarıda raw.persisted.v1, hatada raw.failed.v1 üretmek

İşlem Akışı

Tablo Dağıtım Kuralı

Hedef tablo	Yazılan alan grubu
energy_voltage_measurements	VRMS_*, VFUND_*, VHARM_*, FREQ
energy_current_measurements	IRMS_*, IFUND_*, IHARM_*, IPEAK_*
energy_power_measurements	P_*, Q_*, S_*, PF_*, PHARM_*, QHARM_*, SHARM_*
energy_energy_measurements	PE_*, QE_*

Her tabloda ortak alanlar:

• stream_id
• device_id
• device_time
• stream_time

Segment Tablo Şemaları

Aşağıdaki şemalar Raw Writer yazım hedeflerini tanımlar.

energy_voltage_measurements

Kolon	Tip	Not
stream_id	bigint FK UNIQUE	streams.id
device_id	varchar(21)
device_time	timestamptz
stream_time	timestamptz
vrms_r, vrms_s, vrms_t	double precision
vfund_r, vfund_s, vfund_t	double precision
vharm_r_3/5/7, vharm_s_3/5/7, vharm_t_3/5/7	double precision
freq	double precision

energy_current_measurements

Kolon	Tip	Not
stream_id	bigint FK UNIQUE	streams.id
device_id	varchar(21)
device_time	timestamptz
stream_time	timestamptz
irms_r, irms_s, irms_t	double precision
ifund_r, ifund_s, ifund_t	double precision
iharm_r_3/5/7, iharm_s_3/5/7, iharm_t_3/5/7	double precision
ipeak_r, ipeak_s, ipeak_t	double precision

energy_power_measurements

Kolon	Tip	Not
stream_id	bigint FK UNIQUE	streams.id
device_id	varchar(21)
device_time	timestamptz
stream_time	timestamptz
p_r/s/t, q_r/s/t, s_r/s/t	double precision
pf_r/s/t	double precision
pharm_*, qharm_*, sharm_*	double precision	varsa

energy_energy_measurements

Kolon	Tip	Not
stream_id	bigint FK UNIQUE	streams.id
device_id	varchar(21)
device_time	timestamptz
stream_time	timestamptz
pe_*, qe_*	double precision	enerji sayaçları

Yazım Kuralları

• Yazım anahtarı stream_id’dir.
• Aynı stream_id tekrar işlenirse idempotent upsert uygulanır.
• Segmentlerden biri başarısız olursa event raw.failed.v1 ile işaretlenir.
• Transaction modeli all-or-nothing olarak çalışır: segment yazımlarının tamamı başarılıysa commit edilir, aksi durumda rollback uygulanır.
• Önerilen transaction isolation: READ COMMITTED + idempotent upsert (yüksek throughput için dengeli varsayılan).

Yazım Sonrası Akış

DB yazımı tamamlandıktan sonra servis:

1. Redis device_buffer:{device_id}.assembly bloğunu günceller:
   • raw_persisted = true
   • raw_persisted_at
   • (opsiyonel) written_segments
2. Başarılıysa raw.persisted.v1 üretir.
3. Downstream sentez katmanını tetikler.

Başarısızlıkta:

1. Redis'te raw_persisted = false kalır ve hata meta bilgisi işlenir.
2. raw.failed.v1 üretilir.
3. Hata kodu log + DLQ akışına taşınır.
4. Tekrar işleme idempotent olarak stream_id üstünden yapılır.

Not: Sentez Servisi, yalnız raw_persisted=true işaretli stream setlerini işlemeye alır.

Event Sözleşmeleri

raw.persisted.v1

{
  "event": "raw.persisted.v1",
  "meta": {
    "schema_version": 1,
    "trace_id": "9f3f...",
    "producer_service": "raw-writer-service",
    "produced_at": "2026-03-11T15:22:10.090Z",
    "process_ms": 42
  },
  "context": {
    "device_id": "400000011D081B70",
    "stream_id": 9823412,
    "device_time": "2026-03-11T15:22:06Z",
    "stream_time": "2026-03-11T15:22:10Z"
  },
  "data": {
    "persisted": true,
    "written_segments": [
      "voltage",
      "current",
      "power",
      "energy"
    ]
  },
  "error": null
}

written_segments sabit enum kümesi:

• voltage
• current
• power
• energy

raw.failed.v1

{
  "event": "raw.failed.v1",
  "meta": {
    "schema_version": 1,
    "trace_id": "9f3f...",
    "producer_service": "raw-writer-service",
    "produced_at": "2026-03-11T15:22:10.130Z",
    "process_ms": 42
  },
  "context": {
    "device_id": "400000011D081B70",
    "stream_id": 9823412
  },
  "error": {
    "failed_stage": "raw_writer",
    "error_code": "RAW_DB_WRITE_FAIL",
    "error_message": "energy_current_measurements insert failed",
    "retryable": true,
    "failed_at": "2026-03-11T15:22:10Z",
    "failed_table": "energy_current_measurements"
  }
}

retryable karar matrisi:

• RAW_DB_WRITE_FAIL: true (geçici DB hatası olabilir)
• RAW_PAYLOAD_MISSING: false
• RAW_SCHEMA_MISMATCH: false

Hata Kodları

• RAW_PAYLOAD_MISSING
• RAW_DB_WRITE_FAIL
• RAW_SCHEMA_MISMATCH

Çıktı

Raw Writer Servisinin çıktısı:

• Ham segment tablolarında kalıcı veri
• Kafka’da raw.persisted.v1 (veya hata durumunda raw.failed.v1)

Sentez Servisi raw.persisted.v1 eventini tüketerek hesap aşamasını başlatır.