⚠️ Arşiv Notu: Bu sayfa aktif akışın ana referansı değildir; geçmiş tasarım/bağlam için korunur.

Cınga Energy Data Architecture (Full Archive)

Bu sayfa, konuşmalar sırasında oluşturulan detaylı teknik dokümanın tam arşiv sürümüdür. Parçalı güncel anlatım için /projects/cinga/veri-isleme alt sayfalarını kullanabilirsiniz.

Bu doküman, Cınga projesi için enerji verisi işleme mimarisini tanımlar. Amaç; cihazdan gelen ham veriyi güvenli ve ölçeklenebilir biçimde işleyip, sentez skorlarını ve pencere analizlerini üretirken veritabanı yükünü kontrollü tutmaktır.

Yönetici Özeti

Cınga veri işleme modeli üç katmanda çalışır: ham segment tabloları, sentez tablosu ve pencere (window) tablosu. Ham enerji verisi segmentlerine ayrılarak (voltage, current, power, energy) yazılır; ardından stream bazlı sentez metrikler ve skorlar hesaplanır; son aşamada sabit ve kayar pencereler güncellenir. Kural motoru DB kaynaklıdır, Redis cache ile hızlandırılır ve cache miss durumunda DB fallback uygulanır.

Bu yaklaşımın ana kazanımı; aynı anda hem izlenebilirlik (ham veri korunur), hem hız (işe göre tablo okuma), hem de ölçeklenebilirliktir (queue tabanlı async worker akışı).

Basit İşlem Akışı (Özet)

1. Cihaz payload’ı alınır, streams kaydı oluşturulur.
2. Redis’ten CT ratio, değişken listesi ve kalibrasyon bilgisi alınır.
3. Ham veriler kalibre edilir ve segment tablolara yazılır.
4. Sentez motoru stream-anlık metrikleri ve skorları hesaplayıp energy_measurements_synth tablosuna yazar.
5. Window motoru sabit (1D/1W/1M) ve kayar (1D_Last/1W_Last/1M_Last) pencereleri günceller.
6. Tüm adımlar idempotent upsert mantığıyla yürütülür.

Bu doküman, mevcut veri akışını bozmadan enerji verisini analize daha uygun bir yapıya taşımak için seçilen yeni mimariyi anlatır. Buradaki kararın odağı yalnızca tablo eklemek değildir; asıl amaç, segment bazlı analiz yapan servislerin yalnızca ihtiyaç duyduğu veriyi okuyarak çalışması ve veritabanı yükünün kontrollü biçimde dağılmasıdır.

Tasarım Prensibi

Bu modelde üç temel ilke korunur: ham veri korunur, sentez ayrı yaşar, analiz pencereleri özet katmanda tutulur. Yeni karar bunun üstüne bir katman daha ekler: enerji ham veri tek tabloda değil, segment bazlı tablolarda tutulur.

Mevcut Akışın Kısa Özeti

Cihaz verisi önce streams tablosuna kaydedilir. Ardından measurement pipeline içinde kalibrasyon, temizleme, sentezleme ve günlük hesap adımları çalışır ve sonuçlar measurements tablosuna yazılır. Bu yaklaşım üretimde çalışır; ancak enerji analizlerinde EAV modelinin join/pivot maliyeti ve gereksiz veri okuma oranı büyür.

Bu nedenle enerji tarafı, analiz davranışına uygun şekilde parçalı bir modele alınır.

Yeni Karar: Segment Bazlı Enerji Ham Veri Modeli

Enerji verisi artık tek bir energy_measurements tablosunda değil, analiz doğasına uygun dört segmentte tutulur:

Katman	Tablo	İçerik	Yazım Granülaritesi
Enerji ham (gerilim)	energy_voltage_measurements	VRMS/FUND/HARM ve ilgili voltaj metrikleri	Stream başına tek satır
Enerji ham (akım)	energy_current_measurements	IRMS/PEAK/FUND/HARM ve ilgili akım metrikleri	Stream başına tek satır
Enerji ham (güç)	energy_power_measurements	WATT/VAR/VA/PF/TEMPC	Stream başına tek satır
Enerji ham (sayaç)	energy_energy_measurements	WH/VARH pozitif-negatif kümülatif sayaçlar	Stream başına tek satır
Enerji sentez	energy_measurements_synth	Skorlar, drift, indeksler, kalite işaretleri	Stream başına tek satır
Pencere analizi	energy_windows	Sabit + kayar (rolling) pencerelerde özet metrikler ve trend istatistikleri	Pencere başına tek satır
Genel ölçüm	measurements	Enerji dışı veya EAV esnekliği gereken değişkenler	Stream başına çoklu kayıt

Bu yapı sayesinde, örneğin sadece gerilim anomali analizi yapan servis energy_voltage_measurements tablosunu okuyarak işini tamamlar; akım/güç/sayaç verisini gereksiz yere taşımamış olur.

Neden Segment Bazlı Ayrım?

Sentez, skor ve trend işlerinde analizler çoğunlukla segment içinde yürür. Segment bazlı tablo ayrımı, hem okuma maliyetini düşürür hem de job izolasyonunu güçlendirir.

Tablo Rolleri ve Sınırlar

measurements (korunur)

Bu tablo kaldırılmaz. Enerji dışı değişkenler, sık evrilen parametreler veya EAV esnekliği gereken alanlar için sistem omurgası olarak yaşamaya devam eder.

energy_*_measurements (ham segment tabloları)

Bu tablolar ham enerji verisinin kalıcı ve hızlı okunabilir kaynağıdır. Her biri stream başına tek satır yazar ve ortak anahtar setini paylaşır: stream_id, device_id, stream_time, device_time. Ham tablolarda sentez kolonları tutulmaz.

energy_measurements_synth (sentez katmanı)

Sentezlenmiş metrikler (ör. grid_score, distribution_drift, health_score, unbalance_idx) bu tabloda tutulur. calc_version, rule_version_hash ve quality_flags zorunlu kabul edilir. Böylece kural değiştiğinde ham tablolara dokunmadan sentez katmanı yeniden üretilebilir.

Operasyonel Kural

Ham enerji segment tablolarına sentez alanı eklenmez. Ham ve sentez karışımı kısa vadede kolay görünse de orta vadede audit, versiyonlama ve recompute süreçlerini zorlaştırır.

Pencere (Window) Katmanı

Pencere katmanı enerji analizinin karar tabanıdır. Burada önerilen benzersizlik anahtarı şöyledir:

(device_id, variable_id, window_type, window_start)

Pencere kayıtları yalnızca istatistik değil veri kalitesi de taşır. sample_count, expected_sample_count, completeness_ratio, finalized alanları penceredeki güvenilirliği ölçer. sum, sum_sq, min, max ortalama/dağılım hesaplarını; sum_t, sum_v, sum_tv, sum_t2 trend/eğim çıkarımlarını destekler. İhtiyaca göre p10, p50, p90, skewness, kurtosis da aynı satırda tutulur.

Enerji sayaç değişkenlerinde pencere boyunca first_value, last_value, delta_value hesapları zorunlu kabul edilir; reset/rollover durumları kalite bayrağına yazılır.

Akış Mantığı (Güncel)

Ingestion katmanı tek kaynaklı kalır: cihaz verisi streams üzerinden alınır, pipeline adımları sonrası enerji segment tablolarına ve gerekiyorsa genel measurements tablosuna yazılır. Sentez motoru enerji segmentlerinden beslenerek energy_measurements_synth tablosunu üretir. Window agregatörü ise ham segmentler ve gerekli olduğu durumda sentez katmanından beslenip energy_windows tablosuna özet kayıtları yazar.

Bu yaklaşımda okuma ve hesap yükü fonksiyonel olarak ayrışır; her servis yalnızca kendi ihtiyaç duyduğu katmanı okur.

Sorgu Stratejisi

Kısa zaman aralığında yalnızca gerilim analizi gerekiyorsa yalnızca gerilim segment tablosu okunur. Akım veya güç odaklı analizde ilgili segment seçilir. Sayaç trendi ve tüketim akışında enerji sayaç tablosu temel kaynaktır. Operasyonel skorlar ve sağlık çıktıları sentez tablosundan alınır. Orta-uzun dönem eğilim, drift ve karşılaştırma ihtiyaçları window katmanından karşılanır.

Bu stratejide amaç, "tek sorguda her şey" yaklaşımını bırakıp "işe göre veri" prensibine geçmektir.

Nihai Enerji Tablo Yapıları (v1)

Aşağıdaki tablolar, segment bazlı modelin ilk üretim sürümünde kullanılacak nihai alan setini tanımlar. Her enerji segment tablosu ortak çekirdek alanları paylaşır; bu sayede join, izleme ve geriye dönük doğrulama operasyonları tutarlı kalır.

Ortak Çekirdek Alanlar

Alan	Tip	Not
id	bigint PK	Otomatik artan kimlik
stream_id	bigint	streams.id referansı, tabloda unique
device_id	varchar(21)	Cihaz kimliği
device_time	timestamptz	Cihaz zamanı
stream_time	timestamptz	Sunucu/alım zamanı
ingest_version	integer	Pipeline sürümü
quality_flags	jsonb	Kalite/uyarı bayrakları
created_at	timestamptz	Kayıt oluşturma zamanı

Anahtar Kural

Her segment tablosunda stream_id unique olmalıdır. Böylece aynı stream için aynı segmente ikinci kez ham kayıt yazılması engellenir.

1) energy_voltage_measurements

Bu tablo gerilim segmentini tutar.

Kolon	Tip	Açıklama
va, vb, vc	float	Faz anlık gerilimleri
va_rms, vb_rms, vc_rms	float	Faz RMS gerilimleri
vt_rms	float	Toplam/ortalama RMS gerilim
vfund_a, vfund_b, vfund_c	float	Faz bazlı temel gerilim bileşeni
vharm_a, vharm_b, vharm_c	float	Faz bazlı harmonik gerilim bileşeni
freq	float	Şebeke frekansı
va_rms_min, va_rms_max	float (ops.)	Pencere içi A faz RMS min/max
vb_rms_min, vb_rms_max	float (ops.)	Pencere içi B faz RMS min/max
vc_rms_min, vc_rms_max	float (ops.)	Pencere içi C faz RMS min/max
freq_min, freq_max	float (ops.)	Pencere içi frekans min/max
v_h3_a/b/c, v_h5_a/b/c, v_h7_a/b/c, v_h9_a/b/c	float (ops.)	Faz bazlı 3/5/7/9 harmonik gerilimler

2) energy_current_measurements

Bu tablo akım segmentini tutar.

Kolon	Tip	Açıklama
ia, ib, ic	float	Faz anlık akımları
ia_peak, ib_peak, ic_peak	float	Faz tepe akım değerleri
ia_rms, ib_rms, ic_rms	float	Faz RMS akımları
it_rms	float	Toplam/ortalama RMS akım
ifund_a, ifund_b, ifund_c	float	Faz bazlı temel akım bileşeni
iharm_a, iharm_b, iharm_c	float	Faz bazlı harmonik akım bileşeni
ia_rms_min, ia_rms_max	float (ops.)	Pencere içi A faz RMS min/max
ib_rms_min, ib_rms_max	float (ops.)	Pencere içi B faz RMS min/max
ic_rms_min, ic_rms_max	float (ops.)	Pencere içi C faz RMS min/max
i_h3_a/b/c, i_h5_a/b/c, i_h7_a/b/c, i_h9_a/b/c	float (ops.)	Faz bazlı 3/5/7/9 harmonik akımlar

3) energy_power_measurements

Bu tablo güç ve güç kalitesi segmentini tutar.

Kolon	Tip	Açıklama
qfund_a, qfund_b, qfund_c	float	Faz bazlı temel reaktif güç
qharm_a, qharm_b, qharm_c	float	Faz bazlı harmonik reaktif güç
watt_a, watt_b, watt_c	float	Faz bazlı aktif güç
watt_t	float	Toplam aktif güç
var_a, var_b, var_c	float	Faz bazlı reaktif güç
var_t	float	Toplam reaktif güç
va_a, va_b, va_c	float	Faz bazlı görünür güç
va_t	float	Toplam görünür güç
pfund_a, pfund_b, pfund_c	float	Faz bazlı temel güç bileşeni
pharm_a, pharm_b, pharm_c	float	Faz bazlı harmonik güç bileşeni
vafunda, vafundb, vafundc	float	Faz bazlı temel görünür güç
pfa, pfb, pfc	float	Faz bazlı güç faktörü
pf_t	float	Toplam güç faktörü
tempc	float	Ölçüm entegresi/cihaz sıcaklığı

4) energy_energy_measurements

Bu tablo enerji sayaç segmentini tutar.

Kolon	Tip	Açıklama
wha_pos, wha_neg	float	A faz aktif enerji ithal/ihrac
whb_pos, whb_neg	float	B faz aktif enerji ithal/ihrac
whc_pos, whc_neg	float	C faz aktif enerji ithal/ihrac
varha_pos, varha_neg	float	A faz reaktif enerji +/−
varhb_pos, varhb_neg	float	B faz reaktif enerji +/−
varhc_pos, varhc_neg	float	C faz reaktif enerji +/−
delta_wh_total	float (ops.)	Pencere içi toplam aktif enerji farkı
delta_varh_total	float (ops.)	Pencere içi toplam reaktif enerji farkı
counter_reset_flag	boolean (ops.)	Sayaç reset tespiti
counter_rollover_flag	boolean (ops.)	Sayaç rollover tespiti

5) energy_measurements_synth

Sentez/analitik katman tablosu sadeleştirilmiştir. Bu tabloda pencere (rolling) analizlerinden üretilen metrikler tutulmaz; onlar yalnızca energy_windows katmanında yer alır. energy_measurements_synth yalnızca stream-anlık türevler ve nihai skorlar için kullanılır.

Kimlik ve Sürüm Alanları

Kolon	Tip	Açıklama
id	bigint PK
stream_id	bigint unique	Hedef stream
device_id	varchar(21)
stream_time	timestamptz
calc_version	integer	Hesap motoru sürümü
rule_version_hash	varchar(64)	Kural seti özeti
quality_flags	jsonb	Hesap kalite bayrakları
created_at, updated_at	timestamptz

Basic Sentez Verileri (V1 Minimum Kaydedilecek Kolonlar)

Aşağıdaki set, V1’de mutlaka hesaplanıp energy_measurements_synth tablosuna yazılacak minimum sentez kolonlarını tanımlar.

Kolon	Tip	Zorunluluk	Açıklama
vur	double precision	Zorunlu	Gerilim dengesizlik oranı
vsr	double precision	Zorunlu	Faz gerilim yayılım oranı
iu	double precision	Zorunlu	Akım dengesizlik oranı
load_ratio	double precision	Zorunlu	Yük oranı (P/Pnom)
pf_calc	double precision	Zorunlu	Hesaplanmış güç faktörü
tsi	double precision	Zorunlu	Termal stres indeksi
distribution_drift_i	double precision	Zorunlu	Akım dağılım drift skoru
distribution_drift_v	double precision	Zorunlu	Gerilim dağılım drift skoru
score_grid	double precision	Zorunlu	Şebeke kalite bileşen skoru
score_load	double precision	Zorunlu	Yük davranışı bileşen skoru
score_stress	double precision	Zorunlu	Elektriksel stres bileşen skoru
score_trend	double precision	Zorunlu	Trend bileşen skoru
grid_score	double precision	Zorunlu	Operasyonel şebeke puanı
health_score	double precision	Zorunlu	Genel pompa sağlık skoru (0-100)
severity_level	smallint	Zorunlu	Risk seviyesi (0-4)
health_label	varchar(32)	Zorunlu	Durum etiketi

Genişletilmiş Stream-Anlık Türetilmiş Metrikler (V1+)

Kolon	Tip	Zorunluluk	Açıklama
hvr	double precision	Önerilen	Gerilim harmonik oranı
hir	double precision	Önerilen	Akım harmonik oranı
ipk_rms	double precision	Önerilen	Tepe/RMS akım oranı
q_ratio	double precision	Önerilen	Reaktif güç oranı
hpr	double precision	Opsiyonel	Harmonik aktif güç oranı
hqr	double precision	Opsiyonel	Harmonik reaktif güç oranı
tsi_h	double precision	Önerilen	Harmonik düzeltilmiş termal stres

Nihai Skorlar (V1)

Kolon	Tip	Zorunluluk	Açıklama
score_grid	float	Zorunlu	Şebeke kalite bileşen skoru
score_load	float	Zorunlu	Yük davranışı bileşen skoru
score_stress	float	Zorunlu	Elektriksel stres bileşen skoru
score_trend	float	Zorunlu	Trend bileşen skoru (window dışı girdilerle)
grid_score	float	Zorunlu	Operasyonel şebeke puanı
health_score	float	Zorunlu	Genel pompa sağlık skoru (0-100)
severity_level	smallint	Zorunlu	0-4 risk sınıfı
health_label	varchar(32)	Zorunlu	Sağlıklı/İzle/Risk/Kritik/Acil

Net Sınır

mu_f, sigma_f, trend_f, p10/p50/p90, skewness, kurtosis, maruziyet süreleri ve diğer pencere tabanlı metrikler bu tabloda tutulmaz; yalnızca energy_windows katmanında tutulur.

Örnek Sentez Kural Kayıtları

Aşağıdaki örnekler, synthesis_variable_rules tablosuna yazılabilecek tipik kural kayıtlarını gösterir.

{
  "device_id": "96000000C49BB670",
  "variable_id": "VUR",
  "priority": 10,
  "required_variables": ["VA_RMS", "VB_RMS", "VC_RMS"],
  "conditions": {"all_not_null": true},
  "calculation": {
    "type": "formula",
    "expr": "max(abs(VA_RMS-AVG(VA_RMS,VB_RMS,VC_RMS)),abs(VB_RMS-AVG(VA_RMS,VB_RMS,VC_RMS)),abs(VC_RMS-AVG(VA_RMS,VB_RMS,VC_RMS)))/AVG(VA_RMS,VB_RMS,VC_RMS)"
  },
  "min_value": 0,
  "max_value": 1,
  "status": true,
  "rule_version": 1
}

{
  "device_id": "96000000C49BB670",
  "variable_id": "LOAD_RATIO",
  "priority": 20,
  "required_variables": ["WATT_T", "P_NOM"],
  "conditions": {"gt": [{"var": "P_NOM"}, 0]},
  "calculation": {
    "type": "formula",
    "expr": "WATT_T / P_NOM"
  },
  "min_value": 0,
  "max_value": 2,
  "status": true,
  "rule_version": 1
}

Örnek Kural Kayıtları (Tablo Formatı)

JSON bloklarına ek olarak, aynı örnek kurallar aşağıdaki gibi tablo formatında da gösterilmiştir.

Alan	VUR Kuralı (Örnek)	LOAD_RATIO Kuralı (Örnek)
device_id	96000000C49BB670	96000000C49BB670
variable_id	VUR	LOAD_RATIO
priority	10	20
required_variables	VA_RMS, VB_RMS, VC_RMS	WATT_T, P_NOM
conditions	all_not_null=true	P_NOM > 0
calculation.type	formula	formula
calculation.expr	max(abs(VA_RMS-AVG(...)), abs(VB_RMS-AVG(...)), abs(VC_RMS-AVG(...))) / AVG(...)	WATT_T / P_NOM
min_value	0	0
max_value	1	2
status	true	true
rule_version	1	1

Örnek energy_measurements_synth Kayıtları

Aşağıdaki örnekler, V1 minimum sentez kolonlarının DB’ye nasıl yazılacağını gösterir.

stream_id	device_id	vur	iu	load_ratio	tsi	score_grid	score_load	score_stress	score_trend	grid_score	health_score	severity_level	health_label
9823411	96000000C49BB670	0.0061	0.0420	0.81	0.77	78.4	74.1	71.8	80.3	82.1	76.2	1	İzle
9823412	96000000C49BB670	0.0128	0.0675	0.96	0.92	63.2	58.4	55.1	61.0	66.9	59.4	2	Risk

Bu kayıtların her birinde calc_version, rule_version_hash ve quality_flags alanları da birlikte yazılmalıdır.

6) energy_windows

Pencere bazlı özet/analiz tablosudur. Bu tablo hem sabit (takvim bazlı) hem de kayar (rolling) pencereleri aynı şemada taşır.

Pencere Tipleri

window_type	Sınıf	Tanım
1D	Sabit	Günlük pencere: 00:00:00 – 23:59:59
1W	Sabit	Haftalık pencere (Pzt 00:00 – Paz 23:59:59)
1M	Sabit	Aylık pencere (ayın ilk günü 00:00 – son günü 23:59:59)
1D_Last	Kayan	Son 24 saatlik rolling pencere
1W_Last	Kayan	Son 7 günlük rolling pencere
1M_Last	Kayan	Son 30 günlük rolling pencere

Zaman Semantiği

Sabit pencerelerde window_start/window_end takvim sınırlarını temsil eder ve finalize edilir. Kayan pencerelerde window_end hesap anını temsil eder, window_start = window_end - period mantığıyla ilerler.

Rolling Pencere Disiplini

Kayan pencerelerde başlangıç ve bitiş zamanları sabit bir grid'e hizalanmalıdır (örn. 5dk). Aksi halde aynı pencere tipi için çok yüksek kartinalite oluşur ve index performansı düşer.

Kimlik, Zaman ve Durum Alanları

Kolon	Tip	Zorunluluk	Açıklama
id	bigint PK	Zorunlu
device_id	varchar(21)	Zorunlu
variable_id	varchar(30)	Zorunlu
window_type	varchar(16)	Zorunlu	Sabit/kayan pencere tipi (1D, 1D_Last vb.)
window_start	timestamptz	Zorunlu	Pencere başlangıcı (rolling için anchor grid'e hizalı)
window_end	timestamptz	Zorunlu	Pencere bitişi
anchor_time	timestamptz	Önerilen	Hesap anchor zamanı (5dk/15dk grid)
finalized	boolean	Zorunlu	Sabit pencerelerde kapanış durumu
calc_version	integer	Zorunlu	Hesap sürümü
created_at	timestamptz	Zorunlu
updated_at	timestamptz	Zorunlu

Örneklem ve Veri Kalitesi Alanları

Kolon	Tip	Zorunluluk	Açıklama
sample_count	integer	Zorunlu	Gerçek örnek sayısı
expected_sample_count	integer	Zorunlu	Beklenen örnek sayısı
completeness_ratio	float	Zorunlu	sample_count/expected_sample_count
missing_count	integer	Önerilen	Eksik örnek adedi
outlier_count	integer	Önerilen	Aykırı örnek adedi
invalid_count	integer	Önerilen	Geçersiz örnek adedi
quality_grade	smallint	Önerilen	0-100 veya kademeli kalite notu
quality_flags	jsonb	Zorunlu	Reset/rollover/gap vb. bayraklar

Dağılım ve Temel İstatistik Alanları

Kolon	Tip	Zorunluluk	Açıklama
sum	double precision	Zorunlu	Toplam
sum_sq	double precision	Zorunlu	Kareler toplamı
sum_abs	double precision	Önerilen	Mutlak değer toplamı
min	double precision	Zorunlu	Minimum
max	double precision	Zorunlu	Maksimum
range_value	double precision	Önerilen	max-min
mean	double precision	Zorunlu	Ortalama
stddev	double precision	Zorunlu	Std sapma
p10, p50, p90	double precision	Zorunlu	V1 kuantil çekirdeği
skewness	double precision	Önerilen	Çarpıklık
kurtosis	double precision	Önerilen	Basıklık
variance	double precision	Opsiyonel (V2)	Varyans
cv	double precision	Opsiyonel (V2)	Değişim katsayısı
p01, p05, p25, p75, p95, p99	double precision	Opsiyonel (V2)	Geniş kuantil seti
iqr	double precision	Opsiyonel (V2)	p75-p25

Trend ve Regresyon Alanları

Kolon	Tip	Zorunluluk	Açıklama
sum_t	double precision	Zorunlu	Zaman indeks toplamı
sum_v	double precision	Zorunlu	Değer toplamı
sum_tv	double precision	Zorunlu	Zaman*değer toplamı
sum_t2	double precision	Zorunlu	Zaman kare toplamı
slope	double precision	Önerilen	Doğrusal eğim
intercept	double precision	Opsiyonel (V2)	Regresyon kesişimi
r2	double precision	Opsiyonel (V2)	Uyum katsayısı
trend_label	varchar(16)	Önerilen	up/down/flat

Enerji Sayaçlarına Özel Alanlar

Kolon	Tip	Zorunluluk	Açıklama
first_value	float	Zorunlu (sayaçta)	Pencere ilk sayaç değeri
last_value	float	Zorunlu (sayaçta)	Pencere son sayaç değeri
delta_value	float	Zorunlu (sayaçta)	Net fark
delta_pos	float	Önerilen	Pozitif yön farkı
delta_neg	float	Önerilen	Negatif yön farkı
counter_reset_count	integer	Önerilen	Reset adedi
counter_rollover_count	integer	Önerilen	Rollover adedi

Olay/Maruziyet Alanları (Opsiyonel)

Kolon	Tip	Zorunluluk	Açıklama
above_thr_count	integer	Opsiyonel	Eşik üstü örnek sayısı
below_thr_count	integer	Opsiyonel	Eşik altı örnek sayısı
exposure_time_sec	float	Opsiyonel	Eşik dışı toplam süre
event_count	integer	Opsiyonel	Olay sayısı
event_flags	jsonb	Opsiyonel	Olay sınıfları

V1 Locked Core (Pencere)

Performans hedefiyle V1’de yalnızca çekirdek pencere metrikleri fiziksel kolon olarak açılır; ancak bu çekirdek set pompa skorları ve ileri analizleri besleyecek şekilde korunur.

V1’de kesin açılacak pencere alanları: sample_count, expected_sample_count, completeness_ratio, quality_flags, sum, sum_sq, min, max, mean, stddev, p10, p50, p90, sum_t, sum_v, sum_tv, sum_t2, slope, first_value, last_value, delta_value, counter_reset_count, counter_rollover_count.

V2 Deferred (Pencere)

Aşağıdaki alanlar dokümanda referans olarak korunur ancak V1’de fiziksel kolon olarak açılmaz: p01, p05, p95, p99, intercept, r2, event_* detaylarının genişletilmiş seti. İhtiyaç halinde V2 migration ile devreye alınır.

Önerilen Index Seti

Tablo	Zorunlu Index
Tüm energy_*_measurements	UNIQUE(stream_id)
Tüm energy_*_measurements	(device_id, stream_time DESC)
energy_measurements_synth	UNIQUE(stream_id), (device_id, stream_time DESC)
energy_windows	UNIQUE(device_id, variable_id, window_type, window_start)
energy_windows	(device_id, variable_id, window_type, window_end DESC)
energy_windows	(device_id, window_type, window_start DESC)

Tablo İlişki Notu

energy_*_measurements ve energy_measurements_synth tablolarında stream_id tekilleştirilir; böylece her stream için her segmentte en fazla bir satır bulunur. energy_windows katmanı ise (device_id, variable_id, window_type, window_start) anahtarıyla pencere kayıtlarını tekilleştirir.

Teknik İş Akışı (Ingestion → Synthesis → Window)

Bu bölüm, canlıda bir cihaz paketi geldiğinde verinin hangi teknik sırayla işlendiğini ve hangi tabloların hangi aşamada güncellendiğini tanımlar. Akışın amacı hem yazım gecikmesini düşük tutmak hem de ham veri, sentez ve pencere katmanları arasında veri tutarlılığını korumaktır.

İşlem streams kaydı ile başlar. Paket kabul edildiğinde önce stream üst bilgisi yazılır ve bu akışa ait stream_id üretilir. Sonraki aşamada hesap motoru gerekli konfigürasyonları cache katmanından toplar: cihaza ait CT ratio bilgisi, aktif değişken listesi ve kalibrasyon parametreleri Redis üzerinden çekilir. Konfigürasyonlar alındıktan sonra ham ölçümler kalibrasyon adımından geçirilir ve enerji segmentlerine ayrıştırılır.

Kalibre edilen ham enerji değerleri segment tablolarına yazılır: gerilim için energy_voltage_measurements, akım için energy_current_measurements, güç için energy_power_measurements, sayaç verileri için energy_energy_measurements. Aynı akış içinde enerji dışı değişkenler gerekiyorsa measurements tablosuna EAV formatında yazım sürdürülür.

Ham yazım tamamlandıktan sonra sentez motoru devreye girer. Bu aşamada stream-anlık metrikler hesaplanır (vur, iu, load_ratio, tsi vb.) ve bileşen skorlar ile nihai skorlar üretilir (score_grid, score_load, score_stress, score_trend, health_score). Sonuçlar energy_measurements_synth tablosuna calc_version ve rule_version_hash ile birlikte kaydedilir.

Ardından pencere güncelleme aşaması çalışır. Window motoru ilgili değişken için hem sabit pencereleri (1D, 1W, 1M) hem de kayar pencereleri (1D_Last, 1W_Last, 1M_Last) günceller. Kayan pencerelerde zaman damgaları sabit grid'e hizalanır; böylece pencere kartinalitesi kontrol altında tutulur. Pencere kaydında örneklem kalitesi, temel istatistikler, trend alanları ve sayaç değişkenleri için first/last/delta değerleri güncellenir.

Tekrar eden paket, gecikmeli yeniden işleme veya replay durumlarında tüm yazımlar idempotent yürütülür. Segment ve synth tablolarında stream_id bazlı upsert uygulanır. Window katmanında ise (device_id, variable_id, window_type, window_start) anahtarı üzerinden güncelleme yapılır. Bu sayede aynı veri ikinci kez işlense dahi tutarlılık korunur ve çift kayıt oluşmaz.

Async Queue Processing Model (Redis)

Ingestion hattını hafif tutmak ve sentez/pencere hesaplarını ölçeklenebilir şekilde yönetmek için asenkron kuyruk modeli kullanılır. Ham yazım tamamlandıktan sonra hesaplama işleri Redis kuyruklarına bırakılır; ayrı worker servisleri bu kuyrukları tüketerek ilgili tabloları günceller.

Önerilen kuyruklar:

• synth_queue: yeni stream_id geldiğinde sentez hesap işini taşır.
• window_queue: sentez tamamlanan stream için pencere güncelleme işini taşır.
• dead_letter_queue (önerilen): retry limiti aşan kayıtları izole eder.

Bu modelde worker servisleri event odaklı çalışır. synth_worker, ham segment tablolarından veriyi okuyup energy_measurements_synth tablosuna idempotent upsert yapar. Ardından ilgili stream_idyi window_queueya aktarır. window_worker sabit ve kayar pencereleri günceller ve energy_windows tablosuna idempotent upsert yazar.

Operasyon Notu

Kuyruk tüketiminde aynı işin birden fazla worker tarafından eşzamanlı işlenmesini önlemek için lock/dedupe mekanizması kullanılmalıdır. Örnek: Redis key bazlı kısa TTL lock + stream_id bazlı idempotent upsert.

Örnek İş Akışı

1. Ham segment tablolarına yazım tamamlanır.
2. synth_queueya stream_id push edilir.
3. synth_worker işi alır, sentez hesaplar, energy_measurements_synth upsert eder.
4. Başarılı sentez sonrası window_queueya stream_id push edilir.
5. window_worker fixed + rolling pencereleri günceller, energy_windows upsert eder.
6. Hata durumunda retry uygulanır; limit aşarsa kayıt dead_letter_queueya alınır.

Ölçeklenebilirlik Prensipleri

• Kuyruk tüketimi batch yapılmalıdır (tek tek yerine mini-batch).
• Worker sayısı bağımsız ölçeklenmelidir (synth_worker ve window_worker ayrı).
• Tüm yazımlar idempotent olmalıdır (stream_id veya window unique anahtarı).
• Retry/backoff politikası merkezi tanımlanmalıdır.

Calibration Strategy (DB + Redis Cache)

Kalibrasyon katmanı, ham ölçümlerin fiziksel gerçekliğe en yakın şekilde normalize edilmesi için zorunlu bir adımdır. Cınga mimarisinde kalibrasyon kuralları DB kaynaklı yönetilir, fakat çalışma anında performans için Redis cache üzerinden çözülür.

Kalibrasyon Tablo Yapısı (calibrations)

Kolon	Tip	Zorunluluk	Açıklama
id	bigint PK	Zorunlu	Kalibrasyon kayıt kimliği
device_id	varchar(21) FK	Zorunlu	Hedef cihaz. 0 ise global kalibrasyon
variable_id	varchar(30) FK	Zorunlu	Kalibre edilecek değişken
gain	double precision	Zorunlu	Çarpan katsayısı
offset	double precision	Zorunlu	Ofset değeri
status	boolean	Önerilen	Aktif/Pasif kalibrasyon
priority	integer	Önerilen	Çakışan kurallarda öncelik
valid_from	timestamptz	Opsiyonel	Geçerlilik başlangıcı
valid_to	timestamptz	Opsiyonel	Geçerlilik bitişi
version	integer	Önerilen	Kalibrasyon sürümü
create_time, update_time	timestamptz	Zorunlu	İzleme alanları

Öncelik Kuralı

Kalibrasyon çözümleme sırası:

1. Cihaz özel kalibrasyon (device_id = gerçek cihaz)
2. Global kalibrasyon (device_id = '0')
3. Varsayılan değer (gain=1, offset=0)

Kalibrasyon Uygulama Formülü

Her değişken için standart kalibrasyon dönüşümü:

calibrated_value = raw_value * gain + offset

İhtiyaç halinde V2’de clamp_min / clamp_max sınırları eklenebilir.

Kalibrasyon İş Akışı

1. Stream kaydı sonrası ham değişken seti belirlenir.
2. Worker, Redis’ten cihaza ait kalibrasyon snapshot’ını okur (cal:{device_id}:{version}).
3. Cache miss durumunda DB’den cihaz + global kurallar tek sorguda çekilir.
4. Çözülmüş kalibrasyon map’i Redis’e yazılır (TTL + version).
5. Ham değerlere gain/offset uygulanır.
6. Uygulanan kalibrasyon sürümü/snapshot bilgisi kalite izine eklenir.

Redis Kalibrasyon Cache Prensipleri

• Anahtar versiyonlu olmalıdır (cal:{device_id}:{version}).
• Kalibrasyon güncellemesinde cache invalidation zorunludur.
• Worker içinde kısa süreli local cache (30-60 sn) önerilir.
• Redis erişilemezse DB fallback zorunludur.

Kalibrasyon İçin Önerilen Kısıtlar

• Aynı device_id + variable_id için tek aktif kayıt önerilir.
• Global (device_id='0') ve cihaz özel kayıt aynı anda varsa cihaz özel olan seçilir.
• Geçerlilik tarihleri kullanılıyorsa zaman çakışması engellenmelidir.

Rule Resolution Strategy (DB + Redis Fallback)

Sentez hesaplamalarında kullanılan kural ve parametre setleri için kaynak hiyerarşisi aşağıdaki gibi tanımlanır: DB source-of-truth, Redis hızlandırıcı cache, cache miss durumunda DB fallback. Bu yaklaşım hem merkezi yönetim hem de düşük gecikme hedefini birlikte sağlar.

Kural çözümleme akışı, device_id ve aktif calc_version bağlamında yürütülür. Worker önce Redis’te ilgili kural snapshot’ını arar. Kayıt bulunursa doğrudan kullanır. Kayıt bulunmazsa DB’den kural setini çeker, doğrular, Redis’e yazar ve hesaplamayı bu snapshot ile yürütür.

Versiyonlama Kuralı

Her sentez çıktısı, hesap sırasında kullanılan kural setini açıkça taşımalıdır (rule_version_hash / calc_version). Böylece geçmiş sonuçlar geriye dönük olarak denetlenebilir.

Uygulama Prensipleri

• Redis anahtarları versiyonlu olmalıdır (örn. synth_rules:{device_id}:{version}).
• Kural güncellemesi sonrası cache invalidation veya yeni versiyon anahtarı zorunludur.
• Tek bir stream işlenirken tek snapshot kullanılmalıdır; işlem ortasında kural değişse bile stream içi tutarlılık bozulmamalıdır.
• Redis erişilemezse DB fallback devreye girmelidir.
• DB de erişilemezse iş retry mekanizmasına bırakılmalı, sessiz default kural ile devam edilmemelidir.

Operasyonel Öneri

Worker tarafında kısa süreli local cache (ör. 30-60 sn) kullanımı Redis çağrı sayısını düşürür. Ancak local cache sadece hız katmanıdır; doğruluk kaynağı Redis/DB çözümleme zinciri olarak kalmalıdır.

Sentez Kural Motoru (Rule Engine) Yapısı

Mevcut sentez kural modeli; priority, required_variables, conditions, calculation, min_value, max_value, status alanlarıyla doğru bir çekirdek tasarım sunar. Bu yapı, ham enerji segmentlerinden gelen veriyi deterministic bir sırayla işleyip sentez çıktısına dönüştürmek için uygundur.

Rule Engine Tablo Yapısı (synthesis_variable_rules)

Kolon	Tip	Zorunluluk	Açıklama
id	bigint PK	Zorunlu	Kural kimliği
device_id	varchar(21) FK	Zorunlu	Kural hedefi. 0 ise global kuraldır ve tüm cihazlara uygulanır; cihaza özel kural varsa öncelik cihaz özelindedir.
variable_id	varchar(30) FK	Zorunlu	Üretilecek sentez değişkeni
priority	integer	Zorunlu	Çalıştırma sırası
required_variables	jsonb	Zorunlu	Girdi değişken listesi
conditions	jsonb	Opsiyonel	Kural koşulları
calculation	jsonb	Zorunlu	Hesaplama tanımı/formülü
min_value	double precision	Opsiyonel	Alt sınır clamp
max_value	double precision	Opsiyonel	Üst sınır clamp
status	boolean	Zorunlu	Aktif/Pasif
description	varchar(255)	Opsiyonel	İnsan okunur açıklama
rule_version	integer	Önerilen	Kural sürümü
rule_hash	varchar(64)	Önerilen	Kural snapshot hash
create_time	timestamptz	Zorunlu	Oluşturma zamanı
update_time	timestamptz	Zorunlu	Güncelleme zamanı

Benzersizlik ve Kural Önceliği

Aynı hedef değişken için cihaz bazında tek aktif kural önerilir: UNIQUE(device_id, variable_id) + aktiflik kontrolü.

Ek kural: device_id = '0' global kural anlamına gelir. Çalıştırma sırasında öncelik sırası:

1. Cihaza özel kural (device_id = gerçek cihaz)
2. Global kural (device_id = '0')

Bu modelde her kural, belirli bir hedef değişkeni (variable_id) üretir ve bunu hangi girdilerden hangi koşulda hesaplayacağını açıkça tanımlar. Böylece kural tabanlı hesaplama katmanı kod içine gömülü if-else yapılarından ayrışır ve yönetilebilir hale gelir.

Rule Engine İçin Zorunlu Teknik Kurallar

Kural	Açıklama
Versiyonlama	Her kural seti rule_version veya rule_hash ile sürümlenir; sonuç kaydına aynı sürüm yazılır.
Deterministic sıralama	Çalıştırma sırası priority ASC, id ASC olmalı; aynı girdide aynı çıktı garantilenmeli.
Snapshot tutarlılığı	Tek bir stream hesaplanırken tek rule snapshot kullanılmalı.
Cycle koruması	Kural bağımlılıkları DAG olmalı; döngü (A->B->C->A) save anında engellenmeli.
Eksik veri politikası	required_variables eksikse davranış kural bazında net olmalı (skip/default/fail).
Sınır kontrolü	min_value / max_value clamp tutarlı uygulanmalı ve kalite bayrağına işlenmeli.
Audit izi	Hesapta kullanılan giriş seti ve rule sürümü sonuç kaydında izlenebilir olmalı.

Rule Save Validation

Kural kaydı alınırken syntax doğrulama, bağımlılık kontrolü, cycle analizi, öncelik çakışması ve hedef değişken çakışması otomatik olarak doğrulanmalıdır.

Önerilen Rule Validation Checklist

1. variable_id dolu mu ve sistemde kayıtlı mı?
2. required_variables listesi boş mu, tekrar eden alan içeriyor mu?
3. required_variables içindeki tüm alanlar tanımlı mı?
4. conditions ve calculation JSON şeması geçerli mi?
5. Formül parse edilebilir ve güvenli operatör seti içinde mi?
6. Self-reference veya cycle var mı?
7. Aynı device_id + variable_id için aktif birden fazla kural var mı?
8. priority değeri geçerli aralıkta mı?
9. min_value <= max_value koşulu sağlanıyor mu?
10. Kural aktif edildiğinde test hesaplaması (dry-run) başarılı mı?

Sonuç

Yeni karar ile mimari, mevcut üretim akışını bozmadan enerji tarafını segment bazlı bir read modeline taşır. Bu sayede DB üzerindeki gereksiz okuma azalır, analiz iş yükleri daha izole çalışır, sentez sürüm yönetimi netleşir ve gelecekteki düzeltme/recompute operasyonları çok daha kontrollü yapılır.

---

Not: Bu sayfa drafttır. V1 nihai yapı onaylanmıştır; V2 (harmonik genişletme ve min-max kapsam artışı) ihtiyaç ve saha geri bildirimiyle ilerletilecektir.