@appaflytech/zeyrek-ai-mcp 0.0.1

package/dist/resources/examples/workflow-basic.json

@@ -0,0 +1,94 @@
+{
+  "_meta": {
+    "synthetic": true,
+    "note": "hr projesinde doğrulanmış şekil. Kurallar: step/branch id'leri GERÇEK GUID ve global benzersiz (RowAlreadyExists); DtoId verilen yerde Behavior zorunlu; table rule'da datasourceId + fieldId zorunlu; filtre value JavaScript ifadesi; preview girdisi previewPayload anahtarıyla."
+  },
+  "definition": {
+    "name": "Product Lookup",
+    "slug": "product-lookup",
+    "type": "workflow",
+    "parameterDtoId": "<girdi DTO id: { productName: string }>",
+    "returnDtoId": "<çıktı DTO id: { name, price }>",
+    "parameterBehavior": "object",
+    "returnBehavior": "object",
+    "steps": [
+      {
+        "id": "<GUID-1 üret: crypto.randomUUID()>",
+        "name": "Start",
+        "type": "start",
+        "branches": [
+          {
+            "id": "<GUID-2>",
+            "name": "start",
+            "type": "success",
+            "nextStepId": "<GUID-3>"
+          }
+        ]
+      },
+      {
+        "id": "<GUID-3>",
+        "name": "Load Product",
+        "type": "table",
+        "rule": {
+          "stepType": "table",
+          "entityId": "<products entity id>",
+          "operation": "get",
+          "isSingle": true,
+          "selectFields": [
+            {
+              "alias": "<entity slug>",
+              "fieldSlug": "name",
+              "path": "",
+              "fieldId": "<name alanı id>"
+            },
+            {
+              "alias": "<entity slug>",
+              "fieldSlug": "price",
+              "path": "",
+              "fieldId": "<price alanı id>"
+            }
+          ],
+          "filters": [
+            {
+              "fieldSlug": "name",
+              "operator": "eq",
+              "value": "input.productName",
+              "fieldId": "<name alanı id>"
+            }
+          ],
+          "joins": [],
+          "datasourceId": "<datasource id>"
+        },
+        "branches": [
+          {
+            "id": "<GUID-4>",
+            "name": "success",
+            "type": "success",
+            "nextStepId": "<GUID-6>"
+          },
+          {
+            "id": "<GUID-5>",
+            "name": "fail",
+            "type": "fail",
+            "nextStepId": null
+          }
+        ]
+      },
+      {
+        "id": "<GUID-6>",
+        "name": "Response",
+        "type": "response",
+        "rule": {
+          "stepType": "response",
+          "bodyExpression": "{ name: load_product.data.name, price: load_product.data.price }",
+          "httpStatusCode": 200,
+          "headerExpression": "{  }"
+        },
+        "branches": []
+      }
+    ]
+  },
+  "automationVariant": {
+    "note": "Automation: returnDtoId/parameterDtoId YASAK (validator reddeder), returnBehavior 'object' verilebilir; state=unready NORMALDİR ve tetiklemeyi etkilemez. Tetikleme kapısı automation nesnesindeki entityId + operation + isQueue (false=anlık, true=kuyruk; null=asla tetiklenmez!). steps hem üst seviyede hem automation içinde (PLT-007); response yasak, hata yolu revert."
+  }
+}

package/dist/resources/guides/component.md

@@ -0,0 +1,108 @@
+# Komponent Rehberi (katalog, ortak katman, olay modeli)
+
+Sayfaya konan her şeyin ortak kuralları. Kuruluş sırası ve şema gövdesi için
+`platform_guide('page')`; HTML kaçış kapısının derin sözleşmesi için `platform_guide('html')`.
+
+## Keşif: iki tool, üç bilgi katmanı
+
+```
+component_list  → hangi tipler var (slug, kategori, droppable) — kompakt
+component_get   → tek tipin TAM sözleşmesi, üç katman birleşik:
+                    props/defaults/sizes  (platform sözlüğü — tip/enum/default)
+                    events[].payload/reads (olay yükü sözleşmeleri)
+                    knowledge             (davranış bilgisi: ne işe yarar, nasıl davranır)
+```
+
+- `knowledge` alanı yoksa davranış sözlüğe işlenmemiştir — **tahmin etme**.
+- Yanıtta `guide` dönerse (`html` gibi) o tip için derin rehber vardır; ilk kullanımdan önce oku.
+- Şemaya **uydurma prop yazma**: platform 200 döner ama prop sessizce kaybolur. Tek istisna
+  `isHidden` — katalogda görünmese de her komponentte çalışır (ortak render katmanı çizer).
+
+## Ortak katman gerçekleri (RenderComponent — her komponent için geçerli)
+
+- **`isHidden`** her komponenti gizler; setter ile yazmak katalogda listelenmeyen tiplerde de
+  çalışır. Gizli komponent `mount` olayını görünür olana dek TETİKLEMEZ.
+- **`mount`** olayını komponentin kendisi değil ortak katman yayar: komponent ilk kez
+  görünür olduğunda bir kez. Sayfa açılış akışı `page_container.mount`'a bağlanır.
+- **`name` = `elementId`** kuralı: runtime her komponent için `const <name> = Components[...]`
+  üretir; bozuk ad sayfadaki BÜTÜN ifadeleri öldürür (`platform_guide('page')` Kural 1c-2).
+- **Boyut:** `blocks[].size` katalogdaki `maxSize`'ı aşamaz; yükseklikte
+  `appearance.heightType: 'auto'` tercih edilir. Katalog varsayılanı bazı tiplerde kendi
+  sınırını aşar — körü körüne kopyalama, gateway kırpar ve bildirir.
+
+## Olay modeli
+
+- Olay adları `component_get.events`'ten okunur, **`on` öneki almaz** (tek istisna
+  `texteditor`: onMount/onChange). Uydurma ada bağ sessizce ölü kalır — gateway PAGE-008 ile
+  reddeder.
+- Yük `events[].payload`'dadır ama akışa **`event.data` ile GELMEZ**: motor yükü komponentin
+  KENDİ prop'una yazar (`FlowMachine.onEmit` → `setNode`) ve akışı emit'in `params`'ıyla başlatır.
+  Yani `payload` anahtarları prop adlarıdır ve `self.<anahtar>` ile okunur (ya da
+  `value.type:'property'`); `reads` alanı yükte olmayan prop'ları söyler. `event.data` yalnız
+  `html` komponentinin `fireEvent` aksiyonlarında dolar.
+- Akış bağlama: `flow_create` → `page_schema_patch set_event`. İstisna: `html` komponentinin
+  aksiyonları kendi `flow` prop'uyla bağlanır (`platform_guide('html')`).
+
+## Stil
+
+Her komponentin `style` prop'u vardır ve iç parçalara iner (`textinput.style`: `&__label` ·
+`&__input` · `&__error`; `form.style`: `&__title` · `&__header` · `&__body`). `html`
+komponentinde `style` serbest bir emotion CSS bloğudur. Tasarımı varsayılanda bırakmak
+zorunda değilsin.
+
+## Widget: kayıt → sayfaya koyma → akışlar
+
+Widget, kendi komponent ağacını taşıyan yeniden kullanılabilir pakettir (`kind:'widget'`,
+`widgetType: container | modal | drawer`).
+
+1. **Kayıt:** `component_create` — `kind:'widget'`, `widgetType`, `schema` (widget'ın kendi
+   ağacı; `name = elementId` kuralı burada da geçerli — layout gibi widget adları da kullanan
+   sayfaya sızar).
+2. **Sayfaya koyma:** `add_component` düğümünde `kind:'widget'` ve **`type` = widget KAYDININ
+   ID'si** — slug DEĞİL (runtime widget'ı `widget.id === node.type` ile çözer; slug yazarsan
+   kayıt 200 döner, render sessizce boş kalır — gateway **PAGE-012/LAY-005** ile reddeder).
+   `widgetType` alanını da düğüme yaz.
+3. **Akışlar:** widget'ın kendi flow'ları `flow_*` tool'larında `host:'component'`,
+   `hostId: <widget kaydının id'si>` ile yönetilir. Kayıtta adımlar widget şemasındaki somut
+   `elementId`'leri kullanır; Studio düzenleyicisinin gösterdiği `__widget__` yer tutucusu
+   yalnız editör katmanıdır (kayıt anında gerçek id'ye çevrilir) — API'den yazarken yer
+   tutucu KULLANMA.
+
+## `states` ve `appearance` sözlükleri
+
+Her şema düğümünde iki sözlük vardır; ikisi de ortak render katmanında çözülür:
+
+| `states` | Anlamı |
+|---|---|
+| `isDroppable` | İçine komponent alır (container/form/repeater true) |
+| `isScrollable` | İçeriği kendi alanında kaydırır (sabit yükseklikte `overflow-y: auto`) |
+| `isWrapper` | Sayfanın/layout'un/widget'ın ANA kabı — salt düzen elemanı: `height:100%` + **`min-height:80vh`**, kap başlığı ÇİZİLMEZ. **Yalnız sayfa boyu kaplaması gereken tek kap için kullan:** iç içe kutuya verirsen 720px'lik pencerede o kutu 36px içerikle bile 576px çizilir (ölçüldü, `platform_guide('page')` Kural 1f). Çerçeve/başlık gizlemek için wrapper değil `style` / `hideBorders` kullan; `states` için micro-op olmadığından düzeltmek düğümü yeniden kurmayı gerektirir |
+| `isSticky` | Kaydırmada yerinde kalır (header/sidebar; z-index'i otomatik) |
+
+> **Çocukların DİZİLİMİ `states`'te değil kabın PROP'undadır:** `container` — ve dolayısıyla
+> `page_container` — `layout: 'flex' | 'grid'` + altı ayar (`direction`, `horizontalAlign`,
+> `verticalAlign`, `size`, `gap`, `wrap`) taşır. Katalog varsayılanı `flex`'tir ama varsayılan
+> düğüm kurulurken yazılır: `layout` prop'u hiç yoksa renderer IZGARA çizer, o yüzden şemayı sen
+> kuruyorsan açıkça yaz. Ortalama/yaslama/aralık işini `style` ile değil bu grupla kur:
+> `platform_guide('page')` Kural 1f-2.
+
+| `appearance` | Değerler | Anlamı |
+|---|---|---|
+| `heightType` | `auto` · `fixed` | `auto`: içerik kadar (önerilen — Kural 1d); `fixed`: `blocks.h × 10px` |
+| `marginType` / `marginValue` | `normal` · `none` · `custom` + px | Dış boşluk: normal=5px, custom=`marginValue` |
+| `paddingType` / `paddingValue` | `normal` · `none` · `custom` + px | Droppable kapların iç boşluğu: normal=10px |
+| `alignType` | `left` · `center` · `right` | İçerik hizalama (destekleyen komponentlerde) |
+| `widthType` | `cover` · `contain` | Görsel/medya sığdırma davranışı |
+| `aspectRatio` | sayı | En-boy oranı kilidi (medya komponentleri) |
+
+`isHidden` bu sözlüklerde değil PROP'tur ve her komponentte çalışır; flow'lar `margin` /
+`padding` / `height` prop adlarıyla da appearance'ı setter üzerinden değiştirebilir
+(RenderComponent bu üç prop'u appearance'a çevirir).
+
+## Komponent seçimi
+
+"Hangi işe hangi komponent" tablosu ve `table` / `datatable` karşılaştırması:
+`platform_guide('page')` Kural 1e ve 7e. Kaçınılacak tek şey yarım kurulumdur (süzme
+arayüzü açık, arkası statik uç). Hazır komponentlerin hiçbiri işi karşılamıyorsa `html`
+kaçış kapısıdır — yeteneklerini `platform_guide('html')` anlatır; "platform bunu yapamaz"
+demeden önce onu oku.

package/dist/resources/guides/entity.md

@@ -0,0 +1,348 @@
+# Entity Rehberi
+
+Buradaki kurallar gerçek projelerde (qm, hr, sms, klinik) **deneyerek doğrulandı**.
+
+## Slug seçimi — isim uzayı platformla paylaşımlıdır
+
+Her environment şeması ~75 platform tablosu taşır ve entity slug'ları bu tablolarla aynı isim
+uzayındadır. Çakışan slug `Migration failed … relation "X" already exists` verir ve **entity
+kaydı hiç oluşmaz**. Rezerve adlardan bilinenler: `branches`, `applications`, `caches`,
+`components`, `datasources`, `entities`, `fields`, `files`, `flows`, `folders`, `layouts`,
+`microservices`, `pages`, `permissions`, `projects`, `queries`, `queued_events`, `roles`,
+`steps`, `users`, `variables`, `views`, `workflows`. Alan adı bunlardan biriyse eş anlamlısını
+seç (ör. şube/branş için `branches` değil `specialties`).
+
+> **Ama `users`/`roles`/`files`/`folders` bir istisna:** bunlar "dolu olduğu için kaçınılacak"
+> adlar değil, **platformun sana verdiği hazır entity'ler**. Kopyasını yapmadan önce aşağıdaki
+> bölümü oku.
+
+## Hazır entity'ler — kimlik tablosu ZATEN VAR
+
+Her projeye seed sırasında 9 entity açılır ve **id'leri her kurulumda aynı sabitlerdir**
+(`Defaults` sınıfı) — aramana gerek yok, doğrudan `entity_get` ile çekebilirsin:
+
+| slug | id | Ne için |
+|---|---|---|
+| `users` | `01917ede-330e-7254-8544-eef0db3693af` | **Kimlik.** `id` (uuid PK) · `email` (display, UNIQUE) · `password` · `first_name` · `last_name` |
+| `roles` | `01917ede-88a2-72ea-8397-2619e5d5dca0` | `page_create`/`microservice` `roleIds`'inin okuduğu roller (`role_list`) |
+| `user_roles` | `01917ede-be1e-7d62-9a7c-d0ce4e4daaaf` | kullanıcı ↔ rol |
+| `permissions` · `role_permissions` | `01917ede-a457-…` · `01917ede-d450-…` | yetki matrisi |
+| `files` · `folders` | `0191dbf2-39c4-…` · `0191df94-f635-…` | Drive; `FILE` alanları buraya bağlanır (`entity_list`'te GİZLİ) |
+| `audit_trails` · `audit_trail_values` | `01961f53-25c3-…` · `01961f53-3552-…` | denetim izi |
+
+**`users` gerçek bir entity'dir**, sahte bir sistem tablosu değil: `entity_get` alanlarını verir,
+`RELATION` alanı hedef alabilir, table step / microservice okur, `row_create` yazar, kendi default
+DTO'su vardır. Auth middleware tarifi zaten bunu okur — `ngapps://examples/middleware-authenticate`
+`entityId` olarak `users`'ı kullanır.
+
+### Neden gözden kaçıyor
+
+`entity_list`'i **`applicationId` ile** çağırdığında hazır entity'ler listede **görünmez**: seed
+onlara `EntityApplication` kaydı açmaz, filtre de `EntityApplications.Any(...)` ile süzer. Kimlik
+tablosunu görmek için `entity_list`'i `applicationId` VERMEDEN çağır (ya da yukarıdaki id'yi
+doğrudan kullan).
+
+### Kullanırken bilinmesi gerekenler
+
+- **Silinemez** (`CantDeleteDefaultEntityException`) ve default alanları (`email`, `password`…)
+  silinemez. Buna karşılık **`entity_patch` ile alan EKLENEBİLİR** — telefon, departman, avatar,
+  `musteri_tipi` gibi profil alanları `users`'a eklenebilir.
+- **Eklediğin alan `nullable: true` olmalı.** Platform bu tabloya EF üzerinden de yazıyor
+  (`organization_sync_users`) ve EF senin kolonunu bilmiyor; NOT NULL + varsayılansız bir kolon o
+  yolu kırar.
+- **`password` alanı `Hasher.Hash`'lidir.** Satır yazarken hash'i ifadeyle ürettir
+  (`crypto.SHA256.encode(...)` — gerçek algoritma için `platform_guide('expressions')`); düz metin
+  yazarsan giriş hiçbir zaman eşleşmez.
+- **`isAuditTrailActive`'i AÇMA.** `users` tablosunun audit kolonları EF tarafında `Ignore`
+  edilmiş; `sys_*` eklemek EF'in bilmediği kolonlar yaratır.
+- **`organization_sync_users` Studio operatörlerini bu tabloya süper yönetici rolüyle kopyalar**
+  (yalnız production dışı environment'lara). Yani tablo hem platform operatörünü hem uygulama
+  kullanıcısını taşır ve roller `page.roleIds` yetkilendirmesiyle ortaktır.
+- **İlişki aynı datasource içinde kurulur.** `users` built-in datasource'tadır; entity'lerin dış
+  bir DB'deyse `users`'a ilişki kuramazsın.
+
+### Karar: `users`'ı genişlet mi, ayrı entity mi?
+
+**Karar senin** — ikisi de geçerli. Ayrım şu: `users` **kimliktir** (giriş, `user.id` kapsaması,
+roller), domain kaydı değil.
+
+- **Kimlik alanları** (e-posta, parola, ad, telefon, avatar, dil tercihi) → `users`'a ekle.
+- **Domain verisi** (siparişler, kredi limiti, öğrencinin sınıfı, temsilcinin iş yükü) → ayrı
+  entity + `users`'a `one-to-many`. Bir kişi aynı anda iki rolde olabilir (hem temsilci hem
+  talep sahibi), `users` da silinemeyen/şeması kısmen kilitli bir tablodur.
+
+**Kaçınılacak tek şey:** kendi entity'ne `email` + `password` koyup **ikinci bir kimlik sistemi**
+kurmak. O noktada iki ayrı kullanıcı tablosu, iki ayrı hash düzeni ve `middlewareIds`/`roleIds`
+ile hiç konuşmayan bir yetkilendirme olur. Gateway bu şekli ENT-009 ile hatırlatır (warn — bilerek
+yapıyorsan devam et).
+
+## Alan tipleri (dbType + commonType İKİSİ birden verilir)
+
+| dbType (BÜYÜK HARF zorunlu) | commonType |
+|---|---|
+| `UUID` | `guid` |
+| `VARCHAR`, `TEXT` | `text` |
+| `BOOL` | `bool` |
+| `INT2`, `INT4`, `INT8` | `number` |
+| `DATE` | `date` |
+| `TIME` | `time` |
+| `TIMESTAMP`, `TIMESTAMPTZ` | `datetime` |
+| `JSONB` | `custom` |
+| `FILE` | `file` |
+| `RELATION` | `relation` |
+| `Incremental` (tam bu yazım) | `incremental` |
+
+- Kontrol **büyük/küçük harfe duyarlı** — küçük harf tümüyle reddedilir. `Incremental` bu
+  tablodaki tek karma yazımdır (`PostgreSqlConnector` onu ayrı bir tip grubu olarak yayınlar;
+  fiziksel tip `TEXT`'tir, bu yüzden kayıttan sonra `entity_get` `dbType: "TEXT"` +
+  `commonType: "incremental"` gösterir — bu normaldir, alanı geri çevirme).
+- **Ondalık tip YOK:** `NUMERIC`, `FLOAT4/8`, `MONEY`, `DECIMAL` reddedilir (datasource'un
+  `dataTypes` listesi yanıltır, ona güvenme). Birim konvansiyonu kullan ve birimi
+  `description`'a yaz: para → `INT8` kuruş (`*_minor`), süre → `INT4` dakika, yüzde →
+  `INT4` ×100, puan → `INT4` ×10.
+- `commonType`'sız `UUID`/`BOOL` "isn't a supported database type" hatasıyla reddedilir.
+
+## Alan tipine karar verme (önce buna bak, sonra yaz)
+
+Yanlış tip seçmek sessiz teknik borçtur: satırlar yazılır, servisler 200 döner, ama Studio
+formu doğru bileşeni gösteremez ve veri serbest metne dönüşür. Sırayla sor:
+
+1. **Sabit bir değer kümesi mi?** (durum, öncelik, dönem, unvan, sınav tipi) → **enum**:
+   `valueOptions` dolu + `isEnum: true`. Serbest `VARCHAR` bırakma.
+   - **Aynı anda birden fazla değer seçilebilecekse → multi-enum**: `VARCHAR` +
+     `relationType: 'many-to-many'` + `valueOptions`; `relationId` ve `isEnum` **verilmez** —
+     platform `<slug>_values` enum-values entity'sini ve junction'ı kendisi üretir
+     (`relationMetadata.enumValuesEntityId` yanıtta dolu döner).
+2. **Dosya mı?** → `dbType: 'FILE'` + `commonType: 'file'`; tekil dosya `relationType: 'one-to-many'`,
+   çoklu dosya `relationType: 'many-to-many'`. `relationId` **verme** — platform yerleşik Files
+   entity'sini kendisi bağlar (`one-to-one` verilirse `one-to-many`'ye çevrilir).
+3. **Başka bir kayda referans mı?** → `RELATION` (yukarıdaki ilişkiler bölümü).
+4. **Sıralı, insan okuyabilir bir kod mu?** (talep no `TLP-0001`, teklif no, fatura no) →
+   **`Incremental`** — aşağıdaki bölüm. Primary key ile karıştırma: PK teknik kimliktir,
+   incremental kullanıcıya gösterilen iş numarasıdır; ikisi aynı tabloda birlikte bulunur.
+5. **Serbest metin / sayı / tarih mi?** → tablodaki temel tipler.
+
+> **m2m/FILE/multi-enum alanı iki aşamada kurulur — gateway bunu artık kendisi yapar.**
+> Create yolu junction entity kaydını açar ama **fiziksel tabloyu kurmaz**
+> (`EntityService.CreateAsync` migration'ı yalnız ana entity için koşar); sonuç 500
+> `42P01 relation "…" does not exist` ve alan silinemez de. `entity_create` bu alanları
+> gövdeden ayırır, entity'yi onlarsız kurar, sonra bir güncelleme turunda ekler (update
+> migration'ı junction tabloyu kurar) ve yanıtta `gatewayNormalized` ile bildirir — gövdeye
+> yazmaya devam edebilirsin. Ham HTTP ile çalışıyorsan sırayı elle uygula.
+
+**Enum yazmıyorsan gerekçen olsun.** `courses.semester` ("2025-2026 Güz") bileşik bir etiket
+olduğu için serbest metindir; `course_assignments.semester` (Güz/Bahar/Yaz) enum'dur.
+
+```jsonc
+{ "name": "Durum", "slug": "status", "dbType": "VARCHAR", "commonType": "text",
+  "relationType": "none", "nullable": false,
+  "isEnum": true,
+  "valueOptions": [
+    { "value": "Aktif",      "icon": "#47ad10" },
+    { "value": "Bırakıldı",  "icon": "#888888" },
+    { "value": "Tamamlandı", "icon": "#0052CC" }
+  ] }
+```
+
+- `valueOptions[].icon` bir **hex renktir**, ikon adı değil.
+- `isEnum` Studio tarafında `valueOptions.length > 0` ile türetilir; yine de ikisini birlikte ver.
+- **Enum PostgreSQL'de CHECK constraint üretir.** Var olan bir metin alanını enum'a çevirirken
+  tablodaki değerler `valueOptions` içinde yoksa migration `check constraint ... is violated` ile
+  düşer. Sıra: **önce satırları kanonik değerlere taşı, sonra alanı enum yap.**
+
+## Artan kod alanı (`Incremental`)
+
+Sıralı, önekli, insan okuyabilir kod üretir (`TLP-0001`). Alan tanımı:
+
+```jsonc
+{ "name": "Talep No", "slug": "ticket_no",
+  "dbType": "Incremental", "commonType": "incremental",
+  "relationType": "none", "nullable": false, "unique": true,
+  "properties": { "isCaseSensitive": false } }
+```
+
+**Kod satır yazılırken üretilir ve üretimi ALANA YAZDIĞIN DEĞERİN TİPİ belirler**
+(`EntityService.ApplyIncrementalValuesAsync`) — `row_create`, `row_update` ve workflow table
+create step'inde aynı kural geçerlidir:
+
+```jsonc
+// NESNE verirsen: platform kodu üretir ve değeri onunla DEĞİŞTİRİR
+"ticket_no": { "Prefix": "TLP", "Separator": "-", "Counter": 1, "DigitCount": 4 }   // → "TLP-0001"
+
+// STRING verirsen: olduğu gibi yazılır, üretim ATLANIR (veri taşımada işine yarar)
+"ticket_no": "TLP-0002"
+```
+
+Girdi sınırları (`IncrementalCodeInput.TryParse`; ihlal edilirse nesne geçersiz sayılır ve kod
+üretilmez): `Prefix` ≤ 3 karakter · `Separator` ≤ 1 karakter · `Counter` ≥ 1 ·
+`DigitCount` 1–12.
+
+- **Sayaç kendini onarır:** üretim var olan en yüksek koddan devam eder
+  (`EntityIncrementSequenceService.ResolveStartingCounterAsync`), yani elle `TLP-0005` yazdıktan
+  sonra nesne biçimiyle yazılan ilk satır `TLP-0006` olur. `Counter: 1` vermek "1'den başla"
+  demek değil, "taban 1" demektir.
+- `properties.isCaseSensitive` büyük/küçük harf duyarlılığını belirler (`Field.IsCaseSensitiveIncremental`).
+- Sayfa tarafındaki karşılığı `incrementalinput` komponentidir.
+- `datasource_list.dataTypes` çıktısında bu tipi ayrı bir grup olarak görürsün; listede
+  görmezsen yine de geçerlidir (rehberdeki "dataTypes'a güvenme" uyarısı burada da geçerli).
+
+## Primary key
+
+```jsonc
+// GUID anahtar
+{ "name": "ID", "slug": "id", "dbType": "UUID", "commonType": "guid",
+  "primaryKey": true, "nullable": false, "unique": true, "identity": true,
+  "defaultValueType": "none", "defaultValue": "",
+  "properties": { "generationType": 0 }, "relationType": "none" }
+
+// INT anahtar (auto-increment) — dbType ve commonType dışında birebir aynı
+{ "name": "ID", "slug": "id", "dbType": "INT4", "commonType": "number",
+  "primaryKey": true, "nullable": false, "unique": true, "identity": true,
+  "defaultValueType": "none", "defaultValue": "",
+  "properties": { "generationType": 0 }, "relationType": "none" }
+```
+
+- **GUID zorunlu değildir.** `UUID/guid` ve `INT2|INT4|INT8 / number` ikisi de geçerli birinci
+  sınıf seçeneklerdir; platform kuralı GUID dayatmaz (bu, backend repo'sunun `Guid.CreateVersion7()`
+  kuralıyla karıştırılmamalı — o C# tarafının kuralı, platform verisinin değil). Yüksek hacimli /
+  sıralı okunması doğal tablolarda (yoklama, log, hareket) `INT4` tercih edilebilir; dağıtık
+  üretim, dışa açık id, birleştirilecek veri varsa `UUID`.
+- **`identity: true` + `properties.generationType: 0` olmadan anahtar otomatik üretilmez** ve her
+  satırda id elle gönderilmek zorunda kalır. `generationType` datasource seçenekleri:
+  `0 = Always`, `1 = ByDefault`.
+- `properties.generationType` **yalnız primary key'de** anlamlıdır; identity olmayan alanlarda
+  Studio bu anahtarı zaten siler.
+- Doğrulama: satır yazdıktan sonra `row_list` ile geri oku — id üretilmişse (`1, 2, 3…` ya da
+  UUIDv7) anahtar doğru kurulmuştur.
+
+Gateway bu iki kuralı ENT-006 (PK identity/tip uyumu) ve ENT-007 (enum şekli) olarak denetler.
+
+## Application bağı — ne yapar, ne yapmaz
+
+`applicationIds` **create'te platformca bağlanır** (`CreateEntityCommand` → `EntityService.CreateAsync`
+→ `Entity` ctor). Gateway'in ayrıca patch atmasına gerek yok.
+
+Bağın gerçek etkisi ikidir:
+
+- `EntityRepository.cs:167` — `entity_list`'in `applicationId` filtresi, yani **Studio'nun
+  application bazlı entity listesi**. Bağsız entity o listede görünmez.
+- `MicroserviceRepository.cs:556` — bağımlılık/etki analizi sorgusu.
+
+**Satır uçları bu bağa İHTİYAÇ DUYMAZ.** Bağsız bir entity'de `row_create` / `row_list` sorunsuz
+çalışır (16 satırlık bağsız tabloda doğrulandı). Eski "bağsız entity'de satır uçları 500
+'Sequence contains no matching element' döner" bilgisi **yanlıştı**, kod tarafında karşılığı yok.
+
+**Bağ auto page ÜRETMEZ.** Auto page üreten
+`UpdatePageWhenEntityUpdatedEventHandler`, `EntityApplications`'a değil `PageSettings`'e bakar
+(`PageSettings` boşsa hiç çalışmaz) ve `PageSettings` yalnız `UpdateEntityCommand.AutoPages`
+ile dolar. 10 entity'nin tamamı bağlıyken `entity_page_settings = 0`, `pages = 1` ölçüldü.
+
+Karar: **Studio'dan yönetilecek entity'lerde `applicationIds` ver; yalnız API'den kullanılacaksa
+boş bırakmak geçerli bir tercihtir** (ENT-002 warn'ı bunu hatırlatır, zorunlu kılmaz).
+
+> `entity_patch` uyarısı: `EntityDto` çıktıda `applications` (nesne listesi) döner ama
+> `UpdateEntityCommand` girdide `applicationIds` (Guid listesi) okur. Gateway bu çeviriyi
+> kendisi yapar; ham PUT atarken **siz yapmazsanız her güncelleme bağı sessizce siler.**
+
+## İlişkiler (doğru şekil — 57 alanla doğrulandı)
+
+```jsonc
+{ "name": "Department", "slug": "department_id",
+  "dbType": "RELATION", "commonType": "relation",
+  "relationType": "one-to-many",
+  "relationId": "<hedef entity id>",
+  "nullable": true }
+```
+
+- `relation` alt nesnesini (`primaryKeyId`, `displayFieldId`, ...) **platform kendisi doldurur**
+  — elle verme.
+- `relationType`: `one-to-one | one-to-many | many-to-many`.
+- **m2m yalnız FARKLI iki entity arasında kurulabilir.** Kendine referanslı m2m (ör. ders ↔
+  ön koşul ders) platformda `500 "Operation is not valid due to the current state of the object"`
+  ile reddedilir. Kendine referans gerekiyorsa ara entity + iki one-to-many kullan.
+- m2m değerleri satırlara **id dizisi** olarak yazılır (`{"qualified_courses": ["<id>", "<id>"]}`),
+  okurken `[{ id, <displayAlanı> }]` döner.
+- **m2m mi, ara entity mi:** bağın kendisi ekstra alan taşımıyorsa (ürün↔etiket) → m2m alanı
+  (Studio çoklu seçim UI'ı bedava). Bağın kendi alanları varsa (tarih, puan, durum) → ayrı
+  entity + iki yana one-to-many.
+- İki entity'yi önce ilişkisiz oluşturup ilişki alanını sonra `entity_patch` ile eklemek en
+  güvenli sıra (id'ler ancak oluşunca belli olur).
+- `display: true` entity başına tek alanda olabilir; ilişkilerde görüntülenen değer bu alandır.
+
+## TEXT kolonunda JSON: yazarken string, okurken NESNE döner
+
+Şema ile ifade edilemeyen değişken yapıları (anket cevabı, ayar bloğu, anlık görüntü) `TEXT`
+kolonda JSON metni olarak tutmak meşru bir desendir — ama **gidiş ve dönüş şekli aynı değildir**;
+bilmezsen "kayıt bozulmuş" sanırsın.
+
+- **Yazarken string ver.** Microservice/flow parametresinde `JSON.stringify(...)` gönder; alan
+  `commonType: text` olduğu için dizi/nesne göndermek doğru değildir.
+- **Okurken platform onu senin için AYRIŞTIRIR.** `DictionaryExtensions.ToNested()`
+  (`NgApps.Infrastructure/Extensions/DictionaryExtensions.cs:49-64`) her string değere bakar;
+  kırpılmış hâli `{`…`}` ya da `[`…`]` ile başlayıp bitiyorsa `ToObject<object>()` ile parse eder,
+  patlarsa string olarak bırakır. Yani `row_list` / uç yanıtı sana **hazır nesne/dizi** verir —
+  ikinci kez `JSON.parse` etme.
+- **Yan etki:** JSON'a benzeyen ama JSON olmayan metinler (`[taslak]`, `{sablon}`) de bu kontrole
+  girer; parse başarısız olunca string kalır, veri bozulmaz.
+
+> **Studio tablosunda `[object Object],[object Object]` görmek NORMALDİR ve veri sağlamdır.**
+> Grid hücresi değeri `row[cell.key]?.toString()` ile basıyor
+> (`apps/studio/src/components/data-grid/DataGrid.svelte:125`); parse edilmiş bir dizide bu
+> ifade `[object Object],…` üretir. Ölçüm (anket projesi, 2026-08-19): grid'de `[object Object]`
+> görünen satırın `row_list` çıktısı `question_id / question_text / type / value_text /
+> option_ids` alanlarıyla eksiksizdi. Gerçek içeriği görmek için grid'e değil `row_list`'e bak.
+> Kolonu tabloda okunur göstermek gerekiyorsa özet bir alan daha tut (ör. `answer_summary` TEXT)
+> ya da sayfada `repeater`/`html` ile render et.
+
+## Satır işlemleri
+
+- `row_create/row_update` anahtarları **field slug'larıdır** (name değil): `{"code": "IK"}`.
+- Yazdıktan sonra `row_list` ile geri oku; ilişki alanları `{ id, name }` nesnesi olarak döner.
+- **`isAuditTrailActive: true` ile KURULAN entity'ye satır yazılamaz.** `sys_*` kolonları create
+  yolunda oluşmaz, yalnız ilk **etkin** `entity_update`'inde eklenir; o ana kadar **her**
+  `row_create` şu hatayla 500 verir:
+
+  ```
+  Sequence contains no matching element [InvalidOperationException]
+  ```
+
+  Gateway'in bu vakadaki "entity bir application'a bağlı değil (PLT-004)" ipucu **yanlış yöne
+  gönderir** — entity bağlıyken de aynı hata çıkar, `row_list` çalışır, yalnız yazma kilitlidir.
+  `true → true` aynı-değer patch'i **saymaz** (etkisiz update). İki güvenli yol: entity'yi
+  `isAuditTrailActive: false` ile kur, ya da create'ten sonra `false → true` turunu at.
+
+  > `Sequence contains no matching **element**` (audit kolonu eksik) ile
+  > `Sequence contains no **elements**` (satır yok — genelde preview rollback'i) **farklı**
+  > sorunlardır; karıştırmak teşhisi saptırır.
+
+- **Audit izi ne zaman gerçekten yazılır?** `CreateAuditTrailCommandHandler` şu üç durumda
+  **hiç kayıt açmaz**: `IsAuditTrailActive == false`, `AuditTrailType == null`, ya da
+  `AuditTrailType == simple`. Yani iz tutulması için `isAuditTrailActive: true` **ve**
+  `auditTrailType: "basic" | "detailed"` birlikte gerekir. Enum yalnız üç değer tanır —
+  `simple` · `basic` · `detailed` (`AuditTrailType.cs`); `advanced` diye bir değer **yoktur**,
+  gönderirsen bağlama hatası alırsın.
+- **Audit izi IP adresi tutar.** `audit_trails.IpAddress`, isteğin
+  `HttpContext.Connection.RemoteIpAddress` değerinden doldurulur (`UserContext.cs`) ve satır
+  olaylarıyla (`Row.Created/Updated/Deleted` → `UserIpAddress`) audit consumer'a taşınır; kullanıcı
+  id'si ve e-postası da aynı yolla gider.
+
+  > **Anonim veri toplayan tablolarda `isAuditTrailActive: false` bırak** — anket cevabı, geri
+  > bildirim, başvuru gibi "kimliksiz" vaadi olan her tabloda. `false` iken hiçbir gizli kolon ya
+  > da yan kayıt oluşmaz; `true` + `basic/detailed` iken "anonim" dediğin satırın yanında IP
+  > durur. Bu, ürünün gizlilik vaadini sessizce bozan tek ayardır.
+
+- **`defaultValueType: "static"` sessizce `"none"`e düşer** — DB varsayılanı kurulmaz. Bu yüzden
+  her `BOOL`/sayısal alanı **her** `row_create`'te ve her workflow write adımında **açıkça** yaz;
+  "varsayılanı platform koyar" varsayımı `null` satır üretir.
+- **`row_list`'in `filters` parametresi çalışmıyor** — denenen her biçim
+  `Failed to invoke 'CompileNestedCondition'` ile 500 verir. Daraltmayı `selectedFields` +
+  `order` + `pageLength` ile yap, ya da doğrulamayı entity satırından değil **ucun kendisinden**
+  (`microservice_execute`) yap.
+- **`users`'ta `row_create` verdiğin `id`'yi yok sayar** (PK `identity` + `generationType: 0`);
+  Studio operatörünü proje tablosuna aynı id ile taşıyamazsın, eşleme e-posta üzerinden kurulur.
+- Silmeden önce `entity_dependencies` / `dependency_graph`.
+
+## Büyük entity'lerde
+
+`entity_get view:'outline'` alan listesi; `view:'part', part:'fields[slug=email]'` tek alan;
+değişiklik `entity_patch`.