@appaflytech/zeyrek-ai-mcp 0.0.11 → 0.0.13

package/dist/resources/examples/workflow-call-workflow.json

@@ -0,0 +1,115 @@
+{
+  "_meta": {
+    "synthetic": false,
+    "note": "workflow adımı: bir akışın içinden BAŞKA bir kayıtlı akışı çağırır (alt akış). İki şey burada tuzaktır ve ikisi de ölçüldü: hedef ADLA değil rule.workflowId ile (GUID) seçilir, ve alt akışın girdisi YALNIZ rule.expression ile bağlanır — payloadExpression / customParameters kaydedilir ama SESSİZCE yok sayılır. Bu akış lokal stack'te koşturuldu (test projesi, development, 2026-09-16): iki yol da ayrı ayrı ölçüldü.",
+    "harvestedFrom": "canlı ölçüm 2026-09-16 (workflow_preview, test/development) + kod: zeyrek-backend WorkflowStep.cs:22-49, StepRule.cs:23,79-80"
+  },
+  "_rules": {
+    "hedef": "rule.workflowId bir GUID'dir — slug ya da ad DEĞİL. Id'yi workflow_list ile alın. Alt akış aynı application içinde kayıtlı olmalıdır (preview'daki kaydedilmemiş bir akış çağrılamaz).",
+    "girdi": "GİRDİ YALNIZ rule.expression İLE BAĞLANIR ve hedefin parameter DTO'sunun şeklini üretmelidir: \"({ orderId: load_order.data.id })\". Yürütücü ifadeyi yalnız hedef akışın parameterDtoId'si VARSA değerlendirir (WorkflowStep.cs:27-31).",
+    "sessizDusme": "ÖLÇÜLDÜ 2026-09-16: aynı adıma payloadExpression yazıldığında alan kaydedilir, istek 200 döner, adım hatasız görünür — ama alt akış GİRDİSİZ koşar. Preview'da kanıtı şudur: adımın input satırı yalnız { source: 'workflow', member: 'parameter' } olur, expression ve value alanları HİÇ GELMEZ. customParameters da aynı şekilde yok sayılır (36/S-29).",
+    "adAyniAlanUcAnlam": "rule.expression alanı üç adımda ÜÇ FARKLI şey demektir ve adı yanıltır: workflow adımında GİRDİ EŞLEMESİ, code adımında GÖVDE, query adımında PARAMETRE BAĞLAMA. Bir code adımından kopyalayıp workflow adımına yapıştırmayın.",
+    "cikti": "Alt akışın response gövdesi bu adımın çıktısı olur: <adım>.data. Ayrı bir 'çıktı değişkeni' alanı yoktur. İfade bağlamında adım { data, meta, error } şeklindedir (http adımıyla aynı sarmal).",
+    "ciktiyiDtoBicer": "ÖLÇÜLDÜ: alt akışın returnDtoId'si çıktıyı BİÇER. Alt akış bodyExpression'ında DTO'da olmayan bir anahtar dönerse o anahtar yanıttan sessizce düşer — çağıranda eksik alan görürseniz önce alt akışın return DTO'suna bakın.",
+    "hata": "Alt akış patlarsa bu adım fail dalına gider ve alt akışın son hatalı adımının istisnası taşınır (WorkflowStep.cs:49).",
+    "preview": "workflow_preview alt akışı children[] içinde kind:'subWorkflow' olarak TAM adım iziyle döner — girdinin gerçekten bağlanıp bağlanmadığını oradan görürsünüz."
+  },
+  "calleeDefinition": {
+    "name": "Fatura Oluştur",
+    "slug": "fatura-olustur",
+    "description": "Sipariş id'siyle fatura kaydı açar ve fatura numarasını döner.",
+    "type": "workflow",
+    "parameterDtoId": "<girdi DTO id: { orderId: string }>",
+    "parameterBehavior": "object",
+    "returnDtoId": "<çıktı DTO id: { faturaNo: string }>",
+    "returnBehavior": "object",
+    "steps": [
+      {
+        "id": "<GUID-C1>",
+        "name": "Start",
+        "type": "start",
+        "description": "Alt akışı başlatır.",
+        "branches": [{ "id": "<GUID-C2>", "name": "start", "type": "success", "nextStepId": "<GUID-C3>" }]
+      },
+      {
+        "id": "<GUID-C3>",
+        "name": "Response",
+        "type": "response",
+        "description": "Üretilen fatura numarasını döner; çağıran bunu <adım>.data ile okur.",
+        "rule": {
+          "stepType": "response",
+          "bodyExpression": "({ faturaNo: 'FTR-' + input.orderId })",
+          "httpStatusCode": 200
+        },
+        "branches": []
+      }
+    ]
+  },
+  "definition": {
+    "name": "Sipariş Kapat",
+    "slug": "siparis-kapat",
+    "description": "Siparişi kapatır ve fatura akışını çağırarak fatura numarasını döner.",
+    "type": "workflow",
+    "parameterDtoId": "<girdi DTO id: { orderId: string }>",
+    "parameterBehavior": "object",
+    "returnDtoId": "<çıktı DTO id: { faturaNo: string }>",
+    "returnBehavior": "object",
+    "steps": [
+      {
+        "id": "<GUID-1 üret: crypto.randomUUID()>",
+        "name": "Start",
+        "type": "start",
+        "description": "Akışı başlatır.",
+        "branches": [
+          { "id": "<GUID-2>", "name": "start", "type": "success", "nextStepId": "<GUID-3>" },
+          { "id": "<GUID-9>", "name": "global-error", "type": "global-error", "nextStepId": "<GUID-8>" }
+        ]
+      },
+      {
+        "id": "<GUID-3>",
+        "name": "fatura_akisi",
+        "type": "workflow",
+        "description": "Fatura oluşturma akışını çağırır; sipariş id'sini girdi olarak geçer.",
+        "rule": {
+          "stepType": "workflow",
+          "workflowId": "<workflow_list'ten alınan hedef akış id'si>",
+          "expression": "({ orderId: input.orderId })"
+        },
+        "branches": [
+          { "id": "<GUID-4>", "name": "success", "type": "success", "nextStepId": "<GUID-6>" },
+          { "id": "<GUID-5>", "name": "fail", "type": "fail", "nextStepId": null }
+        ]
+      },
+      {
+        "id": "<GUID-6>",
+        "name": "Response",
+        "type": "response",
+        "description": "Alt akışın ürettiği fatura numarasını 200 ile döner.",
+        "rule": {
+          "stepType": "response",
+          "bodyExpression": "({ faturaNo: fatura_akisi.data.faturaNo })",
+          "httpStatusCode": 200
+        },
+        "branches": []
+      },
+      {
+        "id": "<GUID-8>",
+        "name": "onError",
+        "type": "response",
+        "description": "Akış patlarsa hata kodunu ve mesajını 500 ile döner.",
+        "rule": {
+          "stepType": "response",
+          "bodyExpression": "({ code: error.code, message: error.message })",
+          "httpStatusCode": 500
+        },
+        "branches": []
+      }
+    ]
+  },
+  "usage": {
+    "kurulumSirasi": "1) Alt akışın girdi/çıktı DTO'larını aç, 2) alt akışı workflow_create ile KAYDET, 3) dönen id'yi çağıranın rule.workflowId alanına yaz. Kaydedilmemiş bir akış çağrılamaz.",
+    "girdiKontrolu": "workflow_preview çıktısında çağıran adımın input satırına bakın: expression ve value doluysa girdi bağlanmıştır. Yalnız { source: 'workflow', member: 'parameter' } görüyorsanız girdiniz YOK SAYILDI — büyük olasılıkla payloadExpression yazdınız, rule.expression'a taşıyın.",
+    "yanlisYol": "YANLIŞ: rule: { stepType: 'workflow', workflowId: '…', payloadExpression: \"({ orderId: 1 })\" } — kaydedilir, 200 döner, alt akış girdisiz koşar. DOĞRU: aynı ifadeyi rule.expression'a koyun.",
+    "dogrulama": "workflow_preview; yanıtta children[] içinde kind:'subWorkflow' girişinin input alanı beklediğiniz nesne olmalı."
+  }
+}

package/dist/resources/examples/workflow-http-step.json

@@ -0,0 +1,84 @@
+{
+  "_meta": {
+    "synthetic": false,
+    "note": "http adımı: dış (ya da platformun kendi) HTTP ucunu çağırır. Adımın üç ayrı alanı vardır — urlExpression (JS ifadesi, STRING üretir), httpMethod, contentType — ve gövde AYRI BİR ALAN DEĞİLDİR: payloadExpression tek bir ifadeyle { header, body, queryString } ÜÇÜNÜ BİRDEN taşımak zorundadır. Bu akış lokal stack'te koşturuldu (test projesi, development, 2026-09-16): platformun kendi table ucu çağrıldı, 200 döndü ve çıktı şekli ölçüldü.",
+    "harvestedFrom": "canlı ölçüm 2026-09-16 (workflow_preview, test/development) + kod: zeyrek-backend HttpStep.cs:26-99,143-158, StepRule.cs:47-51"
+  },
+  "_rules": {
+    "payloadExpression": "ÜÇ ANAHTAR DA ZORUNLUDUR, boş olsalar bile: ({ body: {}, header: {}, queryString: {} }). Yürütücü üçüne de C# dynamic üye erişimiyle bakar (HttpStep.cs:32,42,59), eksik anahtar adımı RuntimeBinderException ile düşürür. Ölçülen mesaj birebir: \"'System.Dynamic.ExpandoObject' does not contain a definition for 'queryString'\". Bu bir doğrulama hatası değildir; adım fail dalına gider.",
+    "urlExpression": "Bu bir İFADEDİR, düz metin değil: sabit adres tırnak içinde yazılır ('https://api.example.com/v1/rates'), dinamik adres ifadeyle kurulur ('https://api.example.com/orders/' + input.orderId). Tırnaksız yazarsan JS onu değişken sanır ve adım 'x is not defined' ile düşer.",
+    "output": "ÖLÇÜLDÜ 2026-09-16 — ŞEMAYLA ÇELİŞİR. workflow_step_schema('http') returnScheme'i kök seviyede { httpStatusCode, data } ilan ediyor, AMA ifade bağlamında adım { data, meta: { elapsedTime, httpStatusCode, totalCount }, error } şeklindedir: gövde <adım>.data, durum kodu <adım>.meta.httpStatusCode. <adım>.httpStatusCode UNDEFINED döner. Şemaya göre yazarsan sessizce boş değer alırsın.",
+    "responseParsing": "Yanıt gövdesi JSON'a benziyorsa ayrıştırılır, benzemiyorsa SESSİZCE boş nesne ({}) olur (HttpStep.cs:92) — XML dönen uçtan veri alamazsın ve hata da almazsın (36/W-2, açık bulgu). Ham metne erişmenin yolu yoktur.",
+    "contentType": "KOD OKUMASINDAN (bu koşuda ölçülmedi): 'application/json' → JsonContent; 'application/x-www-form-urlencoded' → düz anahtar/değer; BAŞKA BİR DEĞER ya da BOŞ → gövde body.ToString() ile gider ve nesne gövdesi için bu, tip adının kendisidir (HttpStep.cs:63-85). POST/PUT'ta contentType'ı AÇIKÇA yazın.",
+    "stepName": "Adım çıktısına ADIM ADIYLA erişilir, o yüzden ad geçerli bir JS tanımlayıcısı olmalıdır. Boşluklu ad ('Call Roles') ifadede çağrılamaz; ölçümde call_roles is not defined ile düştü. snake_case kullanın.",
+    "authorization": "Token gerekiyorsa header anahtarına koyun: header: { Authorization: 'Bearer ' + system.token }. Adım platformun kendi kimliğini OTOMATİK taşımaz."
+  },
+  "definition": {
+    "name": "Kur Çek",
+    "slug": "kur-cek",
+    "description": "Dış servisten güncel kuru çeker ve gövdesini döner.",
+    "type": "workflow",
+    "returnDtoId": "<çıktı DTO id: { kur: number }>",
+    "returnBehavior": "object",
+    "steps": [
+      {
+        "id": "<GUID-1 üret: crypto.randomUUID()>",
+        "name": "Start",
+        "type": "start",
+        "description": "Akışı başlatır.",
+        "branches": [
+          { "id": "<GUID-2>", "name": "start", "type": "success", "nextStepId": "<GUID-3>" },
+          { "id": "<GUID-9>", "name": "global-error", "type": "global-error", "nextStepId": "<GUID-8>" }
+        ]
+      },
+      {
+        "id": "<GUID-3>",
+        "name": "kur_servisi",
+        "type": "http",
+        "description": "Kur servisini çağırır; yanıtın gövdesi bir sonraki adıma geçer.",
+        "caution": "Dış bağımlılık: servis yavaşlarsa akış bekler, XML dönerse çıktı sessizce boş nesne olur.",
+        "rule": {
+          "stepType": "http",
+          "urlExpression": "'http://zeyrek-test.zeyrek.local/api/test/m/test/olcum-roller'",
+          "httpMethod": "GET",
+          "contentType": "application/json",
+          "payloadExpression": "({ body: {}, header: { 'X-Environment': 'development' }, queryString: {} })"
+        },
+        "branches": [
+          { "id": "<GUID-4>", "name": "success", "type": "success", "nextStepId": "<GUID-6>" },
+          { "id": "<GUID-5>", "name": "fail", "type": "fail", "nextStepId": null }
+        ]
+      },
+      {
+        "id": "<GUID-6>",
+        "name": "Response",
+        "type": "response",
+        "description": "Çekilen gövdeyi ve HTTP durum kodunu 200 ile döner.",
+        "rule": {
+          "stepType": "response",
+          "bodyExpression": "({ veri: kur_servisi.data, durum: kur_servisi.meta.httpStatusCode })",
+          "httpStatusCode": 200
+        },
+        "branches": []
+      },
+      {
+        "id": "<GUID-8>",
+        "name": "onError",
+        "type": "response",
+        "description": "Akış patlarsa hata kodunu ve mesajını 500 ile döner.",
+        "rule": {
+          "stepType": "response",
+          "bodyExpression": "({ code: error.code, message: error.message })",
+          "httpStatusCode": 500
+        },
+        "branches": []
+      }
+    ]
+  },
+  "usage": {
+    "postGovdesi": "POST için: { stepType: 'http', urlExpression: \"'https://api.example.com/orders'\", httpMethod: 'POST', contentType: 'application/json', payloadExpression: \"({ body: { orderId: input.orderId, adet: 2 }, header: { Authorization: 'Bearer ' + system.token }, queryString: {} })\" }",
+    "queryStringKullanimi": "Sorgu parametresi payloadExpression'ın queryString anahtarına konur, URL'e elle eklenmez: queryString: { from: 'USD', to: 'TRY' }.",
+    "onlemliOkuma": "Gövdeyi <adım>.data ile, durum kodunu <adım>.meta.httpStatusCode ile okuyun; şemanın vaat ettiği <adım>.httpStatusCode undefined'dır (ölçüldü 2026-09-16).",
+    "dogrulama": "workflow_preview ile koşturun ve yanıttaki steps[] içinde http adımının input satırlarına bakın: source:'url' ve source:'payload' iki ayrı satır olarak görünür; hata varsa runtimeErrors alanı adımı adıyla sayar."
+  }
+}

package/dist/resources/examples/workflow-loop-step.json

@@ -0,0 +1,132 @@
+{
+  "_meta": {
+    "synthetic": false,
+    "note": "loop adımı: bir dizinin her öğesi için TEK bir çocuk adım koşturur. Üç şey tuzaktır ve üçü de ölçüldü: çocuk kuralının alanı TEKİLDİR (rule.stepRule, 'children' değil), çocuğun tipi loop'un kendi rule.stepType alanında yazar, ve geçerli öğeye erişim aracı olan loopItem YALNIZ loop'un kendi değerlendirdiği ifadelerde vardır — code çocuğunda YOKTUR. Lokal stack'te koşturuldu (test projesi, development, 2026-09-16).",
+    "harvestedFrom": "canlı ölçüm 2026-09-16 (workflow_preview, test/development) + kod: zeyrek-backend LoopStep.cs:38,45-56,73-77, WorkflowDto.cs:399"
+  },
+  "_rules": {
+    "cocukAlaniTekil": "Çocuğun kural gövdesi rule.stepRule alanına konur — TEKİL. 'children' yazarsan domain tarafı boş kalır, çocuk null kuralla koşar ve loop NullReferenceException verir; hata mesajı yanıltıcı biçimde arrayExpression'ı suçlar (WF-018 lint'i bunu istek gitmeden keser).",
+    "cocukTipi": "Çocuğun tipi loop'un KENDİ rule.stepType alanındadır ('table', 'code', 'http'…), stepRule'un içinde değil. stepRule kendi stepType'ını da taşır; ikisini aynı yazın.",
+    "dizi": "rule.arrayExpression diziyi üreten bir JS ifadesidir: 'input.kalemler || []'. Boş bırakılamaz (WF-018 block). Dizi değilse ya da null ise döngü koşmaz.",
+    "loopItem": "ÖLÇÜLDÜ 2026-09-16 — SINIRLI. Geçerli öğe loopItem adıyla YALNIZ loop'un kendi değerlendirdiği ifadelerde görünür: table çocuğunun filtre ve alan ifadeleri bunu görür (ölçüldü: filtre 'loopItem.slug' → 'super-admin'). AMA code çocuğu kendi JS motorunu kurar ve orada loopItem TANIMSIZDIR: adım 'Error: loopItem is not defined' ile düşer (motorun globalleri input · system · file · crypto · convert · Log · UtcNow …). Her öğe için hesap yapmanız gerekiyorsa hesabı arrayExpression'da önden yapın ya da çocuğu table/http adımı olarak kurun.",
+    "filtredeAlias": "Çocuk table adımının filtresi alias TAŞIMAK ZORUNDADIR ('alias': '<entity alias>', 'path': ''). Alias'sız filtre SESSİZCE DÜŞER: ifade doğru değerlendirilir (preview input satırında loopItem.kod'un değeri görünür) ama sorguya uygulanmaz ve her yineleme AYNI ilk satırı döner — hata yoktur, veri yanlıştır. Ölçüldü 2026-09-16: alias'sız iki yineleme de ilk rolü döndü, alias eklenince her yineleme kendi satırını döndü. Aynı tuzak düz table adımında da geçerlidir (platform_guide('workflow') §'Table adımının filtresi').",
+    "indeksYok": "İndeks değişkeni YOKTUR — yalnız loopItem vardır. Sıra numarası gerekiyorsa diziyi arrayExpression'da üretin: 'input.kalemler.map((k, i) => ({ ...k, sira: i }))' ve çocukta loopItem.sira kullanın.",
+    "cikti": "Çıktı [{ item, result }] dizisidir: item o yinelemenin öğesi, result çocuğun o yinelemedeki çıktısı. İfadede <adım>.data ile okunur; sonuçları düzleştirmek için <adım>.data.map(r => r.result). Bir yineleme düşerse o girişte result HİÇ OLUŞMAZ, yalnız item kalır.",
+    "preview": "workflow_preview her yinelemeyi children[] içinde kind:'loopIteration' olarak ayrı ayrı gösterir — hangi öğede düştüğünü oradan görürsünüz."
+  },
+  "definition": {
+    "name": "Kalemleri İşle",
+    "slug": "kalemleri-isle",
+    "description": "Gelen kalem listesinin her satırı için stok kaydını okur ve sonuçları toplu döner.",
+    "type": "workflow",
+    "parameterDtoId": "<girdi DTO id: { kalemler: array }>",
+    "parameterBehavior": "object",
+    "returnDtoId": "<çıktı DTO id: { sonuclar: array }>",
+    "returnBehavior": "object",
+    "steps": [
+      {
+        "id": "<GUID-1 üret: crypto.randomUUID()>",
+        "name": "Start",
+        "type": "start",
+        "description": "Akışı başlatır.",
+        "branches": [
+          {
+            "id": "<GUID-2>",
+            "name": "start",
+            "type": "success",
+            "nextStepId": "<GUID-3>"
+          },
+          {
+            "id": "<GUID-9>",
+            "name": "global-error",
+            "type": "global-error",
+            "nextStepId": "<GUID-8>"
+          }
+        ]
+      },
+      {
+        "id": "<GUID-3>",
+        "name": "her_kalem",
+        "type": "loop",
+        "description": "Her kalem için stok satırını okur; kalem koduna loopItem ile erişir.",
+        "caution": "Çocuk adım tek bir tanedir ve her yinelemede ayrı koşar; büyük listede tur sayısı kadar sorgu demektir.",
+        "rule": {
+          "stepType": "table",
+          "arrayExpression": "input.kalemler || []",
+          "stepRule": {
+            "stepType": "table",
+            "entityId": "<stoklar entity id>",
+            "datasourceId": "<datasource id>",
+            "operation": "get",
+            "isSingle": true,
+            "alias": "stoklar",
+            "selectFields": [
+              {
+                "alias": "stoklar",
+                "fieldSlug": "adet",
+                "path": "",
+                "fieldId": "<adet alanı id>"
+              }
+            ],
+            "filters": [
+              {
+                "alias": "stoklar",
+                "path": "",
+                "fieldSlug": "kod",
+                "operator": "eq",
+                "value": "loopItem.kod",
+                "fieldId": "<kod alanı id>"
+              }
+            ],
+            "joins": []
+          }
+        },
+        "branches": [
+          {
+            "id": "<GUID-4>",
+            "name": "success",
+            "type": "success",
+            "nextStepId": "<GUID-6>"
+          },
+          {
+            "id": "<GUID-5>",
+            "name": "fail",
+            "type": "fail",
+            "nextStepId": null
+          }
+        ]
+      },
+      {
+        "id": "<GUID-6>",
+        "name": "Response",
+        "type": "response",
+        "description": "Her kalemin okunan stok sonucunu tek listede 200 ile döner.",
+        "rule": {
+          "stepType": "response",
+          "bodyExpression": "({ sonuclar: her_kalem.data.map(r => ({ kod: r.item.kod, adet: r.result.adet })) })",
+          "httpStatusCode": 200
+        },
+        "branches": []
+      },
+      {
+        "id": "<GUID-8>",
+        "name": "onError",
+        "type": "response",
+        "description": "Akış patlarsa hata kodunu ve mesajını 500 ile döner.",
+        "rule": {
+          "stepType": "response",
+          "bodyExpression": "({ code: error.code, message: error.message })",
+          "httpStatusCode": 500
+        },
+        "branches": []
+      }
+    ]
+  },
+  "usage": {
+    "olculenCikti": "[{ item: { kod: 'K-1' }, result: { adet: 12 } }, …] — item öğe, result çocuğun çıktısı.",
+    "indeksEklemek": "arrayExpression: \"(input.kalemler || []).map((k, i) => ({ ...k, sira: i }))\" ve çocukta loopItem.sira.",
+    "codeCocugu": "code çocuğunda loopItem YOKTUR (ölçüldü). Her öğe için hesap gerekiyorsa hesabı arrayExpression'a taşıyın: \"(input.kalemler || []).map(k => ({ ...k, tutar: k.fiyat * k.adet }))\" — böylece çocuk yalnız yazma/okuma yapar ve loopItem.tutar'a bakar.",
+    "dogrulama": "workflow_preview; yanıtta loop adımının output'u [{item, result}] dizisi olmalı ve children[] her yineleme için bir kind:'loopIteration' girişi taşımalı. Bir girişte result yoksa o yineleme düşmüştür — runtimeErrors alanına bakın.",
+    "aliasTuzagi": "Filtreye alias koymayı unutursanız döngü hatasız koşar ve HER yineleme aynı satırı döner; preview'da fark etmek için children[] içindeki her yinelemenin output'unu karşılaştırın."
+  }
+}

package/dist/resources/guides/entity.md

@@ -105,9 +105,11 @@ nullable, gateway'den görünmez:
 
 **İki farklı anahtar, karıştırma:**
 
-- **id** → `page_create/page_update` ve `microservice_create` `roleIds` alanı (gövdede `roles` diye bir
-  yazma alanı YOKTUR; `microservice.roles` middleware'de RUNTIME şeklidir, `{ id, name: '<slug>' }`).
-  `role_list`ten okunur.
+- **id** → `page_create/page_update` ve `microservice_create` `roleIds` alanı; `role_list`ten okunur.
+  **Yazma gövdesinde alan adı `roleIds`, okuma şeklinde `roles`** (`{ id, name: '<slug>' }`) — ve
+  `microservice_patch` **okuma şeklini** yamalar, yani orada yol `/roles`'tır
+  (`platform_guide('microservice')` §"Patch belgesi okuma şeklidir"). `microservice.roles`
+  middleware'de de bu runtime şeklidir.
 - **slug** → `Authorized(user.roles)`, middleware'in kurduğu `user.roles` / `Page.user.roles`.
   Platformun get-user sorgusu `roles`'u `user_roles` üzerinden **slug dizisi** olarak üretir
   (`SELECT … ARRAY(SELECT r.slug FROM roles r INNER JOIN user_roles ur …)`), auth middleware
@@ -233,6 +235,38 @@ olduğu için serbest metindir; `course_assignments.semester` (Güz/Bahar/Yaz) e
   tablodaki değerler `valueOptions` içinde yoksa migration `check constraint ... is violated` ile
   düşer. Sıra: **önce satırları kanonik değerlere taşı, sonra alanı enum yap.**
 
+### Tek bir enum değerini ekle / sil / yeniden adlandır
+
+**Listeyi yeniden göndermek gerekmez.** `entity_patch` düz RFC 6902 op'ları taşır ve seçici
+(`[slug=…]`, `[value=…]`) `valueOptions` derinliğinde de çözülür:
+
+```jsonc
+// ekle — dizinin sonuna; "-" JSON Pointer'ın "diziye ekle" belirtecidir
+{ "op": "add", "path": "/fields[slug=status]/valueOptions/-",
+  "value": { "value": "Onayda", "icon": "#0052CC", "order": 4 } }
+
+// sil
+{ "op": "remove", "path": "/fields[slug=status]/valueOptions[value=İptal]" }
+
+// yeniden adlandır (etiketi değiştir, sırayı koru)
+{ "op": "replace", "path": "/fields[slug=status]/valueOptions[value=İptal]/value", "value": "Reddedildi" }
+```
+
+- **`isEnum` türetilmiştir** (`ValueOptions.Any()`), patch'te ayrıca yazılmaz; alan zaten enum
+  olduğu sürece tek op yeter.
+- **Düz metin alanını enum'a çevirmek bu yol DEĞİLDİR:** `valueOptions` boş/null ise `/-` yolu
+  düşer — tam diziyi `replace` ile yaz (`/fields[slug=status]/valueOptions`).
+- `order`'ı ekleme sırasında ver; verilmezse `0` olur ve sıralı raporlar sessizce bozulur
+  (yukarıdaki `order` maddesi).
+- Çok dilli etiket gerekiyorsa `labels` aynı op'un `value` nesnesine girer.
+- **Sil ve yeniden adlandırmadan ÖNCE satırları taşı.** Değeri hâlâ taşıyan satır varsa istek
+  **reddedilir ve hiçbir şey yazılmaz** — ölçüldü 2026-09-16, mesaj okunabilir: `Migration failed.
+  Please try again. Details: check constraint "check_<field id>" of relation "<tablo>" is violated
+  by some row`. Platform eski değeri satırlarda yeniden adlandırmaz. Sıra: `row_update` ile kanonik
+  değere taşı → sonra enum op'unu gönder (aynı sırayla ölçüldü: taşıma sonrası `remove` geçti).
+- Yanıtın outline'ı alanın yeni değer listesini (`values`, ilk 30 + `valueOptionCount`) taşır —
+  ikinci bir `entity_get` turu gerekmez.
+
 ## Artan kod alanı (`Incremental`)
 
 Sıralı, önekli, insan okuyabilir kod üretir (`TLP-0001`). Alan tanımı:
@@ -1070,3 +1104,6 @@ gönderme.
 `version` bir **string**tir (mikrosaniye zaman damgası, `Number.MAX_SAFE_INTEGER`'ın üstünde):
 sayıya çevirirsen yuvarlanır ve her patch 409 döner. Yanıttaki `newVersion` bir sonraki patch'in
 `baseVersion`'ıdır.
+
+Seçim listesine (enum) tek değer eklemek, silmek ya da yeniden adlandırmak da bu yoldan gider ve
+listeyi yeniden göndermeyi **gerektirmez** — §"Tek bir enum değerini ekle / sil / yeniden adlandır".

package/dist/resources/guides/getting-started.md

@@ -56,6 +56,10 @@ Bağımlılıklar bu sırayı zorunlu kılar; atlama:
                           ifadelerde Functions.<ad>(…) ile, akışlar 'function' adımıyla çağırır;
                           sayfaya özgü fonksiyon (scope:'page') sayfa açıldıktan sonra gelir.
                           Kurallar platform_guide('functions'))
+      function_update    (GÖVDE DEĞİŞİNCE: function_update { id, body } — patch aracı YOKTUR,
+                          fonksiyonun tek büyük alanı gövdedir ve gateway vermediğin alanları
+                          mevcut kayıttan doldurur. Adı değiştirirsen platform çağıranları AYNI
+                          işlemde yeni ada taşır (renamedReferences))
 11. layout_create        (header/sidebar + MUTLAKA bir 'slot' — slot'suz layout'a bağlı sayfa
                           boş görünür; bkz. platform_guide('page') Kural 5)
 12. page_create + …      (İŞ BURADA BİTMEZ: her kaydın yönetim ekranı, kimlik varsa giriş

package/dist/resources/guides/microservice.md

@@ -620,6 +620,45 @@ gerekmese bile** ona bir middleware bağla. Tek `variable` adımlı, hiçbir şe
 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.
 
+## Patch belgesi OKUMA şeklidir — rol listesi `/roles` yolundadır (MS-022)
+
+`microservice_patch` yamayı **`microservice_get`'in döndürdüğü gövdeye** uygular; platform da onu
+kendi tarafında `MicroserviceDto` olarak okuyup `UpdateMicroserviceCommand`'a çevirir
+(`PatchMicroserviceCommand.cs:36-55`). Yani yamalanan belge **yazma komutu değildir** ve iki
+belgenin alan adları her yerde aynı değildir:
+
+| Ne | Create/update GÖVDESİ | Patch YOLU (okuma şekli) |
+|---|---|---|
+| Rol listesi | `roleIds: [<guid>]` | **`/roles`** → `[{ id, name }]` |
+| Middleware listesi | `middlewareIds: [<guid>]` | `/middlewareIds` (aynı) |
+| Alan listesi | `sourceParameters.selectFields` | `/sourceParameters/selectFields` (aynı) |
+
+**Ucun rolünü değiştirmek için tanımı yeniden göndermek gerekmez** — tek op yeter:
+
+```jsonc
+// tüm listeyi yaz (tercih edilen): name isteğe bağlıdır, platform yalnız id okur
+{ "op": "replace", "path": "/roles", "value": [{ "id": "<role_list id>" }] }
+
+// listeye ekle
+{ "op": "add", "path": "/roles/-", "value": { "id": "<role_list id>" } }
+
+// tek rolü çıkar
+{ "op": "remove", "path": "/roles[id=<role_list id>]" }
+```
+
+- **`roleIds` yolu patch belgesinde YOKTUR.** Verirsen gateway `/roles`'a çevirir, çıplak guid'leri
+  `{ id }` nesnesine sarar ve çeviriyi `gatewayNormalized` ile söyler — istek düşmez. Çevrilmeseydi
+  `replace /roleIds` gateway'de `OPERATION_PATH_UNRESOLVABLE` verirdi, `add /roleIds` ise platformda
+  **sessizce yutulurdu** (bilinmeyen üye atılır, 200 döner, rol değişmez).
+- **Tam dizi `replace`'i tercih et.** Rolü olmayan uçta alan `null` serileşebilir ve `/roles/-`
+  çözülemez; gateway bunu tek öğelik tam diziye katlar ve notu yanıta yazar.
+- Rol id'leri `role_list`ten gelir. `role_list` **slug döndürmez** ve iki anahtar farklıdır:
+  buradaki `id` ile yetkilendirmenin karşılaştırdığı `slug` aynı şey değildir
+  (`platform_guide('entity')` §"Hazır entity'ler").
+- Yazmanın kanıtı yanıttadır: outline `roleIds` taşır, ikinci bir `microservice_get` gerekmez.
+- **Rol tek başına kapı değildir** — §"Uçlar varsayılan olarak ANONİMDİR": koruma `middlewareIds`
+  ile gelir.
+
 ## Uçlar varsayılan olarak ANONİMDİR
 
 Çalıştırma rotası `[AllowAnonymous]`'tur (`MicroservicesController.cs:90`): `middlewareIds` boş
@@ -629,6 +668,7 @@ Anonim veri toplama (anket, başvuru, geri bildirim) bu sayede kurulabilir — a
 
 `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.
+Rol listesini **değiştirmek** için yukarıdaki §"Patch belgesi OKUMA şeklidir".
 
 > **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

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

@@ -12,6 +12,10 @@ Gerçek projelerde tek tanım 20-100 bin satır JSON olabilir. **Tam gövdeyi ba
                                                belleğinde çeker, patch'i uygular, politika
                                                kontrolünden geçirir, geri yazar
 5. *_get view:'outline'                      → değişikliği teyit et
+
+function_update {id, body}                   → FONKSİYONDA *_patch YOKTUR: tek büyük alan
+                                               gövdedir, yalnız onu gönder (gateway kalan
+                                               alanları mevcut kayıttan doldurur)
 ```
 
 `view:'full'` **son çaredir** — yalnız küçük kayıtlarda ya da patch'in kurulamadığı köklü
@@ -23,12 +27,19 @@ yeniden yazımlarda.
   ekleme), `/fields/5/nullable`.
 - Dizin indekslerini tahmin etme — `view:'outline'` çıktısındaki sıradan ya da
   `view:'part'` ile doğrulayarak yaz.
+- **Bir listeye tek öğe eklemek listeyi yeniden göndermek değildir:** `add` + `/-`
+  (`/fields[slug=status]/valueOptions/-`, `/sourceParameters/selectFields/-`); tek öğeyi silmek
+  ya da değiştirmek için seçici (`[value=…]`, `[slug=…]`). Enum örnekleri:
+  `platform_guide('entity')` §"Tek bir enum değerini ekle / sil / yeniden adlandır".
 - 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.
+  gövdedir). `function_get` çıktısı `function_update`'in şablonudur; örnek:
+  `ngapps://examples/function-total` `functionUpdateArgs`. Adı değiştirmeden önce
+  `dependency_graph` (`module:'ui-function'`) ile çağıranları bul: `{{ }}`/`code` ifadelerindeki
+  `Functions.<eskiAd>(` çağrıları metinseldir — platform onları aynı işlemde taşır, ayrıntı
+  `platform_guide('functions')` §Güncelleme ve silme.
 
 ## Değiştirmeden önce geçmişe bak