Schema & Data Engine - Motorlar

Schema & Data Engine Nedir?

Schema & Data Engine, TotalApp'in no-code tarafının bel kemiğidir. Platformun kutudan çıktığı haliyle sunmadığı bir ekranı veya özelliği kullanıcıya sunmayı mümkün kılan yapıdır — yeni bir modül için bir geliştiricinin elle bir şeyler inşa etmesini beklemek yerine, motor kullanıcıya o modülün ihtiyaç duyduğu veriyi tanımlamanın bir yolunu verir ve gerisini kendisi halleder.

Asıl amacı basit bir gözlemden yola çıkar: bir kullanıcının yeni bir ekrana veya yeni bir özelliğe ihtiyacı olduğunda, bunun altında aslında ihtiyaç duyulan şey veridir — o ekranın okuyacağı ve yazacağı kayıtları güvenilir şekilde saklayacak bir yer. Ve bu veri sadece "bir yerde" duramaz — deterministik ve güvenilir olmak zorundadır, aksi halde bunun üzerine kurulan her ekran ve her otomasyon aynı güvenilmezliği devralır. Şekli zorlanmayan, zorunlu alanları olmayan ve doğrulaması yapılmayan bir tablo zamanla, hiçbir raporun, gösterge panelinin veya yapay zeka ajanının doğru şekilde üzerinde akıl yürütemeyeceği bozuk, tutarsız kayıtlarla dolar.

Schema & Data Engine'in kapattığı boşluk tam olarak budur. Kullanıcının kendi veri tablosunu — koleksiyon olarak adlandırılır — bir e-tablodaki kolonları taslak haline getirir gibi tasarlamasına izin verir: tabloya bir ad verin, alanlar ekleyin, her alanın tipini seçin (metin, sayı, evet/hayır veya sabit bir seçenek listesi) ve hangi alanların zorunlu olduğunu belirleyin. Bu tanım kaydedildikten sonra, o koleksiyona eklenmeye çalışılan her kayıt, kalıcı hale getirilmeden önce otomatik olarak bu kurallara göre denetlenir.

Kısaca: "Sipariş No: metin, zorunlu", "Toplam Tutar: sayı, zorunlu", "Durum: sadece beklemede / onaylandı / iptal değerlerinden biri olabilir" tanımını bir kere yapın — o andan itibaren o tabloya gönderilen her satır, sunucu tarafında tam olarak bu kurallara göre doğrulanır. Bir kuralı ihlal eden satır doğrudan reddedilir.

Tek cümlede

Schema & Data Engine'e bir kez alan tanımları seti verin — bunu gerçek, doğrulanmış bir depolama şemasına dönüştürür ve kurallara uymayan her kaydı, tam olarak neyin yanlış olduğunu açıklayan net, alan bazlı bir hata mesajıyla reddeder.

Nasıl Çalışır — Bir Kere Tanımla, Her Seferinde Doğrula

Her koleksiyon aynı iki aşamalı yaşam döngüsünden geçer:

1. Koleksiyonu Tasarla → 2. Kayıt Ekle ve Doğrula

Aşama	Ne olur
1. Koleksiyonu Tasarla	Kullanıcı koleksiyona bir ad verir ve alanları tek tek ekler: bir alan adı, bir tip (metin, sayı, evet/hayır veya sabit bir izin verilen değer setine sahip seçenek listesi) ve alanın zorunlu olup olmadığı. Bu tanım bir kere kalıcı hale getirilir ve bundan sonraki her kaydın karşılaştırılacağı şema haline gelir.
2. Kayıt Ekle ve Doğrula	O koleksiyona her kayıt gönderildiğinde, motor onun alan tanımlarına bakar ve gelen her değeri kayıt hiç depoya yazılmadan önce üç kontrolden geçirir — zorunluluk, tip ve seçenek listesi üyeliği. Tek bir başarısız kontrol, tüm kaydı belirli, insan tarafından okunabilir bir hatayla reddeder.

Neden her eklemede doğrulama yapılıyor, sadece kayıt anında değil?

Çünkü TotalApp'teki koleksiyonlar sadece bir formu dolduran bir kişi tarafından doldurulmuyor — aynı zamanda workflow node'ları, yapay zeka ajanları ve gelen webhook'lar tarafından da yazılıyor. Tasarım anında bir kere doğrulama yapmak, daha sonra bozuk bir otomatik yazmayı durdurmak için hiçbir işe yaramaz. Her tekil ekleme işlemini şemaya göre yeniden kontrol etmek, koleksiyonu, ona ne yazdığından bağımsız olarak güvenilir bir bariyer haline getiren şeydir.

Girdi — Bir Koleksiyon Tasarımcısının Yapılandırdığı Şey

Her koleksiyon bir ad ve bir alan listesiyle tanımlanır. Her alan tam olarak dört bilgi parçası taşır:

Alan Adı

Kolonun adı, her kayıtta görüneceği haliyle — ör. order_id, total_price, status.

Alan Tipi

Dört tipten biri: metin (string), sayı, evet/hayır (boolean) veya seçenek listesi (enum) — sabit bir izin verilen string değerler seti.

Zorunlu Bayrağı

Alanın her kayıtta mutlaka bulunması ve boş olmaması gerekip gerekmediği. Eksik, null veya boş string olan zorunlu bir alan anında reddedilir.

Seçenekler (yalnızca seçenek listesi alanları)

Bir seçenek listesi alanının alabileceği tam değer seti — ör. beklemede, onaylandı, iptal. Bu listenin dışındaki her değer reddedilir.

Çıktı — Geriye Ne Döner

Başarılı bir ekleme tam oluşmuş kaydı döner; başarısız bir ekleme ise belirli, alan bazlı bir hata döner:

Sonuç	Anlamı
Başarılı (200)	Kayıt, üretilen bir `id`, `collectionId`'si, gönderilen `data`'sı ve `createdAt`/`updatedAt` zaman damgalarıyla birlikte döner.
Eksik zorunlu alan (400)	`Missing required field: "order_id"` — boş bırakılan tam alanı belirtir.
Yanlış tip (400)	`Field "total_price" must be a number` — alanı ve beklenen tipi belirtir.
Geçersiz seçenek değeri (400)	`Field "status" must be one of: pending, approved, cancelled` — kabul edilecek her değeri listeler.
Bilinmeyen koleksiyon (404)	Belirtilen koleksiyon çağıranın tenant'ı için mevcut değil — ya hiç oluşturulmamıştır ya da başka bir tenant'a aittir.

Reddedilir, asla sessizce dönüştürülmez

Motor, çağıranın adına kötü girdiyi asla "düzeltmeye" çalışmaz — bir string'i sayıya asla dönüştürmez veya geçersiz bir alanı sessizce atmaz. Doğrulamayı geçemeyen bir kayıt, çağıranın (bir kişi, bir workflow node'u veya bir yapay zeka ajanı) tam olarak neyi düzeltmesi gerektiğini her zaman bilmesi için, kesin bir hatayla doğrudan reddedilir.

Depolama — Tenant Bazlı, Çift Backend

Her koleksiyon ve her kayıt, isteğin JWT'sinden çözülen, kimliği doğrulanmış çağıranın tenant'ına özeldir — asla istemci tarafından sağlanan bir header'dan değil. Bir tenant başka bir tenant'ın koleksiyonlarını asla göremez, listeleyemez veya onlara yazamaz; başka bir tenant'a ait bir koleksiyon ID'si için yapılan istek, var olup olmadığını sızdırmak yerine 404 ile reddedilir.

Motor, koleksiyonların ve kayıtların gerçekte kalıcı hale getirildiği yer için birbiriyle değiştirilebilir iki depolama backend'ini destekler:

Tenant JSON Dosyaları

Hafif varsayılan seçenek — her tenant, TotalApp genelinde kullanılan aynı sunucu tabanlı JSON kalıcılık desenini takip ederek diskte kendi schema-data-collections.json (alan tanımları) ve schema-data-records.json (kayıt satırları) dosyalarını alır. Sıfır kurulum, küçük-orta ölçekli kayıt hacimleri ve hızlı prototipleme için ideal.

PostgreSQL (JSONB)

Daha büyük veya daha yüksek verim ihtiyacı olan tenant'lar için, aynı koleksiyon/kayıt modeli hibrit bir PostgreSQL şemasına eşlenir: bir system_collections tablosu her tenant'ın alan tanımlarını JSONB olarak saklar, bir tenant_records tablosu ise gerçek satır verisini hızlı sorgulama için bir GIN index'i ve (tenant_id, collection_id) üzerinde bir kompozit index ile JSONB olarak saklar. Bir koleksiyona alan eklemek bir meta-veri güncellemesidir, asla maliyetli bir ALTER TABLE migration'ı değil.

Hangi backend olursa olsun aynı doğrulama

Tenant hangi backend'de olursa olsun, doğrulama kuralları, API şekli ve hata mesajları aynıdır — depolama katmanı, aynı insertSchemaRecord / fetchSchemaRecords sözleşmesinin arkasındaki bir uygulama detayıdır. Bir kere tasarlanan bir koleksiyon, satırları bir JSON dosyasına mı yoksa bir Postgres tablosuna mı düştüğünden bağımsız olarak aynı şekilde davranır.

Son Kullanıcılar Bunu Nasıl Kullanıyor?

Kendi Tablonuzu Tasarlayın

Custom Collections ekranından bir kullanıcı:

Yeni bir koleksiyona ad verir — "Envanter Sayımı", "Etkinlik Katılımcıları" veya "Freelancer Ödemeleri" gibi tamamen serbest bir şey.
Alanları tek tek ekler: bir ad, bir tip (metin / sayı / evet-hayır / seçenek listesi) ve zorunlu olup olmadığı.
Tasarımı kaydeder — koleksiyon tanımı anında kalıcı hale getirilir.
Alan tanımlarından bir veri giriş formu otomatik olarak üretilir: bir seçenek listesi alanı bir açılır menü olur, bir evet/hayır alanı bir onay kutusu olur, bir sayı alanı sayısal bir girdi olur.
Formu göndermek doğrulanmış bir kayıt ekler; sunucu kaydedilmeden önce her kuralı uygular.
O koleksiyona ait tüm kayıtlar canlı, filtrelenebilir bir tabloda listelenir.

Yapay Zeka Ajanları ve Entegrasyonlar için Temiz-Veri Kapısı

Bir workflow node'u — Shopify'dan gelen bir webhook veya bir yapay zeka ajanının ürettiği yapılandırılmış bir çıktı — bir koleksiyona yazmaya çalıştığında, kullanıcının tanımladığı kurallar bir güvenlik duvarı görevi görür. Bir yapay zeka modelinden gelen doğrulanmamış çıktı asla doğrudan kalıcı depoya yazılmaz; her zaman önce bu motordan geçer.

Örnek: bir workflow node'u "yapay zeka destekli veri temizleme" yapar ve sonucunu bir koleksiyona POST eder. Kullanıcı tanımlı kuralları ihlal eden her çıktı — yanlış tip, eksik zorunlu alan, geçersiz seçenek değeri — otomatik olarak reddedilir. Bu, üst akıştaki prompt ne kadar iyi yazılmış olursa olsun, LLM halüsinasyonuna karşı yapısal bir savunma sağlar.

Hızlı Prototipleme ve Mini-CRM İhtiyaçları

Bir kullanıcının ihtiyacı — basit envanter takibi, hafif bir CRM, etkinlik yönetimi — mevcut bir TotalApp modülüyle eşleşmediğinde, bu motor sayesinde tek bir satır kod yazmadan kendi mini veri deposunu tasarlayabilir; tıpkı Airtable veya Notion'ın veritabanı özelliğinin çalışma şekli gibi, ama TotalApp'in kendi tenant izole altyapısında çalışarak.

Schema & Data Engine Nereye Uyuyor?

Bu motor, diğer motorların doğrulanmış kayıtlar yazdığı veri katmanı ve Database Tools ekranlarının arkasındaki depodur:

Tüketici	Schema & Data Engine'i nasıl kullanıyor
Matris Ajanı	Bir puanlama sonucu (geçme/kalma kapısı, toplam puan, kategori dökümü), kullanıcı tarafından tasarlanmış bir "Değerlendirme Sonuçları" koleksiyonunda doğrulanmış bir satır olarak kalıcı hale getirilebilir; böylece her puan, onu üreten ekrandan bağımsız olarak filtrelenebilir ve raporlanabilir hale gelir.
Denetim Ajanı	Her PPTX/PDF denetim bulgusu (slayt numarası, kural, önem derecesi, kanıt), kendi denetim raporu dosyasında izole kalmak yerine, kullanıcı tarafından tasarlanmış bir "Denetim Bulguları" koleksiyonuna yazılabilir.
Database Tools	ORM Mapper, Schema Visualizer, Visual Query Builder ve Seed Data Generator'ın hepsi aynı koleksiyon/kayıt modeli üzerinden okur ve yazar — burada tasarlanan bir koleksiyon, bu araçların incelediği, diyagramlaştırdığı, sorguladığı ve tohumladığı "varlık"tır.
Workflow / Entegrasyon node'ları	Gelen webhook payload'ları ve yapay zeka ajanı çıktıları, bir kişinin bir formu doldurmasıyla aynı doğrulanmış ekleme yolundan geçerek koleksiyonlara yazılır.

Sıkça Sorulan Sorular

Bunu kullanmak için SQL yazmam gerekiyor mu?

Hayır. Bir koleksiyon tasarlamak tamamen görseldir — alanları adlandırır ve tiplerini bir listeden seçersiniz. Koleksiyon sonuçta tenant JSON dosyaları veya bir PostgreSQL tablosu tarafından destekleniyor olsun, kullanıcıdan asla bir migration veya SQL ifadesi istenmez.

Zaten kayıtları olan bir koleksiyona yeni bir alan eklersem ne olur?

Mevcut kayıtlar, düzenlenene kadar yeni alan için basitçe bir değere sahip olmaz — yeni eklenen bir alan, yalnızca zorunlu olarak işaretlenirse gelecekteki eklemeler için zorunlu hale gelir. Yıkıcı bir migration adımı yoktur; backend ister JSON dosyaları ister Postgres JSONB olsun, alan tanımı güncellemesi anındadır.

İki tenant aynı isimde veya aynı alan düzenine sahip koleksiyonlara sahip olabilir mi?

Evet, hiçbir çakışma olmadan. Her koleksiyon ve her kayıt, onu oluşturan tenant'a özeldir — başka bir tenant'taki aynı koleksiyon adı veya alan düzeni, tamamen bağımsız, izole bir veri setidir.

Neden geçersiz bir alan, geçerli kısımları kaydetmek yerine tüm kaydı reddediyor?

Eksik zorunlu bir alana veya aralık dışı bir değere sahip kısmen kaydedilmiş bir kayıt, hiç kayıt olmamasından daha kötü olurdu — bu koleksiyon üzerine kurulan raporlar, gösterge panelleri ve alt akış otomasyonları yalnızca depolanan her satır şemayı karşılıyorsa güvenilirdir. Motor bilinçli olarak katıdır: tüm kayıt bir birim olarak doğrulanır ve ya eksiksiz olarak depolanır ya da hiç depolanmaz.

Schema & Data Engine verisi tenant bazlı mı?

Evet. Koleksiyonlar ve kayıtlar, kesinlikle çağıranın imzalı JWT'sine gömülü tenant ID'sinden çözülür — asla istemci tarafından sağlanan bir header'dan değil — böylece bir tenant'ın koleksiyonları ve verisi başka bir tenant tarafından asla görülemez veya yazılamaz.