@appaflytech/zeyrek-ai-mcp 0.0.5 → 0.0.7

package/dist/resources/guides/microservice.md

@@ -43,23 +43,119 @@ servis formunda görünür ve `microservice_get` outline görünümünde geri ok
      (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ç).
+     **Alan kapsamı:** view kaynaklı uç `selectFields` boşken yalnız view'ın indekslediği
+     alanları + birincil anahtarı döndürür. İndekslenmemiş kolon (maaş, TCKN) kendiliğinden
+     gelmez; daha fazlasını istiyorsan `selectFields` ile açıkça iste (İK koşusu M-7).
    - `workflow`: çok adımlı iş mantığı gerekiyorsa microservice'i workflow'a bağla
-     (`workflowId`).
+     (`workflowId`). **Yanıtı açık bir DTO sözleşmesine bağlamanın tek yolu da budur** — DTO
+     alanları uçta değil akıştadır; bkz. aşağıda §"Yanıt sözleşmesi (DTO) uca DEĞİL workflow'a
+     bağlanır".
    - `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).
+
+     > **BOŞ STRING PARAMETRE `NULL`'A ÇEVRİLİR — sorgu sessizce 0 satır döner.** Platform
+     > önizleme/çalıştırma parametrelerini normalize ederken boş ya da yalnız boşluktan oluşan
+     > değeri `null` yapar. `WHERE company_id = @company` yazıp `company: ''` gönderirsen koşul
+     > `= NULL` olur ve **hiçbir satırla eşleşmez**: HTTP 200, boş sonuç, hata yok, uyarı yok.
+     > Üç koşuda üst üste ölçüldü (09-02, 09-04 birinci ve dördüncü koşu) ve üçünde de teşhis
+     > ancak `SELECT (@p IS NULL)` gibi bir sonda ile yapılabildi.
+     >
+     > **Parametre listesi ZORUNLUDUR.** `@token` kullanan bir sorguyu `query_create` ile
+     > kaydederken her belirteci `parameters` içinde `{ name, type, value }` olarak bildir. Eksik
+     > bırakılırsa istek **400** döner ve mesaj hangi belirtecin bildirilmediğini adıyla söyler.
+     > (2026-09-04'ten önce aynı durum `500 "Please correct the query syntax."` veriyordu ve SQL'i
+     > suçluyordu; kaydetme yolu gövdeyi önce bir kez çalıştırıp yanıt şemasını ürettiği için
+     > bağlanmamış belirteç sözdizimi hatası gibi görünüyordu.) `value` yalnız kayıt anında
+     > kullanılır: SQL doğrulanır ve `returnScheme` ondan üretilir.
+     > Yorum satırındaki `{{ad}}`/`@ad` belirteçleri parametre sayılmaz — kaydetme yolu
+     > sorguyu yorumlarından arındırdıktan sonra tarar. SQL çalıştırılamazsa kayıt **yine de**
+     > oluşur: `returnScheme` boş kalır ve yanıttaki `message` nedeni söyler; SQL'i düzeltip
+     > `query_update` ile kaydet.
+     >
+     > "Filtre yok" demek istiyorsan iki doğru kalıptan birini kullan:
+     > `(@company IS NULL OR c.company_id::text = @company)` ya da bir sentinel değer
+     > (`'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.
+     >
+     > **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
+     > query adımından çağır; reçete aşağıda §"Kimlik kapsaması × uç kaynağı".
+2. **`selectFields` asla boş bırakılmaz.** Boş = platform TÜM alanları döndürür (view kaynaklı
+   uçta: yalnız view'ın indekslediği alanlar + birincil anahtar); 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).
+3b. **Kayıtlı ucu önizleme:** `microservice_preview` tam gövde istemez — `id` verirsen gateway
+   tanımı platformdan çeker ve yalnız `previewParameters`'ı senden alır (09-04 Y-09). Şekil
+   `{ body: [{…}] }` · `{ queryString: {…} }` · `{ routeParams: {…} }`; **tanımsız bir şekil
+   sessizce yutulur** ve bütün sayaçlar 0 döner (09-02 M-2).
 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`.
+4b. **`query_preview` yazma sorgusunu ÇALIŞTIRIR, GERİ ALIR ve BUNU SÖYLEMEZ.**
+   `INSERT`/`UPDATE`/`DELETE` önizlediğinde `affectedRowCount` **gerçek** sayıyı döndürür ama
+   transaction geri alınır ve tabloda satır kalmaz. **Yanıtta rollback işareti yoktur** — yalnız
+   `{ affectedRowCount, elapsedMilliseconds }` gelir (2026-09-07'de ölçüldü; `rolledBack` alanı
+   yalnız OKUYAN sorgunun yanıt şeklinde var ve orada hep `false`). Yani sayıya bakan çağıran
+   yazdığını sanır: 09-04 4. koşusunda 624 satırlık bir seed böyle "yazıldı" sanıldı. Kalıcı
+   yazma için sorguyu kaydedip query kaynaklı bir uçtan ya da workflow'dan çalıştır; kalıcılığın
+   tek kanıtı sonradan çekilen `row_list`'tir. **Var olan satırlardan türetilmiş satır üretmenin
+   uçtan uca reçetesi** (anahtar sözleşmesi dâhil) `platform_guide('entity')` §"Toplu ve
+   türetilmiş satır" bölümündedir; aynı davranış `platform_guide('workflow')` "Query adımı"
+   bölümünde de yazılıdır.
+
+4c. **Sayfalama toplamı `Total-Count` header'ından gelir.** Sayfalı bir uç kurduğunda toplam
+   kayıt sayısı gövdede değil header'dadır (`microservice_execute` yanıtında `headers` altında,
+   küçük harfle `total-count`). Tabloya bağlarken sayfa göstergesinin okuduğu sözleşme budur;
+   ayrıntı `platform_guide('page')` sayfalama bölümü. Alternatif olarak sorgunun kendisi
+   `COUNT(*) OVER()` ile toplamı satıra koyabilir — o zaman header'a hiç bağımlı kalmazsın.
+
 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.
 
+## Yanıt sözleşmesi (DTO) uca DEĞİL workflow'a bağlanır (MS-018, block)
+
+`returnDtoId` · `parameterDtoId` · `returnBehavior` · `parameterBehavior` **microservice
+komutunda yoktur** (`Create/UpdateMicroserviceCommand`). Gövdeye yazarsan platform 200 döner ve
+alanı sessizce düşürür: uç sözleşmesiz kalır, ne hata ne uyarı gelir (2026-09-09 koşusu `S-2`).
+Gateway bu gövdeyi artık MS-018 ile **platforma hiç göndermeden** reddeder.
+
+Yanıt şeklini kaynak belirler:
+
+| Kaynak | Yanıt şeklini ne belirler | Açık DTO sözleşmesi |
+|---|---|---|
+| `table` | `sourceParameters.selectFields` (+ join alanları) | yok |
+| `query` | sorgunun `returnScheme`'i — kayıt anında SQL'den üretilir | yok |
+| `view` | view'ın indekslediği alanlar + birincil anahtar (`selectFields` ile genişletilir) | yok |
+| `workflow` | akışın `returnDtoId` + `returnBehavior` sözleşmesi | **var** |
+
+Yani "yanıtın alanları şu DTO'dan olsun" diyeceksen uç **workflow kaynaklı** kurulur:
+
+1. `dto_list` ile mevcut DTO'yu bul (platform entity başına DTO üretir) ya da `dto_create` → `dtoId`
+2. `workflow_create` → `returnDtoId: dtoId` + `returnBehavior: 'object' | 'array' | 'primitive'`.
+   WF-002: `type:'workflow'` akışta `returnDtoId` **zorunludur** (yoksa akış `unready` kalır);
+   `returnBehavior`'ı boş bırakırsan gateway `object` ile doldurup `gatewayNormalized` der.
+3. `microservice_create` → `source: 'workflow'` + `workflowId` — DTO alanı **uca yazılmaz**.
+4. Aynı uç `middlewareIds` ile kimlik kapsamasını da taşır (§"Kimlik kapsaması × uç kaynağı").
+
+Kayıtlı bir akışa sözleşmeyi sonradan bağlamak tek çağrıdır:
+`workflow_patch(id: <workflowId>, ops: [{ op: 'add', path: '/returnDtoId', value: <dtoId> }, { op: 'add', path: '/returnBehavior', value: 'object' }])`.
+
+**Sözleşmenin bağlandığını uçtan oku:** workflow kaynaklı uçta `microservice_get` yanıtındaki
+`returnScheme` **DTO'nun alanlarını** taşır; table/query/view kaynaklı uçta şema kaynaktan türer.
+Bağlanmamış sözleşmenin belirtisi budur — uç 200 döner ama `returnScheme` DTO'yu değil kaynağı
+yansıtır (2026-09-09'da ölçüldü: `returnDtoId` yazılan table kaynaklı uçta şema `['id','name']`
+kaldı, DTO'nun beş alanı gelmedi).
+
+Sözleşme yalnız **2xx** yanıtlarda uygulanır: 401/422 döndüren bir `response` adımının gövdesi
+DTO'dan süzülmez (WF-026 — `platform_guide('workflow')` §Hata yolu). Sözleşme **süzer, uydurmaz**:
+`bodyExpression`'ın ürettiği DTO dışı alan yanıttan düşer, DTO'da olup üretilmeyen alan gelmez
+(ölçüm: `gizliNot` alanı yanıtta yok, `slot_minutes` de yok).
+
 ## 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)):
@@ -69,18 +165,35 @@ servis formunda görünür ve `microservice_get` outline görünümünde geri ok
   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)).
+
+- **Upsert eşleşmesi `filters` ile kurulur, PK `fields`'a KONMAZ** (ölçüm: İK koşusu M-4,
+  2026-09-01). PK'yı `fields`'a koyarsan `AlwaysGeneratedFieldCantBeWritten` alırsın. Doğru şekil:
+  `filters`'a `source: "body"` + `isRequired: false` bir id filtresi; gövdede id **varsa** eşleşen
+  satır güncellenir, **yoksa** yeni satır açılır. `isRequired: true` yaparsan "yeni kayıt" yolu
+  kapanır (id gelmeyince uç reddeder).
+
+> **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.
 - **`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
+- `selectFields[]` / `filters[]` öğelerinde platform **`fieldId`** ister; gateway'e **`fieldSlug`**
+  vermen yeter — kök entity'nin alanları için id'yi gateway çözer ve `gatewayResolved` ile bildirir
+  (join'lenen entity'lerin alanlarında hâlâ `fieldId` gerekir). Kök `entityId` de slug olabilir.
+  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"`).
+  (`"'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.
@@ -90,6 +203,11 @@ servis formunda görünür ve `microservice_get` outline görünümünde geri ok
   `{ 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).
+- **Platformun ürettiği alanları `fields` içine koymayın.** Primary key/identity gibi
+  `alwaysGenerated` alanlar yazılırsa istek 400 döner ve hatalı alan slug'larını sayar; bu alanlar
+  create'te platformca üretilir, upsert eşleşmesi gerekiyorsa değer `fields` yerine `filters`ta
+  taşınır. Incremental alanın create/update zamanlaması ayrı tasarım konusudur; mevcut sınır için
+  [`writeOn` tasarımına](../../../../zeyrek-backend/docs/alan-yazma-zamani/01-tasarim.md) bakın.
 
 ```jsonc
 {
@@ -208,6 +326,19 @@ karşılamayı imkânsız kılar. Karar kuralı:
   "isRequired": false, "children": [], "order": 0 }
 ```
 
+> **`source: "query-string"` / `"body"` / `"header"` filtresinde `value` VERİLMEZ** (ölçüm: İK
+> koşusu M-2, 2026-09-01). Değer çağrıdan gelir, parametre adı alan slug'ından türer. `value`
+> yazarsan platform onu JS ifadesi sanıp eval eder → `JavaScriptException: <ad> is not defined`
+> ile 500. `value` yalnız `source: "expression"` ve `"static"` kaynaklarında anlamlıdır. Sabit
+> ön-süzme (tenant, aktiflik) `expression` ile yapılır. Gateway **MS-015** lint'i bu
+> kombinasyonu istek platforma gitmeden yakalar.
+
+> **Dış kaynaklı filtreye (`query-string` / `body` / `header`) `value` yazılmaz.** Değer çağrıdan
+> gelir; tanımdaki `value` çalışma zamanında yok sayılır — parametre gelmezse filtre atlanır ve uç
+> **süzülmemiş** tam liste döner (2026-09-03 öncesinde aynı alan JS olarak değerlendirilip 500
+> veriyordu; İK koşusu M-2). Tanımdan gelen sabit değer istiyorsan `source: 'static'` ya da
+> `'expression'` kullan.
+
 ### 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.
@@ -267,12 +398,69 @@ hem `joins` ile getirin hem `selectFields`'a koyun; ondan sonra `filters[0][fiel
 > (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.
+>
+> **`middlewareIds`'i `microservice_create` GÖVDESİNDE ver, sonradan patch'leme.** Ucu kurup
+> ardından `microservice_patch` ile `/middlewareIds` yazmak her uç için fazladan bir tur demektir:
+> 2026-09-06 koşusunda dokuz uç kuruldu ve dokuz patch çağrısının dokuzu da yalnız bu yolu yazdı
+> (~3 dk). Alan create gövdesinde zaten kabul ediliyor.
 
 > 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.
 
+### Kimlik kapsaması × uç kaynağı — query kaynaklı uç BAĞLAM GÖRMEZ
+
+Yukarıdaki `source: 'expression'` + `value: 'user.id'` kalıbı **yalnız table kaynaklı** uçlarda
+vardır. Agregasyon/rapor uçları query kaynaklı olduğu için aynı kalıp orada yoktur ve
+**parametrelerinin tamamı çağrıdan gelir** — kapsamı gövdeye yazan bir uç sahtelenebilir.
+
+| Uç kaynağı | Parametre/filtre nereden gelir | Kapsam sunucuda zorlanır mı |
+|---|---|---|
+| `table` | `filters[]` · `source:'expression'`, `value:'user.id'` | **Evet** (MS-011 middleware bağını denetler) |
+| `query` | Yalnız çağrının kendisi: **body → query-string → header** (`Query.PrepareQueryParameters` → `FindValue`) | **Hayır** — ifade değerlendirmesi yoktur |
+| `workflow` | Adım ifadeleri; `user.*` bağlı middleware'den gelir | **Evet** (ölçüldü 2026-09-07) |
+| `view` | Arama sözleşmesi (`searchText`) + view'ın indekslediği alanlar | **ölçülmedi** — kapsam şartsa workflow yolunu kullan |
+
+Query parametresine ifade kaynağı **eklenemez**: `parameters[].source` komut şemasında yoktur,
+platform anahtarı sessizce atar (gateway `unmappedMembers` ile söyler) ve kayıtlı şema
+`source: 'body'` kalır. Bu bir eksik değil, modülün tanımı: query modülü SQL seviyesinde çalışan
+ham SQL yüzeyidir, istek bağlamını bilmez.
+
+**Ölçüm (2026-09-07, aynı sorgu, aynı middleware — middleware `user.owner_key = 'OWNER-A'` kurdu):**
+
+| Uç | Gövde | Yanıt |
+|---|---|---|
+| `source:'query'` | `{ owner_key:'OWNER-A' }` | `{ owner_key:'OWNER-A', row_count:3, total:60 }` |
+| `source:'query'` | `{ owner_key:'OWNER-B' }` | `{ owner_key:'OWNER-B', row_count:2, total:300 }` ← **başkasının verisi** |
+| `source:'workflow'` | `{ owner_key:'OWNER-B' }` | `{ owner_key:'OWNER-A', row_count:3, total:60 }` ← gövde **yok sayıldı** |
+| `source:'workflow'` | `{ owner_key:'OWNER-B', min_amount:20 }` | `{ owner_key:'OWNER-A', row_count:2, total:50 }` ← kapsam dışı filtre gövdeden okundu |
+
+#### Reçete: kapsanmış agregasyon ucu
+
+Sorguyu değiştirmeye gerek yok; onu **bir katman yukarıdan** çağırırsın.
+
+1. `query_create` — agregasyonu kapsam parametresiyle yaz:
+   `… WHERE company_id = @company_id AND created_at >= @from`, `parameters` ile her belirteci bildir.
+2. `workflow_create` (`type: 'workflow'`) — start → **query adımı** → response. Adımın bağlaması
+   kapsamı middleware'den, kalan filtreleri gövdeden alır:
+   `rule.expression = "{ company_id: user.company_id, from: input.from }"`
+   (bağlamanın iki yazımı ve canlı motorun tuzağı: `platform_guide('workflow')` §"Query adımı").
+3. `microservice_create` — `source: 'workflow'`, `workflowId`, **`middlewareIds` dolu**.
+4. Doğrula: aynı ucu gövdeye **başka birinin** kapsam değerini yazarak çağır; yanıt değişmemeli.
+
+`middlewareIds` boşken bu akış `500 JavaScriptException: user is not defined` verir (ölçüldü) —
+MS-011'in workflow tarafındaki karşılığıdır ve gateway o dizinin boş kalmasını göremez, çünkü
+uçtan görünen tek şey `workflowId`'dir.
+
+Middleware tarafındaki karşılığı ve `user` değişkenini kuran akış:
+`platform_guide('middleware')` Tarif 3c.
+
+**Her agregasyonu sarmalama.** Kapsam gerekmeyen bir özet (herkese açık istatistik, zaten
+middleware'in reddettiği bir panelde tüm şirketleri gösteren yönetici raporu) düz `source:'query'`
+kalır: fazladan workflow, DTO ve response adımı bedavaya gelmez. Ölçü basit — **bu parametreyi
+çağıran seçebilmeli mi?** Hayırsa sarmala.
+
 ### `sort` ve `limit` her zaman verilir
 
 **MS-008 (block).** Platform bunları null bırakır; Studio formu ise `data.sort.name` /
@@ -285,6 +473,24 @@ Gateway bu kuralları MS-005/MS-006 olarak istek gitmeden denetler; platform val
 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").
+Kayıtlı query'nin `@ad` / `{{ad}}` belirteçleri uçta **body → query-string → header** sırasıyla
+bağlanır; bunun için parametreler query kaydedilirken `parameters` ile bildirilmiş olmalıdır
+(`platform_guide('workflow')` §"Query adımı"). Davranış `query_preview` ile aynıdır.
+
+**`language` AYRILMIŞ bir parametredir.** Ham sorguda `{{language}}` (ya da `@language`)
+kullanırsan platform onu isteğin diliyle kendisi doldurur — `parameters` listesine yazmana gerek
+YOKTUR ve yazarsan doğrulama onu zorunlu saymaz. Çok dilli companion tablosunu elle join eden bir
+raporun dili böyle alınır:
+
+```sql
+SELECT p.id, COALESCE(l.title, d.title) AS title
+FROM products p
+LEFT JOIN products_localization l ON l.product_id = p.id AND l.language = {{language}}
+LEFT JOIN products_localization d ON d.product_id = p.id AND d.language = 'en'
+```
+
+`query_preview` da aynı parametreyi ekleyerek koşar, yani şema çıkarımı `{{language}}` yüzünden
+"eksik parametre" diye patlamaz.
 
 ## Middleware'siz uçta çok adımlı yazım ATOMİK DEĞİL (ölçüm 2026-08-19)
 
@@ -328,6 +534,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)
@@ -336,13 +598,23 @@ kabul etti. Ayrıntı ve doğru rol kapısı tarifi: `platform_guide('middleware
 - `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)
+- Backend zorunlulukları (MS-017, block — istek gitmeden): `name` ve `url` boş olamaz (update'te
+  `slug` da); `queryId`/`entityId`/`workflowId` verilirse boş GUID olamaz; `source: 'expression'`
+  alan ve filtrede `value` dolu; tekil filtrede `fieldId`; `writeOn` yalnız `operation: 'upsert'`
+  ucunda; join'de `entityId` + `fieldId`. Tam katalog: `ngapps://rules/backend-constraints`.
+- Query kaydı (QRY-001, block): `rawQuery`'deki her `@ad` / `{{ad}}` `parameters[]`'ta
+  `{ name, type }` ile bildirilir — yalnız create denetler, update sessiz geçer ve sorgu çalışma
+  anında düşer; `slug`/`rawQuery`/`datasourceId` zorunlu; `outputType` `array` | `object`.
 - 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.
+- **`microservice_update` / `microservice_patch` tüm operasyon tiplerinde çalışır.** Eski
+  "`operation: 'get'` tipli kayıtta HER ZAMAN 500 (`Application cannot be tracked`)" kuralı P-02
+  regresyonuydu; 2026-08-16'da düzeltildi, 2026-09-01 İK koşusunda get ucunda
+  `microservice_patch` ile canlı doğrulandı (M-9). Get-tipi bir microservice'i değiştirmek için
+  artık delete+create gerekmez. `entity_patch`, `workflow_patch`, `row_update` sağlamdır.
+- **`microservice_patch` tam gövde geri yazar: okunan kayıtta olmayan alan SİLİNİR.** 09-04
+  koşusunda gidiş-dönüşte `description` düştü ve MS-014 patch'i bloke etti (Y-16). Gateway artık
+  açıklamasız bir patch gövdesini hiç göndermez; hata mesajı düzeltmeyi verir
+  (`{ "op": "add", "path": "/description", "value": "…" }`). Patch yanıtındaki `silentlyDropped`
+  alanı, gönderilen ama kaydedilmeyen alanları listeler — boş değilse platform bir alanı yutmuş
+  demektir.

package/dist/resources/guides/middleware.md

@@ -7,6 +7,12 @@ kestirmeden reddetmek (auth guard), (2) isteğin devamında kullanılacak **değ
 istenen her uca/sayfaya bağlanır. Buradaki kurallar backend kodundan ve qm projesinin canlı
 kayıtlarından doğrulandı.
 
+> **Middleware `microservice_debug` ağacında görünmez.** `executionItems` yalnız ucun kendi
+> adımlarını izler; middleware ucun ÖNÜNDE ayrı bir workflow olarak koşar. Gateway bu boşluğu
+> yanıta `middlewares` alanı ekleyerek kapatır (uca bağlı middleware workflow'ları, adım
+> özetiyle) — kapı 200 dönerken bile açık kalmış olabilir, adımları oradan oku (ölçüm: 09-04
+> koşusu Y-04, Y-03).
+
 **Ö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
@@ -249,11 +255,35 @@ qm kanıtı: `sy-users-get-my-profile` (`id eq user.id`), `qm-document-revision-
 değil, middleware değişkenidir. (Sayfalardaki sabit `patient_id` benzeri geçici çözümlerin
 kalıcı hâli de bu.)
 
+## Tarif 3c — Agregasyon (query kaynaklı) ucun kapsaması: sorguyu WORKFLOW'dan çağır
+
+Tarif 3 **table kaynaklı** uçlar içindir; expression filtresi orada vardır. Bir KPI/rapor ucu
+ham SQL istediği için query kaynaklıdır ve o yolda expression yoktur: kayıtlı sorgunun
+parametreleri **yalnız çağrıdan** (body → query-string → header) bağlanır, `user` oraya hiç
+girmez. Kapsamı gövdeye koyarsan çağıran başkasının kapsamını yazabilir — 2026-09-07'de ölçüldü:
+middleware `OWNER-A` kimliğini kurmuşken gövdeye `OWNER-B` yazan çağrı `OWNER-B`'nin verisini
+döndürdü.
+
+Kapsam bir katman yukarıda kurulur:
+
+1. Sorguyu kapsam parametresiyle kaydet (`… WHERE company_id = @company_id`).
+2. Bir `type: 'workflow'` akışı aç: start → **query adımı** → response. Adımın bağlaması
+   `rule.expression`'da: `{ company_id: user.company_id, from: input.from }` — kapsam
+   middleware'den, kalan filtreler gövdeden.
+3. Ucu `source: 'workflow'` + `middlewareIds` dolu olarak kur.
+
+Ölçüm: gövdeye kasten yanlış `company_id` yazıldığında yanıt değişmedi; `middlewareIds` boş
+bırakıldığında akış `500 JavaScriptException: user is not defined` verdi. Reçetenin tamamı
+`platform_guide('microservice')` §"Kimlik kapsaması × uç kaynağı", bağlamanın yazım tuzağı
+`platform_guide('workflow')` §"Query adımı".
+
 ## 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.
+  `user.` okuyan expression varken `middlewareIds` boşsa warn alırsın. **Aynı 500'ü workflow
+  kaynaklı uçta gateway GÖREMEZ** (uçtan görünen tek şey `workflowId`'dir): `user.*` okuyan bir
+  akışı bağladığın uçta `middlewareIds`'i doldurmayı sen garanti edeceksin.
 - `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 —
@@ -265,6 +295,17 @@ kalıcı hâli de bu.)
   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>' }`).
 
+## Ön koşul: uygulamanın kullanıcısı olmalı
+
+Middleware bağlamadan önce `users` tablosunda satır olduğundan emin ol — `row_list('users')` tek
+çağrı. Yeni projede o tablo **boş** gelir ve Studio operatörü uygulamanın kullanıcısı değildir;
+kapı bağlanınca her istek 401 döner ve bu ancak sayfa boş açılınca fark edilir (09-02 ve 09-04
+koşularında ikisinde de yaşandı).
+
+İlk kullanıcıyı açmanın desteklenen tek yolu bootstrap desenidir:
+`platform_guide('getting-started')` §"İlk kullanıcıyı kim açar?". Kısa yol arama — bakım uçları
+(`Sync*`) ürün yüzeyinin parçası değildir ve gateway onları araç olarak yayınlamaz.
+
 ## Korumalı bir ucu TEST ederken: token ÇEREZDEN okunur
 
 `microservice_execute` ile middleware'li bir ucu denerken `Authorization: Bearer <token>` vermek
@@ -279,3 +320,50 @@ 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.
+
+## Korumalı SAYFAYI görsel doğrulama — jeton bağlama hiç girmeden
+
+Giriş ucunun yanıtındaki jeton gateway tarafından maskelenir (`access_token: "***"`), yani jetonu
+okuyup elle taşıyamazsın — ve taşımaya çalışmak uygulamanın yanıt sözleşmesini geçici olarak
+bozmak demektir (ölçüm 2026-09-04, benchmark 4. koşu). Doğru yol dört adımdır:
+
+1. `microservice_execute` ile giriş ucunu çağır. Yanıtta jeton `***`, ama `tokenRefs` alanında
+   maskelenen her JWT için kısa ömürlü bir referans döner: `{ "body.access_token": "tok_…" }`.
+2. `page_screenshot` (ya da `page_runtime_get`) çağrısına `asUser: "tok_…"` ver. Gateway referansı
+   kendi içinde çözer; jeton ne yanıta ne günlüğe girer. Referans 15 dakika geçerlidir, süresi
+   dolarsa çağrı **hata verir** — sessizce kimliksiz isteğe düşmez.
+3. Uygulamanın kendi oturum çerezi ayrı bir addaysa (`cookie.CORE_Token` gibi) onu
+   `cookies: { "CORE_Token": "…" }` ile ekle; `asUser` her zaman `NG_AccessToken` adıyla taşınır.
+4. Kapının gerçekten kapalı olduğunu `page_runtime_get(anonymous: true)` ile kanıtla: beklenen
+   sonuç `middlewareBlocked: true` + 401'dir.
+
+
+## Korumalı ucu teşhis etmek: `asUser`
+
+Bir uca `middlewareIds` bağladığın anda `microservice_execute`, `microservice_preview` ve
+`microservice_debug` gateway'in **servis jetonuyla** gider ve o jeton uygulamanın kendi
+`users` tablosuna çözülmez — üçü de 401 döner. Ölçüldü 2026-09-05: agregasyonlar korumaya
+alındıktan sonra kuru koşu ve adım adım teşhis araçlarının ikisi de kullanılamaz hâle geldi.
+
+Üçü de artık `asUser` (ve gerekiyorsa `cookies`) alır ve jetonu **hem** `Authorization` başlığında
+**hem** `NG_AccessToken` çerezinde taşır — middleware jetonu çerezden okuduğu için tek kanal
+yetmiyordu:
+
+```jsonc
+// 1) uygulamanın kendi giriş ucunu anonim çağır, jeton referansını al
+{ "tool": "microservice_execute", "application": "<app>", "microservice": "sign-in",
+  "anonymous": true, "body": { "email": "…", "password": "…" } }
+// → tokenRefs: { "body.access_token": "tok_…" }   (jeton hiç görünmez, 15 dk geçerli)
+
+// 2) korumalı ucu O KİMLİKLE çalıştır
+{ "tool": "microservice_debug", "application": "<app>", "microservice": "funnel",
+  "asUser": "tok_…", "body": { … } }
+```
+
+Uygulaman jetonu kendi çerez adından okuyorsa (`CORE_Token` gibi) `cookies: { CORE_Token: "<jwt>" }`
+ver. `anonymous: true` ile `asUser` birlikte verilemez — biri kimliksiz isteği, diğeri belirli bir
+üyenin kimliğiyle atılan isteği ister.
+
+`microservice_debug` yanıtındaki `middlewareNote` artık gerçeği söyler: middleware koştu ve
+geçirdi mi, yoksa isteği kesti mi. Not eskiden ucun LİSTE kaydına bakıyordu ve liste DTO'su
+`middlewareIds` taşımadığı için bağlı bir uçta bile "bağlı değil" diyordu.

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ı