Rules & Alerts

Bu sayfa, Cınga backend içinde kural motoru, alarm üretimi, durum takibi ve reaksiyon aksiyonları için kullanılan veri modelini detaylı biçimde açıklar.

Amaç, alarm davranışını uygulama kodu içinde dağınık if-else bloklarından çıkarıp veri modeliyle yönetilebilir hale getirmektir.

Bu Katmanın Amacı

Rules & Alerts katmanı şu soruları çözer:

• Hangi koşullar alarm üretir?
• Bir alarm tek bir koşula mı bakar, bir grup koşula mı?
• Süreli alarm nasıl takip edilir?
• Bir kural hangi cihazda aktif?
• Alarm tetiklenince ne yapılır?
• Reset olduğunda ne yapılır?
• Hangi olay tarihsel olarak kaydedilir?

Genel Kural Akışı

1. rule_groups

rule_groups, bir alarm veya karar senaryosunun üst kapsayıcı tablosudur.

Neden vardır?

Gerçek sahada alarm çoğu zaman tek bir koşul değildir. Birden fazla koşul birlikte değerlendirilir. Bazı senaryolarda tüm kurallar sağlanmalı, bazılarında herhangi biri yeterlidir. Bu nedenle tekil rule tanımından önce bir kapsayıcı grup gerekir.

Kolonlar

Kolon	Tip	Null	Anlamı
id	int	hayır	Kural grubu anahtarı
project_id	int	evet	Hangi proje ailesine ait olduğu
name	varchar(100)	hayır	Grup adı
description	varchar(255)	evet	Açıklama
match_type	enum	hayır	all veya any
multi_trigger	boolean	hayır	Aynı alarm tekrar tekrar tetiklenebilir mi
notify_on_reset	boolean	hayır	Reset olduğunda bildirim üretilecek mi
priority	int	hayır	Değerlendirme/işleme önceliği
valid_from	timestamp	evet	Geçerlilik başlangıcı
valid_to	timestamp	evet	Geçerlilik bitişi
publish_bit	int	evet	Cihaz publish maskesi ile bağ kurulacaksa ilgili bit
is_active	boolean	hayır	Grup aktif mi
create_time	timestamp	hayır	Oluşturma
update_time	timestamp	hayır	Güncelleme

Örnek kayıt

{
  "id": 1,
  "project_id": 1,
  "name": "Yüksek Akım Alarmı",
  "description": "Akım belirli eşik üzerine çıktığında alarm üretir",
  "match_type": "all",
  "multi_trigger": false,
  "notify_on_reset": true,
  "priority": 1,
  "publish_bit": 1,
  "is_active": true
}

Tasarım notu

rule_groups, tek tek kural satırlarının toplandığı bir konteyner değil; alarmın iş mantığı sınırıdır. Bildirim, reset davranışı ve öncelik burada yaşar.

2. rules

rules, bir rule group içindeki tekil koşulları tanımlar.

Neden vardır?

Aynı alarm grubu içinde farklı tip kurallar birlikte bulunabilir. Örneğin:

• 3 faz akımın da eşik üstünde olması
• belirli bir register bitin aktif olması
• belirli süredir stream gelmemesi

Bu çeşitlilik tek bir tablo içinde rule_type ile ayrılır.

Kolonlar

Kolon	Tip	Null	Anlamı
id	int	hayır	Rule anahtarı
group_id	int	hayır	Bağlı olduğu rule group
rule_type	enum	hayır	Kural tipi
variable_id	varchar(30)	evet	Değişken temelli kurallarda hedef değişken
operator	varchar(10)	evet	>, <, =, >= vb.
value	decimal(18,6)	evet	Eşik değeri
duration_sec	int	evet	Süreli kurallarda gereken süre
old_register_value	varchar(32)	evet	Register transition için eski değer
new_register_value	varchar(32)	evet	Register transition için yeni değer
register_bit	int	evet	Register bit kuralı için bit no
create_time	timestamp	hayır	Oluşturma
update_time	timestamp	hayır	Güncelleme

Desteklenen rule tipleri

Tip	Kullanım
threshold	Tek anlık eşik kontrolü
duration	Belirli süre eşik üstünde/altında kalma
register_transition	Register eski-yeni geçişi
register_bit	Belirli register bit kontrolü
stream_gap	Belirli süre stream gelmemesi

Örnek kayıtlar

Süreli yüksek akım kuralı:

{
  "id": 1,
  "group_id": 1,
  "rule_type": "duration",
  "variable_id": "IFUND_R",
  "operator": ">",
  "value": 45.0,
  "duration_sec": 300
}

Stream gap kuralı:

{
  "id": 5,
  "group_id": 3,
  "rule_type": "stream_gap",
  "duration_sec": 7200
}

Tasarım notu

Bu tablo kuralın tanımını taşır; hangi cihazda aktif olduğunu taşımaz. Bu ayrım özellikle aynı kural setinin birçok cihaza bağlanabilmesi için önemlidir.

3. device_rule_assignments

Bu tablo bir rule group’un hangi cihazlarda aktif olduğunu tutar.

Neden vardır?

Aynı rule group farklı cihazlara atanabilir. Rule tanımı ile rule assignment aynı tabloda olursa tekrar ve karmaşa oluşur.

Kolonlar

Kolon	Tip	Null	Anlamı
id	int	hayır	Atama anahtarı
device_id	varchar(21)	hayır	Kuralın aktif olduğu cihaz
rule_group_id	int	hayır	Atanan rule group
is_active	boolean	hayır	Atama aktif mi
assigned_by	int	evet	Atamayı yapan kullanıcı
create_time	timestamp	hayır	Oluşturma
update_time	timestamp	hayır	Güncelleme

Örnek kayıt

{
  "id": 1,
  "device_id": "46000000C47CA670",
  "rule_group_id": 1,
  "is_active": true,
  "assigned_by": 1
}

4. device_rule_state

Bu tablo cihaz bazında kuralın o anki state’ini taşır.

Neden vardır?

Rule geçmişini her pakette baştan hesaplamak pahalıdır. Özellikle duration kuralı, reset mantığı ve multi-trigger davranışı için son bilinen state tutulmalıdır.

Neyi taşır?

• şu an tetikli mi
• kaç kez tetiklendi
• son tetik zamanı
• son reset zamanı
• son event referansı

Kolonlar

Kolon	Tip	Null	Anlamı
id	int	hayır	State kaydı
device_id	varchar(21)	hayır	Cihaz
rule_group_id	int	hayır	İlgili rule group
is_triggered	boolean	hayır	Alarm şu an aktif mi
trigger_count	int	hayır	Kaç kez tetiklendi
last_trigger_time	timestamp	evet	Son tetik zamanı
last_reset_time	timestamp	evet	Son reset zamanı
last_event_id	bigint	evet	Son event referansı
update_time	timestamp	hayır	Güncelleme

Örnek kayıt

{
  "id": 1,
  "device_id": "46000000C47CA670",
  "rule_group_id": 1,
  "is_triggered": true,
  "trigger_count": 2,
  "last_trigger_time": "2026-04-03T10:30:00Z",
  "last_reset_time": "2026-04-03T08:15:00Z",
  "last_event_id": 1,
  "update_time": "2026-04-03T10:30:05Z"
}

Tasarım notu

Bu tablo event geçmişi değildir; yalnız current state’tir. Tarihsel iz için rule_events kullanılır.

5. rule_events

Bu tablo alarm olaylarının tarihsel kaydını tutar.

Neden vardır?

device_rule_state yalnız son durumu gösterir. Ne zaman trigger oldu, ne zaman reset oldu, ne zaman notified oldu gibi zaman çizgisi rule_events içinde yaşar.

Kolonlar

Kolon	Tip	Null	Anlamı
id	bigint	hayır	Event anahtarı
device_id	varchar(21)	hayır	İlgili cihaz
rule_group_id	int	hayır	İlgili kural grubu
event_type	enum	hayır	triggered / reset / notified / command_sent
measurement_stream_id	int	evet	Olayı tetikleyen stream
message_id	bigint	evet	Üretilen inbox mesajı varsa
details	json	evet	Açıklayıcı payload
create_time	timestamp	hayır	Olay zamanı

Örnek kayıt

{
  "id": 1,
  "device_id": "46000000C47CA670",
  "rule_group_id": 1,
  "event_type": "triggered",
  "measurement_stream_id": 5001,
  "message_id": 2002,
  "details": {
    "reason": "IFUND_R, IFUND_S, IFUND_T 45A üstünde 300 sn kaldı",
    "max_current_a": 46.8
  },
  "create_time": "2026-04-03T10:30:00Z"
}

6. rule_actions

Bu tablo alarm veya reset durumunda yapılacak aksiyonların sözlüğüdür.

Neden vardır?

Kuralın koşulu ile reaksiyonu aynı şey değildir. Aynı alarm farklı projelerde farklı bildirim veya komut davranışı üretebilir.

Kolonlar

Kolon	Tip	Null	Anlamı
id	int	hayır	Aksiyon anahtarı
name	varchar(100)	hayır	Aksiyon adı
description	varchar(255)	evet	Açıklama
send_inbox_message	boolean	hayır	Inbox mesajı üretilecek mi
push_template_id	bigint	evet	Push şablonu
notify_owner	boolean	hayır	Owner’a bildir
notify_subusers	boolean	hayır	Alt kullanıcılara bildir
notify_technician	boolean	hayır	Teknik ekibe bildir
notify_admin	boolean	hayır	Admin’e bildir
device_command_id	int	evet	Cihaza komut tetiklenecekse
create_time	timestamp	hayır	Oluşturma
update_time	timestamp	hayır	Güncelleme

Örnek kayıt

{
  "id": 1,
  "name": "Yüksek Akım Bildirimi",
  "description": "Yüksek akım durumunda inbox ve push bildirimi oluşturur",
  "send_inbox_message": true,
  "push_template_id": 2,
  "notify_owner": true,
  "notify_subusers": true,
  "notify_technician": true,
  "notify_admin": false,
  "device_command_id": null
}

7. rule_group_actions

Bu tablo bir rule group’u trigger ve reset aksiyonlarına bağlar.

Neden vardır?

Aynı kural için tetikleme ile reset davranışları farklı olabilir. Bu ikisini tek satırda ama ayrı kolonlarla tutmak group düzeyinde net bir bağ kurar.

Kolonlar

Kolon	Tip	Null	Anlamı
id	int	hayır	Kayıt anahtarı
rule_group_id	int	hayır	Rule group
trigger_action_id	int	evet	Alarm tetiklenince çalışacak aksiyon
reset_action_id	int	evet	Alarm reset olunca çalışacak aksiyon
create_time	timestamp	hayır	Oluşturma
update_time	timestamp	hayır	Güncelleme

Rule Engine’in Veri Kaynağı

Bu modelde kural motoru accepted stream sonrası measurement verilerinden beslenir. Ancak her kural değerlendirmesi için doğrudan veritabanına yük bindirmek yerine cache-first yaklaşım tercih edilir.

DB’nin rolü:

• kalıcı accepted veri
• kural tanımı
• event geçmişi
• son durumun kalıcı temsili

Redis/cache’in rolü:

• sıcak evaluation context
• duration takibi
• sayaçlar ve kısa süreli rule çalışma durumu

Sonuç

Rules & Alerts veri modeli, alarm davranışını şu parçalara ayırır:

• tanım → rule_groups, rules
• atama → device_rule_assignments
• current state → device_rule_state
• history → rule_events
• reaction → rule_actions, rule_group_actions

Bu ayrım sayesinde sistem hem esnek alarm tanımlayabilir hem de neyin ne zaman tetiklendiğini tarihsel olarak izleyebilir.