Variables Katmanı

Variables katmanı, Cınga veri işleme zincirinin sözlük (schema dictionary) katmanıdır. Bu katmanda amaç sadece değişken adlarını tutmak değildir; her değişkenin hangi segmente ait olduğunu, hangi birimde işlendiğini, kalibrasyon/sentez tarafında nasıl davranacağını ve kural motoru tarafından nasıl referans alınacağını tek kaynaktan yönetmektir.

Pratikte bu katman iki tabloyla çalışır: variable_segments ve variables. Segment tablosu değişkenleri mantıksal kümelere ayırır (ör. voltage, current, power, energy). variables tablosu ise her ölçüm alanının teknik kimliğini taşır.

variable_segments Tablosu

Kolon	Tip	Zorunluluk	Açıklama
id	integer PK	Zorunlu	Segment kimliği
name	varchar(100) UNIQUE	Zorunlu	Segment adı
description	varchar(255)	Opsiyonel	Segment açıklaması
create_time	timestamptz	Zorunlu	Oluşturma zamanı
update_time	timestamptz	Zorunlu	Güncelleme zamanı

Bu tablo, enerji segment tabloları ile isimsel/işlevsel hizayı korur. Örneğin bir değişken voltage segmentine bağlıysa, ham verinin energy_voltage_measurements tarafında yer alması beklenir.

Önerilen variable_segments İçeriği

id	name	description
1	voltage	Gerilim ölçümleri (anlık, RMS, fundamental, harmonic, frequency)
2	current	Akım ölçümleri (anlık, RMS, peak, fundamental, harmonic)
3	power	Güç ölçümleri (aktif/reaktif/görünür, PF, güç harmonikleri)
4	energy	Enerji sayaçları (aktif/reaktif, alım/verim, leading/lagging)

variables Tablosu

Kolon	Tip	Zorunluluk	Açıklama
id	varchar(30) PK	Zorunlu	Değişken kodu (ör. VRMS_R)
description	varchar(255)	Opsiyonel	İnsan okunur açıklama
unit	varchar(10)	Opsiyonel	Ölçü birimi
segment_id	integer FK	Zorunlu	variable_segments.id
create_time	timestamptz	Zorunlu	Oluşturma zamanı
update_time	timestamptz	Zorunlu	Güncelleme zamanı

Mimarideki Rolü

Variables katmanı üç kritik noktada doğrudan etkili olur.

İlk olarak kalibrasyon çözümlemesinde, hangi değişkene hangi gain/offset uygulanacağı bu sözlük üzerinden belirlenir. İkinci olarak sentez rule engine tarafında required_variables doğrulaması bu sözlüğe göre yapılır; tanımsız alan içeren kuralın aktifleşmesi engellenir. Üçüncü olarak window katmanında variable_id bazlı tekilleştirme ve trend hesapları bu tablo referansıyla çalışır.

Önerilen Yönetişim Kuralları

• Değişken kodları stabil tutulmalı; aynı fiziksel anlam için farklı kod türetilmemeli.
• Birim (unit) alanı boş bırakılmamalı; raporlama tutarlılığı için zorunlu hale getirilmeli.
• Segment ataması zorunlu olmalı; segment_id null kabul edilmemeli.
• Sentezde kullanılan değişkenler için sözlük doğrulaması (pre-save validation) yapılmalı.

Kalibrasyon Notu

Cınga’da kalibrasyon segment bazlı sabit bir kurala bağlanmaz. Bunun nedeni sistemin yalnızca enerji değişkenleriyle sınırlı olmamasıdır; ileride su basıncı, debi, zaman tabanlı veya farklı proses değişkenleri de sözlüğe eklenecektir. Bu yüzden dokümanda segment özel “uygulanır/uygulanmaz” matrisi tutulmaz.

Temel ilke nettir: gerekli görülen her değişkene kalibrasyon uygulanabilir. Kalibrasyonun uygulanıp uygulanmayacağı, değişken bazlı aktif kural çözümlemesi ile belirlenir. Aktif kural yoksa kalibrasyon adımı pas geçilir.

Enerji Parametre Sözlüğü

Aşağıdaki liste, Cınga enerji tarafında konuştuğumuz ham parametre setini variables tablosunda tek tek tanımlamak için referans alınabilir.

Harmonik okumada MAX78630 tarafında HARM seçimi yapıldıktan sonra VHARM_x ve IHARM_x register okumaları seçilen harmonik derecesini verir. Bu yüzden sözlüğe toplam harmonik bileşenlerinin yanında seçilebilir harmonik alanları da eklendi (3, 5, 7, 9). İleri kullanım için güç tarafı da aynı prensiple genişletildi; seçilebilir QHARM_h_x, PHARM_h_x ve SHARM_h_x alanları (h=3,5,7,9) sözlüğe eklendi.

Bu sözlük, okunabilirliği artırmak için aşağıda segment gruplarına ayrılmıştır.

Gerilim Değişkenleri

Sıra No	Değişken	Açıklama	Birim	Segment.AltSegment
V1	VINST_R	R faz anlık gerilim	V	voltage.instantaneous
V2	VINST_S	S faz anlık gerilim	V	voltage.instantaneous
V3	VINST_T	T faz anlık gerilim	V	voltage.instantaneous
V4	VRMS_R	R faz RMS gerilim	V	voltage.rms
V5	VRMS_S	S faz RMS gerilim	V	voltage.rms
V6	VRMS_T	T faz RMS gerilim	V	voltage.rms
V7	VRMS_A	RMS gerilim ortalaması (Total/3)	V	voltage.rms
V8	VFUND_R	R faz temel gerilim bileşeni	V	voltage.fundamental
V9	VFUND_S	S faz temel gerilim bileşeni	V	voltage.fundamental
V10	VFUND_T	T faz temel gerilim bileşeni	V	voltage.fundamental
V11	VHARM_R	R faz harmonik gerilim bileşeni	V	voltage.harmonic
V12	VHARM_S	S faz harmonik gerilim bileşeni	V	voltage.harmonic
V13	VHARM_T	T faz harmonik gerilim bileşeni	V	voltage.harmonic
V14	VHARM_3_R	R faz 3. harmonik gerilim bileşeni	V	voltage.harmonic
V15	VHARM_3_S	S faz 3. harmonik gerilim bileşeni	V	voltage.harmonic
V16	VHARM_3_T	T faz 3. harmonik gerilim bileşeni	V	voltage.harmonic
V17	VHARM_5_R	R faz 5. harmonik gerilim bileşeni	V	voltage.harmonic
V18	VHARM_5_S	S faz 5. harmonik gerilim bileşeni	V	voltage.harmonic
V19	VHARM_5_T	T faz 5. harmonik gerilim bileşeni	V	voltage.harmonic
V20	VHARM_7_R	R faz 7. harmonik gerilim bileşeni	V	voltage.harmonic
V21	VHARM_7_S	S faz 7. harmonik gerilim bileşeni	V	voltage.harmonic
V22	VHARM_7_T	T faz 7. harmonik gerilim bileşeni	V	voltage.harmonic
V23	VHARM_9_R	R faz 9. harmonik gerilim bileşeni	V	voltage.harmonic
V24	VHARM_9_S	S faz 9. harmonik gerilim bileşeni	V	voltage.harmonic
V25	VHARM_9_T	T faz 9. harmonik gerilim bileşeni	V	voltage.harmonic
V26	VHARM_THD_R	R faz toplam harmonik gerilim bozulması (THD)	%	voltage.harmonic
V27	VHARM_THD_S	S faz toplam harmonik gerilim bozulması (THD)	%	voltage.harmonic
V28	VHARM_THD_T	T faz toplam harmonik gerilim bozulması (THD)	%	voltage.harmonic
V29	FREQ	Şebeke frekansı	Hz	voltage.frequency

Akım Değişkenleri

Sıra No	Değişken	Açıklama	Birim	Segment.AltSegment
I1	IINST_R	R faz anlık akım	A	current.instantaneous
I2	IINST_S	S faz anlık akım	A	current.instantaneous
I3	IINST_T	T faz anlık akım	A	current.instantaneous
I4	IPEAK_R	R faz tepe akım	A	current.peak
I5	IPEAK_S	S faz tepe akım	A	current.peak
I6	IPEAK_T	T faz tepe akım	A	current.peak
I7	IRMS_R	R faz RMS akım	A	current.rms
I8	IRMS_S	S faz RMS akım	A	current.rms
I9	IRMS_T	T faz RMS akım	A	current.rms
I10	IRMS_A	RMS akım ortalaması (Total/3)	A	current.rms
I11	IFUND_R	R faz temel akım bileşeni	A	current.fundamental
I12	IFUND_S	S faz temel akım bileşeni	A	current.fundamental
I13	IFUND_T	T faz temel akım bileşeni	A	current.fundamental
I14	IHARM_R	R faz harmonik akım bileşeni	A	current.harmonic
I15	IHARM_S	S faz harmonik akım bileşeni	A	current.harmonic
I16	IHARM_T	T faz harmonik akım bileşeni	A	current.harmonic
I17	IHARM_3_R	R faz 3. harmonik akım bileşeni	A	current.harmonic
I18	IHARM_3_S	S faz 3. harmonik akım bileşeni	A	current.harmonic
I19	IHARM_3_T	T faz 3. harmonik akım bileşeni	A	current.harmonic
I20	IHARM_5_R	R faz 5. harmonik akım bileşeni	A	current.harmonic
I21	IHARM_5_S	S faz 5. harmonik akım bileşeni	A	current.harmonic
I22	IHARM_5_T	T faz 5. harmonik akım bileşeni	A	current.harmonic
I23	IHARM_7_R	R faz 7. harmonik akım bileşeni	A	current.harmonic
I24	IHARM_7_S	S faz 7. harmonik akım bileşeni	A	current.harmonic
I25	IHARM_7_T	T faz 7. harmonik akım bileşeni	A	current.harmonic
I26	IHARM_9_R	R faz 9. harmonik akım bileşeni	A	current.harmonic
I27	IHARM_9_S	S faz 9. harmonik akım bileşeni	A	current.harmonic
I28	IHARM_9_T	T faz 9. harmonik akım bileşeni	A	current.harmonic
I29	IHARM_THD_R	R faz toplam harmonik akım bozulması (THD)	%	current.harmonic
I30	IHARM_THD_S	S faz toplam harmonik akım bozulması (THD)	%	current.harmonic
I31	IHARM_THD_T	T faz toplam harmonik akım bozulması (THD)	%	current.harmonic

Güç Değişkenleri

Sıra No	Değişken	Açıklama	Birim	Segment.AltSegment
P1	QFUND_R	R faz temel reaktif güç	var	power.fundamental
P2	QFUND_S	S faz temel reaktif güç	var	power.fundamental
P3	QFUND_T	T faz temel reaktif güç	var	power.fundamental
P4	QHARM_R	R faz harmonik reaktif güç	var	power.harmonic
P5	QHARM_S	S faz harmonik reaktif güç	var	power.harmonic
P6	QHARM_T	T faz harmonik reaktif güç	var	power.harmonic
P7	QHARM_3_R	R faz 3. harmonik reaktif güç bileşeni	var	power.harmonic
P8	QHARM_3_S	S faz 3. harmonik reaktif güç bileşeni	var	power.harmonic
P9	QHARM_3_T	T faz 3. harmonik reaktif güç bileşeni	var	power.harmonic
P10	QHARM_5_R	R faz 5. harmonik reaktif güç bileşeni	var	power.harmonic
P11	QHARM_5_S	S faz 5. harmonik reaktif güç bileşeni	var	power.harmonic
P12	QHARM_5_T	T faz 5. harmonik reaktif güç bileşeni	var	power.harmonic
P13	QHARM_7_R	R faz 7. harmonik reaktif güç bileşeni	var	power.harmonic
P14	QHARM_7_S	S faz 7. harmonik reaktif güç bileşeni	var	power.harmonic
P15	QHARM_7_T	T faz 7. harmonik reaktif güç bileşeni	var	power.harmonic
P16	QHARM_9_R	R faz 9. harmonik reaktif güç bileşeni	var	power.harmonic
P17	QHARM_9_S	S faz 9. harmonik reaktif güç bileşeni	var	power.harmonic
P18	QHARM_9_T	T faz 9. harmonik reaktif güç bileşeni	var	power.harmonic
P19	P_R	R faz aktif güç	W	power.active
P20	P_S	S faz aktif güç	W	power.active
P21	P_T	T faz aktif güç	W	power.active
P22	Q_R	R faz reaktif güç	var	power.reactive
P23	Q_S	S faz reaktif güç	var	power.reactive
P24	Q_T	T faz reaktif güç	var	power.reactive
P25	S_R	R faz görünür güç	VA	power.apparent
P26	S_S	S faz görünür güç	VA	power.apparent
P27	S_T	T faz görünür güç	VA	power.apparent
P28	P_A	Aktif güç ortalaması (Total/3)	W	power.active
P29	Q_A	Reaktif güç ortalaması (Total/3)	var	power.reactive
P30	S_A	Görünür güç ortalaması (Total/3)	VA	power.apparent
P31	PFUND_R	R faz temel güç oranı	-	power.fundamental
P32	PFUND_S	S faz temel güç oranı	-	power.fundamental
P33	PFUND_T	T faz temel güç oranı	-	power.fundamental
P34	PHARM_R	R faz harmonik güç oranı	-	power.harmonic
P35	PHARM_S	S faz harmonik güç oranı	-	power.harmonic
P36	PHARM_T	T faz harmonik güç oranı	-	power.harmonic
P37	PHARM_3_R	R faz 3. harmonik aktif güç oranı/bileşeni	-	power.harmonic
P38	PHARM_3_S	S faz 3. harmonik aktif güç oranı/bileşeni	-	power.harmonic
P39	PHARM_3_T	T faz 3. harmonik aktif güç oranı/bileşeni	-	power.harmonic
P40	PHARM_5_R	R faz 5. harmonik aktif güç oranı/bileşeni	-	power.harmonic
P41	PHARM_5_S	S faz 5. harmonik aktif güç oranı/bileşeni	-	power.harmonic
P42	PHARM_5_T	T faz 5. harmonik aktif güç oranı/bileşeni	-	power.harmonic
P43	PHARM_7_R	R faz 7. harmonik aktif güç oranı/bileşeni	-	power.harmonic
P44	PHARM_7_S	S faz 7. harmonik aktif güç oranı/bileşeni	-	power.harmonic
P45	PHARM_7_T	T faz 7. harmonik aktif güç oranı/bileşeni	-	power.harmonic
P46	PHARM_9_R	R faz 9. harmonik aktif güç oranı/bileşeni	-	power.harmonic
P47	PHARM_9_S	S faz 9. harmonik aktif güç oranı/bileşeni	-	power.harmonic
P48	PHARM_9_T	T faz 9. harmonik aktif güç oranı/bileşeni	-	power.harmonic
P49	SFUND_R	R faz temel görünür güç	VA	power.fundamental
P50	SFUND_S	S faz temel görünür güç	VA	power.fundamental
P51	SFUND_T	T faz temel görünür güç	VA	power.fundamental
P52	SHARM_3_R	R faz 3. harmonik görünür güç bileşeni	VA	power.harmonic
P53	SHARM_3_S	S faz 3. harmonik görünür güç bileşeni	VA	power.harmonic
P54	SHARM_3_T	T faz 3. harmonik görünür güç bileşeni	VA	power.harmonic
P55	SHARM_5_R	R faz 5. harmonik görünür güç bileşeni	VA	power.harmonic
P56	SHARM_5_S	S faz 5. harmonik görünür güç bileşeni	VA	power.harmonic
P57	SHARM_5_T	T faz 5. harmonik görünür güç bileşeni	VA	power.harmonic
P58	SHARM_7_R	R faz 7. harmonik görünür güç bileşeni	VA	power.harmonic
P59	SHARM_7_S	S faz 7. harmonik görünür güç bileşeni	VA	power.harmonic
P60	SHARM_7_T	T faz 7. harmonik görünür güç bileşeni	VA	power.harmonic
P61	SHARM_9_R	R faz 9. harmonik görünür güç bileşeni	VA	power.harmonic
P62	SHARM_9_S	S faz 9. harmonik görünür güç bileşeni	VA	power.harmonic
P63	SHARM_9_T	T faz 9. harmonik görünür güç bileşeni	VA	power.harmonic
P64	PF_R	R faz güç faktörü	-	power.factor
P65	PF_S	S faz güç faktörü	-	power.factor
P66	PF_T	T faz güç faktörü	-	power.factor
P67	PF_TOT	Toplam güç faktörü	-	power.factor

Enerji Değişkenleri

Sıra No	Değişken	Açıklama	Birim	Segment.AltSegment
E1	PE_POS_R	R faz alınan aktif enerji sayacı	Wh	energy.active
E2	PE_NEG_R	R faz verilen aktif enerji sayacı	Wh	energy.active
E3	PE_POS_S	S faz alınan aktif enerji sayacı	Wh	energy.active
E4	PE_NEG_S	S faz verilen aktif enerji sayacı	Wh	energy.active
E5	PE_POS_T	T faz alınan aktif enerji sayacı	Wh	energy.active
E6	PE_NEG_T	T faz verilen aktif enerji sayacı	Wh	energy.active
E7	QE_POS_R	R faz reaktif enerji leading sayacı (kapasitif)	varh	energy.reactive
E8	QE_NEG_R	R faz reaktif enerji lagging sayacı (indüktif)	varh	energy.reactive
E9	QE_POS_S	S faz reaktif enerji leading sayacı (kapasitif)	varh	energy.reactive
E10	QE_NEG_S	S faz reaktif enerji lagging sayacı (indüktif)	varh	energy.reactive
E11	QE_POS_T	T faz reaktif enerji leading sayacı (kapasitif)	varh	energy.reactive
E12	QE_NEG_T	T faz reaktif enerji lagging sayacı (indüktif)	varh	energy.reactive

Ingest Paket Profilleri (BASIC / DETAIL / EXPERIMENT)

Ingest tarafında tek paket limitine uyum için değişkenler paket profillerine ayrılır. Cihaz Info.Command ile profil tipini bildirir.

BASIC Paketi

Temel operasyonel izleme için zorunlu alanlar:

• STATUS, STOP, RESET
• VRMS_R, VRMS_S, VRMS_T
• IRMS_R, IRMS_S, IRMS_T
• P_R, P_S, P_T
• Q_R, Q_S, Q_T
• S_R, S_S, S_T
• PF_R, PF_S, PF_T
• FREQ
• PCB_T

DETAIL Paketi

Temel bileşen + harmonik (3/5/7) detayları:

• VFUND_R, VFUND_S, VFUND_T
• IFUND_R, IFUND_S, IFUND_T
• VHARM_3_R, VHARM_3_S, VHARM_3_T
• VHARM_5_R, VHARM_5_S, VHARM_5_T
• VHARM_7_R, VHARM_7_S, VHARM_7_T
• IHARM_3_R, IHARM_3_S, IHARM_3_T
• IHARM_5_R, IHARM_5_S, IHARM_5_T
• IHARM_7_R, IHARM_7_S, IHARM_7_T
• IPEAK_R, IPEAK_S, IPEAK_T

EXPERIMENT Paketi

V1’de zorunlu olmayan, ileri analiz/Ar-Ge amaçlı alanlar:

• VINST_R, VINST_S, VINST_T
• IINST_R, IINST_S, IINST_T
• VHARM_9_R, VHARM_9_S, VHARM_9_T
• IHARM_9_R, IHARM_9_S, IHARM_9_T
• VHARM_THD_R, VHARM_THD_S, VHARM_THD_T
• IHARM_THD_R, IHARM_THD_S, IHARM_THD_T
• QHARM_*, PHARM_*, SHARM_* genişletilmiş harmonik güç alanları
• V1 hesaplarında doğrudan kullanılmayan diğer opsiyonel alanlar

Notlar:

• Stream servis assembly sırasında bu paketleri tek sete birleştirir.
• stream_end=true görüldüğünde set finalize edilir.
• Paket profili değişiklikleri variables sözlüğü ile birlikte versiyonlanmalıdır.

Performans ve Bakım Önerileri

Variables tarafı düşük hacimli görünse de yanlış tasarım ileride rule çözümleme ve validasyon maliyetini büyütür. Bu yüzden aşağıdaki öneriler önemlidir:

• variables.id kısa ve stabil kalsın; isim değişikliği yerine yeni değişken açmayı tercih edin.
• variables.segment_id için index zorunlu olsun (idx_variables_segment_id).
• variables.id üzerinde case standardı belirleyin (örn. her zaman UPPERCASE).
• variable_segments.name tekilleştirme korunsun; segment adını migration dışında değiştirmeyin.
• Rule save anında required_variables içindeki tüm alanlar variables tablosundan doğrulansın.
• CT etkisindeki değişken listesi kodda merkezi bir map olarak tutulsun; sorgu sırasında tekrar tekrar hesaplanmasın.
• Uygulama başında (veya kısa TTL ile) variables sözlüğünü Redis/local cache’e alıp read path’i hafifletin.

Variables katmanı doğru yönetildiğinde, Cınga’da tablo tasarımı, kalibrasyon, sentez ve pencere katmanları arasında anlamsal tutarlılık kalıcı hale gelir.

Not: Bu sayfadaki sözlük şu aşamada enerji değişkenlerine odaklıdır. Sistemde bulunan enerji dışı ek değişkenler ilerleyen sürümlerde aynı yapı korunarak bu sözlüğe eklenecektir.

Değişken Yönetimi için Önerilen İşletim Modeli

Yeni değişken ekleme sürecini deploy bağımlılığından çıkarmak için “schema-as-data” modeli önerilir. Bu modelde değişken sözlüğü Git deposunda tek bir kaynak dosyada (variables.yaml veya variables.json) tutulur. Değişiklikler PR ile yönetilir; böylece review, versiyonlama ve geri alma (rollback) süreçleri doğal olarak sağlanır.

Uygulama tarafında bir senkronizasyon komutu (sync-variables) çalıştırılarak bu dosya DB’ye upsert edilir. Böylece yeni değişken eklemek için kod deploy etmek gerekmez; sadece sözlük dosyası güncellenir ve senkronizasyon çalıştırılır.

Bu modelin güvenli çalışması için üç ek adım önerilir:

• Senkronizasyon öncesi dry-run ile fark (diff) gösterimi,
• Senkronizasyon sonrası Redis sözlük cache invalidation,
• Senkronizasyon çıktısının log/audit kaydı.

Bu yaklaşımla değişken ekleme süreci hem hızlanır hem izlenebilir hale gelir.

Deployment Hook ile Otomatik Senkronizasyon

İleride deploy anında sözlük senkronizasyonunu otomatik çalıştırmak mümkündür ve önerilir. Bunun için CI/CD veya servis açılış aşamasına bir “post-deploy sync” adımı eklenir.

Önerilen sıra şu şekildedir: önce sync-variables --dry-run ile değişiklik önizlenir; beklenmeyen veya kırıcı durum yoksa sync-variables --apply ile DB upsert yapılır; son adımda Redis cache invalidation tetiklenir.

Bu akışla yeni değişkenler deploy paketine manuel müdahale olmadan sisteme alınır. Aynı zamanda idempotent çalıştığı için tekrar tetiklenmesi güvenlidir.

Güvenli kullanım için önerilen korumalar:

• transaction tabanlı yazım,
• schema doğrulama,
• strict mode (hatalı satırda fail),
• senkronizasyon raporu ve audit log.

Böylece değişken yönetimi “kod değişikliği + manuel DB işlemi” modelinden çıkıp, kontrollü ve otomatik bir operasyon haline gelir.