@appaflytech/zeyrek-ai-mcp 0.0.11 → 0.0.13

package/dist/resources/guides/workflow.md

@@ -227,19 +227,68 @@ tanımı kendi global-error dalınla gönder — dal **bağlıysa** (`nextStepId
 dokunmaz. `nextStepId: null` ile bağlanmamış gönderirsen gateway ikinci bir dal eklemez, mevcut
 dalını enjekte ettiği hata adımına bağlar.
 
-**Fail dallarını tek tek bağlamana gerek yok.** Bir adımın `fail` dalı bağlanmamışsa
-(`nextStepId: null`) ya da hiç yoksa, hata **kendiliğinden** global-error dalına gider. `fail`
-dalını yalnız o adıma özel bir telafi akışı (örn. "kayıt yoksa oluştur") istiyorsan bağla.
+### `gatewayOnError`'un 500 gövdesi: patlayan adım ve alt akış zinciri (2026-09-16)
+
+```jsonc
+// POST /m/web/ticket-ac → 500   (ebeveyn → callChild → çocuk akış → childBoom patladı)
+{ "code": "JavaScriptException", "message": "Error: x is not defined\n   at <anonymous>:1:8",
+  "detail": "…", "type": "JavaScriptException",
+  "step":  { "name": "callChild", "type": "workflow" },          // bu akışta patlayan adım
+  "cause": { "code": "JavaScriptException", "message": "…",       // alt akışın KENDİ hata gövdesi
+             "step": { "name": "childBoom", "type": "code" } } }   // çocukta patlayan adım
+```
+
+- **`step` yalnız `{ name, type }`'tır.** `error.step.input` ifade değerlerini (parola dahil),
+  `error.step.data` adımın çıktısını taşır; ikisi de dışarı yazılmaz. `error.step`'i bütün olarak
+  gövdeye koyarsan platform onu **siler** (`ResponseStep` global-error kipinde `error.step` ile
+  birebir aynı `step` alanını kaldırır) — alt küme yaz.
+- **`cause` bir seviye aşağıyı taşır** ve her seviyede yalnız `code`, `message`, `detail`, `type`,
+  `step { name, type }` ve `cause` geçer (gateway beyaz listeye süzer, en fazla dokuz seviye). Backend
+  2026-09-17'den beri zinciri `error.cause`'ta kendisi kurar; üç durum kapsanır:
+  - **Alt akış patladı:** `cause.step` çocukta patlayan adım, çocuk da alt akış çağırıyorsa zincir
+    seviye seviye iç içe iner. Çocuk Studio'da hata yolsuz kurulduysa da adım adı gelir.
+  - **Loop iterasyonu patladı:** `step` loop adımı, `cause.step.name` `loopRows[0]` gibi
+    `<loop adı>[<sıra>]`, iterasyondaki alt akışın zinciri onun altında.
+  - **Çocuk istisnasız 2xx dışı döndü** (`response` 422): `code` `SubWorkflowFailedException`,
+    `message` `Sub-workflow '<ad>' returned 422 (<gövde code>): <gövde message>`.
+
+  Eski backend'de `error.cause` yoktur; gateway o zaman patlayan `workflow` adımının `step.data`'sına
+  (çocuğun kendi gövdesi) düşer — loop ve istisnasız çocuk orada kaybolur. Çocuk kendi 4xx/5xx yanıtını
+  elle yazdıysa (`({ success: false, token })`, `({ err: error })`) o gövdenin yalnız bu alanları geçer.
+  Canlı ölçüldü (2026-09-16/17): torunun `token` ve `step.input`'u üst gövdeye ulaşmadı; üç seviyeli
+  zincir ve `loopRows` → `loopRows[0]` → `boomStep` hem hata yolsuz hem gateway hata yollu uçta döndü.
+- **Gateway zinciri okur (yalnız 5xx):** `microservice_execute`/`debug`/`preview` `runtimeErrors`'a
+  `hata gövdesi — hata yolu: 'callChild' (workflow) → 'childBoom' (code) · 'childBoom' (code)
+  JavaScriptException: …` satırını ekler (debug ucunun `{ data, executionItems }` sarmalı açılır);
+  fırlatan çağrıların (senkron automation'lı `row_create`, `workflow_preview`…) araç hatası da
+  gövdede bulunan `detail`'i, koddan farklı `type`'ı ve varsa zinciri yazar. 4xx gövdeleri
+  süslenmez — onlar bilinçli iş yanıtıdır.
+- **Eski kayıtlar:** 2026-09-16 öncesi gateway `({ code: error.code, message: error.message })`
+  yazıyordu. Global-error dalının hedefi olan, adı `gatewayOnError[n]`, ifadesi bu metinle AYNEN
+  aynı ve açıklaması gateway'in eski metni (ya da boş) olan adım bir sonraki
+  `workflow_create`/`update`/`patch`/`preview`'da yeni gövdeye yükseltilir (`gatewayNormalized`:
+  "hata gövdesi genişletildi"; önizleme kaydetmez). Yanıta alan eklenir, `code`/`message` değişmez.
+  Açıklaması ya da ifadesi elle değiştirilmiş adıma dokunulmaz; yükseltme açıklamayı da yenilediği
+  için sonradan bilerek eski gövdeye dönen `bodyExpression` bir daha ezilmez.
+- **Dışarı ne verdiğine sen karar verirsin.** Adım adları iç yapıyı, `detail` iç istisna mesajını
+  (kısıt adı, host) gösterebilir. **Middleware'in 500 gövdesi korumalı uçların anonim çağıranına da
+  gider** (`ExecuteMicroserviceBehavior`). Herkese açık yüzeyde istemiyorsan hata adımının
+  `bodyExpression`'ını daralt, örn. `({ code: error.code, message: error.message })`.
 
 Global-error dalında `error` değişkeni tanımlıdır:
 
 ```jsonc
 { "code": "RowAlreadyExists", "message": "…", "detail": "…", "type": "…",
-  "step": { "id": "…", "name": "writeRow", "type": "table", "data": …, "input": [ … ] } }
+  "step": { "id": "…", "name": "writeRow", "type": "table", "data": …, "input": [ … ] },
+  "cause": null }   // alt akış / loop iterasyonunda { code, message, detail, type, step: { name, type }, cause }
 ```
 
-`error.step` hangi adımın patladığını söyler — hata yanıtına koymadan önce iki kez düşün, iç
-yapıyı dışarı sızdırır.
+Fail dalında aynı zincir `<adım adı>.error.cause`'tadır (`<adım adı>.error` = `{ code, message, detail,
+type, cause }`).
+
+`error.step` hangi adımın patladığını söyler. `input`/`data` alanları ifade değerlerini ve adım
+çıktısını taşır — gövdeye yalnız ihtiyaç duyduğun alt kümeyi yaz (gateway'in varsayılanı
+`{ name, type }`'tır, yukarıdaki §`gatewayOnError`'un 500 gövdesi).
 
 **Kurallar ve sınırlar:**
 
@@ -257,9 +306,14 @@ yapıyı dışarı sızdırır.
   bağlı — §izin matrisi) ya da `email`/`table` adımına bağla. Bağlı hata yolu yoksa `WF-021` uyarır.
 - **Hata yolu hiç yoksa** (fail dalı ve global-error dalı bağlı değil) adım patladığında motor
   canlıda `WorkflowStepFailedException` fırlatır (2026-09-16): HTTP yanıt 500 +
-  `{ code, message, detail, type }` (patlayan adımın hatası), zamanlanmış iş ve automation geçmişi
-  `failed` + `Step 'x' failed: <sebep>`, senkron automation tetikleyen satır yazımını düşürür.
-  Önizlemede fırlatmaz, ağaç döner. Çalışır, ama çıktı lokalize değildir.
+  `{ code, message, detail, type, step: { name, type }, cause }` — `step` ve `cause` 2026-09-17'den
+  beri, gateway hata adımıyla aynı şekil (yerel ortamda ayrıca `stackTrace`). Zamanlanmış iş ve
+  automation geçmişi `failed` + `Step 'x' failed: <sebep>`, senkron automation tetikleyen satır
+  yazımını düşürür. Önizlemede fırlatmaz, ağaç döner. Çalışır, ama çıktı lokalize değildir.
+- **Adım hata yolunun DIŞINDA patlarsa** (ör. `revert`'in `revertType` ifadesi tırnaksız) kod
+  `EvaluateWorkflowStepFailedException`, mesaj `Step '<ad>' threw outside its error path: <sebep>`
+  olur: fail dalı ve global-error dalı ÇALIŞMAZ, canlı koşu düşer. 2026-09-17'den beri önizleme
+  ağacı kaybolmaz; adım `hasError: true` ile işaretlenir.
 
 > **Preview HTTP 200 dönerken bile akış patlamış olabilir.** `executionSuccess` yalnız SON adıma
 > bakar; ortada patlayıp hata dalından dönen akış `true` gösterir. Gateway tüm adımları (iç içe
@@ -347,6 +401,100 @@ gidilir, hiçbiri tutmazsa `else` dalı yürür:
 > `rule.isExpression` bayrağı bu iki alan için **okunmaz**.
 
 
+## HTTP adımı: gövde ayrı alan değil, `payloadExpression` üç anahtarı birden taşır (WF-033)
+
+Dört alan: `rule.urlExpression` · `httpMethod` · `contentType` · `payloadExpression`.
+**Gövdenin kendi alanı yoktur** — `payloadExpression` tek bir ifadeyle `{ header, body,
+queryString }` **üçünü birden** üretmek zorundadır; yürütücü üçüne de `dynamic` üye erişimiyle
+bakar (`HttpStep.cs:32,42,59`).
+
+```jsonc
+"rule": {
+  "stepType": "http",
+  "urlExpression": "'https://api.example.com/orders'",
+  "httpMethod": "POST",
+  "contentType": "application/json",
+  "payloadExpression": "({ body: { orderId: input.orderId }, header: { Authorization: 'Bearer ' + system.token }, queryString: {} })"
+}
+```
+
+| Tuzak | Ne olur |
+|---|---|
+| Bir anahtar eksik (`queryString` yok) | Adım **düşer**: `RuntimeBinderException` — ölçülen mesaj birebir `'System.Dynamic.ExpandoObject' does not contain a definition for 'queryString'`. Boş da olsa `{}` yazın |
+| `urlExpression` tırnaksız | İfadedir, düz metin değil: `https://…` yazarsan JS onu değişken sanır ve adım `x is not defined` der |
+| `contentType` boş | Gövde `body.ToString()` ile gider (`HttpStep.cs:63-85`); nesne gövdesi tip adına dönüşür. POST/PUT'ta açıkça yazın |
+| Yanıt JSON değil | Gövde **sessizce** boş nesne olur (`:92`) — XML dönen uçtan veri de hata da alamazsınız |
+| Adım adında boşluk | Çıktıya adım adıyla erişilir; ad geçerli JS tanımlayıcısı olmalı (`call_roles`, `Call Roles` değil) |
+
+**Çıktıyı okurken şemaya değil ölçüme güvenin (2026-09-16).** `workflow_step_schema('http')`
+`returnScheme`'i kök seviyede `{ httpStatusCode, data }` ilan eder, ama koşumda ifade bağlamındaki
+adım `{ data, meta: { elapsedTime, httpStatusCode, totalCount }, error }` şeklindedir:
+
+- gövde → **`<adım>.data`**
+- durum kodu → **`<adım>.meta.httpStatusCode`**
+- `<adım>.httpStatusCode` → **undefined** (şemanın vaat ettiği ad çalışmaz)
+
+Tam örnek ve POST varyantı: `ngapps://examples/workflow-http-step`.
+
+## Workflow adımı: başka bir akışı parametreyle çağırmak (WF-032)
+
+Ortak mantığı (kayıt açma, bildirim, numaralandırma) **bir kez** `type:'workflow'` akışı olarak
+yazıp diğer akışlardan çağırmanın yolu budur — 30 adımı kopyalamak değil. Adım tipi `workflow`;
+üç akış tipinde de kullanılabilir. Kuralı **iki alan** taşır ve girdi eşlemesi ikincisidir:
+
+```jsonc
+{ "id": "<GUID>", "name": "createTicket", "type": "workflow",
+  "description": "Telemetri olayından create-ticket akışıyla kayıt açar.",
+  "rule": {
+    "workflowId": "<create-ticket akışının id'si>",
+    "expression": "({ title: input.title, source: 'telemetry', payload: parseEvent.data })"
+  },
+  "branches": [
+    { "id": "<GUID>", "name": "success", "type": "success", "nextStepId": "<sonraki>" },
+    { "id": "<GUID>", "name": "fail", "type": "fail", "nextStepId": "<hata adımı>" }
+  ] }
+```
+
+- **Eşleme `rule.expression`'daki nesne literalidir: her anahtar çağrılan akışın parametre
+  DTO'sundaki bir alan, her değer bir JS ifadesi** (`input.x`, önceki adımın `<ad>.data.x`'i,
+  sabit). Studio'nun adım editörü de aynı şeyi yapar — akış seçilince ifadeyi `parameterScheme`'den
+  `{ "alan": <örnek> }` olarak doldurur (`WorkflowTrigger.svelte`). Table adımının `fields[]`
+  listesinin buradaki karşılığı budur; ayrı bir liste alanı **yoktur** ve gerekmez.
+- **Çağrılan akışın `parameterDtoId` + `parameterBehavior`'ı OLMAK ZORUNDA.** `WorkflowStep`
+  ifadeyi yalnız `workflow.HasParameter` iken değerlendirir (`WorkflowStep.cs`); DTO'suz alt
+  akışa yazılan ifade hiç koşmaz, alt akış boş `input` ile çalışır ve **200 döner**. Gateway
+  çağrılan akışı okuyup bunu **block** eder (WF-032). Reçete: `dto_create` → `workflow_patch(id:
+  <alt akış>, ops: [{ op: 'add', path: '/parameterDtoId', value: <dtoId> }, { op: 'add', path:
+  '/parameterBehavior', value: 'object' }])`.
+- **Başka hiçbir alan girdi taşımaz.** Şema üyeleri (`payloadExpression`, `customParameters`,
+  `queryParameters`, `bodyExpression`, `fields`) kaydedilir ama `WorkflowStep` okumaz; şema dışı
+  adlar (`parameters`, `input`, `payload`, `args`…) platformda hiç kaydedilmez (`unmappedMembers`).
+  İki durumda da alt akış boş girdi alır (RFQ koşusu W-7, 2026-09-14: beş biçim denendi, beşinde
+  de boş girdi). Gateway DOLU değer görürse block eder; `workflow_get`'in geri okuttuğu
+  `fields: []` / `customParameters: null` gibi boş varsayılanlar kuralı tetiklemez.
+- **Ad tuzağı:** `rule.expression` `code` adımında GÖVDE (çalıştırılan kod), `workflow` ve
+  `microfunction` adımında GİRDİ (argüman nesnesi) demektir. Aynı ad, iki anlam.
+- **Alt akış girdiyi `input.<alan>` ile okur ve onun `input`'u bu nesnedir** — çağıranın
+  `input`'unu görmez; çağıranın bir alanı gerekiyorsa eşlemeye koy. `parameterBehavior: 'array'`
+  ise ifade dizi üretmelidir (gateway nesne literali görürse uyarır).
+- **Çıktı alt akışın yanıt gövdesidir** (`response` adımının `returnDtoId` süzgecinden geçmiş
+  hâli) ve sonraki adımlara `<adım adı>.data` ile akar. Alt akış 2xx dışı dönerse ya da bir
+  adımı düşerse çağıran adım **fail** dalına gider; `<adım adı>.data` o zaman alt akışın hata
+  gövdesidir.
+- **Şekli tahmin etme, oku:** `workflow_step_schema(step)` çağrılan akışın `parameterScheme` ve
+  `returnScheme`'ini döner; ya da `workflow_get(<workflowId>)` → `parameterDtoId` → `dto_get`.
+- **Loop içinde:** `rule.stepType: 'workflow'`, `rule.arrayExpression`, çocuk kural
+  `rule.stepRule: { workflowId, expression: "({ title: loopItem.title })" }` — WF-032 çocuğu da
+  denetler.
+- **Önizlemede** alt akışın kendi adım izi `steps[].children[]` altında `kind: 'subWorkflow'` ile
+  gelir; çağıran adımın `input[]` listesinde `member: 'parameter'` satırı ifadenin ürettiği nesneyi
+  gösterir — **satır yoksa ya da değeri boşsa girdi bağlanmamıştır.** Alt akışı tek başına
+  sınamak için kendi `previewPayload`'ı ile `workflow_preview` çağır.
+- Aynı alt akışı birden çok adımdan çağırmak serbesttir; özyineleme runner'ın koşum sayacına
+  takılır (kural envanteri WF-028 — gateway kuralı değil, backend davranışı).
+
+Tam örnek (çağıran + çağrılan akış, canlı ölçümle yazıldı): `ngapps://examples/workflow-call-workflow`.
+
 ## Loop step — dizinin her öğesi için bir adım koştur
 
 Tek uçta "başlık + N alt kayıt" yazmanın yolu budur (anket + sorular + seçenekler tek çağrıda;
@@ -367,9 +515,19 @@ Tek uçta "başlık + N alt kayıt" yazmanın yolu budur (anket + sorular + seç
   (`StepRuleDto StepRule`); `children` gönderirsen `rule.Children` boş kalır ve loop
   **`NullReferenceException`** ile patlar — hata mesajı `arrayExpression`'ı işaret ettiği için
   seni ifadeyi suçlamaya iter, oysa sorun anahtar adıdır.
-- **Geçerli öğe `loopItem`'dır.** Çocuğun `fields[].value` / `filters[].value` ifadelerinde
-  `loopItem.<alan>` yazılır; `input` ve önceki adımlar (`createSurvey.data.id`) da görünmeye
-  devam eder.
+- **Geçerli öğe `loopItem`'dır — ama YALNIZ loop'un kendi değerlendirdiği ifadelerde.** Çocuğun
+  `fields[].value` / `filters[].value` ifadelerinde `loopItem.<alan>` yazılır (ölçüldü 2026-09-16:
+  `table` çocuğunun filtresinde `loopItem.slug` → `'super-admin'`); `input` ve önceki adımlar
+  (`createSurvey.data.id`) da görünmeye devam eder.
+- **`code` çocuğunda `loopItem` YOKTUR (ölçüm 2026-09-16).** `code` adımı kendi JS motorunu kurar
+  ve `LoopStep`'in `loopItem` ataması oraya ulaşmaz: adım **`Error: loopItem is not defined`** ile
+  düşer, o yinelemenin çıktısında `result` hiç oluşmaz. Motorda görünenler `input` · `system` ·
+  `file` · `crypto` · `convert` ve ifade fonksiyonlarıdır. **Her öğe için hesap yapman gerekiyorsa
+  hesabı `arrayExpression`'da önden yap** — orası JS'tir ve diziyi istediğin şekle sokabilirsin:
+  `(input.kalemler || []).map(k => ({ ...k, tutar: k.fiyat * k.adet }))`; çocuk sonra
+  `loopItem.tutar`'a bakar.
+- **İndeks değişkeni yoktur.** Sıra numarası gerekiyorsa diziyi `arrayExpression`'da üret:
+  `input.kalemler.map((k, i) => ({ ...k, sira: i }))`.
 - **Çıktı `[{ item, result }]` dizisidir.** `result` çocuk adımın çıktısıdır; `table create`
   için `{ id }`. Sonraki adımda `loopQuestions.data` ile okunur — **yazılan kayıtların id'sini
   girdideki öğeyle eşleştirmenin yolu budur.**
@@ -385,6 +543,9 @@ Tek uçta "başlık + N alt kayıt" yazmanın yolu budur (anket + sorular + seç
   İstemci alt kayıtları **düz** gönderir ve satırları `key`/`qkey` ile eşler — iç içe dizi
   göndermek gerekmez (iç içe loop denenmedi; `loopItem` iç loop'ta gölgeleneceği için önerilmez).
 
+Tam örnek, ölçülen çıktı şekli ve `code` çocuğu tuzağının çıkış yolu:
+`ngapps://examples/workflow-loop-step`.
+
 > **Table step'te `create`/`update` satır değerleri `fields[]`'tedir ve JS İFADESİDİR.**
 > `{ "fieldId": "<alan id>", "source": "expression", "value": "input.title", "order": 0 }` —
 > `PrepareParameters` her `fields[].value`'yu `EvaluateExpression` ile koşturur

package/dist/resources/schema-fingerprint.json

@@ -1,8 +1,10 @@
 {
-  "hash": "54430a8d4050fd201aaee88608a5d06b947edf6d561ad31354914422df4e94ce",
-  "generatedAt": "2026-09-16T11:17:11.569Z",
-  "types": 185,
-  "files": 107,
+  "hash": "05c7864d58e308973805f7becee1578ce9eddad196abcdf7eebb43b1e7677549",
+  "generatedAt": "2026-09-16T15:53:10.903Z",
+  "types": 186,
+  "files": 108,
   "note": "Şemaları üreten backend kaynaklarının parmak izi. Elle düzenlemeyin: 'npm run generate-schemas' yazar, 'npm run schema:check' denetler.",
-  "missing": []
+  "missing": [
+    "NgApps.Infrastructure.Models.IdNamePair`1[[System.Guid, System.Private.CoreLib, Version=10.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e]]"
+  ]
 }