Master Data & Operations

Bu sayfa, Cınga backend içinde tekrar kullanılan sözlük tablolarını, servis/operasyon tablolarını ve telemetry dışındaki yardımcı veri katmanlarını detaylı biçimde açıklar.

Bu tablolar doğrudan paket işlemez; fakat sistemin ortak dilini, servis görünürlüğünü ve operasyonel izlenebilirliğini sağlar.

Bu Katmanın Amacı

Bu katman üç farklı ihtiyacı karşılar:

1. Master data / sözlük
   • üretici, model, ekipman tipi, değişken, proje, mesaj tipi gibi ortak tanımlar
2. Operasyon / log
   • servisler, log seviyeleri, log kayıtları
3. Tekrarlı referansların normalize edilmesi
   • aynı isim ve açıklamaların bütün sistemde tek kaynaktan gelmesi

1. projects

projects, ürün ailelerini ve çözüm versiyonlarını tanımlar.

Neden vardır?

Cınga, PowerStat, Maraba, WeatherStat gibi ürün aileleri aynı veri modelini paylaşabilir; ancak firmware, register yapısı, komut sözlüğü ve rule mantıkları proje bazında farklılaşabilir.

Kolonlar

Kolon	Tip	Null	Anlamı
id	int	hayır	Proje anahtarı
name	varchar(100)	hayır	Proje adı
description	text	evet	Açıklama
is_active	boolean	hayır	Aktiflik
create_time	timestamp	hayır	Oluşturma
update_time	timestamp	hayır	Güncelleme

2. manufacturers

Üretici sözlüğünü taşır.

Neden vardır?

Motor, sürücü, softstarter, modem, trafo ve cihaz gibi farklı ekipmanların üreticisi tekrar eden master data’dır. Serbest text yerine ortak sözlük daha sağlıklıdır.

Kolonlar

Kolon	Tip	Null	Anlamı
id	int	hayır	Üretici anahtarı
name	varchar(100)	hayır	Üretici adı
description	varchar(255)	evet	Açıklama
is_active	boolean	hayır	Aktiflik
create_time	timestamp	hayır	Oluşturma
update_time	timestamp	hayır	Güncelleme

3. equipment_types

Ekipman tipi sözlüğünü tutar.

Neden vardır?

manufacturer_models tablosu çok farklı fiziksel varlık türlerini tek yerde tanımlayabilir; bunu mümkün kılan şey modelin hangi ekipman tipine ait olduğunun açıkça belirtilmesidir.

Kolonlar

Kolon	Tip	Null	Anlamı
id	int	hayır	Tip anahtarı
code	varchar(50)	hayır	Teknik kod
name	varchar(100)	hayır	İnsan okunur ad
description	varchar(255)	evet	Açıklama
is_active	boolean	hayır	Aktiflik
create_time	timestamp	hayır	Oluşturma
update_time	timestamp	hayır	Güncelleme

4. manufacturer_models

Bu tablo üretici + ekipman tipi + model kombinasyonunu taşır.

Neden vardır?

Aynı üreticinin birden çok motoru, sürücüsü, softstarter’ı veya cihaz modeli olabilir. Teknik özellikler model seviyesinde tanımlanmalıdır.

Kolonlar

Kolon	Tip	Null	Anlamı
id	int	hayır	Model anahtarı
manufacturer_id	int	hayır	Üretici
equipment_type_id	int	hayır	Ekipman tipi
name	varchar(100)	hayır	Model adı
series	varchar(100)	evet	Seri/familya
description	varchar(255)	evet	Açıklama
specs	json	evet	Teknik özellikler
is_active	boolean	hayır	Aktiflik
create_time	timestamp	hayır	Oluşturma
update_time	timestamp	hayır	Güncelleme

Örnek kayıt

{
  "id": 6,
  "manufacturer_id": 3,
  "equipment_type_id": 7,
  "name": "PSE370-600-70",
  "series": "PSE",
  "description": "ABB soft starter modeli",
  "specs": { "nominal_current_a": 370, "voltage_v": 400 },
  "is_active": true
}

5. variables ve variable_segments

Bu iki tablo sistem içindeki measurement sözlüğünü oluşturur.

variable_segments

Segment düzeyi sınıflandırma sağlar.

Örnek segmentler:

• Electrical
• Environmental
• Status
• Energy

variables

Her ölçüm değişkeninin resmi tanımıdır.

Kolonlar (variables)

Kolon	Tip	Null	Anlamı
id	varchar(30)	hayır	Değişken kodu
name	varchar(100)	evet	İnsan okunur ad
description	text	evet	Açıklama
unit	varchar(20)	evet	Birim
segment_id	int	hayır	Segment
data_type	enum	hayır	numeric / integer / boolean / string / json
ct_calibration	boolean	hayır	CT kalibrasyonu gerekli mi
is_active	boolean	hayır	Aktiflik
create_time	timestamp	hayır	Oluşturma
update_time	timestamp	hayır	Güncelleme

Neden önemlidir?

Bu tablo hem measurement tarafında hem synthesis/calibration/rule tarafında ortak referans olur. Bu yüzden veri modelinin en kritik sözlüklerinden biridir.

6. message_types

Telemetry paket tiplerinin sözlüğüdür.

Neden vardır?

timed, interrupt, alarm, manual, boot gibi paket tiplerini serbest string olarak kullanmak yerine normalize etmek accepted stream’lerin yorumlanmasını kolaylaştırır.

Kolonlar

Kolon	Tip	Null	Anlamı
id	int	hayır	Tip anahtarı
code	varchar(30)	hayır	Teknik kod
description	text	hayır	Açıklama
is_active	boolean	hayır	Aktiflik
create_time	timestamp	hayır	Oluşturma
update_time	timestamp	hayır	Güncelleme

7. firmwares

Firmware sürüm bilgisini taşır.

Neden vardır?

Cihaz modeli ile yüklü firmware aynı şey değildir. Aynı proje içinde farklı sürümler olabilir; beta, stable, rc ve deprecated kanalları ayrı tutulmalıdır.

Kolonlar

Bu tablo sürüm, kanal, dosya bilgisi, hash ve release note taşır. Özellikle şu alanlar kritik rol oynar:

• project_id
• version
• version_code
• channel
• file_url
• hash_md5
• hash_sha256

Bu yapı OTA, firmware görünürlüğü ve cihaz sürüm yönetimi için önemlidir.

8. register_structure

Bu tablo register bit anlam sözlüğünü proje bazında tanımlar.

Neden vardır?

Aynı register bit farklı projelerde farklı anlam taşıyabilir. Bu nedenle register bit açıklamasını kod içine gömmek yerine proje bazlı sözlükte tutmak daha doğrudur.

Kolonlar

Kolon	Tip	Null	Anlamı
id	int	hayır	Kayıt anahtarı
project_id	int	hayır	Proje
bit	int	hayır	Bit numarası
name	varchar(50)	hayır	Teknik isim
description	varchar(255)	evet	Açıklama
default_stop_enabled	boolean	hayır	Varsayılan stop davranışı
default_publish_enabled	boolean	hayır	Varsayılan publish davranışı
is_active	boolean	hayır	Aktiflik
create_time	timestamp	hayır	Oluşturma
update_time	timestamp	hayır	Güncelleme

9. device_commands

Bu tablo cihaz komut sözlüğünü taşır.

Neden vardır?

Restart, register set, zaman senkronizasyonu veya publish mask ayarı gibi komutları kod içine dağılmış metinler olarak değil, proje bazlı sözlük olarak tanımlamak gerekir.

Kolonlar

Kolon	Tip	Null	Anlamı
id	int	hayır	Komut anahtarı
project_id	int	hayır	Hangi projede geçerli
code	varchar(50)	hayır	Komut kodu
end_point	varchar(150)	hayır	Hedef endpoint
template	text	hayır	Parametreli komut şablonu
timeout_ms	int	hayır	Timeout
description	varchar(255)	evet	Açıklama
is_active	boolean	hayır	Aktiflik
create_time	timestamp	hayır	Oluşturma
update_time	timestamp	hayır	Güncelleme

10. services, log_levels, logs

Bu üçlü operasyonel görünürlük katmanını oluşturur.

services

Servis sözlüğünü taşır.

Amaç:

• logların hangi servis tarafından üretildiğini normalize etmek
• servis isimlerini koddan bağımsız sözlük olarak tutmak

log_levels

Log severity sözlüğüdür.

logs

Gerçek operasyon log kaydıdır.

Neden vardır?

Sistem davranışını üretim ortamında anlamak için structured log gerekir. Özellikle ingest, heartbeat, rule engine ve push worker gibi servisler cihaz veya stream bağlamlı log üretmelidir.

logs kolonları

Kolon	Tip	Null	Anlamı
id	bigint	hayır	Log anahtarı
level_id	int	hayır	Log seviyesi
service_id	int	evet	Hangi servis üretti
event_code	varchar(50)	evet	Teknik olay kodu
device_id	varchar(21)	evet	Cihaz bağlamı
user_id	int	evet	Kullanıcı bağlamı
stream_id	int	evet	Stream bağlamı
message	text	hayır	Kısa açıklama
details	json	evet	Structured detay
create_time	timestamp	hayır	Log zamanı

Örnek kayıt

{
  "id": 1,
  "level_id": 2,
  "service_id": 2,
  "event_code": "STREAM_RECEIVED",
  "device_id": "46000000C47CA670",
  "stream_id": 5001,
  "message": "Ham veri paketi başarıyla işlendi.",
  "details": { "payload_size": 512, "ip": "10.10.1.25" },
  "create_time": "2026-04-03T10:30:00Z"
}

11. synthesis.* ve calibration.*

Bu tablolar türetilmiş veri ve kalibrasyon kurallarını tanımlar.

synthesis.rules

Bir değişkenin başka değişkenlerden nasıl üretileceğini tanımlar.

synthesis.assignments

Bu sentez kuralının:

• global,
• cihaz bazlı,
• grup bazlı hangi scope’ta aktif olduğunu belirler.

calibration.profiles

Gain/offset temelli kalibrasyon profillerini tanımlar.

calibration.assignments

Kalibrasyon profilinin hangi cihaz veya grup için geçerli olduğunu belirler.

Neden bu yapı önemli?

Çünkü türetilmiş veri ve kalibrasyon mantığı sabit kod yerine veri modeli ile yönetilebilir hale gelir. Ayrıca scope bazlı override davranışı mümkündür.

12. group.*

Bu alan cihaz veya kural kümelerini mantıksal olarak gruplamak için kullanılır.

group.groups

Bir grup nesnesinin kendisini taşır.

Gruplar şu amaçlarla kullanılabilir:

• customer group
• project group
• synthesis group
• reporting group
• alarm group

group.assignments

Bir cihazın hangi gruba dahil olduğunu tutar.

Neden vardır?

Aynı kural, kalibrasyon veya raporlama mantığının cihazlara tek tek değil grup bazlı uygulanması için gerekir.

Sonuç

Master Data & Operations katmanı, Cınga backend’in ortak sözlüğünü ve operasyonel görünürlük temelini kurar. Bu tablolar doğrudan telemetry üretmese de, sistemin geri kalanının ortak dilde konuşmasını sağlar:

• üretici ve model sözlüğü burada yaşar
• değişkenlerin resmi tanımı burada yaşar
• register bit ve cihaz komut sözlüğü burada yaşar
• servisler ve log seviyeleri burada normalize edilir
• sentez ve kalibrasyon kuralları burada tanımlanır

Bu katman iyi tasarlanmadığında sistemde isimler, anlamlar ve olay kodları dağılır. İyi tasarlandığında ise geri kalan bütün modüller aynı referans dilini konuşur.