@appaflytech/zeyrek-ai-mcp 0.0.1

package/dist/resources/guides/microservice.md

@@ -0,0 +1,313 @@
+# Microservice Rehberi
+
+## Karar kuralları
+
+1. **Kaynak seçimi sırası: `table` → `view` → `workflow` → `query`.**
+   - `table`: tek entity üzerinde CRUD/listeleme — varsayılan tercih. Filtre, join, sıralama,
+     alan seçimi hepsi `sourceParameters` ile platform-native.
+   - `view`: **tam metin ARAMA** — kaynak bir view arama indeksidir (raporlama değil!). Uç
+     **zorunlu `searchText`** parametresi ister (yoksa `MissingParameterException`), `limit`
+     (varsayılan 20) ve `offset` alır. Kurulum sırası: `view_create` (aranacak tablo/alanlar +
+     analizör) → `view_rebuild` → `source:'view'` microservice. Satış özeti / top-N gibi
+     rapor işleri view'e DEĞİL raw query'e aittir (`query_create` + query kaynaklı uç).
+   - `workflow`: çok adımlı iş mantığı gerekiyorsa microservice'i workflow'a bağla
+     (`workflowId`).
+   - `query`: yalnız ham SQL gerçekten şartsa. Politika lint'i her query kullanımında gerekçe
+     ister (MS-002, warn).
+2. **`selectFields` asla boş bırakılmaz.** Boş = platform TÜM alanları döndürür; join'li
+   sorguda maliyet katlanır. Join varken boş bırakmak block'tur (MS-001).
+3. **Join'ler ilişkilerden türetilir.** `sourceParameters.joins` öğesi:
+   `{ alias, entityId, fieldId, path, joins }` — iç içe join mümkündür. Her join'in getirdiği
+   alanlar da `selectFields`'ta `{ alias, fieldId, path, fieldSlug }` ile açıkça seçilir.
+   **`path` boş bırakılamaz** — Studio join'li seçimleri yalnız `path` üzerinden eşleştirir
+   (aşağıdaki bölüme bak).
+4. **HTTP sözleşmesi:** `type: 'rest-api'` + `httpMethod: get|post|put|delete` + `url`
+   (route şablonu). Zamanlanmış işler `type: 'schedule-job'`, kuyruk tüketicileri `consumer`.
+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.
+
+## 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`.
+- **`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
+  ([TableStep](../../../../zeyrek-backend/src/NgApps.Domain/Contexts/Flow/Workflows/Steps/TableStep.cs)).
+- **`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ı —
+  komutta öyle bir alan yok, gönderilirse yok sayılır; asıl zorunluluk selectFields'taki fieldId.)
+- `selectFields[]` öğelerinde **`fieldId` zorunlu** (yalnız `fieldSlug` yetmez); kök tablo
+  alanlarında alias = **entity'nin slug'ı** ve `path` **yazılmaz**. Alias verilmezse
+  `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"`).
+- **Operatör sözlüğü kapalıdır:** `eq · neq · lt · lte · gt · gte · contains · icontains ·
+  in · notin · startswith · endswith · istartswith · iendswith`. **`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.
+- **Write operasyonunda (`create`/`update`) yanıt yalnız primary key'dir** — platform sonucu
+  PK'ya indirger ve `selectFields`'ı kaydederken sessizce boşaltır. Yanıtın başka alan da
+  dönmesi gerekiyorsa **`returnFields`** kullanılır (öğeler `selectFields` ile aynı şekildedir:
+  `{ alias, fieldId, fieldSlug }`). Aynı kural workflow table create/update step'lerinde de
+  geçerlidir. Boş `returnFields` ile write operasyonu yazarsan MS-009 uyarır; buna karşılık
+  write operasyonunda boş `selectFields` **uyarı üretmez** (platform onu zaten yok sayar).
+
+```jsonc
+{
+  "name": "Get Orders", "slug": "get-orders",
+  "type": "rest-api", "httpMethod": "get", "url": "orders",
+  "source": "table", "returnType": "flat",
+  "isReturnSchemaArray": true, "isParameterSchemaArray": false,
+  "entityId": "<orders entity id>",
+  "sourceParameters": {
+    "operation": "get",
+    "entityId": "<orders entity id>",
+    "alias": "orders",
+    "isSingle": false,
+    "selectFields": [
+      { "alias": "orders", "fieldId": "<code alanı id>", "fieldSlug": "code" },
+      { "alias": "orders", "fieldId": "<total alanı id>", "fieldSlug": "total" }
+    ],
+    "joins": [],
+    "filters": [],
+    "sort":  { "name": "sortField", "type": "sortType", "source": "query-string" },
+    "limit": { "name": "limit", "offset": "offset", "source": "query-string" }
+  }
+}
+```
+
+## İ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:
+
+| Okuma yolu | İlişki alanının şekli |
+|---|---|
+| `row_list` | **her zaman** `{ id, <displayAlanı> }` — handler her ilişki alanı için join'i kendisi üretir (`GetRowsQuery.ProcessRelation`) |
+| microservice / workflow table adımı | **yalnız `joins` içinde bildirdiğin ilişki** nesne olur (`ModifyResponse` → `ProcessJoins`); bildirmediğin alan **düz FK string**'idir |
+
+Yani `row_list` çıktısına bakıp yazdığın `x.owner_id.email` ifadesi bir uçta `undefined` döner —
+hata vermez, sessizce boş sonuç üretir (rol dizisi boşalırsa yetki kapısı yanlış karar verir).
+Gateway bu okumayı **WF-020** ile uyarır. Çözüm: ya alanı `joins` + `selectFields` ile getir,
+ya hedef tabloyu ayrı okuyup id ile eşleştir; her iki şekle dayanan yazım
+`var v = x.owner_id && x.owner_id.id ? x.owner_id.id : x.owner_id;`.
+
+## Table join kuralları (\"null key\" hatasının gerçek sebebi)
+
+Join motoru çalışır; hatalar **alias disiplinsizliğinden** çıkar (`PostgreSqlRelationHandler`
+girdileri doğrulamadan sözlük kurar, eksik alias opak 500'e dönüşür — bug değil):
+
+- **Kök `alias` (sourceParameters.alias) join varken ZORUNLUDUR** ve kök entity'nin slug'ı
+  olmalıdır. Join'in ON koşulunun sol tarafını bu alias kurar
+  (`PostgreSqlRelationHandler.HandleJoin` → `$"{alias}.{ilişkiAlanı}"`); boş bırakılırsa SQL'e
+  `.<alan>` gider, SqlKata onu `""."<alan>"` diye tırnaklar ve Postgres **`42601: zero-length
+  delimited identifier`** ile reddeder — hata ne alanı ne sebebi söyler. Runtime'da varsayılan
+  ATANMAZ (şema üretimi `Entity.Slug`'a düşer, çalıştırma düşmez). Gateway alias'ı kök
+  `selectFields`'tan türetebiliyorsa doldurur (`gatewayNormalized`), türetemezse **MS-013**
+  block'uyla isteği hiç göndermez. Aynı kural workflow/middleware table step'i için de geçerli
+  (**WF-019**).
+- Her join'de `alias`, `entityId`, `fieldId` ZORUNLU; alias'lar benzersiz olmalı.
+- `fieldId` = ana entity'deki **ilişki alanının** id'si (hedef entity'nin değil).
+- Join'in getirdiği her alan `selectFields`'ta **join'in alias'ı + `path` zinciriyle** seçilir;
+  ana tablo alanları entity slug alias'ıyla, `path` yazılmadan.
+- Alias'sız join/select → 500 "null key"; tanımsız alias → "missing FROM-clause entry".
+
+### `path` kuralı (Studio bunsuz join alanlarını GÖSTEREMEZ)
+
+`path`, kökten o düğüme kadarki **ilişki alanı id'lerinin nokta ile birleşimidir**. İki farklı
+biçim var, karıştırma:
+
+| Nerede | Değer | Örnek |
+|---|---|---|
+| `joins[].path` | `<kökEntityId>` **+** ilişki alanı zinciri | `<ordersId>.<orders.customer>` |
+| iç içe `joins[].joins[].path` | zincir uzar | `<ordersId>.<orders.customer>.<customers.city>` |
+| join'li `selectFields[].path` | **kök entity id'si OLMADAN** aynı zincir | `<orders.customer>` |
+| kök tablo `selectFields[].path` | alan hiç yazılmaz (ya da boş) | — |
+| kök tablo `filters[].path` | alan hiç yazılmaz | — |
+
+Bu kural **MS-007 (block)** olarak denetlenir. `path: ""` verilen join'ler **runtime'da çalışır** (SQL alias üzerinden kurulur, `ms_source_entity_joins`
+satırları da oluşur) ama Studio formu seçili alanları `path` eşleşmesiyle bulduğu için
+(`MicroserviceFormTableRelations.svelte`: `item.path === getPath(relationFieldId)`) hiçbir join
+alanı seçili görünmez. Sessiz bozulma — execute testi bunu yakalamaz, ancak Studio'da bakınca
+anlaşılır.
+
+```jsonc
+"sourceParameters": {
+  "operation": "get", "entityId": "<orders id>", "alias": "orders", "isSingle": false,
+  "selectFields": [
+    { "alias": "orders",    "fieldId": "<code id>", "fieldSlug": "code" },
+    { "alias": "customers", "fieldId": "<name id>", "fieldSlug": "name", "path": "<orders.customer ilişki alanı id>" }
+  ],
+  "joins": [
+    { "alias": "customers", "entityId": "<customers id>", "fieldId": "<orders.customer ilişki alanı id>",
+      "path": "<orders entity id>.<orders.customer ilişki alanı id>", "joins": [] }
+  ],
+  "sort":  { "name": "sortField", "type": "sortType", "source": "query-string" },
+  "limit": { "name": "limit", "offset": "offset", "source": "query-string" }
+}
+```
+
+> **Gateway bunları senin yerine dolduruyor.** `path`, `sort` ve `limit` eksikse gateway
+> create/update/patch/preview yollarında hesaplayıp ekler ve yanıtta `gatewayNormalized` ile
+> bildirir. Elle yazarsan dokunmaz — o yüzden **yanlış** yazılmış bir path yine MS-007 block'una
+> takılır. Kuralı bilmen yine de gerekir: geri okuduğun kayıtta ne göreceğini bu belirler.
+
+### Filtre zorunlu mu, opsiyonel mi (`isRequired`)
+
+`isRequired: true` verilen filtre **istekte parametre yoksa çalışmayı engeller**. Varsayılan
+olarak zorunlu yazmak, tek uçla hem "hepsini listele" hem "filtreleyerek listele" senaryosunu
+karşılamayı imkânsız kılar. Karar kuralı:
+
+| Uç | `isRequired` | Neden |
+|---|:-:|---|
+| Liste uçları (`isSingle: false`) | `false` | Parametre gelirse süzer, gelmezse tam liste döner |
+| Tekil kayıt (`isSingle: true`) | `true` | Anahtar olmadan "tek kayıt" anlamsız |
+| `update` / `delete` | `true` | **Güvenlik**: filtresiz update tüm tabloyu yazar |
+
+```jsonc
+{ "alias": "announcements", "fieldId": "<id alanı>", "operator": "eq",
+  "source": "query-string", "filterType": "single", "conditionType": "or",
+  "isRequired": false, "children": [], "order": 0 }
+```
+
+### Dinamik filtre (`enableDynamicFilters`) — süzülebilir tablonun uç şekli
+
+`enableDynamicFilters: true` verilen uç, süzme koşullarını **tanımdan değil çağrıdan** alır.
+Validator dört şey dayatır ([CreateMicroserviceCommandValidator:76-86](../../../../zeyrek-backend/src/NgApps.Application/Contexts/Studio/Microservices/CreateMicroserviceCommand.cs)):
+`source: 'table'` · `operation: 'get'` · `isSingle: false` · **tüm single filtrelerin
+`source: 'expression'` olması** (aksi hâlde `PrefilterMustBeExpression`). Yani statik
+`query-string` filtresiyle birlikte kullanılamaz; `expression` filtreleri burada süzme değil
+**sabit prefilter**dir (tenant/aktiflik gibi). Gateway bunu MS-010 ile istek gitmeden yakalar.
+
+Çağrıdaki `filters` üç şekilde kabul edilir
+([DynamicFilter.Parse](../../../../zeyrek-backend/src/NgApps.Domain/Contexts/Studio/Microservices/DynamicFilter.cs)):
+
+| Şekil | Örnek |
+|---|---|
+| JSON **string** | `?filters=[{"field":"status","operator":"eq","value":"Bekliyor"}]` |
+| Gövde/nesne | `body.filters = [{ field, operator, value, conditionType, filterType, children }]` |
+| **Köşeli parantez query-string** | `?filters[0][field]=status&filters[0][operator]=eq&filters[0][value]=Bekliyor` |
+
+Üçüncü biçimin regex'i `^filters((?:\[[^\[\]]*\])+)$` — anahtarın tamamı `filters` + köşeli
+parantez grupları olmalı ve **ilk segment tam sayı** olmalı. `filters[0].field` gibi noktalı
+karışık biçim **eşleşmez**; iç içe grup için de parantez kullanılır
+(`filters[0][children][0][field]`). Boş köşeli parantez (`filters[]`) otomatik indekslenir.
+
+Runtime'da dinamik filtreler statik olanların **yerine geçmez, onlarla birleştirilir**
+(`TableMicroserviceExecutor:166` → `DynamicFilter.Combine`).
+
+#### `field` **join'li nokta yolu kabul eder** (`hasta.ad`, `manager.departman.name`)
+
+Dinamik filtre alanı düz kolonla sınırlı değildir; `DynamicFilter.ResolveField` yolu
+[EntityPathResolver](../../../../zeyrek-backend/src/NgApps.Domain/Contexts/Datastore/Entities/EntityPathResolver.cs)
+ile çözer. Üç şekil de geçerlidir:
+
+| `field` | Anlamı |
+|---|---|
+| `status` | Kök tablonun kolonu |
+| `hasta.ad` | `hasta` join'inin `ad` kolonu |
+| `manager.departman.name` | İç içe join zinciri (`join.Children` üzerinden yürür) |
+
+Ara segmentler **ilişki alanının slug'ı ya da join'in alias'ı** ile eşleşir; son segment
+hedef entity'deki alan slug'ıdır. Tek koşul: alan **`selectFields` içinde
+`mode: 'default'` ile seçili olmalı** — değilse `FilterFieldNotInSelectedException`
+("filtre alanı seçili değil") alırsınız. Yani "hasta adına göre randevu ara" için hasta adını
+hem `joins` ile getirin hem `selectFields`'a koyun; ondan sonra `filters[0][field]=hasta.ad`
+çalışır. m2m alanlar da desteklenir (`EXISTS` alt sorgusuna çevrilir).
+
+> **Expression filtresi istek parametresi TAŞIYAMAZ.** Microservice'te expression'lar
+> `workflowContext.JavascriptEngineInstance` ile eval edilir ve o bağlamda `input` global'i
+> **yoktur** — `value: "input.doctor_id"` yazarsan uç `500 JavaScriptException: input is not
+> defined` verir (`input` workflow table step'inin sözlüğüdür, microservice'in değil).
+> Expression'ın okuyabildiği iki şey vardır: **sabit değerler** (`"'Aktif'"`, `new Date()`) ve
+> **middleware değişkenleri** (`user.id`, `settings.x` — bağlı middleware'in set-user/variable
+> step'leri kurar).
+>
+> **Kimlik kapsaması (tenant/hasta/doktor) bu yüzden parametreyle DEĞİL middleware'le yapılır:**
+> uca auth middleware'ini bağla (`definition.middlewareIds`), owner filtresini
+> `source: 'expression'`, `value: 'user.id'` yap — dinamik filtreyle birlikte sorunsuz çalışır
+> (qm kanıtı: `sy-users-get-my-profile`). Ayrıntı ve tarifler: `platform_guide('middleware')`.
+> Middleware bağlamadan `user.` okuyan expression yazarsan MS-011 uyarır — runtime'da
+> `user is not defined` 500'ü yersin.
+
+> Sayfa tarafındaki karşılığı: kullanıcı ekrandan süzüyorsa (`table` + `filterMode` açık, ya da
+> `datatable` + `isFilterable` kolonlar) uç `enableDynamicFilters: true` olmalı; komponent seçilen
+> koşulları kendi `filters` prop'una yazar ve akış onu uca `filters` parametresi olarak geçirir.
+> Süzme yoksa statik query-string filtreleri yeterlidir — bkz. `platform_guide('page')` Kural 1e.
+
+### `sort` ve `limit` her zaman verilir
+
+**MS-008 (block).** Platform bunları null bırakır; Studio formu ise `data.sort.name` /
+`data.sort.sortValue` (ve `data.limit.name` / `data.limit.limitValue`) diye guard'sız okur —
+aynı bileşende 8 ayrı dereference var — ve **sayfayı komple patlatır** (workflow table step'inde
+`TypeError: Cannot read properties of null (reading 'sortValue')`). Yukarıdaki iki varsayılanı
+her table kaynaklı microservice'e ve her workflow table step'ine koy.
+
+Gateway bu kuralları MS-005/MS-006 olarak istek gitmeden denetler; platform validator'ı da artık alias/fieldId eksiklerini kayıt anında anlaşılır 400 ile reddeder (TableSourceJoinIncomplete / TableSourceSelectFieldIncomplete). Kurallara uyduğun hâlde join
+hatası alırsan `microservice_debug` çıktısıyla raporla — o zaman gerçek bir bug'dır.
+Query source'a kaçış yalnız ham SQL şartsa; query yazarken parser `SELECT` sonrası satır sonu
+kabul etmez — ilk kolon `SELECT` ile aynı satırda olmalı ("Please use a supported query type").
+
+## Middleware'siz uçta çok adımlı yazım ATOMİK DEĞİL (ölçüm 2026-08-19)
+
+`middlewareIds` boş bir uçta, akış non-2xx bitse (`response 422`) ya da bir adım istisna atsa
+(500) bile **önceden yazılan satırlar commit edilir.** Aynı akış herhangi bir middleware'in
+arkasına alındığında her iki durumda da düzgün rollback olur.
+
+| Uç | `response 422` | adım içi istisna (500) |
+|---|:-:|:-:|
+| `middlewareIds: []` | satır **kalıyor** ✕ | satır **kalıyor** ✕ |
+| middleware bağlı | geri alınıyor ✅ | geri alınıyor ✅ |
+
+Sebep: `ExecuteMicroserviceBehavior.HandleMiddlewaresAsync` `middlewares.Count is 0` iken
+`BeginTransactionAsync("execute-microservice")`'e **hiç ulaşmadan** döner. O zaman transaction
+anahtarını içteki `TransactionPipelineBehaviorBase` alır ve iç handler döner dönmez commit eder;
+dış davranışın `IsSuccessStatusCode()` kontrolü ve `RollbackTransactionAsync()` çağrısı kapanmış
+bir transaction üzerinde koşup `catch { }` içinde yutulur.
+
+**Kural:** çok adımlı yazan (response + N satır) bir uç kuruyorsan, **kimlik doğrulaman
+gerekmese bile** ona bir middleware bağla. Tek `variable` adımlı, hiçbir şeyi reddetmeyen bir
+"geçirgen" middleware yeterlidir ve **anonim erişimi bozmaz** (tokensız POST → 200 + satır,
+ölçüldü). Aynı desen sayfa yolunda da vardır (`ExecutePageBehavior`).
+
+Zayıf alternatif: bütün doğrulamaları ilk yazmadan **önce** bitirip yazma bölümünde hiç
+`response`/hata üretmemek — beklenmedik istisnaya karşı korumasızdır.
+
+## Uçlar varsayılan olarak ANONİMDİR
+
+Çalıştırma rotası `[AllowAnonymous]`'tur (`MicroservicesController.cs:90`): `middlewareIds` boş
+bir uç, `Authorization` header'ı hiç olmayan bir isteği kabul eder (ölçüldü: 200 + satır).
+Anonim veri toplama (anket, başvuru, geri bildirim) bu sayede kurulabilir — ama tersi de doğru:
+**koruma yalnız `middlewareIds` ile gelir.**
+
+`roles` bir kapı değildir: `roleIds` dolu + `middlewareIds` boş bir uç tokensız POST'u 200 ile
+kabul etti. Ayrıntı ve doğru rol kapısı tarifi: `platform_guide('middleware')` Tarif 3b.
+
+> **Anonimlik/erişim testi `microservice_execute` + `anonymous: true` ile yapılır.** Bayrak
+> verildiğinde gateway isteğe HİÇBİR `Authorization` header'ı koymaz (varsayılan davranışta
+> kendi token'ını koyar ve test anlamsızlaşır): korumalı uçtan 401, anonim uçtan 200 beklenir.
+> Ham `curl` tercih edersen yolu `microservice_get` yanıtındaki **`resolvedUrl`**'den al —
+> rota `/{project}/m/{application}/{microservice SLUG'ı}`'dır ( `url` alanı rotaya GİRMEZ) ve
+> `Host: <org>.<suffix>` + `X-Environment` başlıkları zorunludur.
+
+## Sık hatalar
+
+- `selectFields: []` + join → tüm alanlar + katlanmış maliyet (MS-001, block)
+- `operation: 'list'` → geçersiz; `get` + `isSingle: false` kullanın (PLT-006)
+- Üst seviye `entityId` eksik (MS-004, warn)
+- Gerekçesiz `source: 'query'` (MS-002, warn)
+- Execute'ta dönen `httpStatus` microservice'in kendi sonucudur — 4xx/5xx görünce önce
+  `microservice_debug` ile hangi adımın ürettiğine bak, tanımı ona göre düzelt.
+- **`microservice_update` / `microservice_patch`, `operation: 'get'` tipli microservice'lerde
+  HER ZAMAN 500 verir** (`The instance of entity type 'Application' cannot be tracked` —
+  platform regresyonu, P-02 olarak düzeltilecek). Ayrım **operasyona** bağlıdır, tool'a değil:
+  `operation: 'create' | 'update' | 'delete' | 'upsert'` kayıtlarında PUT/PATCH sorunsuz çalışır
+  (crm koşumunda `update` uçlarında yeniden doğrulandı, 2026-08-25); yalnız `get` (liste ya da
+  `isSingle`) uçlarında patlar. Get-tipi bir microservice'i değiştirmen gerekiyorsa **`microservice_delete` +
+  `microservice_create`** kullan ve tanımı ilk POST'ta doğru üret; silme kümesini kendi
+  ürettiğin slug listesiyle sınırla. `entity_patch`, `workflow_patch`, `row_update` sağlamdır.

package/dist/resources/guides/middleware.md

@@ -0,0 +1,271 @@
+# Middleware Rehberi
+
+Middleware bir **workflow tipidir** (`type: 'middleware'`): seçildiği microservice ya da sayfa
+çalışmadan **önce** koşar. İki iş için kullanılır: (1) isteği **doğrulamak** ve geçmeyeni
+kestirmeden reddetmek (auth guard), (2) isteğin devamında kullanılacak **değişkenleri kurmak**
+(`user`, `settings`, `permissions`…). Genel amaçlıdır — bir kez yazılır, `middlewareIds` ile
+istenen her uca/sayfaya bağlanır. Buradaki kurallar backend kodundan ve qm projesinin canlı
+kayıtlarından doğrulandı.
+
+**Önce "gerekli mi?" sorusu.** Middleware kurulum listesinin zorunlu maddesi değildir: oturum
+kavramı olmayan bir üründe auth middleware'i, ayar tablosu olmayan bir üründe setter gereksizdir
+(karar tablosu: `platform_guide('getting-started')`). Buna karşılık **kimlik kurduysan eksiksiz
+kur** — giriş sayfası + korunacak her uç ve her sayfa `middlewareIds`'e bağlı. Kısmi koruma,
+sistemi güvenli gösterip açık bırakır.
+
+## Çalışma modeli — bunları bilmeden middleware yazma
+
+1. **Sıra ada bağlıdır.** Bağlı middleware'ler **ada göre alfabetik** koşar — uç yolunda
+   `ExecuteMicroserviceBehavior.cs:96`, sayfa yolunda `ExecutePageBehavior.cs:121`, ikisi de
+   `middlewares.OrderBy(m => m.Name)`. `middlewareIds` dizisinin sırası **hiç okunmaz** (kayıt
+   onu gönderdiğin sırada saklamaz bile). "Önce settings, sonra auth" gibi bir sıra istiyorsan
+   adlandırmayla kur — qm'deki `[SY] Settings Setter` adının `[` öneki bilinçli bir sıralama
+   hilesidir.
+2. **Non-2xx yanıt = kesme.** Bir middleware'in `response` step'i 2xx dışı dönerse hedef
+   microservice/sayfa **hiç çalışmaz**; middleware'in yanıtı (status + body + header +
+   uiActions) istemciye döner. Guard davranışı budur. Response'suz biten middleware sorunsuz
+   geçer (setter deseni).
+   **`redirect` bu kurala DAHİL DEĞİLDİR** — durum kodunu değiştirmez, akış 2xx biter ve hedef
+   normal çalışır. Ayrıntı ve doğru tarif: Tarif 1b (ölçüm 2026-08-19).
+3. **Değişkenler istek boyunca yaşar.** `set-user` / `variable` step'lerinin kurduğu
+   değişkenler istek kapsamındaki `WorkflowContext`'e yazılır (`AddVariable`) ve her akış
+   koşusunun JS motoru o anki değişkenlerden kurulur (`WorkflowRunner` →
+   `JavascriptEngineInstance`). Hedef microservice'in **expression filtrelerinde/alanlarında**
+   ve step ifadelerinde doğrudan okunur (`user.id`, `settings.auth_method`). Ayrıca microservice
+   yolunda middleware'in response gövdesindeki `user` / `data` anahtarları da değişkene
+   terfi eder (`ExecuteMicroserviceBehavior.cs:105` — sayfa yolunda bu terfi YOKTUR).
+
+   **Ama başka bir middleware'in kurduğuna GÜVENME.** Değişken teknik olarak sonraki
+   middleware'e geçer; pratikte kuran middleware `set-user`'a **ulaşmadan** bitebilir (çerez
+   yok, koşul else dalı, erken `response`) ve o zaman `user` hiç tanımlanmaz: okuyan middleware
+   `user is not defined` ile **500** verir — kullanıcı 401 yerine 500 görür, log da sebebi
+   söylemez (crm koşumu 2026-08-25). Kural: **rol/yetki kapısını ayrı bir middleware'e
+   ayırma**, kimlik middleware'inin içine `set-user`'dan sonra koy (Tarif 3b). Zinciri yine de
+   kuracaksan ifadeyi guard'la: `typeof user === 'undefined' ? false : Authorized(user.roles)`.
+   Gateway `set-user` adımı olmadan `user` okuyan middleware'i **MW-003** ile uyarır.
+4. **`input` YOKTUR.** Middleware girdisini HTTP bağlamından okur: `cookie`, `header`,
+   `queryString`, `body`, `triggerSource` (hangi microservice/sayfa tetikledi: type, name,
+   slug, roles, impersonatedUserId). Hazır fonksiyonlar: `system.validateToken(...)`,
+   `system.generateToken(...)`, `crypto.JWT.encode/validate`, `Authorized(user.roles)`,
+   `request.url.searchParams`, `GenerateGuid()`, `UtcNow()`, `system.getPageUrl(slug)` —
+   **tam sözlük ve gerçek örnekler: `platform_guide('expressions')`**.
+5. `returnDtoId` middleware'de **zorunlu değildir** ve `state: 'unready'` normaldir —
+   koşmayı etkilemez.
+6. Middleware transaction içinde koşar: hedef başarısız olursa middleware'in yazdıkları da
+   geri alınır (microservice yolu).
+
+## Yalnız middleware'de geçerli step'ler
+
+| Step | Ne yapar | Kritik alanlar |
+|---|---|---|
+| `set-user` | Oturum kullanıcısını kurar; değişken adı **sabit `user`** | `rule.expression` (JS — değeri üretir), opsiyonel `rule.dataTransferObjectId` (şekli tanımlar) |
+| `variable` (Set Variable) | Keyfî adlı değişken kurar | **`rule.name` = değişken adı**, `rule.expression`, opsiyonel `rule.dataTransferObjectId` |
+| `setcookie` | Yanıta cookie yazar | token tazeleme |
+| `redirect` | Tarayıcıyı yönlendirir (`uiActions`) | **`rule.expression` bir JS ifadesidir ve DEĞERİ yoldur** — aşağıdaki Tarif 1b |
+
+`response` workflow+middleware'de; diğer adımlar (start, condition, code, loop, table, query,
+http, workflow, email, file-upload) üç tipte de geçerlidir. `rule.dataTransferObjectId`
+verilirse değişkenin şeması `workflow_middleware_variables` çıktısında görünür — Studio'nun
+expression editörü ve senin keşif yolun budur; **değişken adını/alanını tahmin etme, oradan oku.**
+
+## Tarif 1 — Auth guard (qm `Authenticate`'ten damıtıldı)
+
+**Önce dönüş şeklini bil:** `system.validateToken(token)` bir `JwtValidationResult` döner —
+`{ isValid: bool, claims: { … } }`. **Claim'ler bir seviye içeridedir** ve anahtarları,
+token'ı üretirken `system.generateToken({ … })`'a verdiğin sözlüğün anahtarlarıdır
+(`claims.userId`, `claims.email` …) — `token.data.id` diye evrensel bir alan YOKTUR.
+
+```
+start → token   [code: return system.validateToken(cookie.<TokenCookie>)]
+token → valid?  [condition: token.data.isValid && token.data.claims.<idAnahtarın>]
+  ├─ else → response 401   (ya da redirect → login sayfası)
+  └─ ok   → userTable [table get: users, filtre source:'expression'
+            value:'token.data.claims.<idAnahtarın>']
+            → var mı? [condition] ─ else → response 401
+            → roles     [table get: user_roles — kullanıcının rol BAĞLARI]
+            → allRoles  [table get: roles — id + slug]
+            → setUser   [set-user: aşağıdaki eşleştirme ifadesi]
+```
+
+### ⚠️ `roles.data[].role_id` bir NESNE DEĞİL, düz FK'dır
+
+`row_list` bir ilişki alanını her zaman `{ id, <displayAlanı> }` nesnesi döndürür (her ilişki
+için join'i kendisi üretir). **Table adımı üretmez:** yalnız `joins` içinde bildirdiğin ilişki
+nesneye çevrilir (`PostgreSqlRelationHandler.ModifyResponse` → `ProcessJoins`), bildirmediğin
+alan **düz FK string'i** olarak gelir. Yani `p.role_id.slug` `undefined`'dır, `.filter(Boolean)`
+onu eler ve `user.roles` **boş dizi** olur → `Authorized(user.roles)` her zaman `false`, rolü
+olan kullanıcı bile 403 alır. Hata yoktur, log yoktur — sessiz yetki kaybı (crm koşumu B-1).
+Gateway bu okumayı **WF-020** ile uyarır.
+
+İki doğru çözüm var:
+
+1. **Adıma join ekle** (`joins: [{ alias: 'roles', entityId: '<roles>', fieldId: '<user_roles.role_id>', path: '<user_roles entityId>.<user_roles.role_id>' }]`)
+   ve `selectFields`'a join'li alanı koy. Bu yolda kök `alias` ZORUNLUDUR (bkz. workflow rehberi
+   — alias'sız join Postgres'te `42601` verir).
+2. **Hedef tabloyu ayrı bir adımla oku ve id üzerinden eşleştir** (join derdi olmayan, her iki
+   şekle de dayanıklı yol):
+
+```js
+(function () {
+  var link = roles.data || [];
+  var all  = allRoles.data || [];
+  var slugs = link.map(function (ur) {
+    var rid = ur.role_id && ur.role_id.id ? ur.role_id.id : ur.role_id;   // iki şekli de karşılar
+    var m = all.filter(function (x) { return x.id === rid; })[0];
+    return m && m.slug;
+  }).filter(function (s) { return !!s; });
+  return Object.assign({}, userTable.data, { roles: slugs, roles_csv: ',' + slugs.join(',') + ',' });
+})()
+```
+
+`roles_csv`'yi de kurmak sayfa akışlarını kolaylaştırır: `Page.user.roles` dizisi set-user
+DTO'sundan düşebilir, CSV metin alanı düşmez (bkz. FLOW-016).
+
+**Rol karşılaştırması SLUG üzerindendir:** `microservice.roles` rolü `{ id, name: '<slug>' }`
+olarak taşır (rolün gerçek adı "Yönetici" olsa bile), `Authorized` bunlarla karşılaştırır —
+`user.roles` da slug taşımalıdır.
+
+Tam gövde iskeleti: `ngapps://examples/middleware-authenticate`. Bağlamak için:
+microservice'te `definition.middlewareIds: ["<middleware workflow id>"]`
+(create/update gövdesinde), sayfada `page_create/page_update` `middlewareIds` parametresi.
+
+## Tarif 1b — Girişe yönlendirme (`redirect` step'inin tam şekli)
+
+Aynı middleware hem sayfaya hem uca bağlıysa, **başarısızlık cevabı ikisinde farklı olmalı**:
+tarayıcıdaki kullanıcı giriş sayfasına gitmeli, uç çağrısı 401 almalı. Ayrımı
+`triggerSource.type` yapar.
+
+`redirect` adımı `rule.expression`'ı **JavaScript olarak değerlendirir ve sonucu yol (path)
+olur** (`RedirectStep.cs`) — sabit bir yol yazacaksan bile **tırnak içinde** yazmalısın, çünkü
+tırnaksız `giris` runtime'da `giris is not defined` verir. Yol daha sonra
+`{scheme}://{host}/view/{proje}/{application}/{path}` mutlak adresine çevrilir
+(`ServeFileBehavior.cs`), yani başına `/` koyma.
+
+```jsonc
+// condition: triggerSource.type === 'page'  → toLogin ; else → response 401
+{ "id": "<GUID>", "name": "toLogin", "type": "redirect",
+  "rule": { "stepType": "redirect", "expression": "'giris'", "isPostBack": false },
+  "branches": [{ "id": "<GUID>", "name": "success", "type": "success", "nextStepId": null }] }
+```
+
+### ⚠️ `redirect` TEK BAŞINA kapı tutmaz — arkasına `response` bağla
+
+**Ölçüm (2026-08-19):** yalnız `redirect` ile biten bir middleware'e bağlı korunan sayfaya
+**tokensız** `GET {app}/p/{slug}` isteği atıldı → **HTTP 200 ve şemanın tamamı döndü**, yanıtta
+`uiActions` bile yoktu. Kontrol ölçümü (koşulsuz `response 401` dönen middleware) aynı sayfada
+401 verdi ve şema sızmadı — yani sayfa middleware'leri koşuyor, sorun `redirect` adımında.
+
+Sebep zincirin iki ucunda:
+
+- `RedirectStep.cs` yalnız bir `UiAction` kaydedip **success dalından devam ediyor**; durum
+  kodunu değiştirmiyor. `response` adımı gelmezse akış 2xx biter.
+- `ExecutePageBehavior` yalnız `!result.IsSuccessStatusCode()` iken kesiyor, dolayısıyla sayfa
+  normal servis ediliyor.
+- `PagesController.HandleResult` `uiActions`'ı **yalnız** `!IsSuccessStatusCode() &&
+  UiActions.Any()` dalında yayınlıyor — middleware geçtiğinde yönlendirme de kayboluyor.
+  Yani response'suz `redirect` ne kapıyı tutar ne tarayıcıyı yönlendirir: tamamen ölüdür.
+
+**Doğru şekil** (ölçülerek doğrulandı — 401 döndü, şema sızmadı, `uiActions` yönlendirmeyi
+taşıdı):
+
+```
+guard → [condition] triggerSource.type === 'page'
+         ├─ if   → [redirect] "'giris'"  →  [response] 401   ← kapıyı BU response tutuyor
+         └─ else → [response] 401
+```
+
+`redirect` adımının `branches[].nextStepId`'si `null` değil, **`response` adımını** göstermeli.
+
+- İfade olduğu için yol dinamik yazılabilir: `"'giris?next=' + encodeURIComponent(request.url.pathname)"`.
+- `page.roleIds` erişim kapatmaz; **`microservice.roles` de kapatmaz** (aşağıdaki Tarif 3b).
+  Korumalı her sayfada yukarıdaki `redirect → response` zinciri kurulmalı ve **tokensız bir
+  istekle 401 verdiği görülerek** kabul edilmeli. Karşılığı: `platform_guide('page')` Kural 8.
+
+## Tarif 3b — Rol kapısı: `microservice.roles` TEK BAŞINA hiçbir şeyi kapatmaz
+
+**Ölçüm (2026-08-19):** `roleIds: ['<admin rol id>']` verilmiş ama `middlewareIds` **boş** bir
+uca **tokensız** POST atıldı → **200**, satır yazıldı.
+
+Rol karşılaştırması yürütme hattında yoktur. Tek mekanizma, middleware ifadelerinde
+çağrılabilen **`Authorized(userRoles)`** yardımcısıdır (`WorkflowContext.cs:411`) ve
+karşılaştırdığı `triggerSource.roles`, `ExecuteMicroserviceBehavior`'ın middleware'e taşıdığı
+`microservice.roles` listesidir. Yani `roles` bir kapı değil, **middleware'e verilen veridir**;
+middleware `Authorized` çağırmazsa tamamen dekoratiftir.
+
+İki tuzak:
+
+- `Authorized`, kaynağın rolleri **boşsa `true` döner** — rolsüz bir uç, kimliği doğrulanmış
+  herkese açıktır.
+- `roles` dolu + `middlewareIds` boş olan uç, Studio'da "rol kapılı" görünür ama **tamamen
+  açıktır**.
+
+```
+guard → … → setUser → [condition] Authorized(user.roles)
+                        ├─ else → [response] 403
+                        └─ ok   → (akış biter, hedef uç çalışır)
+```
+
+Doğrulama: korumalı ucu **kimliksiz** çağır — `microservice_execute` (ya da `microservice_debug`)
+**`anonymous: true`** ile hiçbir `Authorization` header'ı göndermez; korumalı uçtan 401, anonim
+uçtan 200 beklenir. Sayfa tarafının karşılığı `page_runtime_get` + `anonymous: true`
+(`middlewareBlocked` dönmeli ve şema sızmamalı). Bayrağı vermezsen gateway her çağrıya kendi
+token'ını koyar ve test anlamsızlaşır.
+
+## Tarif 2 — Setter (qm `[SY] Settings Setter`: 3 step)
+
+**Yalnız ayarların satır olarak tutulduğu bir tablo varsa ve uçlar gerçekten bu değerleri okuyorsa
+kurulur.** Her projenin ayar middleware'ine ihtiyacı yoktur; okunmayan bir `settings` değişkeni
+sadece fazladan parça demektir. Karar tablosu: `platform_guide('getting-started')`.
+
+```
+start → settings [table get: ayarlar tablosu] → setVar [variable name:'settings',
+        expression: '{ ...settings.data }', dataTransferObjectId: <ayarlar DTO>]
+```
+
+Response yok — tek işi değişken kurmak; bağlandığı her uçta `settings.<alan>` okunur.
+
+## Tarif 3 — Kimlik kapsaması: "sadece benim kayıtlarım" ucu
+
+Kullanıcıya özel veri dönen uçlarda kimliği **istemci parametresinden alma** (sahtelenir);
+middleware'in kurduğu `user`'dan oku:
+
+1. Uca auth middleware'ini bağla (`middlewareIds`).
+2. Filtreyi expression yap: `{ fieldId: <owner alanı>, operator: 'eq',
+   source: 'expression', value: 'user.id', filterType: 'single', isRequired: false }`.
+
+qm kanıtı: `sy-users-get-my-profile` (`id eq user.id`), `qm-document-revision-requests-get`
+(`requested_by eq user.id`). **Bu desen `enableDynamicFilters: true` ile birlikte çalışır** —
+"dinamik filtre + zorunlu kimlik parametresi olmaz" kısıtının çözümü budur: kimlik parametre
+değil, middleware değişkenidir. (Sayfalardaki sabit `patient_id` benzeri geçici çözümlerin
+kalıcı hâli de bu.)
+
+## Tuzaklar
+
+- Expression'daki değişken adı, bağlı middleware'lerden birinin kurduğu adla **birebir**
+  eşleşmeli — eşleşmezse runtime'da `user is not defined` 500'ü. Gateway MS-011 uyarır:
+  `user.` okuyan expression varken `middlewareIds` boşsa warn alırsın.
+- `set-user` adı sabittir; ikinci kullanıcı değişkeni gerekiyorsa `variable` step'i kullan.
+- Middleware'i `workflow_preview` ile test etmek sınırlıdır (HTTP bağlamı preview'da yoktur);
+  gerçek doğrulama, middleware'i bağladığın ucu `microservice_execute` ile çağırmaktır —
+  korumalı uçta tokensız çağrı guard yanıtını (401/redirect) döndürmeli.
+- Middleware yazdıktan sonra `workflow_middleware_variables` ile değişkenin (ve şemasının)
+  gerçekten listelendiğini doğrula.
+- Middleware'li ucu **üye token'ıyla** test etmek için `microservice_execute`'a
+  `headers: { Authorization: 'Bearer <token>' }` ver — gateway o çağrıda kendi admin
+  token'ını KOYMAZ, istek tamamen verdiğin kimlikle gider. Tarayıcı yolunu test etmek için
+  token'ı cookie header'ıyla da geçebilirsin (`headers: { Cookie: '<ad>=<token>' }`).
+
+## Korumalı bir ucu TEST ederken: token ÇEREZDEN okunur
+
+`microservice_execute` ile middleware'li bir ucu denerken `Authorization: Bearer <token>` vermek
+**yetmez** — bu tarifle kurulan auth middleware'i token'ı **çerezten** okur (`cookie.<AD>_Token`).
+Ölçüm (anket projesi, 2026-08-19, `anket-kaydet` ucu):
+
+```
+headers: { "Authorization": "Bearer <token>" }        → 401 unauthorized
+headers: { "Cookie": "ANKET_Token=<token>" }          → 200
+```
+
+Token'ı önce giriş ucundan al (`microservice_execute` ile `giris`), sonra `Cookie` başlığıyla
+korumalı ucu çağır. Çerez adı middleware'in `cookie.<ad>` ifadesindedir; `workflow_get` ile oku,
+tahmin etme. **401 alman middleware'in çalıştığının kanıtıdır** — uç bozuk değildir.

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

@@ -0,0 +1,35 @@
+# Var Olan Projede Güvenli Değişiklik
+
+Gerçek projelerde tek tanım 20-100 bin satır JSON olabilir. **Tam gövdeyi bağlama çekme.**
+
+## Akış
+
+```
+1. project_overview                          → neyi değiştireceğini ve id'sini bul
+2. *_get view:'outline'                      → kaydın iskeleti (step grafı / alan listesi)
+3. *_get view:'part', part:'steps[id=...]'   → yalnız değişecek parçanın tam hâli
+4. *_patch operations:[...]                  → RFC 6902 işlemleri; gateway tam gövdeyi kendi
+                                               belleğinde çeker, patch'i uygular, politika
+                                               kontrolünden geçirir, geri yazar
+5. *_get view:'outline'                      → değişikliği teyit et
+```
+
+`view:'full'` **son çaredir** — yalnız küçük kayıtlarda ya da patch'in kurulamadığı köklü
+yeniden yazımlarda.
+
+## Patch yazım notları
+
+- `path` JSON Pointer'dır: `/steps/2/rule/limit`, `/sourceParameters/selectFields/-` (diziye
+  ekleme), `/fields/5/nullable`.
+- Dizin indekslerini tahmin etme — `view:'outline'` çıktısındaki sıradan ya da
+  `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.
+
+## Uyum kuralları
+
+- Yeni modül eklerken önce `project_overview` ile mevcut adlandırma/ilişki düzenine bak;
+  projenin dilinden kopuk slug/ad üretme.
+- Silmeden önce `entity_dependencies` / `workflow_dependencies`.
+- Studio'da aynı anda düzenleme yapılıyor olabilir: patch, get ile put arasındaki hâlin üstüne
+  yazar. Kritik kayıtlarda değişiklik öncesi kullanıcıya haber ver.