@appaflytech/zeyrek-ai-mcp 0.0.4 → 0.0.6

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.