@appaflytech/zeyrek-ai-mcp 0.0.6 → 0.0.7

package/dist/resources/guides/entity.md

@@ -433,10 +433,12 @@ 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` değil boş nesne `{}` döner** (ölçüm: İK koşusu D-8, 2026-09-01). JS'te
-  `{}` truthy'dir: `if (row.manager_id)` "yöneticisi var" der. Varlık kontrolünü
-  `row.manager_id?.id` üzerinden yap. (Backend'in `null` döndürmesi P0-6 olarak planlı; o gelene
-  dek bu şekil geçerlidir.)
+- **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
 
@@ -578,16 +580,55 @@ bilmezsen "kayıt bozulmuş" sanırsın.
 - `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"}`.
-- **Toplu yazımın (`rows[]`) id döndürmesine GÜVENME.** 2026-09-05'te uç `data: [{ "<pk slug>":
-  değer }, …]` döndürüyordu; 2026-09-07 ölçümünde iki ayrı entity'de **boş gövde** döndü (gateway
-  onu `{success: true}` diye gösterir) — satırlar yazıldı ama anahtarlar gelmedi. Fark `B-63`
-  olarak takipte. Yazdığın satırların anahtarları lazımsa yanıta bel bağlama, `row_list` çek ve
-  bu turu bütçene ekle. Daha iyisi: türetilmiş satırı bu id'lerle kurma — §"Toplu ve türetilmiş
-  satır"daki SQL yolunda id hiç dolaşmaz.
-- Yazdıktan sonra `row_list` ile geri oku; ilişki alanları `{ id, name }` nesnesi olarak döner.
-- **Boş to-one ilişki `null` döner**, boş nesne değil — `if (row.manager_id)` kontrolü doğru
-  çalışır (İK koşusu D-8; 2026-09-03 öncesinde `{}` dönüyordu ve JS'te truthy'ydi). Boş
-  many-to-many alan `[]` 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:
@@ -621,9 +662,24 @@ 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.
+- **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ış
@@ -746,6 +802,254 @@ 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;

package/dist/resources/guides/expressions.md

@@ -35,6 +35,7 @@ tetikleyen satır `row` / `previousRow` / `user`.
 | `Now(tz)` | Verilen saat diliminde şimdi, **`"yyyy-MM-ddTHH:mm:ss"` METİN olarak**. **JS motoru UTC'ye sabitlidir** (`opt.TimeZone = Utc`), yani `new Date()` her zaman UTC'dir — yerel gün/saat mantığı için bunu kullanın, offset'i koda gömmeyin | `Now('Europe/Istanbul')` → `"2026-08-18T19:11:10"` |
 | `Today(tz)` | O saat diliminde bugün, `"yyyy-MM-dd"` metni — gün sınırı filtreleri için en kısa yol | `Today('Europe/Istanbul') + 'T00:00:00'` |
 | `ToTimeZone(v, tz)` | Bir değeri (Date, DateTimeOffset ya da ISO metin) o saat dilimine çevirir, aynı metin biçiminde | `ToTimeZone(Steps.randevu.data.baslangic, 'Europe/Istanbul')` |
+| `Functions.<ad>(…)` | **YOK — sunucuda kullanıcı fonksiyonu yüklenmez** (2026-09-10). Gateway `WF-030` ile istek gitmeden bloklar; zorlanırsa Jint `Functions is not defined` fırlatır. Sunucuda paylaşılan hesap **`source:'workflow'` fonksiyondur** ve çıplak adla çağrılır (`sum(1, 2)`, `function_create source:'workflow'`) |
 
 > **Bu üçü METİN döner, Date DÖNMEZ** — bilerek. `UtcNow()` bir JS `Date` döndürür ve üzerinde
 > `getTime()`/`getUTCFullYear()` çalışır; ama Jint'in `DateTimeOffset` → `Date` çevriminde **saat
@@ -105,6 +106,7 @@ dalından devam eder.
 | `LocalStorage` · `Widget` · `params` | yerel veri · widget bağlamı · olay parametreleri |
 | `t(key)` | Çeviri anahtarını çözer: aktif dil → projenin varsayılan dili → anahtarın kendisi. Boş string de "eksik" sayılır. Sözlük `machine.context.state.translations`'tan gelir; dil `language-selector` ile değişince bir sonraki çağrı yeni dili görür. **Yalnız UI flow kodunda vardır** — backend ifadelerinde karşılığı `Loc()`'tur (`platform_guide('workflow')`) | `t('home.welcome')` |
 | `log(...)` | console (proxy'leri temizler) |
+| `Functions` | **Kullanıcı fonksiyonları** (`function_create`): `Functions.toplamHesapla(fiyat, adet)` — uygulama kapsamlılar her sayfada, sayfa kapsamlılar yalnız kendi sayfasında. **Yalnız tarayıcı**; sunucuda bu ad alanı yoktur (2026-09-10, `WF-030`) |
 
 > **`.map is not a function` bir dizi sözleşmesi sorunu DEĞİL, düşmüş bir adımdır.**
 > Ölçüldü 2026-09-05 (`f09-repro/probe`, yerel kurulum): başarılı bir microservice adımında
@@ -179,3 +181,4 @@ Karıştırma: `roles_csv` **UI/filtre** tarafının yoludur; backend middleware
 | `system.` / `file.` / `crypto.` / `convert.` | ✓ | — |
 | `cookie` | okunur sözlük (`cookie.X`) | `get/set/remove` fonksiyonları |
 | `await` | — (senkron ifade) | ✓ (`code` adımı) |
+| `Functions.<ad>()` (kullanıcı fonksiyonu) | — (sunucuda yok, `WF-030` block) | ✓ uygulama + o sayfanın sayfa fonksiyonları |