@appaflytech/zeyrek-ai-mcp 0.0.5 → 0.0.7

package/dist/resources/guides/entity.md

@@ -4,6 +4,12 @@ Buradaki kurallar gerçek projelerde (qm, hr, sms, klinik) **deneyerek doğrulan
 
 ## Slug seçimi — isim uzayı platformla paylaşımlıdır
 
+> **Yanıttaki `silentlyDropped`'ı oku.** Gateway her yazma çağrısında gönderdiğin gövdeyi
+> kaydedilenle karşılaştırır ve kayda geçmeyen alanları bu listede sayar — istek 200 döner, alan
+> yok sayılmıştır. Bu, hata listesinde hiç görünmeyen tek sinyaldir; yazmadan sonra yanıtın o
+> alanına bakmayı alışkanlık yap. Ayrıntılı örnek: `platform_guide('microservice')`.
+
+
 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`,
@@ -48,18 +54,24 @@ doğrudan kullan).
   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.
+  (bakım yolları dâhil) 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.
+- **Tablo hem platform operatörünü hem uygulama kullanıcısını taşıyabilir** ve roller
+  `page.roleIds` yetkilendirmesiyle ortaktır. Ama **yeni projede boş gelir**: Studio operatörü
+  kendiliğinden uygulama kullanıcısı olmaz. İlk kullanıcıyı açmanın yolu
+  `platform_guide('getting-started')` §"İlk kullanıcıyı kim açar?".
 - **İ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.
+- **Sonuç: kimlik gerektiren her uygulama built-in datasource'ta kurulur.** Entity'lerini dış bir
+  DB'ye açarsan giriş, `user.id` kapsaması ve roller kullanılamaz hâle gelir — bunlar `users`'a
+  ilişki üzerinden bağlıdır. Built-in her projeyle birlikte doğar (`datasource_list` çıktısında
+  `isBuiltIn: true`); `datasource_create` yalnız **kullanıcı kendi veritabanını verdiğinde**
+  çağrılır ve o kurulum bu bedeli kabul etmiş olur.
 
 ### Karar: `users`'ı genişlet mi, ayrı entity mi?
 
@@ -76,6 +88,50 @@ kurmak. O noktada iki ayrı kullanıcı tablosu, iki ayrı hash düzeni ve `midd
 ile hiç konuşmayan bir yetkilendirme olur. Gateway bu şekli ENT-009 ile hatırlatır (warn — bilerek
 yapıyorsan devam et).
 
+### Rol yönetimi — `roles` da sıradan bir entity
+
+**`role_create` diye bir tool yoktur ve olmayacak.** Rol tablosu built-in datasource'ta yaşar;
+uygulamanın rol açması/düzenlemesi gerekiyorsa yol her domain tablosuyla aynıdır: entity + kendi
+microservice ucun + sayfa. `role_list` yalnız okur.
+
+`roles` entity'sinin açtığı alanlar — fiziksel tabloda ayrıca `template_*` kolonları var, hepsi
+nullable, gateway'den görünmez:
+
+| alan | not |
+|---|---|
+| `id` | uuid PK; `page.roleIds` ve `microservice.roles` BUNU ister |
+| `name` | **UNIQUE** (`ix_roles_name`) — aynı adı ikinci kez yazan insert veritabanı hatasıyla düşer |
+| `slug` | **yetkilendirmenin karşılaştırdığı alan**; `role_list` bunu DÖNDÜRMEZ |
+
+**İki farklı anahtar, karıştırma:**
+
+- **id** → `page_create/page_update` ve `microservice_create` `roleIds` alanı (gövdede `roles` diye bir
+  yazma alanı YOKTUR; `microservice.roles` middleware'de RUNTIME şeklidir, `{ id, name: '<slug>' }`).
+  `role_list`ten okunur.
+- **slug** → `Authorized(user.roles)`, middleware'in kurduğu `user.roles` / `Page.user.roles`.
+  Platformun get-user sorgusu `roles`'u `user_roles` üzerinden **slug dizisi** olarak üretir
+  (`SELECT … ARRAY(SELECT r.slug FROM roles r INNER JOIN user_roles ur …)`), auth middleware
+  tarifi de aynı şeyi yapar — `platform_guide('middleware')` §Rol karşılaştırması SLUG üzerinden.
+
+Bu yüzden **slug'sız yazılan rol sessizdir:** insert 200 döner, satır `role_list`te görünür,
+`page.roleIds` ile bağlanır — ama `Authorized(user.roles)` o rol için hiçbir zaman tutmaz. Gateway
+bunu `ROL-002` ile uyarır.
+
+Rol açma reçetesi:
+
+1. `entity_get('01917ede-88a2-72ea-8397-2619e5d5dca0')` ile alan id'lerini al.
+2. Yazma ucunu kur: `microservice_create` `source:'table'`, `entityId` = roles, `operation:'create'`,
+   `fields` = `name` + `slug` (slug'ı ifadeyle ada göre üretmek serbest; **`super-admin` slug'ını
+   verme** — platform süper yöneticiyi `slug == 'super-admin'` ile arar).
+3. Rolü kullanıcıya bağlamak ayrı bir satırdır: `user_roles` (`01917ede-be1e-7d62-9a7c-d0ce4e4daaaf`)
+   `user_id` + `role_id`; çift **(user_id, role_id) UNIQUE**'tir, aynı bağı iki kez yazma.
+4. Yeni rol, kullanıcının bir sonraki isteğinde geçerlidir — middleware rolleri her çağrıda
+   tablodan okur; jeton tazelemeye gerek yoktur (rolleri jetona kendi gömen bir middleware
+   yazdıysan orada geçerli değil).
+
+`permissions` / `role_permissions` **Studio'nun yetki matrisidir**, uygulama sayfasının yetkisi
+değil; uygulama tarafında yetkiyi `page.roleIds` ve middleware ifadesi kurar.
+
 ## Alan tipleri (dbType + commonType İKİSİ birden verilir)
 
 | dbType (BÜYÜK HARF zorunlu) | commonType |
@@ -101,6 +157,11 @@ yapıyorsan devam et).
   `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.
+- **Katalogu okumak gerekiyorsa** (bu datasource'ta hangi `dbType` var, hangisi varsayılan, tip
+  hangi seçenekleri kabul ediyor, hangi tipe dönüştürülebilir) `datasource_configuration_options`
+  çağır: varsayılan yanıt ~5 KB'lık **özettir**; 816 kayıtlık collation DEĞER listesi yalnız
+  `includeCollations: true` ile gelir (tam yanıt ~45 KB). Katalogda görünen bir tipin
+  `entity_create` tarafından kabul edileceğini varsayma — yukarıdaki ondalık maddesi bunun kanıtı.
 
 ## Alan tipine karar verme (önce buna bak, sonra yaz)
 
@@ -138,13 +199,35 @@ olduğu için serbest metindir; `course_assignments.semester` (Güz/Bahar/Yaz) e
   "relationType": "none", "nullable": false,
   "isEnum": true,
   "valueOptions": [
-    { "value": "Aktif",      "icon": "#47ad10" },
-    { "value": "Bırakıldı",  "icon": "#888888" },
-    { "value": "Tamamlandı", "icon": "#0052CC" }
+    { "value": "Aktif",      "icon": "#47ad10", "order": 1 },
+    { "value": "Bırakıldı",  "icon": "#888888", "order": 2 },
+    { "value": "Tamamlandı", "icon": "#0052CC", "order": 3 }
   ] }
 ```
 
 - `valueOptions[].icon` bir **hex renktir**, ikon adı değil.
+- **`valueOptions[].order` seçeneğin İŞ SIRASIDIR (2026-09-05).** Huni, aşama, öncelik gibi
+  sıralı raporlarda sırayı sorguya statik `VALUES` listesi olarak gömmek gerekmez — sıra alan
+  tanımında durur ve `entity_get` ile geri gelir. Verilmezse `0`'dır; sıralı bir enum tanımlarken
+  doldurun, çünkü etiket değişince sorguya gömülmüş liste sessizce yanlış sıralar.
+- **Sıra SQL'den de okunur.** `value_options` tenant veritabanında `fields` tablosunda `jsonb`
+  kolondur ve anahtarları küçük harftir (`value` · `icon` · `order`). Sıralı bir rapor sırayı
+  buradan JOIN'ler:
+
+  ```sql
+  WITH ord AS (
+    SELECT opt->>'value' AS status, (opt->>'order')::int AS pos
+    FROM fields f CROSS JOIN LATERAL jsonb_array_elements(f.value_options) AS opt
+    WHERE f.entity_id = '<entity id>' AND f.slug = 'status')
+  SELECT o.status, COALESCE(c.total, 0) AS candidates
+  FROM ord o
+  LEFT JOIN (SELECT status, COUNT(*) AS total FROM candidates GROUP BY status) c
+    ON c.status = o.status
+  ORDER BY o.pos
+  ```
+
+  Ölçüldü 2026-09-05 (`query_preview`): dört durumluk bir enum bu sorguyla doğru sırada döndü,
+  sorguda tek bir sabit değer yok.
 - `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
@@ -181,6 +264,11 @@ Girdi sınırları (`IncrementalCodeInput.TryParse`; ihlal edilirse nesne geçer
   (`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.
+- **Kodu kaydetmeden görmek:** `row_next_code` aynı nesneyi alır (`prefix` · `separator` ·
+  `counter` · `digitCount`) ve sıradaki kodu sayacı ilerletmeden döner (`persist: false`).
+  `counter` ile `digitCount` platform tarafında **zorunludur** (`GetNextIncrementalCodeQuery`
+  validator'ı `NotEmpty` der, yani 0 kabul edilmez); eksik gönderirsen uç 400 verir — gateway de
+  bu ikisini zorunlu tutar (ölçüm: 09-02 D-2).
 - `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
@@ -194,6 +282,15 @@ parametre YOKTUR). Kısıt (`FieldDtoValidator`): `isLocalized: true` iken `prim
 · `unique` `false` olmalı ve `relationType: 'none'` olmalı — bunlardan biri doluysa platform
 reddeder.
 
+**`display: true` alanı `isLocalized` OLABİLİR** (ürün kararı 2026-09-08). Alan companion'a
+taşınır ama okuyucular onu çözer: `entity_get` companion alanını ana listeye katar, `row_list`
+bire-çok ilişkinin etiketini istek dilinde döndürür (`kategori_id: { id, ad }`).
+
+> **İlişkinin hedefinde de çalışır.** Çoka-çok listesi `[{ id, <display> }]` olarak istek dilinde
+> gelir, join'li (bire-çok) tablonun çok dilli kolonu mikroservis alan seçicisinde görünür ve
+> `returnScheme`'e girer. Çevirisi olmayan satır varsayılan dile düşer, listeden düşmez.
+> Ölçüldü 2026-09-08 (`dil-iliski2`: `etiketler[].ad` ve `kategori_id.ad` iki dilde).
+
 **Platform bunun için ayrı bir uç açmaz.** Bir entity'de `isLocalized` alanı olduğunda (create ya
 da update'te) platform otomatik olarak `{entity_slug}_localization` adlı **companion bir entity**
 kurar/genişletir:
@@ -208,6 +305,29 @@ language                              Text
 artı `(relation, language)` üzerinde unique index. Yani bir satırın Türkçe/İngilizce değerleri
 **ayrı satırlardır**, ana tabloda değil bu companion entity'de yaşar.
 
+**Satır araçları companion'ı senin yerine konuşur — normalde companion'a hiç dokunmazsın:**
+
+| İstediğin | Çağrı |
+|---|---|
+| Satırı bir dilde yaz | `row_create(row, localizations: { tr: {…}, en: {…} })` |
+| Toplu yaz | `row_create(rows: [{ …, localizations: { tr: {…} } }])` — `localizations` SATIRIN İÇİNDE |
+| Yalnız çeviriyi güncelle | `row_update(row: { <pk>: … }, localizations: { en: {…} })` — ana satır değişmese de olur |
+| Satırı bir dilde oku | `row_list(language: 'en')` / `row_get(language: 'en')` — alan düz gelir |
+| Bütün dilleri gör | `row_list(includeTranslations: true)` → satırda `localizations.<dil>.<alan>` |
+| Çok dilli alana filtre/sıralama | `row_list(language, filters)` — alan slug'ı düz yazılır |
+
+`language` verilmezse platform `Accept-Language`'a, o da yoksa projenin varsayılan diline düşer;
+bölgeli kod ('tr-TR') kabul edilir ve gateway 'tr'ye indirger. **Okumada çevirisi olmayan alan
+varsayılan dile düşer ama filtre ve sıralama fallback GÖRMEZ** — o satır filtrede eşleşmez ve
+sıralamada `NULL` sayılır.
+
+Dil satırlarını platform yazar: `row_delete` companion satırlarını ana satırdan önce kendisi siler,
+desteklenmeyen bir dil kodu 400 döner ve ana satır da yazılmaz. Yanıtta
+`gatewayNormalized: ["platform 'localizations' alanını tanımıyor …"]` görürsen platform bu
+sözleşmeden eski bir sürümdedir; gateway o zaman companion'a kendisi yazar ve `localizations.count`
+ile kaç dil satırı yazdığını söyler — `localizationsFailed` ise ana satır yazılmış, dil satırları
+yazılmamıştır. Aşağıdaki elle tarif yalnız o eski yol ve `rows` ile toplu yazma için gerekir.
+
 **Kullanım (tamamı mevcut genel araçlarla, yeni tool GEREKMEZ):**
 
 ```
@@ -219,6 +339,14 @@ artı `(relation, language)` üzerinde unique index. Yani bir satırın Türkçe
 
 `{fk_slug}` companion entity'nin `entity_get`'inde görünen ilişki alanının slug'ıdır (ana entity
 adından türetilir); satırı elle kurmadan önce mutlaka `entity_get` ile doğrula, tahmin etme.
+Companion'ı adından değil **ana entity'nin `localizationEntityId` alanından** bul — ad kalıbı
+(`{slug}_localization`) bir kolaylıktır, bağ ise `entity_get`'in döndürdüğü bu id'dir.
+
+> **Toplu uçta `localizations` SATIRIN İÇİNDEDİR** (2026-09-08): `rows: [{ kod: 'A1',
+> localizations: { tr: { ad: 'Kalem' }, en: { ad: 'Pen' } } }]`. Üst düzeye koymak toplu uçta
+> hangi satıra ait olduğunu söyleyemeyeceği için gateway tarafından reddedilir. `localizations`
+> bu yüzden hem okuma hem yazma tarafında **ayrılmış bir anahtardır**: `includeTranslations: true`
+> ile okunan satırda da aynı adla gelir, yani bu adda gerçek bir kolonun olamaz.
 
 ```jsonc
 // GUID anahtar
@@ -249,6 +377,10 @@ adından türetilir); satırı elle kurmadan önce mutlaka `entity_get` ile doğ
 
 Gateway bu iki kuralı ENT-006 (PK identity/tip uyumu) ve ENT-007 (enum şekli) olarak denetler.
 
+> **Çok dilli bir entity TEK adımda silinir.** `entity_delete` ana entity'ye uygulanır, companion
+> da onunla düşer. (Aynı gün daha erken bir ölçümdeki "önce companion'ı sil" adımı artık geçersiz;
+> EF izleme hatası giderildi. Ölçüldü 2026-09-08, `dil-iliski`.)
+
 ## Application bağı — ne yapar, ne yapmaz
 
 `applicationIds` **create'te platformca bağlanır** (`CreateEntityCommand` → `EntityService.CreateAsync`
@@ -273,8 +405,9 @@ Karar: **Studio'dan yönetilecek entity'lerde `applicationIds` ver; yalnız API'
 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.**
+> `UpdateEntityCommand` girdide `applicationIds` (Guid listesi) okur. `PATCH /entities/{id}`
+> yolunda bu çeviriyi **platform** yapar; ham PUT atarken **siz yapmazsanız her güncelleme bağı
+> sessizce siler.**
 
 ## İlişkiler (doğru şekil — 57 alanla doğrulandı)
 
@@ -300,6 +433,122 @@ boş bırakmak geçerli bir tercihtir** (ENT-002 warn'ı bunu hatırlatır, zoru
 - İ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.
+- **Boş ilişki `null` döner** (2026-09-09'dan beri). Öncesinde platform her üyesi `null` olan bir
+  nesne (`{"name": null, "id": null}`) döndürüyordu; gateway `prune` bunu `{}`'ye indirdiği için
+  ajan tarafında `{}` görünüyordu ve JS'te truthy olduğu için `if (row.manager_id)` "yöneticisi
+  var" diyordu (İK koşusu D-8). Şekil `row_list`'in okuma yolunda düzeltildi. **Gateway `null`
+  alanları tümüyle atar**, yani `row_list` çıktısında boş ilişki alanını **hiç görmezsin** —
+  alanın yokluğu "boş" demektir.
+
+## Index'ler
+
+`indexes` alanı `entity_create` ve `entity_update` gövdesinde geçer.
+**Studio'da index ekranı YOKTUR** — bu alan platformun tek index yönetim yüzeyidir, yanlış
+yazdığın bir index'i arayüzden görüp düzeltemezsin. Tam şema:
+`ngapps://schemas/CreateEntityCommand` (`EntityIndexDto`).
+
+```jsonc
+{ "indexes": [
+  { "id": "<guid, opsiyonel — verilmezse platform üretir>",
+    "name": "candidate_company_status",
+    "unique": true,
+    "fieldIds": ["<field id>", "<field id>"] }
+] }
+```
+
+Alan adları 422 ile kendini söyler; **sessiz olan kurallar** şunlar:
+
+- **`unique` — `isUnique` DEĞİL.** Yanlış anahtar hata vermez, platform onu yok sayar ve index
+  UNIQUE OLMADAN kurulur. Aynı tuzak `fields` için de var, ama o 422 döner
+  (`Indexes[0].FieldIds: 'Field Ids' must not be empty`); doğru ad **`fieldIds`**.
+- **`fieldIds` sırası bileşik index'in KOLON SIRASIDIR.** Dizideki konum `Order` olarak
+  yazılır, DDL kolonları o sırayla kurar. `(company_id, status)` ile `(status, company_id)`
+  farklı index'lerdir; öndeki kolon önek sorgularını hızlandıran kolondur.
+- **`entity_update` gövdesinde `indexes` YOKSA entity'nin BÜTÜN index'leri silinir** — kayıt da
+  düşer, `DROP INDEX` de koşar. Gateway `entity_update` çağrısında alan verilmemişse mevcut
+  index'leri gövdeye taşır ve bunu `gatewayNormalized` ile bildirir; silmek istiyorsan
+  `indexes: []` yazarak **açıkça** iste.
+- **Var olan bir index'te `name` / `unique` / `fieldIds` değiştirmek İŞE YARAMAZ:** platform farkı
+  yalnız `id` üzerinden alır, aynı `id` ile yapılan değişiklik UYGULANMAZ ve hata da vermez.
+  Değiştirmenin yolu index'i silip **yeni bir `id`** ile yeniden yazmaktır.
+
+**Sıra:** `fieldIds` alan **id'si** ister, slug değil — ve alan id'lerini platform ÜRETİR
+(`FieldDto.Id` gövdede yoksa sunucuda atanır). İki geçerli yol var:
+
+1. Entity'yi index'siz kur, `entity_get view:'outline'` ile alan id'lerini oku, index'i
+   `entity_patch` ile ekle. **Varsayılan yol budur.**
+2. Tek çağrıda kuracaksan `fields[].id`'leri kendin ver ve aynı guid'leri `fieldIds`'e yaz.
+   (Ölçüldü 2026-09-07: üç alanı ve bileşik unique index'i olan bir entity tek `entity_create`
+   çağrısıyla kuruldu.)
+
+Var olmayan bir alan id'si reddedilir ama **hata mesajı yanıltıcıdır**: platform
+`This record is in use. Related table: 'Fields', column: 'Field Id'. Please remove its relations
+first.` der — sanki bir bağımlılık varmış gibi. Gerçek sebep bunun tersidir: o id'de alan YOKTUR.
+Bu mesajı alınca bağımlılık aramaya gitme, `fieldIds`'i alan listesiyle karşılaştır.
+
+Doğrulama kuralları (hepsi 422 döner):
+
+- `fieldIds` boş olamaz ve aynı alanı iki kez taşıyamaz.
+- `name` zorunlu; **önek hariç** en fazla 32 karakter.
+- Index adları entity içinde benzersizdir (büyük/küçük harf duyarsız).
+
+Ada dokunma: platform ada `IX_<entity id'sinin 5 hanesi>_` öneki ekler ve okuma yolu **önekli**
+adı döner. Gidiş-dönüş kararlıdır — okuduğun adı geri yazabilirsin, önek ikinci kez eklenmez.
+
+Kurulabilen tek şekil **artan (ASC), çok kolonlu, opsiyonel UNIQUE** b-tree'dir. `DESC`, kısmi
+index (`WHERE`), ifade index'i, `INCLUDE` ve GIN/GiST platform yüzeyinde yoktur; bunlardan birine
+ihtiyacın varsa `platform_gap_report` ile bildir.
+
+Platformun kendi ürettiği örnek, bileşik unique için okunabilir bir kalıptır: çoklu dilli alan
+kurulunca yan entity'ye `(relation, language)` üzerinde unique bir index açılır — yani "bir
+satırın her dilde en fazla bir çevirisi olur" kuralı index'le zorlanır.
+
+Yazdığın index'i `entity_get view:'outline'` çıktısındaki `indexes` bloğundan doğrula; DDL'in
+gerçekten kurulduğunu görmek istiyorsan `query_preview` ile
+`select indexname, indexdef from pg_indexes where tablename = '<slug>'` sorgusunu koştur —
+`entity_get` yalnız metadata'yı kanıtlar, `CREATE UNIQUE INDEX` satırını değil.
+
+## Backend doğrulama sınırları (ENT-015 · ENT-016 · ENT-017 · ENT-018 · ENT-004 · ENT-013)
+
+Bu tablo `CreateEntityCommandValidator` / `UpdateEntityCommandValidator` / `FieldDtoValidator`'ın
+aynasıdır. Gateway aynı kuralı **istek gitmeden** `block` olarak uygular ve mesaj platformun 422
+cümlesidir — 2026-09-08 koşusunda bu kurallar ancak platforma gidip öğrenildi (index adı 33
+karakter, primaryKey yok). Tam katalog, kaynak referanslı JSON: `ngapps://rules/backend-constraints`.
+
+| Alan | Kural | ID |
+|---|---|---|
+| `name` | zorunlu, en fazla 255 karakter | ENT-015 |
+| `description` | en fazla 1024 | ENT-015 |
+| `slug` | zorunlu (create) | ENT-015 |
+| `fields[].name` | en fazla 50 | ENT-015 |
+| `fields[].description` | en fazla 512 | ENT-015 |
+| `fields[].slug`, `fields[].dbType` | zorunlu; dbType en fazla 50 | ENT-015 |
+| `fields[]` | **tam 1** alan `primaryKey: true` — "Please select exactly one primary key." | ENT-016 |
+| `fields[]` | adlar tekil (büyük/küçük harf duyarsız): create `name`, update `slug` üzerinden | ENT-016 |
+| `fields[].display` | en fazla 1 alan | ENT-004 |
+| `primaryKey` / `identity` | `nullable: false`; PK ayrıca `hidden: false` | ENT-017 |
+| `isLocalized` | `primaryKey`/`identity`/`unique` yok, `relationType: 'none'` | ENT-017 |
+| `folderId` | yalnız `commonType: 'file'` alanında | ENT-017 |
+| `properties.generationType` | yalnız `commonType` `guid` ya da `number` | ENT-017 |
+| `commonType` / `defaultValueType` / `relationType` | sözlükten; bilinmeyen değer 400 `InvalidEnumTokenException` (`multiFile` diye bir tip YOK) | ENT-017 |
+| `recordTransferMode: 'specific'` | `transferRowIds` dolu, tekil, boşsuz | ENT-018 |
+| `indexes[]` | ad önek hariç en fazla 32, `fieldIds` dolu ve tekil, adlar tekil | ENT-013 |
+
+**Birincil anahtar kalıbı** (bu rehberde yoktu; 2026-09-08 koşusunda iki hatalı çağrı + bir
+keşif turuna mal oldu):
+
+```jsonc
+{ "slug": "id", "name": "Id", "dbType": "UUID", "commonType": "guid",
+  "primaryKey": true, "unique": true, "identity": true, "nullable": false,
+  "properties": { "generationType": 0 } }
+```
+
+**Create tuzağı:** create yolu alan adlarını `name` üzerinden tekil arar. `name` yazılmayan iki alan
+aynı (boş) gruba düşer ve platform "Duplicate value: 'Slug'" der — mesaj slug'ı suçlar, sebep ad
+eksikliğidir. Her alana `name` yaz; update yolu aynı denetimi `slug` üzerinden yapar.
+
+Satır yazma da aynı katalogdan denetlenir (ROW-002, `row_create` / `row_update`): satır sözlüğü
+boş olamaz, boş anahtar taşıyamaz, bütün değerleri null olamaz; toplu yolda her satır ayrı bakılır.
 
 ## TEXT kolonunda JSON: yazarken string, okurken NESNE döner
 
@@ -328,8 +577,58 @@ bilmezsen "kayıt bozulmuş" sanırsın.
 
 ## Satır işlemleri
 
+- `row_*` tool'ları `entityId` olarak slug kabul eder (`employees`, çakışmada
+  `BuiltIn/employees`); gateway id'ye çevirir ve yanıtta `gatewayResolved` ile bildirir.
 - `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.
+- **Satırlar bir DOSYADAN geliyorsa gövdeye hiç koyma: `path`.** `row_create { entityId, path:
+  "seed.csv" }` gateway'e dosyayı okutur, 1000'lik partilere böler ve ardışık bulk çağırır;
+  bağlama tek bir `{ written, batches }` döner. Ölçüm: 170 KB'lık tohum verisi `rows[]` ile üç
+  kez ajan bağlamından geçti (2026-09-03 koşusu P3-3). `.json` satır dizisi ya da `.csv` (UTF-8,
+  ayraç ilk satırdan; `;` sayısı `,` sayısını geçerse `;`) okur, değerler string gider ve tipe
+  backend çevirir. Sınır 50 MB / 100.000 satır — üstü içe aktarma zinciridir.
+- **Partiler arası transaction YOKTUR.** Her parti kendi içinde tek transaction'dır: düşen parti
+  kendi satırlarını geri alır, **önceki partiler yazılmış kalır**. Gateway ilk düşen partide durur
+  ve `stopped.fileLine` ile hangi DOSYA SATIRINDAN devam edileceğini söyler. Hepsi-ya-hiç
+  gerekiyorsa `path` değil `import_run` kullanın.
+- **İlişki alanına id yerine ad yazmak: `relationsByName: true`.** `departman: "Satış"` hedef
+  tablonun display ya da benzersiz alanında aranır ve id'ye çevrilir; yalnız toplu yolda
+  (`rows` / `path`) çalışır. Eşleşmeyen değer 422 döner ve hangi satırın hangi alanı olduğunu
+  söyler — sessizce boş bırakmaz. Öncesinde m2m ve tekil ilişki için `row_list` ile display → id
+  sözlüğü elle kuruluyordu.
+- **Toplu yazımda (`rows[]`) yanıt `data: [{ "<pk slug>": değer }, …]` döner** — istek sırasında,
+  her satır için bir kayıt. `row_create` bunu 2026-09-04'ten beri, `row_update` **2026-09-09'dan
+  beri** yapar; o tarihe kadar toplu update yalnız `{success:true}` dönüyordu ve hangi satırın
+  yazıldığını öğrenmek için fazladan bir `row_list` turu gerekiyordu.
+- Yazdıktan sonra `row_list` ile geri oku; ilişki ve dosya alanları `{ id, <displayAlanı> }`
+  nesnesi olarak döner.
+- **Okunan şekli olduğu gibi geri yazabilirsin (2026-09-09'dan beri).** İlişki, dosya ve m2m
+  alanlarında yazma yolu hem id string'ini hem `{ id, … }` nesnesini kabul eder; nesne verilirse
+  `id` okunur. Öncesinde bu **sessizce veri kaybettiriyordu**: dosya alanında `500
+  InvalidCastException`, tekil ilişkide `200` + FK'nın `NULL`'a düşmesi, m2m'de `200` + bağın
+  silinmesi (2026-09-09 koşusu S-01). İd string'i hâlâ en kısa ve en güvenli şekildir.
+- **Boş to-one ilişki `null`, boş many-to-many alan `[]` döner** (2026-09-09'dan beri). m2m
+  öncesinde JSON metni olarak `""` dönüyordu — `Array.isArray` `false`, `forEach` çökerdi (S-02).
+  Gateway `null` alanları attığı için boş to-one ilişki yanıtta **hiç görünmez**.
+
+### Alan tipi × yazarken × okurken
+
+Tek tabloda tüm şekiller. "Yazarken" sütunundaki **her iki** biçim de kabul edilir; id string'i en
+kısa ve en güvenli olandır.
+
+| Alan tipi | Yazarken | Okurken (`row_list`) | Boşken okurken |
+|---|---|---|---|
+| tekil ilişki (`relation`, one-to-many) | `"<id>"` · `{ "id": "<id>", … }` | `{ id, <displayAlanı> }` | `null` (gateway alanı hiç göstermez) |
+| tekil dosya (`file`) | `"<fileId>"` · `{ "id": "<fileId>", … }` | `{ id, display_name }` | `null` (gateway alanı hiç göstermez) |
+| çoklu ilişki (m2m) | `["<id>", …]` · `[{ "id": "<id>", … }, …]` | `[{ id, <displayAlanı> }, …]` | `[]` |
+| çoklu dosya (FILE m2m) | `["<fileId>", …]` · `[{ "id": "<fileId>", … }, …]` | `[{ id, display_name }, …]` | `[]` |
+| `text` kolonda JSON | `JSON.stringify(...)` (string) | **ayrıştırılmış** nesne/dizi | — |
+| enum (`valueOptions`) | değerin kendisi (`"active"`) | aynı string | `null` |
+| ilişki, `relationsByName: true` ile | görünen ad (`"Satış"`) — display ya da benzersiz alan | `{ id, <displayAlanı> }` | `null` |
+
+Üç tuzak aynı tablodan okunur: (1) yazma ve okuma şekli **farklıdır**, ama 2026-09-09'dan beri
+okunan şekil geri yazılabilir; (2) `text` kolonda JSON'u okurken **ikinci kez** `JSON.parse` etme;
+(3) `row_get` ilişki alanlarını `row_list`'ten farklı olarak **düz FK** döner — nesne bekleyen kod
+orada `undefined` alır.
 - **`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:
@@ -363,18 +662,411 @@ bilmezsen "kayıt bozulmuş" sanırsın.
   > 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.
+- **Varsayılan alanın adı `default-value`, `static` DEĞİL.** `defaultValueType` üç değer alır:
+  `none` · `default-value` (sabit değer, `defaultValue` ile birlikte) · `sql-expression`.
+  `defaultValueType: "default-value"` **gerçekten DB varsayılanı kurar** — `ALTER TABLE … ADD
+  COLUMN … NOT NULL DEFAULT …` üretilir, dolu tabloda mevcut satırlar da o değerle dolar (ölçüm
+  2026-09-09: 3 satırlık tabloya tek çağrıda `NOT NULL DEFAULT 0` eklendi, üç satır da `0` oldu).
+  Eski "`static` sessizce `none`'a düşer" notu bir **yanlış anlaşılmaydı**: `static` diye bir değer
+  hiç olmadı, geçersiz belirteç sessizce `none`'a düşüyordu. 2026-09-09'dan beri geçersiz belirteç
+  **istek anında reddedilir** ve kabul edilen değerleri sayar:
+  `Please use a valid value for 'DefaultValueType': none, default-value, sql-expression. Received: 'static'.`
+  Aynı düzeltme **her** enum alanı için geçerlidir — yanlış yazılmış bir `operator`, `module` ya da
+  `commonType` artık sessizce ilk üyeye düşmez.
+- **Dolu tabloya zorunlu (NOT NULL) alan eklemenin iki yolu var**, ikisi de ölçüldü:
+  1. Alana varsayılan ver (`defaultValueType: "default-value"` + `defaultValue`) → **tek çağrı**.
+  2. Önce `nullable: true` ekle → satırları `row_update` ile doldur → `entity_patch` ile
+     `/fields[slug=…]/nullable` `false` yap → **üç tur**.
+
+  Varsayılansız zorunlu alan doğrudan eklenirse istek artık bu iki yolu adıyla söyleyen bir hata
+  döner (eskiden ham migration hatası geliyordu: `column "…" contains null values`).
+- **`row_list.filters` desteklenir.** Tekil filtre `{ field, operator, value, filterType:'single' }`,
+  grup filtre `{ filterType:'group', conditionType, children:[...] }` biçimindedir. Tekil filtrede
+  `field`, grupta `children` zorunludur; `in`/`notin` operatörleri liste değer ister. Eksik/yanlış
+  şekiller SQL derleyicisine düşmeden alanı ve beklenen şekli söyleyen doğrulama hatası döner.
+- **`row_create` identity Guid birincil anahtara verdiğin `id`'yi artık korur** — 2026-09-04
+  öncesinde platform değeri sessizce kendi ürettiğiyle değiştiriyordu (`EntityRuntimeValidator`);
+  şimdi değer verilmişse o yazılır, verilmemişse üretilir. Seed ve veri taşımada "gönderilen id ile
+  oluşan id farklı" sınıfı buradan geliyordu. `users` tablosunun kendi kısıtları ayrıdır; oradaki
+  eşlemeyi e-posta üzerinden kurmak en güvenli yoldur.
 - Silmeden önce `entity_dependencies` / `dependency_graph`.
 
+## Toplu ve türetilmiş satır
+
+`row_*` bir **veritabanı yönetim yüzeyidir**: satırı gövdede taşır, iş kurallarını koşturur,
+anahtarı üretir. **Var olan satır kümesinden TÜRETİLEN** bir küme onun işi değildir — durum
+geçmişi, hareket/log tablosu, junction dolgusu, backfill. İki koşu bunu elle yazdı (2026-09-05:
+802 satır, 2026-09-06: 552 satır); ikincisinde koşunun 65 dakikasının **~21'i** tek bu faza gitti,
+gateway süresi ise aynı fazda toplam 7.9 sn'ydi — maliyetin tamamı gövde yazmaktı.
+
+Türetilmiş satırın yolu **ham SQL**'dir: `INSERT … SELECT` kaydedilir ve query kaynaklı bir uçtan
+çalıştırılır. `candidate_id` gibi bağlar `SELECT`'in içinde kalır, hiçbir id yanıttan yanıta
+taşınmaz.
+
+| Satırlar nereden geliyor | Yol |
+|---|---|
+| Dışarıdan: kullanıcı verisi, içe aktarma, sabit liste | `row_create` / `row_update` |
+| Var olan satırlardan türetiliyor: geçmiş, hareket, junction, backfill | kayıtlı `INSERT … SELECT` + `source: 'query'` uç |
+
+> **Ham SQL UYGULAMA katmanını atlar, VERİTABANI katmanını atlamaz.**
+> Koşmayan: automation'lar (satır olayı hiç doğmaz), `EntityRuntimeValidator`'ın tip ayrıştırma
+> ve identity anahtar üretimi, incremental kod üretimi, çoklu dilli companion yazımı, audit izi.
+> **Koşan:** tablonun bütün veritabanı kısıtları — NOT NULL, FK, UNIQUE ve **enum'un CHECK
+> constraint'i**. Ölçüldü: `source` alanına listede olmayan bir değer yazmak
+> `23514 … violates check constraint "check_<alan id'si>"` veriyor (HTTP 500). Kısıt adı alanın
+> **id'sini** taşır (tireler alt çizgi olur), kolon adını değil — 23514 alırken suçluyu böyle
+> bulursun. Yani enum'a çöp yazamazsın, ama iş kuralın automation'daysa o çalışmaz:
+> seed/backfill için istediğin tam olarak budur, **iş kuralı çalışması gereken satırı bu yoldan
+> yazma.**
+
+### Reçete (uçtan uca ölçüldü, 2026-09-07)
+
+```jsonc
+// 1) sorguyu KAYDET — query_create
+{ "name": "Aday Geçmişi Dolgusu", "slug": "seed_candidate_history",
+  "datasourceId": "<built-in datasource id>",
+  "rawQuery": "INSERT INTO status_history (id, candidate_id, status, occurred_at) SELECT gen_random_uuid(), c.id, c.status, c.applied_at FROM candidate c" }
+
+// 2) ucu aç — microservice_create (MS-002 warn'ı bekleniyor: ham SQL bilinçli tercih)
+{ "name": "Aday Geçmişi Dolgusu", "slug": "seed-candidate-history",
+  "description": "Var olan adaylardan durum geçmişi satırlarını üretir (tek seferlik dolgu).",
+  "type": "rest-api", "httpMethod": "post", "url": "seed-candidate-history",
+  "source": "query", "queryId": "<query id>" }
+
+// 3) çalıştır — microservice_execute { method: 'POST' } → HTTP 204, GÖVDE YOK
+// 4) doğrula — row_list('<hedef entity>') → satırlar burada; sayım tek doğrulama yolu
+```
+
+### Ölçülmüş sözleşme
+
+- **Tablo adı = entity slug'ı, kolon adı = alan slug'ı.** İlişki alanının kolonu da kendi
+  slug'ıdır (`src_id`), ayrı bir FK adı türetilmez. Şema öneki YAZMA: bağlantı zaten ortamın
+  şemasına bağlıdır.
+- **Anahtar sözleşmesi anahtar TİPİNE göre TERSİNE döner** — ikisi de `identity: true` +
+  `generationType: 0` olduğu hâlde:
+
+  | Anahtar | Ham SQL'de | Yanlışta ne olur |
+  |---|---|---|
+  | `UUID` / `guid` | anahtarı **SEN ver** (`gen_random_uuid()`) | `23502: null value in column "id" … violates not-null constraint` (HTTP 500) |
+  | `INT2/INT4/INT8` / `number` | anahtarı **HİÇ VERME** | `428C9: cannot insert a non-DEFAULT value into column "id" … GENERATED ALWAYS` (HTTP 500) |
+
+  Sebebi: GUID anahtarı **uygulama** üretiyor (`EntityRuntimeValidator`, `Guid.CreateVersion7()`),
+  kolonun veritabanı varsayılanı yok; INT anahtar ise Postgres `GENERATED ALWAYS` identity'sidir.
+  Alan tanımındaki `specifications.hasAutoData: true` bir **Studio ipucudur, DB varsayılanı
+  değildir** — ham SQL'de sana anahtarı üretmez.
+- **`gen_random_uuid()` v4 üretir**, platformun kendi anahtarları v7'dir (zaman sıralı). Aynı
+  tabloda iki sürüm karışır; anahtara göre sıralayan bir ekranın varsa sıralamayı zaman
+  kolonundan yap.
+- **`query_preview` yazan sorguyu çalıştırır ve GERİ ALIR ve bunu SÖYLEMEZ.** Yanıt yalnız
+  `{ affectedRowCount, elapsedMilliseconds }` taşıyor; `affectedRowCount` gerçek sayıyı döndüğü
+  için başarı gibi görünüyor, tabloda satır kalmıyor. Kalıcılığın tek kanıtı sonradan çekilen
+  `row_list`'tir.
+- **`query_create` gövdeyi kaydetmeden önce bir kez koşturur ve geri alır** — yazan bir sorguyu
+  kaydetmek satır bırakmaz, ama SQL hatası kayıt anında patlar. Yazan sorgunun `returnScheme`'i
+  boş döner (yanıt şeması yalnız okuyan sorgudan üretilir).
+- **Uç `204` ve BOŞ gövde döner** — `affectedRowCount` bile gelmez. Kaç satır yazıldığını
+  `row_list` ile say.
+- `;` ile birden çok ifade ya da `RETURNING` içeren sorgu `multiple` tipine düşer ve okuma
+  yolundan koşar (kaynak: `PostgreSqlConnector.FindQueryType`); tek ifadeli sade `INSERT` için
+  tip `insert`'tür.
+- **`WITH … INSERT` (CTE önekli yazma) BUGÜN REDDEDİLİYOR.** Ölçüldü 2026-09-07: `query_create`
+  `500 "Please correct the query syntax."`, `query_preview` `400 "Please use a supported query
+  type."` veriyor. Sorgu Postgres'te geçerlidir; reddeden, platformun tip sınıflandırıcısıdır
+  (`FindMainCommand` `WITH`i çözemeyip `NotSupportedQueryTypeException` atıyor). Depo kodunda
+  `WITH` çözümü **var** (`bcf722d1`, 2026-09-04) ama canlıda yok — `B-63`. **Bugünkü yazım:**
+  CTE yerine `JOIN (VALUES …) AS x(kolon, kolon)` kullan ve ifade `INSERT` ile başlasın.
+
+### Merdiven kalıbı: aşama geçmişi (S-4'ün tam şekli)
+
+Her adayın **bulunduğu aşamaya kadarki** geçişlerini üretir. 300 adaydan **579 satır** tek çağrıda
+yazıldı (ölçüldü 2026-09-07); huni piramidi 210 → 135 → 90 → 60 → 39 → 24 → 12 → 6 → 3, FK'sız
+satır 0, `applied_at`'ten önceye düşen satır 0.
+
+```sql
+INSERT INTO candidate_status_history (id, candidate_id, from_status, to_status, occurred_at)
+SELECT gen_random_uuid(), c.id, p.stage, n.stage,
+       c.applied_at + (n.pos - 1) * interval '3 days'
+FROM candidate c
+JOIN (VALUES (1,'Applied'),(2,'Screening'),(3,'Interview'),(4,'Offer'),(5,'Hired'))
+     AS cur(pos, stage) ON cur.stage = c.status          -- adayın bugünkü aşaması
+JOIN (VALUES (1,'Applied'),(2,'Screening'),(3,'Interview'),(4,'Offer'),(5,'Hired'))
+     AS n(pos, stage) ON n.pos > 1 AND n.pos <= cur.pos  -- ona kadarki her aşama
+JOIN (VALUES (1,'Applied'),(2,'Screening'),(3,'Interview'),(4,'Offer'),(5,'Hired'))
+     AS p(pos, stage) ON p.pos = n.pos - 1               -- bir önceki aşama
+```
+
+Merdiven listesi CTE olamadığı için üç kez tekrarlanır (yukarıdaki `WITH` maddesi). Zaman damgası
+`applied_at`'ten türetildiği için geçmiş **tarihseldir** — `UtcNow()` tuzağı (`AUT-003`) bu yolda
+hiç doğmaz, çünkü automation yoktur.
+
+Toplu **güncelleme** de aynı yola aittir: var olan satırlardan hesaplanan bir damga/toplam için
+`UPDATE … FROM` yaz, satırları `row_update`'in gövdesinde taşıma.
+
+## İçe aktarma — dosyayı gövdede taşıma
+
+Excel/CSV/JSON'dan gelen bir tabloyu `row_create` gövdesiyle satır satır yazmayın. 300 satırlık bir
+listeyi elle taşımak iki koşunun en pahalı kalemiydi; dosyanın kendisi zaten elinizde.
+
+**Hangi yol?** Tablo ZATEN VARSA ve satır sayısı 5.000'in altındaysa `row_create { path }`
+yeter — tek adım, şema kurmaz, kuru koşu yapmaz. Şema kurmak, sütun tipini tartışmak, ilişki
+adaylarını tespit etmek ya da hepsi-ya-hiç garantisi gerekiyorsa `import_*` zinciri gerekir:
+kuru koşusu vardır, hataları satır satır listeler ve sınırlı kapsamla geri alınabilir (§4).
+
+Zincir dört çağrıdır ve **hiçbiri satırı gövdede taşımaz**:
+
+```
+import_analyze { datasourceId, path }        → sayfalar, sütunlar, çıkarılan tipler, ilk satırlar
+import_plan    { datasourceId, fileId, tables } → planId + KURU KOŞU sayıları ve satır hataları
+import_run     { datasourceId, planId }      → jobId (202), iş arka planda
+import_status  { jobId }                     → validating → writing → completed + sonuç
+```
+
+`path` yerine `fileId` de verilebilir (dosya `file_upload` ile önceden yüklendiyse).
+
+### 1. Analiz — hiçbir şey yazılmaz
+
+Tipi, başlık satırını ve yerel ayarı görmeden plan gövdesi yazmayın. Yerel ayar sonucun
+kendisidir: `tr-TR` profilinde `15.03.2024` tarih ve `42.500,00` ondalık; `en-US` profilinde
+ikisi de **metin** olur. Yanıttaki `unconvertible` sıfır değilse önce `locale`'i sorgulayın,
+sonra sütun tipini.
+
+`summary` sayfa/satır/aday/uyarı sayısını, `note` ilişki adaylarını özetler.
+
+**`unique` bayrağı bir gözlemdir, kısıt değil.** "Bu dosyadaki bütün değerler farklıydı" demektir;
+30 satırlık bir örnekte maaş ya da ad sütunu da benzersiz çıkar. Plan gövdesinde `field.unique`
+yalnız **anahtar sütun** için `true` verilir (`flags` içinde `key` olan); her benzersiz sütunu
+unique kurmak tabloyu tek dosyaya kilitler ve aynı zammı iki kişiye veren bir sonraki dosya
+`unique` hatasıyla düşer.
+
+### 1a. JSON dosyası — kök dört biçimden biri
+
+`.json` de okunur ve aynı zincirden geçer. Kökün şekli sayfaların nasıl çıkacağını belirler:
+
+| Kök | Ne olur |
+|---|---|
+| Nesne dizisi `[{...}, {...}]` | Tek sayfa; sayfa adı dosya adıdır, başlık satırı anahtarların birleşimidir (ilk görülme sırasına göre) |
+| Tek nesne `{ "ad": "Test" }` | Tek satırlık sayfa; mevcut bir tabloya tek kayıt eklemenin en kısa yolu |
+| HER özelliği nesne dizisi olan nesne `{ "iller": [...], "ilceler": [...] }` | Her özellik ayrı sayfa; sayfa adı özelliğin adıdır — çok tablolu planın JSON karşılığı budur. Bir özellik bile nesne dizisi değilse kök tek satır sayılır |
+| `{ "meta": {...}, "data": [...] }` | `row_export`'un ürettiği gövde; `data` tek sayfa olur, `meta` `_zeyrek` sayfasına düşer ve analizde atlanır |
+
+Boş nesne, skaler kök, sözdizimi ya da kodlama hatası gerekçeli `400 ImportFileUnreadableException`
+alır. Metin BOM'a, yoksa katı UTF-8'e, olmazsa windows-1254'e göre çözülür; `headerRow` yok sayılır.
+
+**JSON'da tip dosyadan gelir, yerel ayardan değil.** Sayı ve `true`/`false` doğrudan okunur;
+`locale` yalnız metin olarak yazılmış tarih ve sayıları çözmek için kalır. Eksik anahtar boş
+hücredir. İç içe nesne sıkıştırılmış JSON metnine düşer. Skaler dizi `"; "` ile birleşir —
+`multi-value` adayı bu sayede JSON'da da çıkar, ayracı `"; "` verin.
+
+### 1b. İlişki adayları — tekrar eden sütunlar
+
+Analiz her sayfa için `relationCandidates` döner. Bunlar **öneridir**: seçimi `import_plan`
+gövdesindeki `columns[].relation` yapar. Aday yoksa sütun metin kalır ve hiçbir tablo açılmaz;
+`recommended` değeri `text` olan bir aday da (bkz. `manual`) siz seçmedikçe hiçbir şey açmaz.
+
+| `kind` | Ne gördü | Seçenekler | Ne zaman hangisi |
+|---|---|---|---|
+| `category` | Az sayıda değer kendini tekrar ediyor | `relation-existing` · `relation-new` · `select` · `text` | `target.existingEntityId` doluysa **önce onu dene** (`relation-existing`); yoksa 20'den az değer için `select`, üstü için `relation-new` |
+| `multi-value` | Bir hücrede ayraçla ayrılmış liste | `multi-relation-new` · `multi-relation-existing` · `multi-select` · `text` | Ayracı `delimiter` ile geçir. `multi-relation-new` ayrı bir tablo, ana tabloda bir m2m alanı ve junction tablosunu kurar; 20'den az değer için `multi-select` daha ucuzdur. **MEVCUT tabloya** `many: true` yazılıyorsa m2m alanı tabloda zaten olmalı — yoksa plan `ImportPlanStale` ile düşer |
+| `hierarchy` | İki sütun arasında üst/alt bağımlılığı (`ilçe → il`) | `hierarchy-two-tables` · `hierarchy-parent-only` · `text` | `hierarchy-two-tables` varsayılan; `parentColumnIndex` ve `parentTable` ALT sütunun `relation`'ına konur |
+| `cross-sheet` | Değerler başka bir sayfanın benzersiz sütununda | `relation-sheet` · `text` | O sayfayı da `tables`'a ekleyin; `target.sheetKey` hangi sayfa olduğunu söyler |
+| `manual` | Hiçbir şey tekrar etmiyor — sütun serbest metinden ayırt edilemiyor | `relation-existing` · `relation-new` · `text` | Değerler mevcut bir tabloyla örtüşüyorsa önerisi `relation-existing` olur (personel dosyasındaki `İl` sütunu, satır başına benzersiz olsa bile `İller` tablosuna bağlanır); örtüşme yoksa öneri `text`'tir ve **tablo açmak insan kararıdır**. Ortalama 40 karakterden uzun metin hiç önerilmez |
+
+**Platform tablosunu önce dene.** `roles` (ad) ve `users` (e-posta) projede zaten vardır; aday
+onlarla eşleşiyorsa yeni tablo açmak yerine `relation-existing` seçin — yoksa aynı kavramın iki
+tablosu olur.
+
+**`fdViolations > 0` ise bağımlılık yaklaşıktır.** Aday yine gelir ama kaç satırın kuralı bozduğunu
+söyler; `unmatched: 'error'` ile koşun ve düşen satırları rapor dosyasından okuyun.
+
+**`parentCandidates` — her sütun bir üst sütunun altına bağlanabilir.** Aday, `column` ·
+`distinctCount` · `nameViolations` üçlüsüyle gelir. Ad tekrarı bağlanmaya engel değildir:
+bir alt kaydın kimliği adı değil, **üstüyle birlikte adıdır**. Türkiye verisinde "Merkez" ilçesi
+onlarca ilde, "Cumhuriyet" mahallesi onlarca ilçede geçer; `nameViolations` bunu sayar, seçim
+sizindir. Seçtiğinizde `parentColumnIndex` (ve yeni tablo açıyorsanız `parentTable`) o sütunun
+`relation`'ına yazılır — hiyerarşi adayıyla aynı gövde.
+
+### 1c. Hiyerarşi gövdesi — İl → İlçe → Mahalle
+
+Zincir ayrı bir kural değildir: her ardışık çift kendi `hierarchy` adayını üretir ve her biri
+**alt sütunun** `relation`'ına yazılır. Üst tablo ayrıca bir sütuna bağlanmaz.
+
+```json
+"columns": [
+  { "index": 0, "include": true,
+    "relation": { "newTable": { "name": "İller", "slug": "iller" }, "unmatched": "error" } },
+  { "index": 1, "include": true,
+    "relation": { "newTable": { "name": "İlçeler", "slug": "ilceler" },
+                  "parentColumnIndex": 0,
+                  "parentTable": { "name": "İller", "slug": "iller" },
+                  "unmatched": "error" } },
+  { "index": 2, "include": true,
+    "relation": { "newTable": { "name": "Mahalleler", "slug": "mahalleler" },
+                  "parentColumnIndex": 1,
+                  "parentTable": { "name": "İlçeler", "slug": "ilceler" },
+                  "unmatched": "error" } }
+]
+```
+
+Planın döndüğü `tables[].order` **backend planlayıcısından gelir** (FK topolojik sırası):
+`iller` → `ilceler` → `mahalleler` → ana tablo. Ajan sıralamaz, sıraya güvenir.
+
+Ana tabloda **ilişki yazdığınız her sütun için** bir ilişki alanı açılır: yukarıdaki gövde
+`il`, `ilce` ve `mahalle` için üç alan verir. Bir sütuna doğrudan bağlanmak istemiyorsanız
+`relation`'ını yazmayın, yalnız `parentColumnIndex` hedefi olarak bırakın; alt seviye yine
+kapsamlı çözülür.
+
+**Zincir kimlikle çözülür, adla değil.** Satır yazılırken en üstteki sütun kapsamsız, her alt
+seviye bir üstündeki çözülmüş id ile eşlenir; alt tablo satırları da üst zincirinin tamamıyla
+tekilleştirilir. Bu yüzden "Bolu/Merkez" ile "Çorum/Merkez" ayrı iki ilçe satırı olur.
+
+**Adaylar en yakın üstten başlar.** `import_analyze` zincirde üç çift döndürür (`il→ilçe`,
+`il→mahalle`, `ilçe→mahalle`) ve sıralamayı üst sütunun farklı değer sayısına göre azalan yapar;
+listedeki ilk aday `ilçe→mahalle` olur. Bir sütun yalnız **bir** ilişki taşıyabildiği için
+`il→mahalle`'yi de seçerseniz `ilçe→mahalle` ezilir ve zincir kopar.
+
+### 2. Plan — kuru koşu
+
+`import_plan` tek satır bile yazmadan tip dönüşümünü, zorunluluğu, benzersizliği ve ilişki
+çözümünü dener. Gövde analiz çıktısından kurulur:
+
+```json
+{
+  "datasourceId": "…",
+  "fileId": "…",
+  "locale": "tr-TR",
+  "errorPolicy": "skip-rows",
+  "tables": [
+    {
+      "sheetKey": "Personel",
+      "mode": "create",
+      "target": { "name": "Personel", "slug": "personel" },
+      "columns": [
+        { "index": 0, "field": { "slug": "sicil_no", "name": "Sicil No", "commonType": "number", "dbType": "INT8", "unique": true, "nullable": false } },
+        { "index": 1, "field": { "slug": "ad_soyad", "name": "Ad Soyad", "commonType": "text", "dbType": "VARCHAR", "display": true } }
+      ]
+    },
+    {
+      "sheetKey": "Departmanlar",
+      "mode": "upsert",
+      "target": { "entityId": "…" },
+      "keyField": "ad",
+      "emptyCellPolicy": "keep",
+      "columns": [{ "index": 0, "existingFieldSlug": "ad" }]
+    }
+  ]
+}
+```
+
+- `mode: create` → `target.name` + `target.slug` ve her sütunda `field`.
+- `mode: append | upsert | update` → `target.entityId` ve her sütunda `existingFieldSlug`.
+- `upsert`/`update` → `keyField` **zorunlu** ve benzersiz olmalı (unique alan, tek alanlı unique
+  index, `code` ya da `id`); değilse 422.
+- `emptyCellPolicy: keep` boş hücreyi yok sayar — mevcut değeri silmez ve "değişti" saymaz.
+
+> **Kuru koşu hatalarını düzeltmeden `import_run` çağırmayın.** `errorPolicy: 'skip-rows'`
+> hatalı satırı sessizce atlar; plandaki `errors` listesine bakmadan çalıştırırsanız eksik
+> tablonun farkına varmazsınız. Hata oranı %50'yi geçerse `import_run` `force: true` ister.
+
+### 3. Çalıştır ve izle
+
+`import_run` **202** döner, gateway beklemez. `import_status` `writing` durumunda
+`progress.written/total` verir ve `retryAfterSeconds: 5` ekler; `completed` olunca
+`result.tables[].inserted/updated/unchanged/skipped` ve `reportFileId` gelir. Atlanan satırların
+tam listesi o dosyadadır (`file_download`).
+
+İçe aktarma **development kararıdır**: `import_plan`, `import_run`, `import_undo` ve `import_cancel`
+production'da istek gitmeden reddedilir.
+
+Şemalar: `ngapps://schemas/ImportAnalysisDto`, `ngapps://schemas/ImportPlanDto`,
+`ngapps://schemas/DataJobDto`.
+
+### 4. Geçmiş, iptal ve geri alma
+
+- `import_history` en yeniden eskiye listeler; `kind: 'import'` planları da getirir.
+- `import_cancel` `pending`/`validating`'i hemen, `writing`'i parti sonunda durdurur; yazılanlar kalır,
+  geri alınamaz. İş önce biterse 409.
+- `import_undo` yalnız `undoAvailableUntil` dolu `completed` işte çalışır; 202 döner, bitmeden
+  tekrar çağrılmaz. Kapsam:
+  - açılan tablo, başka tablo bağlı değilse **bütün satırlarıyla** silinir;
+  - referans satırları silinir, güncellenen sütunlar önceki değerine döner;
+  - mevcut tabloya **eklenen** satırlar kalır (yalnız ekleme yapan işte pencere açılmaz);
+  - çakışma denetimi yoktur.
+
+## Dışa aktarma ve geri yükleme
+
+`row_export` bir tablonun satırlarını dosyaya yazar ve dosyayı **Sürücü'ye** koyar. Bağlama yalnız
+`fileId`, ad ve bayt sayısı döner — içerik hiç geçmez, okumak isterseniz `file_download`.
+
+```
+row_export { entityId, format: 'xlsx' | 'csv' | 'json', scope, reimportable? }
+  → { fileId, fileName, bytes }        ≤ 5.000 satır
+  → { jobId }                          üstü; import_status { jobId } ile izlenir,
+                                       biten işin dosyası result.reportFileId
+```
+
+Kapsam üç şekildedir: `{ kind: 'view', filters, sort }` (grid'in gördüğü küme),
+`{ kind: 'all' }`, `{ kind: 'selected', rowIds }` (en çok 1.000 id — üstü filtreyle).
+Sütunlar `columns: 'visible'` + `selectedFields` ile daraltılır. CSV UTF-8 BOM'ludur; ayraç ve
+ondalık projenin dilinden gelir (tr `;` · `1,5`, en `,` · `1.5`), şablonda `locale` ile seçilir.
+
+### Akış C — dışa aktar, düzenle, geri yükle
+
+Bir tabloyu toplu düzeltmenin yolu satır satır `row_update` değildir. `reimportable: true`
+dosyaya `id` sütununu ve `_zeyrek` meta sayfasını ekler; o iki şey olmadan geri yükleme hangi
+satırın hangisi olduğunu bilemez ve her satırı yeni kayıt sayar.
+
+```
+row_export { entityId, reimportable: true }   → fileId
+file_download { id: fileId, outPath }         → dosya diske iner
+<dosyayı düzenle>
+file_upload { path }                          → yeni fileId
+import_analyze { datasourceId, fileId }       → meta sayfa okunur, tablo tanınır
+import_plan { …, tables: [{ mode: 'upsert', keyField: 'id' }] }
+import_run  { planId }                        → 202, import_status ile izlenir
+```
+
+`keyField: 'id'` ile mod `upsert`: dosyadaki id eşleşen satır güncellenir, eşleşmeyen eklenir.
+`reimportable` ilişki sütunlarını ad+id olarak yazar, dolayısıyla adı elle değiştirseniz de id
+kazanır — ilişkiyi gerçekten değiştirmek istiyorsanız id sütununu düzenleyin.
+
+### Şablon — dosyanın şeklini önce görün
+
+`row_export { entityId, template: true, format?, locale? }` tablonun alanlarından **iki sentetik
+örnek satırlı** şablon üretir ve değiştirilmeden geri yüklenir: PK, sistem ve artan kod sütunu yok,
+`password` sıradan metin, ipucu veri alanında değil (xlsx başlık yorumu + `_zeyrek`, json `meta`).
+`inline: true` şekli yanıta da koyar: `sample.columns` (slug, başlık, tip, zorunlu, seçenekler),
+`sample.keyField`, `sample.data`. İlişki sütunu boş ve `manual`dır: hücreye hedefin `matchField`
+değerini yazın, şablon hedeften satır okumaz. `data` JSON biçimindedir (ondalık nokta, tarih
+`yyyy-MM-dd`); bu değerlerle CSV yazıyorsanız analiz ve planda `locale: 'en-US'` verin.
+`password` gibi gizli adlı sütunun örnek değeri gateway'de `***` maskelenir; kendi değerinizi
+yazın. Toplu yazımda satır satır `row_create` yerine:
+
+```
+row_export { entityId, template: true, inline: true }   → sample.columns, sample.data, sample.keyField
+<başlıkları aynen koruyarak CSV metni üret>
+file_upload { text, filename: '<slug>.csv' }           → fileId
+import_analyze { datasourceId, fileId, locale }         → sütun slug'ları = alan slug'ları
+import_plan { datasourceId, fileId, locale, tables: [{ mode: 'append' | 'upsert', keyField: sample.keyField, … }] }
+import_run { planId }                                    → 202, import_status ile izlenir
+```
+
 ## Büyük entity'lerde
 
 `entity_get view:'outline'` alan listesi; `view:'part', part:'fields[slug=email]'` tek alan;
 değişiklik `entity_patch`.
+
+## Sürüm ve 409 — `entity_patch` tam gövde YAZMAZ
+
+`entity_patch` okuduğu tanımın üstüne JSON Patch uygular ama geri **tam gövde göndermez**: op'lar
+platformun `PATCH /entities/{id}` ucuna `{ baseVersion, ops }` olarak gider ve yalnız değişen
+alanlar yazılır. Bir alan adı değişimi `fields` tablosunda **tek** UPDATE üretir (ölçüldü
+2026-09-08, `pg_stat_user_tables`).
+
+`baseVersion` okunan kaydın `version` alanıdır ve zorunludur (eksikse 422). Sen okuduktan sonra
+kayıt değiştiyse platform **409 `AggregateVersionConflictException`** döner ve HİÇBİR op uygulanmaz
+— `entity_get` ile yeniden okuyup patch'i güncel hâle göre kur, aynı op'ları eski sürümle tekrar
+gönderme.
+
+`version` bir **string**tir (mikrosaniye zaman damgası, `Number.MAX_SAFE_INTEGER`'ın üstünde):
+sayıya çevirirsen yuvarlanır ve her patch 409 döner. Yanıttaki `newVersion` bir sonraki patch'in
+`baseVersion`'ıdır.