Cınga Backend Veri Modeli Rehberi
Bu bölüm, Cınga backend veri modelini yalnız tablo isimleri ve alan listeleri üzerinden değil; her tablonun neden var olduğu, ne zaman kayıt üretildiği, ne içerdiği, neyi bilerek içermediği ve sistemde hangi rolü üstlendiği üzerinden açıklar.
Bu rehberin amacı, ileride kod yazarken veya servis davranışı tasarlarken veri katmanında yorum farkı bırakmamaktır. Buradaki yaklaşım, veritabanını yalnız bir depolama alanı olarak değil; sistem davranışını tanımlayan resmi sözleşme katmanı olarak ele alır.
Bu veri modeli rehberinde her ana tablo mümkün olduğunca şu bakış açısıyla belgelenir:
- neden vardır
- ne zaman kayıt oluşur
- ne içerir
- neyi bilerek içermez
- kolonların tipi/null/anlamı nedir
- örnek kayıt nasıl görünür
Veri Modelinin Ana Katmanları
Cınga backend veri modeli birbiriyle ilişkili ama farklı amaçlara hizmet eden birkaç ana katmandan oluşur.
1. Telemetry Lifecycle
Bu katman sistemin veri işleme çekirdeğidir. Cihazdan gelen ham paket, kabul edilmiş telemetry event, typed measurement tabloları, generic ölçümler, runtime state ve ledger izleri burada tanımlanır.
İlgili sayfa:
2. Inventory & Topology
Bu katman fiziksel dünya modelini kurar. Cihaz, modem, SIM, pompa, pano, trafo, parsel ve adres ilişkileri burada taşınır.
İlgili sayfa:
3. Identity & Access
Kullanıcı, rol, device-level authority, permission ve mobil cihaz ilişkileri bu katmanda tanımlanır.
İlgili sayfa:
4. Rules & Alerts
Rule tanımı, assignment, state, event ve aksiyon katmanı burada modellenir.
İlgili sayfa:
5. Messaging, Notes & Push
Kullanıcıya dönük mesajlar, inbox durumu, notlar ve push şablonları bu katmanda ele alınır.
İlgili sayfa:
6. Finance & Irrigation
Telemetry’nin iş tarafındaki sonucu olan finans kayıtları ve sulama oturumları burada tanımlanır.
İlgili sayfa:
7. Master Data & Operations
Projeler, üreticiler, modeller, değişkenler, firmware, komut sözlükleri, log ve operasyon tabloları bu katmanda toplanır.
İlgili sayfa:
Veri Katmanları Arasındaki Özet Ayrım
Aşağıdaki tablo veri modelinin yüksek seviye rol dağılımını özetler:
| Katman | Ana Rol | Örnek Tablolar |
|---|---|---|
| Telemetry | Paket kabulü, accepted event, measurement persistence | raw_data, streams, measurement.*, measurements |
| Runtime State | Son bilinen canlı durum | device_runtime_state, device_register_state (önerilen) |
| Inventory | Fiziksel varlık ve saha topolojisi | devices, modems, sim.*, pumps, electricity_boxes |
| Access | Kullanıcı, authority ve izin modeli | users, authorities, permissions |
| Rules | Kural tanımı, state ve alarm geçmişi | rule_groups, rules, device_rule_state, rule_events |
| Messaging | Kullanıcıya dönük mesaj ve notlar | inbox, message_read_state, notes, push_templates |
| Business | Finans ve sulama oturumları | finances, irrigations |
| Master Data | Ortak sözlük ve operasyon referansları | projects, variables, manufacturer_models, logs |
En Kritik Tasarım Kararları
Bu rehber boyunca özellikle korunacak bazı çekirdek kararlar vardır.
Raw ve Stream Ayrımı
raw_data journal’dır, streams accepted event’tir. Her raw kayıt stream üretmek zorunda değildir.
Measurement Ayrımı
Enerji verileri yüksek hacimli ve çok kolonlu olduğu için measurement.* tablolarında tutulur. Daha generic ve düşük yoğunluklu ölçümler measurements tablosunda yaşar.
Device ve Runtime State Ayrımı
devices tablosu kimlik ve metadata taşıyan ana envanter kaydıdır. Sık değişen son durum alanları ayrı runtime tablolarına ayrılmalıdır.
Rule Tanımı ile Rule State Ayrımı
Kuralın ne olduğu ile o kuralın o anda tetiklenip tetiklenmediği aynı tabloda tutulmaz. Tanım ve state ayrıdır.
Mesaj Gövdesi ile Kullanıcı Okuma Durumu Ayrımı
inbox mesajın kendisini taşır; message_read_state ise kullanıcı bazlı görünürlük ve okuma durumunu taşır.
Telemetry Çekirdeği İçin Özet Akış
Bu akışın ayrıntıları Telemetry Lifecycle sayfasında detaylandırılmıştır.
Bu Rehber Nasıl Kullanılmalı?
Bu klasör, koda başlamadan önce ve servis sözleşmesi yazarken referans belge olarak kullanılmalıdır.
Önerilen kullanım:
- telemetry ile ilgili bir geliştirme yapılacaksa önce
telemetry-lifecycle - cihaz/topoloji ile ilgili bir geliştirme yapılacaksa
inventory-topology - yetki modeli ile ilgili bir geliştirme yapılacaksa
identity-access - alarm davranışı ile ilgili bir geliştirme yapılacaksa
rules-and-alerts - kullanıcı mesajları ile ilgili bir geliştirme yapılacaksa
messaging-and-notes - finans veya sulama iş akışı ile ilgili bir geliştirme yapılacaksa
finance-and-irrigation - ortak sözlük, firmware, komut, log veya operasyonel referanslar için
master-data-and-operations
Sonuç
Bu klasör, Cınga backend veri modelinin yalnız şema değil; davranış ve sorumluluk sözleşmesi olarak okunması için hazırlanmıştır. Her alt sayfa, ilgili tablo grubunu neden-sonuç ilişkisi, kolon sözleşmesi ve örnek kayıtlar üzerinden detaylandırır. Böylece veritabanı tasarımı ileride kod yazımı ve servis davranışı için net bir referans haline gelir.