@appaflytech/zeyrek-ai-mcp 0.0.6 → 0.0.8

package/dist/resources/guides/microfunction.md

@@ -0,0 +1,166 @@
+# Microfunction Rehberi
+
+Microfunction, kullanıcının yazdığı **tek bir fonksiyonun** platformun dışında, kendi
+runtime'ında koşmasıdır: Node ya da Python kodu kaydedilir, yayınlanır, workflow adımı onu
+çağırır ve çıktısı sonraki adımlara akar. Platformun JavaScript ifade motoru (global function'lar,
+code step) sürecin İÇİNDE koşar; microfunction ise ayrı bir runtime'dadır — bu yüzden ağır iş,
+üçüncü parti kütüphane ve zaman aşımı riski taşıyan işler oraya taşınır.
+
+Kayıtlar **proje + environment** kapsamlıdır (`development` ile `production` ayrı kayıtlardır);
+`microfunction_list` bir uygulamaya değil projeye bakar. Süzme ve sayfalama uçta yapılır:
+`searchTerm` ad, slug ve açıklamada arar, `status` durum süzgecidir, `pageIndex`/`pageLength` sayfa
+verir (gateway kendi çağrısında 200 gönderir; platform varsayılanı 10'dur).
+
+## Ne zaman microfunction, ne zaman code step
+
+| İhtiyaç | Doğru yer |
+|---|---|
+| Birkaç satır dönüşüm, alan eşleme, koşul | `code` step / ifade (aynı süreç, en ucuz) |
+| İfadelerde çıplak adla çağrılacak yardımcı | global function (`global_function_create`, JS) |
+| Kütüphane gerektiren iş (kriptografi, PDF, görüntü, parse) | microfunction (zip kaynak) |
+| Python gereken iş | microfunction — platformun ifade motoru YALNIZ JavaScript'tir |
+| Uzun süren/CPU yiyen iş | microfunction (kendi bütçesi, API sürecini bloke etmez) |
+
+Global function'lar JS'tir ve Python fonksiyonlarına bağlanmaz; microfunction çağrısı yalnız
+workflow adımından (ve test için `microfunction_invoke`'tan) yapılır.
+
+## Çalışma zamanı sözleşmesi (protocol 1)
+
+Kullanıcı kodu **tek bir handler** dışa aktarır. Inline kaynakta dosya adı SABİTTİR: Node'da
+`function.js`, Python'da `function.py`; entrypoint `function.handler`'dır ve gönderilmez.
+
+```js
+// node — function.js
+exports.handler = async (args, context) => {
+  return { total: args.a + args.b, environment: context.environment }
+}
+```
+
+```python
+# python — function.py
+def handler(args, context):
+    return {"total": args["a"] + args["b"], "environment": context["environment"]}
+```
+
+- `args` — adımın `rule.expression`'ından üretilen argüman nesnesi. Fonksiyonun
+  `parameterDtoId`'si yoksa `{}` gelir.
+- `context` — **salt okunur anlık görüntü**. İçine yazmak hiçbir şeyi değiştirmez; akışa dönen
+  tek kanal fonksiyonun DÖNÜŞ DEĞERİdir.
+
+`context` şekli (ölçüldü, `MicrofunctionStep.BuildContext`):
+
+```jsonc
+{
+  "input": {},                    // akışın parameterDto girdisi
+  "variables": {},                // workflow değişkenleri (middleware'in kurduğu 'user' dahil)
+  "steps": { "<adım adı>": { "data": {}, "error": { "code": null, "message": null, "type": null } } },
+  "user": { "id": "…", "email": "…", "roles": [] },
+  "request": { "headers": {}, "queryString": {} },
+  "triggerSource": {},
+  "language": "tr",
+  "project": "<proje slug'ı>",
+  "environment": "development"
+}
+```
+
+**`request` yalnız `headers` + `queryString` taşır** ve `authorization` · `cookie` ·
+`x-impersonated-user-id` başlıkları AYIKLANIR (ölçüldü 2026-09-10) — token'ı fonksiyona taşımaya
+çalışmayın, taşınmaz. Çerez okuma yolu yoktur.
+
+Yanıt zarfını shim üretir; `microfunction_invoke` bunu olduğu gibi döner:
+
+```jsonc
+{ "protocol": 1, "ok": true, "output": { "total": 3 }, "error": null, "logs": [], "durationMs": 12 }
+```
+
+- `ok: false` ⇒ `error: { type, message, stack }` ve adım **fail dalına** düşer.
+- `logs` yalnız `preview: true` çağrılarında dolar (`console.log` / `print` yakalanır). Normal
+  koşumda log toplanmaz — hata ayıklarken `microfunction_invoke(preview: true)` kullanın.
+- İstek gövdesi (args + context) 5 MB'ı aşarsa adım `MicrofunctionPayloadTooLargeException` ile
+  fail dalına düşer: bütün tabloyu fonksiyona geçirmeyin, işi fonksiyona taşıyacak kadarını geçirin.
+
+## Yaşam döngüsü: kayıt yayınlanmadan ÇALIŞMAZ
+
+```
+draft ──publish──▶ publishing ──▶ published ──update──▶ published + hasUnpublishedChanges
+                        └────────▶ publish-failed (publishError)
+```
+
+1. `microfunction_create` kaydı **draft** açar. `publish: true` verirseniz aynı çağrıda yayın istenir.
+2. Yayın **asenkrondur**: çağrı `publishing` döner, kuyruk paketi runtime'a kurar ve bir `probe`
+   çağrısıyla duman testi yapar. Sözdizimi/import hatası **yayın anında** `publish-failed` olur —
+   koşumda değil. Durumu `microfunction_get` ile birkaç saniye arayla okuyun.
+3. Yayındaki kaydı `microfunction_update` ile değiştirirseniz runtime **ESKİ sürümü koşmaya
+   devam eder**: `hasUnpublishedChanges: true` olur (`revision` ≠ `publishedRevision`). Yeni kodu
+   canlıya almak için `microfunction_publish`.
+4. `microfunction_delete` runtime'daki fonksiyonu da kaldırır; bir workflow adımı kaydı
+   kullanıyorsa 400 ile reddedilir.
+
+## Workflow adımı (WF-MF-001)
+
+Adım tipi `microfunction`; `workflow`, `automation` ve `middleware` akışlarının hepsinde
+kullanılabilir. Kuralı iki alan taşır:
+
+```jsonc
+{
+  "id": "<GUID>",
+  "name": "toplam",
+  "type": "microfunction",
+  "description": "İki sayıyı microfunction'da toplar.",
+  "rule": {
+    "microfunctionId": "<published kaydın id'si>",
+    "expression": "({ a: input.a, b: input.b })"
+  },
+  "branches": [
+    { "id": "<GUID>", "name": "success", "type": "success", "nextStepId": "<sonraki adım>" },
+    { "id": "<GUID>", "name": "fail", "type": "fail", "nextStepId": "<hata adımı>" }
+  ]
+}
+```
+
+- `microfunctionId` **zorunludur** ve gateway kaydı çağrıdan önce okur: durum `published` değilse
+  (ya da kayıt o ortamda yoksa) istek platforma GÖNDERİLMEZ. Adım taslak bir fonksiyona bağlıysa
+  akış kaydedilir, koşar ve sessizce fail dalına düşer (`MicrofunctionNotPublishedException`) —
+  ön-denetimin varlık sebebi budur.
+- `expression` argüman nesnesini üreten JavaScript ifadesidir; şemayı `microfunction_get`
+  çıktısındaki `parameterScheme` verir. Fonksiyonun parametre DTO'su varken ifade boşsa gateway
+  uyarır (fonksiyon `args` içinde hiçbir alan göremez).
+- Çıktı sonraki adımlara `Steps.<adım adı>.data` ile akar; şemasını `returnDtoId` belirler.
+- Adım **senkrondur**: akış fonksiyon dönene kadar bekler. Zaman aşımı fonksiyonun
+  `timeoutSeconds` bütçesidir, aşılırsa fail dalı.
+- `workflow_preview` adımı GERÇEK runtime'da koşturur; preview'ın rollback garantisi fonksiyonun
+  dış dünyada yaptığı işi geri ALMAZ.
+
+Tam gövde örneği: `ngapps://examples/microfunction-node-sum`.
+
+## Built-In ve AWS Lambda farkı
+
+| | `built-in` | `aws-lambda` |
+|---|---|---|
+| Nerede koşar | Platformun kendi Fission kümesi | Müşterinin AWS hesabı |
+| Runtime kaydı | YOK — `runtimeId` verilmez | `microfunction_runtime_create` ile zorunlu |
+| Zaman aşımı tavanı | 300 s | 900 s |
+| `memoryMb` | kaydedilir, küme limiti geçerlidir | gerçekten uygulanır |
+| Ölçüm alanları | `billedDurationMs`/`memoryUsedMb` boş | Lambda raporundan dolar |
+
+`azure-functions` enum'da tanımlıdır ama v1'de reddedilir (Faz 2). Lambda hesabı kimlik
+bilgilerini düz metin tutar (Datasource emsali) ve DTO'da maskeli döner — dar yetkili bir IAM
+kullanıcısı verin, `roleArn` fonksiyonun koşacağı execution rolüdür ve **zorunludur** —
+deseni tutmayan hesap gateway'de durur (MFR-001, block). Kaydettikten sonra
+`microfunction_runtime_test_connection` ile doğrulayın.
+
+## Sınırlar (v1)
+
+- **Bağımlılık build'i yok:** inline kod yalnız standart kütüphanedir; bağımlılık zip içinde gelir.
+- **MCP'den zip yükleme ve indirme yok** (`sourceKind: 'archive'` kaydı açılabilir, dosya
+  Studio'dan yüklenir) — Faz 2. Yüklenmiş zip platform ucunda okunabilir durumdadır
+  (`GET /{proje}/microfunctions/{id}/archive`, `application/zip`) ve Studio inspector'ında bir
+  indirme düğmesi taşır.
+- `timeoutSeconds` ve `memoryMb` komutta non-nullable int'tir: **göndermezseniz 0 gider ve platform
+  422 döner.** Gateway değer uydurmaz, eksikliği çağrıdan önce söyler (MF-001, block; ürün
+  varsayılanları 30 / 256). Aynı kural provider ↔ `runtimeId` eşleşmesini, inline kaynakta `code`
+  zorunluluğunu ve env anahtarlarını da çağrıdan önce denetler.
+- Env değişkenleri düz metin saklanır; anahtar `^[A-Z_][A-Z0-9_]*$`, toplam ≤ 4 KB. Sır yönetimi
+  için kullanmayın.
+- Asenkron (fire-and-forget) çağrı, preview ekranı, microservice'in doğrudan microfunction kaynağı
+  olması ve metering Faz 2'dedir.

package/dist/resources/guides/microservice.md

@@ -77,6 +77,12 @@ servis formunda görünür ve `microservice_get` outline görünümünde geri ok
      > (`'all'`) ve SQL'de ona bakan bir dal. Aynı davranış workflow query adımında da geçerli;
      > oradaki anlatım `platform_guide('workflow')` "Query adımı" bölümünde.
      >
+     > **`(@p = '' OR kolon = @p)` YAZMA** — "filtre boşsa hepsini getir" dalı hiçbir zaman
+     > çalışmaz, çünkü boş değer `NULL` bağlanır. Değeri form bileşeninden gelen parametrede
+     > dokunulmamış alanın `null` ya da `''` göndermesi fark etmez; ikisi de `NULL` olur
+     > (2026-09-15 bulgusu: pano 0 kart, `COALESCE`/`IS NULL` ile 141). Gateway bu kalıbı
+     > `query_create`/`query_update`/`query_preview`'da **QRY-007** (warn) ile işaretler.
+     >
      > **KAPSAM UYARISI: query kaynaklı ucun parametreleri ÇAĞRIDAN gelir.** Middleware'in
      > kurduğu `user` bu yola girmez — kimlik/tenant kapsamını gövdeye yazan bir uç
      > sahtelenebilir (ölçüldü 2026-09-07). Kapsam sunucuda zorlanacaksa sorguyu bir workflow
@@ -116,6 +122,11 @@ servis formunda görünür ve `microservice_get` outline görünümünde geri ok
 5. **Doğrulama akışı:** `microservice_preview` (kaydetmeden) → kaydet → `microservice_execute`
    (gerçek runtime yolu) → sonuç beklenmedikse **aynı parametrelerle `microservice_debug`** —
    adım adım executionItems ağacı döner.
+   Çağrı parametrelerini (sorgu parametresi, filtre değeri) üst düzey `parameters: { ad: değer }`
+   ile ver; gateway GET'te query-string'e, POST/PUT'ta gövdeye koyar. Değeri NULL bağlanan query
+   parametresini debug yanıtı `unboundParameters` ile söyler — ağaçta o satırın `value` anahtarı
+   görünmez. Tool'un tanımadığı bir üst düzey argüman artık reddedilir (GW-005); 2026-09-15'e
+   kadar `parameters` hata vermeden atılıyordu ve dört farklı filtre aynı gövdeyi döndürdü (G-13).
 
 ## Yanıt sözleşmesi (DTO) uca DEĞİL workflow'a bağlanır (MS-018, block)
 
@@ -159,8 +170,9 @@ DTO'dan süzülmez (WF-026 — `platform_guide('workflow')` §Hata yolu). Sözle
 ## Asgari doğru table-source microservice (platformda doğrulanmış kurallar)
 
 - `operation` enum'u **tam olarak** şudur ([MicroserviceTableOperation](../../../../zeyrek-backend/src/NgApps.Domain/Contexts/Studio/Microservices/MicroserviceTableOperation.cs)):
-  `get · create · update · delete · upsert · count`. **`list` yoktur** — liste için
-  `operation: 'get'` + `isSingle: false`, tek kayıt için `isSingle: true`.
+  `get · create · update · delete · upsert · count · bulk-create · bulk-update · bulk-delete`.
+  **`list` yoktur** — liste için `operation: 'get'` + `isSingle: false`, tek kayıt için
+  `isSingle: true`.
 - **`upsert` vardır ve tercih edilmelidir.** Aynı formun hem yeni kayıt hem düzenleme
   yapmasını iki ayrı uç + akışta condition dallanmasıyla kurmayın: tek `operation: 'upsert'`
   ucu yeterlidir. Aynı işlem workflow **table step**'inde de desteklenir
@@ -174,9 +186,42 @@ DTO'dan süzülmez (WF-026 — `platform_guide('workflow')` §Hata yolu). Sözle
 
 > **Upsert'te üretilen alan tuzağı.** `operation: 'upsert'` UPDATE yolunda da alan ifadelerini
 > yeniden değerlendirir; sicil/kod gibi üretilen bir değeri `source: 'expression'` ile yazarsan
-> güncellemede **sessizce değişir** (İK koşusu M-3: EMP-0005 → EMP-0006). Alan bazlı
-> `writeOn: create | update | always` platformda **yok**; o gelene kadar oluşturma ve güncelleme
-> için iki ayrı uç kurun. Gateway **MS-016** ile uyarır.
+> güncellemede **sessizce değişir** (İK koşusu M-3: EMP-0005 → EMP-0006). Çözüm alan bazlı
+> **`writeOn: create | update | always`**'dir (varsayılan `always`) ve 2026-09-04'ten beri
+> platformdadır: üretilen alana `writeOn: 'create'` verirsen upsert'in UPDATE dalı o alanı satıra
+> hiç koymaz (`ToRow(entityDto, writeOn)` iki satırı ayrı kurar). `writeOn` YALNIZ
+> `operation: 'upsert'` ucunda anlamlıdır — başka operasyonda `always` dışında bir değer
+> **MS-017** ile reddedilir. Gateway **MS-016** ile uyarır; alan `writeOn: 'create'` taşıyorsa
+> susar. **`writeOn` bir "kısmi güncelleme" bayrağı DEĞİLDİR** — hangi DALIN yazacağını söyler,
+> "gövdede gelmeyen alanı atla" demez (aşağıdaki §Güncelleme sözleşmesi).
+- **Toplu yazma için `bulk-create` / `bulk-update` / `bulk-delete` vardır.** Aynı tabloya N satır
+  yazmak için akışta döngü kurmayın: bu üç uç gövdedeki **JSON diziyi** tek çağrıda işler
+  ([TableMicroserviceExecutor](../../../../zeyrek-backend/src/NgApps.Domain/Contexts/Studio/Microservices/Executors/TableMicroserviceExecutor.cs)).
+  Kurallar:
+  - Gövde bir **dizi** olur; her eleman bir satırdır. `bulk-delete` gövdesinde yalnız birincil
+    anahtar alanı aranır ve tek bir `IN` filtresine çevrilir.
+  - `filters` **kullanılmaz** — satırlar ve anahtarlar gövdeden okunur.
+  - Tek istekte en fazla **1000 satır** (`EntityConstants.BulkRowLimit`); aşılırsa
+    `BulkRowLimitException` (422).
+  - Parti **hep-ya-hiç**tir: bir satır doğrulamadan geçmezse `BulkRowFailedException` hangi
+    satırın (index) patladığını söyler ve hiçbir satır yazılmaz.
+  - **Dosya alanı olan tablolarda `bulk-create`/`bulk-update` da desteklenir** — her satırın
+    dosya (ve çoka-çok dosya) alanı, tekil `create`/`update` ile **aynı format** üzerinden
+    (`{ type, fileName, value, clone, override, id }`) satır satır `fileService`'e gönderilir;
+    artık dosya alanı yüzünden 422 dönmez. Aynı entegrasyon workflow **table step**'inde de
+    vardır (satır dizisindeki dosya değeri de aynı formatı izler).
+  - **Bulk upsert yoktur.**
+  - `bulk-update` gövdesinde birincil anahtar **bulunur ve zorunludur** — tekil `update`'in
+    aksine satırı belirleyen filtre değil, gövdedeki anahtardır. `UpdateRowsAsync` bu anahtarı
+    `SET` listesinden dışlayıp `WHERE`'e taşır, bu yüzden alan listesinde görünmesi doğrudur ve
+    GENERATED ALWAYS koruması onu es geçer.
+  - Workflow **table step**'inde de aynı üç işlem vardır; orada satır dizisi adımın `expression`
+    alanından (JS) gelir, gövdeden değil. **Ancak studio'nun workflow table formunda bu
+    `expression` alanı için editör henüz yoktur** — akış adımında bulk seçilirse satır dizisi
+    girilemez ve adım `MissingParameterException` ile düşer. v1'de bulk yalnız microservice
+    ucundan kullanılır.
+  - Adımda tanımlı ama değeri boş bırakılan alanlar gövdeden/expression'dan gelen veriyi
+    **ezmez**; yalnız değeri dolu olan sabitler her satıra uygulanır.
 - **`count` vardır** — kayıt sayısı için tüm satırları çekip uzunluğuna bakmayın; panel/KPI
   sayaçlarının doğru şekli budur.
 - Gövde kökünde **`entityId` zorunlu**. (Eski "kökte datasourceId zorunlu" bilgisi yanlıştı —
@@ -188,9 +233,12 @@ DTO'dan süzülmez (WF-026 — `platform_guide('workflow')` §Hata yolu). Sözle
   `ArgumentNullException(key)`, farklı alias verilirse "missing FROM-clause entry" gelir.
 - `sort` ve `limit` **her zaman** verilir (MS-008, block) — aşağıya bak.
 - Filtrelerde `value` bir **JavaScript ifadesidir** — sabit metin tırnak içinde
-  (`"'ACTIVE'"`), dinamik değer ifade olarak (`"input.status"`).
+  (`"'ACTIVE'"`), dinamik değer ifade olarak (`"input.status"`). **İki operatör bunun dışındadır:**
+  `isnull` ve `isnotnull` değer taşımaz — `value` verilmez, `source` da zorunlu değildir; verirsen
+  platform yok sayar, doğrulama da değer beklemez.
 - **Operatör sözlüğü kapalıdır:** `eq · neq · lt · lte · gt · gte · contains · icontains ·
-  in · notin · startswith · endswith · istartswith · iendswith`. **`like` YOKTUR** — metin
+  in · notin · startswith · endswith · istartswith · iendswith · isnull · isnotnull`.
+  **`like` YOKTUR** — metin
   araması `contains`/`icontains` iledir. Kritik tuzak: platform bilinmeyen operatörü 400 ile
   reddetmez, **sessizce `eq`'e düşürür** (enum çözümlemesi unknown'da default'a düşer) — uç
   testten geçer ama arama hiçbir şey döndürmez. Gateway MS-012/WF-015 bunu istek gitmeden keser.
@@ -230,6 +278,61 @@ DTO'dan süzülmez (WF-026 — `platform_guide('workflow')` §Hata yolu). Sözle
 }
 ```
 
+## Güncelleme sözleşmesi: yazılan alan kümesi TANIMDAN gelir, gövdeden DEĞİL
+
+`create` / `update` / `upsert` ucunda **SET listesi `fields[]`'tir**; gövde yalnız o alanların
+DEĞERİNİ taşır. Studio'daki karşılığı "Oluşturulacak veya güncellenecek alanlar" ekranındaki
+**İstek alanları** listesidir: önce hangi alanların yazılacağı seçilir, gövde sonra gelir.
+İki yön de sessizdir, ikisi de 200 döner (ölçüm: 2026-09-15, `emrah/test`, `development`):
+
+| Tanımda (`fields[]`) | Gövdede | Sonuç |
+|---|---|---|
+| alan **var** | anahtar **yok** | kolona **NULL yazılır** — eski değer silinir |
+| alan **var** | anahtar var | değer yazılır |
+| alan **yok** | anahtar var | **yok sayılır** — o alan bu uçtan hiç değiştirilemez |
+
+Kod yolu: gövdede anahtar yoksa alan `null` değerini alır
+(`MicroserviceRuntimeCacheDto.SetSourceEntityFieldAndFilterValue`, `:145-148`), `ToRow` Default
+modlu **bütün** alanları sözlüğe basar (`:169-175`) ve `UpdateRowAsync` SET listesini doğrudan o
+sözlüğün anahtarlarından kurar (`PostgreSqlEntityConnector.cs:262-273`; null → `DBNull.Value`).
+"Yalnız gövdede gelen alanı yaz" diye bir bayrak **yoktur**.
+
+Ölçülen üç vaka (`pu_test`: `title` · `owner` · `status`):
+
+| # | Uç tanımı | Gövde | Sonuç |
+|---|---|---|---|
+| 1 | `fields: [title, owner, status]` | `{ id, status: 'done' }` | 200 — `status` değişti, **`title` ve `owner` NULL** oldu (`entity_audit_trails` ikisini de yalnız `previousValue` ile gösteriyor) |
+| 2 | `fields: [status]` | `{ id, status, title: '…', owner: '…' }` | 200 — yalnız `status` değişti; listelenmeyen iki alan **yazılmadı** |
+| 3 | `fields: [title, owner, status]`, `status` kolonu NOT NULL | `{ id, title }` | **400 `RowValidationFailed`** ("Please complete all required fields") — satır hiç değişmedi |
+
+Yani kolon `nullable` ise kayıp **sessizdir**, NOT NULL ise istek **gürültülü** düşer. Kanban'da
+kart sürüklemek, satır içi tek alan düzenlemek, "arşivle" düğmesi — hepsi 1. satırın tuzağıdır:
+kart doğru sütuna geçer, başlığı ve sorumlusu silinir.
+
+### Kısmi güncellemenin üç doğru yolu
+
+1. **Eylem başına uç (varsayılan tercih).** Kartı taşıyan uç yalnız `status` yazar, başlığı
+   düzenleyen uç yalnız `title`: `fields[]` = o eylemin gerçekten yazdığı alanlar. Fazladan okuma
+   yok, eşzamanlı düzenlemede birbirini ezme yok, yetki yüzeyi de dar kalır (2. ölçüm bunun
+   kanıtıdır — uç, gövdeye konan `title`/`owner`'ı yok sayar).
+2. **Tam form ucunda gövde de tam olur.** Düzenleme formu kaydediyorsa gövde `fields[]`'teki HER
+   alanı taşır; kullanıcının dokunmadığı alan da forma yüklendiği hâliyle geri gönderilir. Uçta
+   yapılacak bir şey yoktur — eksik gönderen istemci alanı siler.
+3. **Oku-birleştir (alan kümesi ancak çağrı anında belliyse).** Akışta önce `table get`, sonra
+   `table update`; gelmeyen alan okunan değere düşer:
+
+   ```js
+   typeof input.title !== 'undefined' && input.title !== null ? input.title : read_row.data.title
+   ```
+
+   Ölçüldü: `{ id, status }` gövdesiyle `title` ve `owner` korundu, `status` yazıldı. Bedeli iki
+   veritabanı turu ve **son yazan kazanır** — okuma ile yazma arasında başkasının yazdığı alan
+   geri alınır. Bu yüzden 1. yol varken bu yola girilmez.
+
+> Aynı kural workflow **table step**'inde birebir geçerlidir; orada değer gövdeden değil
+> ifadeden gelir ve `undefined` dönen ifade de `null` yazar —
+> `platform_guide('workflow')` §"Table update adımı".
+
 ## İlişki alanı: `row_list` NESNE döner, uç/step JOIN'siz DÜZ FK döner
 
 Aynı alan iki yoldan farklı şekilde gelir ve bu fark sessizce yanlış sonuç üretir:
@@ -531,6 +634,62 @@ kabul etti. Ayrıntı ve doğru rol kapısı tarifi: `platform_guide('middleware
 > rota `/{project}/m/{application}/{microservice SLUG'ı}`'dır ( `url` alanı rotaya GİRMEZ) ve
 > `Host: <org>.<suffix>` + `X-Environment` başlıkları zorunludur.
 
+## Alias nerede geçerli
+
+Alias bir **SQL tablo takma adıdır**: yalnız okunan tarafta anlamı vardır. Sözleşme iki ayrı
+tiple modellenmiştir ve ikisi karıştırılırsa alan sessizce düşer.
+
+| Yer | Tip | Alanlar |
+|---|---|---|
+| `selectFields[]` · `returnFields[]` | `TableSelect` | `alias` · `fieldId` · `path` · `fieldSlug` |
+| `filters[]` · `joins[]` | filtre/join | `alias` (+ kendi alanları) |
+| `sourceParameters.alias` | kök alias | join varken ZORUNLU, kök entity'nin slug'ı |
+| **`fields[]` (yazılacak alanlar)** | `TableField` | `fieldId` · `source` · `value` · `folderId` · `order` · `writeOn` — **`alias` YOK** |
+
+`fields[]` yalnız `create` / `update` / `upsert` operasyonlarında bulunur ve WHERE değil SET
+üretir: hangi tabloya yazılacağı zaten `entityId` ile bellidir, takma ada ihtiyaç yoktur. Aynı
+`TableField` tipi workflow table adımlarının `rule.fields[]` listesinde de kullanılır.
+
+Yazma alanına `alias` koyarsan istek **hata vermez**, alan model bağlamada düşer. Gateway bunu
+istek gitmeden gövdeden çıkarır ve `gatewayNormalized` ile bildirir — böylece `silentlyDropped`
+listesi yalnız gerçek kayıpları gösterir.
+
+## Zamanlanmış iş (`type: 'schedule-job'`) — `typeParameters.schedule`
+
+Zamanlama tek bir tanımdır; `cronExpression` tek başına verilirse **UTC cron** sayılır (eski gövde).
+Yeni işte tanımı `typeParameters.schedule` ile yazın ve kaydetmeden önce
+`microservice_schedule_forecast` ile sıradaki koşuları görün.
+
+| Alan | Değer |
+|---|---|
+| `mode` | `once` · `interval` · `cron` |
+| `timeZoneId` | IANA (`Europe/Istanbul`); yoksa `UTC`. Saatler BU dilimde yorumlanır |
+| `startAt` | yerel tarih-saat, dilimsiz (`2026-09-14T09:00:00`); once/interval için, cron'da `end.type:'after'` ile zorunlu |
+| `every` · `unit` | 1–1000 · `minute` `hour` `day` `week` `month` |
+| `timeOfDay` | `HH:mm` — `day`/`week`/`month` için zorunlu |
+| `daysOfWeek` | `monday`…`sunday` — `week` için en az bir |
+| `daysOfMonth` | 1–31, `-1` = ayın son günü — `month` için en az bir |
+| `cronExpression` | Quartz cron (6–7 alan, `?` zorunlu) — yalnız `cron` modu |
+| `end` | `{type:'never'}` · `{type:'on', at}` · `{type:'after', count}` (1–10000) |
+
+```json
+{ "mode": "interval", "timeZoneId": "Europe/Istanbul", "startAt": "2026-09-14T00:00:00",
+  "every": 2, "unit": "week", "daysOfWeek": ["tuesday", "thursday"], "timeOfDay": "09:00",
+  "end": { "type": "after", "count": 30 } }
+```
+
+- Aralık başlangıçtan sayılır: "7 dakikada bir" saat başında sıfırlanmaz, "3 günde bir" ay sonunda
+  başa sarmaz, "2 haftada bir" gerçekten iki haftada birdir. Cron'da bunlar DOĞRU İFADE EDİLEMEZ
+  (`MON/2` = haftada 3 gün) — bu ihtiyaçlar için `interval` kullanın.
+- `after N` başlangıçtan hesaplanan N'inci koşuda biter; `microservice_schedule_control trigger`
+  sayılmaz. Biten iş `microservice_schedule_get`'te `state: 'ended'` görünür.
+- Geçersiz tanım `422` + alan adıyla lokalize mesaj döner (bozuk cron artık `500` değil). `after` ile
+  toplam süre sınırlıdır (gün × sayı ≤ 36500, hafta ≤ 5200, ay ≤ 1200).
+- **`schedule` ile `cronExpression` çelişemez.** `microservice_get` ikisini de döndürür; güncellemede
+  yalnız `typeParameters.schedule`'ı değiştirin (cron modunda `schedule.cronExpression`). Yalnız
+  `cronExpression`'ı değiştiren PUT/PATCH `422 ScheduleCronConflict` alır — sessizce eski cron
+  kalmaz. `typeParameters: null` işi zamanlayıcıdan siler.
+
 ## Sık hatalar
 
 - `description` boş (MS-014, block — uç listesinde ne işe yaradığı okunamaz)

package/dist/resources/guides/modify-existing.md

@@ -25,6 +25,29 @@ yeniden yazımlarda.
   `view:'part'` ile doğrulayarak yaz.
 - Silme yerine `replace` tercih et; `remove` kullanacaksan önce o path'i `part` ile görüntüle.
 - Yanıttaki outline özeti değişikliğin uygulandığı hâli gösterir — teyit için oku.
+- **Kullanıcı fonksiyonunda patch aracı yok:** `function_update` tam gövde yazar ama vermediğin
+  alanları mevcut kayıttan doldurur — yalnız `body` göndermen yeter (fonksiyonun tek büyük alanı
+  gövdedir). Adı değiştirmeden önce `dependency_graph` (`module:'ui-function'`) ile çağıranları
+  bul: `{{ }}`/`code` ifadelerindeki `Functions.<eskiAd>(` çağrıları metinseldir ve kırılır.
+
+## Değiştirmeden önce geçmişe bak
+
+Platform her tanım yazmasını append-only bir deftere düşürür. Bir kaydı değiştirmeden önce son
+revizyonunu okumak, başka birinin işinin üstüne yazmayı önler:
+
+```
+revision_list {projectId, module:'page', recordId, pageLength: 3}
+  → son satırda revisionNo, operation, actor ve source
+revision_diff {projectId, module:'page', recordId}
+  → son iki sürüm arasındaki alan bazlı fark + summaryText
+```
+
+`source` işin nereden geldiğini söyler: `mcp` bu gateway'in kendi izidir, `studio` bir insanın
+Studio'da yaptığıdır, `merge` / `deployment` / `template` / `revert` ise taşıma yollarıdır.
+Son revizyon `studio` ise ve dakikalar önceyse, üstüne yazmadan önce kullanıcıya sor.
+
+Gövdenin tamamı gerekirse `revision_get {projectId, id}` — ama büyük sayfalarda MB'lar tutar ve
+yanıt kırpılabilir; ne değiştiğini anlamak için `revision_diff` yeter.
 
 ## Uyum kuralları