@appaflytech/zeyrek-ai-mcp 0.0.5 → 0.0.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (145) hide show
  1. package/.env.example +2 -2
  2. package/.env.production.example +9 -1
  3. package/README.md +14 -38
  4. package/dist/config.js +36 -3
  5. package/dist/knowledge/backendConstraints.js +982 -0
  6. package/dist/knowledge/componentCatalog.js +549 -92
  7. package/dist/knowledge/componentEvents.js +120 -25
  8. package/dist/knowledge/coverage.js +43 -0
  9. package/dist/knowledge/flowGuards.js +30 -0
  10. package/dist/knowledge/functionGuards.js +134 -0
  11. package/dist/knowledge/guideSections.js +49 -0
  12. package/dist/knowledge/hydrate.js +97 -0
  13. package/dist/knowledge/languageCodes.js +36 -0
  14. package/dist/knowledge/languages.js +105 -0
  15. package/dist/knowledge/layoutSummary.js +10 -0
  16. package/dist/knowledge/localization.js +51 -0
  17. package/dist/knowledge/normalize.js +500 -16
  18. package/dist/knowledge/outlines.js +167 -12
  19. package/dist/knowledge/policy.js +14 -5
  20. package/dist/knowledge/propTypes.js +80 -0
  21. package/dist/knowledge/rules.js +961 -44
  22. package/dist/knowledge/schemaGuard.js +199 -0
  23. package/dist/knowledge/styleResolve.js +63 -4
  24. package/dist/observability/trace.js +27 -3
  25. package/dist/platform/csv.js +123 -0
  26. package/dist/platform/errors.js +107 -6
  27. package/dist/platform/http.js +34 -4
  28. package/dist/platform/patch.js +27 -0
  29. package/dist/platform/refs.js +104 -0
  30. package/dist/platform/responses.js +25 -6
  31. package/dist/platform/screenshot.js +544 -16
  32. package/dist/platform/secrets.js +40 -0
  33. package/dist/platform/tokenVault.js +89 -0
  34. package/dist/platform/writeDiff.js +281 -0
  35. package/dist/resources/examples/flow-call-function.json +66 -0
  36. package/dist/resources/examples/function-total.json +70 -0
  37. package/dist/resources/examples/layout-app-shell.json +1 -1
  38. package/dist/resources/examples/microfunction-node-sum.json +56 -0
  39. package/dist/resources/examples/microservice-table-list.json +2 -4
  40. package/dist/resources/examples/page-dynamic-form.json +3 -3
  41. package/dist/resources/examples/page-flex-sections.json +99 -0
  42. package/dist/resources/examples/page-sign-in.json +4 -3
  43. package/dist/resources/guides/component.md +81 -8
  44. package/dist/resources/guides/entity.md +712 -20
  45. package/dist/resources/guides/expressions.md +47 -2
  46. package/dist/resources/guides/external-component.md +9 -0
  47. package/dist/resources/guides/functions.md +262 -0
  48. package/dist/resources/guides/getting-started.md +82 -7
  49. package/dist/resources/guides/layout.md +53 -10
  50. package/dist/resources/guides/merge.md +231 -0
  51. package/dist/resources/guides/microfunction.md +166 -0
  52. package/dist/resources/guides/microservice.md +287 -15
  53. package/dist/resources/guides/middleware.md +89 -1
  54. package/dist/resources/guides/modify-existing.md +23 -0
  55. package/dist/resources/guides/page.md +402 -49
  56. package/dist/resources/guides/translation.md +150 -8
  57. package/dist/resources/guides/view.md +16 -1
  58. package/dist/resources/guides/workflow.md +199 -28
  59. package/dist/resources/knowledge.js +5 -0
  60. package/dist/resources/rules.js +27 -0
  61. package/dist/resources/schema-fingerprint.json +8 -0
  62. package/dist/resources/schemas/AnalyzeImportQuery.json +51 -0
  63. package/dist/resources/schemas/ApplyMergePlanCommand.json +19 -0
  64. package/dist/resources/schemas/CreateBulkRowCommand.json +36 -0
  65. package/dist/resources/schemas/CreateDatasourceCommand.json +15 -6
  66. package/dist/resources/schemas/CreateDiscoveredEntitiesCommand.json +19 -8
  67. package/dist/resources/schemas/CreateEntityCommand.json +52 -12
  68. package/dist/resources/schemas/CreateEnvironmentCommand.json +31 -0
  69. package/dist/resources/schemas/CreateGlobalFunctionCommand.json +95 -0
  70. package/dist/resources/schemas/CreateImportPlanCommand.json +278 -0
  71. package/dist/resources/schemas/CreateMergePlanCommand.json +34 -0
  72. package/dist/resources/schemas/CreateMicrofunctionCommand.json +117 -0
  73. package/dist/resources/schemas/CreateMicrofunctionRuntimeCommand.json +51 -0
  74. package/dist/resources/schemas/CreateMicroserviceCommand.json +145 -3
  75. package/dist/resources/schemas/CreateQueryCommand.json +56 -3
  76. package/dist/resources/schemas/CreateRowCommand.json +38 -0
  77. package/dist/resources/schemas/CreateViewCommand.json +13 -10
  78. package/dist/resources/schemas/CreateWorkflowCommand.json +106 -14
  79. package/dist/resources/schemas/DataJobDto.json +267 -0
  80. package/dist/resources/schemas/ExportRowsCommand.json +172 -0
  81. package/dist/resources/schemas/Filter.json +3 -1
  82. package/dist/resources/schemas/GetRowsQuery.json +6 -1
  83. package/dist/resources/schemas/GlobalFunctionDto.json +89 -0
  84. package/dist/resources/schemas/GlobalFunctionUpdateResultDto.json +249 -0
  85. package/dist/resources/schemas/ImportAnalysisDto.json +401 -0
  86. package/dist/resources/schemas/ImportPlanDto.json +260 -0
  87. package/dist/resources/schemas/ImportSampleDto.json +90 -0
  88. package/dist/resources/schemas/InvokeMicrofunctionCommand.json +25 -0
  89. package/dist/resources/schemas/PreviewMicroserviceCommand.json +135 -1
  90. package/dist/resources/schemas/PreviewQueryCommand.json +5 -2
  91. package/dist/resources/schemas/PreviewWorkflowCommand.json +45 -9
  92. package/dist/resources/schemas/ResolveMergeConflictsCommand.json +58 -0
  93. package/dist/resources/schemas/RevertMergePlanCommand.json +19 -0
  94. package/dist/resources/schemas/RunImportCommand.json +62 -0
  95. package/dist/resources/schemas/StepDto.json +34 -3
  96. package/dist/resources/schemas/UpdateBulkRowCommand.json +36 -0
  97. package/dist/resources/schemas/UpdateDatasourceCommand.json +15 -6
  98. package/dist/resources/schemas/UpdateEntityCommand.json +52 -11
  99. package/dist/resources/schemas/UpdateGlobalFunctionCommand.json +66 -0
  100. package/dist/resources/schemas/UpdateMicrofunctionCommand.json +121 -0
  101. package/dist/resources/schemas/UpdateMicrofunctionRuntimeCommand.json +54 -0
  102. package/dist/resources/schemas/UpdateMicroserviceCommand.json +147 -4
  103. package/dist/resources/schemas/UpdateQueryCommand.json +13 -3
  104. package/dist/resources/schemas/UpdateRowCommand.json +40 -0
  105. package/dist/resources/schemas/UpdateViewCommand.json +15 -10
  106. package/dist/resources/schemas/UpdateWorkflowCommand.json +106 -14
  107. package/dist/server.js +17 -1
  108. package/dist/tools/access.js +3 -3
  109. package/dist/tools/activities.js +40 -0
  110. package/dist/tools/applications.js +1 -1
  111. package/dist/tools/automations.js +76 -34
  112. package/dist/tools/common.js +55 -0
  113. package/dist/tools/components.js +16 -7
  114. package/dist/tools/datasources.js +83 -21
  115. package/dist/tools/dependencies.js +1 -1
  116. package/dist/tools/deployments.js +34 -2
  117. package/dist/tools/dtos.js +25 -12
  118. package/dist/tools/entities.js +113 -28
  119. package/dist/tools/environments.js +52 -0
  120. package/dist/tools/externalComponents.js +9 -3
  121. package/dist/tools/files.js +57 -42
  122. package/dist/tools/flows.js +205 -13
  123. package/dist/tools/folders.js +7 -2
  124. package/dist/tools/functions.js +331 -0
  125. package/dist/tools/globalFunctions.js +63 -0
  126. package/dist/tools/importSchemas.js +79 -0
  127. package/dist/tools/imports.js +241 -0
  128. package/dist/tools/layouts.js +103 -29
  129. package/dist/tools/merges.js +113 -0
  130. package/dist/tools/microfunctions.js +155 -0
  131. package/dist/tools/microservices.js +270 -40
  132. package/dist/tools/organizations.js +5 -6
  133. package/dist/tools/pages.js +421 -104
  134. package/dist/tools/platformInfo.js +155 -11
  135. package/dist/tools/projects.js +183 -33
  136. package/dist/tools/queries.js +32 -10
  137. package/dist/tools/revisions.js +94 -0
  138. package/dist/tools/rows.js +484 -50
  139. package/dist/tools/screenWrite.js +68 -0
  140. package/dist/tools/screens.js +28 -0
  141. package/dist/tools/templates.js +32 -5
  142. package/dist/tools/translations.js +24 -8
  143. package/dist/tools/views.js +20 -10
  144. package/dist/tools/workflows.js +56 -21
  145. package/package.json +7 -2
@@ -15,7 +15,10 @@ Uydurma fonksiyon adı runtime'da `X is not defined` 500'üdür — yalnız bura
15
15
  **Değişkenler:** step çıktıları (`<stepAdı>.data`), middleware değişkenleri (`user`,
16
16
  `settings`, `permissions`… — `workflow_middleware_variables` ile keşfet), HTTP bağlamı:
17
17
  `cookie`, `header`, `queryString`, `body`, `triggerSource`/`context` (tetikleyen ucun
18
- type/name/roles/impersonatedUserId'ı). Workflow'da istek girdisi `input.`, automation'da
18
+ type/name/roles/impersonatedUserId'ı). Gövde bir JSON **nesnesi** ise `body.alan` diye okunur,
19
+ gövde bir JSON **dizisi** ise `body[0].alan` diye — 2026-09-04 öncesinde nesne gövde de diziye
20
+ sarılıyordu ve `body.alan` sessizce `undefined` dönüyordu, bu yüzden gövdeye bakan yetki kapıları
21
+ açık kalıyordu. Workflow'da istek girdisi `input.`, automation'da
19
22
  tetikleyen satır `row` / `previousRow` / `user`.
20
23
 
21
24
  **Fonksiyonlar (qm'de aktif kullanılanlar önce):**
@@ -32,6 +35,7 @@ tetikleyen satır `row` / `previousRow` / `user`.
32
35
  | `Now(tz)` | Verilen saat diliminde şimdi, **`"yyyy-MM-ddTHH:mm:ss"` METİN olarak**. **JS motoru UTC'ye sabitlidir** (`opt.TimeZone = Utc`), yani `new Date()` her zaman UTC'dir — yerel gün/saat mantığı için bunu kullanın, offset'i koda gömmeyin | `Now('Europe/Istanbul')` → `"2026-08-18T19:11:10"` |
33
36
  | `Today(tz)` | O saat diliminde bugün, `"yyyy-MM-dd"` metni — gün sınırı filtreleri için en kısa yol | `Today('Europe/Istanbul') + 'T00:00:00'` |
34
37
  | `ToTimeZone(v, tz)` | Bir değeri (Date, DateTimeOffset ya da ISO metin) o saat dilimine çevirir, aynı metin biçiminde | `ToTimeZone(Steps.randevu.data.baslangic, 'Europe/Istanbul')` |
38
+ | `Functions.<ad>(…)` | **YOK — sunucuda kullanıcı fonksiyonu yüklenmez** (2026-09-10). Gateway `WF-030` ile istek gitmeden bloklar; zorlanırsa Jint `Functions is not defined` fırlatır. Sunucuda paylaşılan hesap **`source:'workflow'` fonksiyondur** ve çıplak adla çağrılır (`sum(1, 2)`, `function_create source:'workflow'`) |
35
39
 
36
40
  > **Bu üçü METİN döner, Date DÖNMEZ** — bilerek. `UtcNow()` bir JS `Date` döndürür ve üzerinde
37
41
  > `getTime()`/`getUTCFullYear()` çalışır; ama Jint'in `DateTimeOffset` → `Date` çevriminde **saat
@@ -57,6 +61,27 @@ tetikleyen satır `row` / `previousRow` / `user`.
57
61
  (motor tr-TR + UTC); automation zinciri istek başına workflow başına 10 koşumda
58
62
  `InfiniteLoopException` ile kesilir (sonsuz döngü koruması).
59
63
 
64
+ > **İki ayrı sınır var ve önce KÜÇÜK olan konuşur.** `AutomationConsumer` automation'ı
65
+ > çalıştırmadan önce `triggerCount > 2` kontrolü yapar (yani 3. tetiklemede keser);
66
+ > `WorkflowContext.CheckProcessCount` ise workflow koşumunu 10'da keser. Yukarıdaki 10 yalnız
67
+ > ikincisidir. Hata mesajı artık hangi automation'ın kaç kez tetiklendiğini ve sınırı söyler.
68
+ >
69
+ > **Kapıyı doğru yere koy:** sayaç, akışın ilk adımı koşmadan önce artar. Tetikleyen satıra geri
70
+ > yazan bir automation'da `row.status !== previousRow.status` kapısını akışın içindeki bir
71
+ > `condition` ADIMINA koymak koşumu saydırmayı sürdürür; aynı ifade `automation.condition`
72
+ > alanında ise yeniden tetikleme hiç doğmaz ve sayaç artmaz (`RowConsumer.cs:130-143`).
73
+ >
74
+ > **Yanıltıcı `failed` DÜZELTİLDİ (2026-09-05).** Sayaç pas başına İKİ artıyordu: runner'ın kendi
75
+ > 10'luk koruması (`CheckProcessCount`) ile tetikleme zincirinin sayacı aynı sözlüğü paylaşıyordu,
76
+ > bu yüzden tetikleyen satırını güncelleyen her automation ikinci pasında `processCount: 3` ile
77
+ > kesiliyordu — ölçümde 10 durum değişikliğinin **10'unda da**. İki sayaç ayrıldı; artık her pas
78
+ > zinciri bir artırır: 1. pas kapıyı geçip yazar, 2. pas kapıya takılıp durur ve zincir `2`'de
79
+ > biter. Ölçüm (aralıklı 10 güncelleme): 20 olay, hepsi `completed`, `failed` yok.
80
+ >
81
+ > Kalan tek durum bir YARIŞTIR: aynı satıra ara vermeden art arda güncelleme atılırsa bir zincir
82
+ > önceki zincirin yazması havadayken başlayabilir ve seyrek bir `failed` düşebilir (10 hızlı
83
+ > güncellemede 1). Satır başına tek akış bekliyorsanız güncellemeleri aralıklandırın.
84
+
60
85
  **Tohum parola üretmek istiyorsan** hash'i platformun kendisine ürettir: parolayı düz metin alan
61
86
  bir workflow yazıp `crypto.SHA256.encode(input.password)` sonucunu döndür, ya da kullanıcı kaydını
62
87
  açan ucu kullan. Dışarıda kendi SHA-256'nı hesaplayıp yazarsan giriş akışı **hiçbir zaman**
@@ -73,13 +98,32 @@ dalından devam eder.
73
98
  | `Page` | `Page.user`, `Page.variables`, `Page.components`, `Page.properties`, `Page.queryParams`, `Page.authorized(roles)` |
74
99
  | **Komponent adları** | Her komponent adıyla doğrudan değişkendir: `specialties_table.rows = data` hem prop'u yazar hem UI'ı günceller (change event). Addaki `-` silinir: `tickets-table` → `ticketstable` |
75
100
  | `state.page` / `state.app` | Kalıcı state (oku/yaz): `state.page.selectedId = row.id`. **Tanımlı değişkenler de buradadır:** `variable_create` ile yazılan her `key` sayfa düzeyinde `state.page.<key>`, uygulama düzeyinde `state.app.<key>` olur; `value` nesneyse alanlarına inilir (`state.page.MyTest.isActive`) |
76
- | `Steps` | Adım çıktıları: `Steps.load_specialties` (stepId ile); `error` = son hata |
101
+ | `Steps` | Adım çıktıları: `Steps.load_specialties` — anahtar adımın **ADIdır**, `stepId` değil (`setStorage(task.name, …)`); `Steps.<adım>.error` o adımın hatası — ama YALNIZ HTTP durum metnidir (401 için `'Unauthorized'`), ucun mesajı değil. `Steps.error` ise hata akışı için doldurulur (`onError` koşmadan önce `setStorage('error', …)` yapar) ama **YAPIŞKANDIR**: storage sayfa başına tek `FlowMachine`'de yaşar ve `'error'` anahtarı hiç temizlenmez, yani ilk hatadan sonra o sayfadaki her akışta dolu kalır — normal akışta `Steps.error` okuyan bir ifade bayat hatayı görür ve şekli `{ message, code, step: { id, name, type, data } }`'dir: kullanıcıya gösterilecek metin `Steps.error.message`'tır (`err.response.data.message`, boşsa durum metni). **Başarılı bir adımda `Steps.<adım>.data` gerçek bir `Array`'dir** — `.map` · `.filter` · `.concat` · `.length` çalışır. Adım HATA dönerse aynı alan ucun hata gövdesini taşır; aşağıdaki kutuya bakın |
77
102
  | `self` · `item` · `Row` / `RowIndex` | Tetikleyen komponent (yazılabilir) · repeater/tablo satırı (yazmak satırı günceller) |
78
103
  | `event` | `{name, data, source: {id, props}}` |
79
104
  | `cookie` | `cookie.get(name)` / `cookie.set(name, value, {expiresInHours, path})` / `cookie.remove(name)` — tarayıcı cookie'si |
80
105
  | `setComponentProperty(name, key, value)` / `getComponentProperty(name, key)` | fonksiyon alternatifi |
81
106
  | `LocalStorage` · `Widget` · `params` | yerel veri · widget bağlamı · olay parametreleri |
107
+ | `t(key)` | Çeviri anahtarını çözer: aktif dil → projenin varsayılan dili → anahtarın kendisi. Boş string de "eksik" sayılır. Sözlük `machine.context.state.translations`'tan gelir; dil `language-selector` ile değişince bir sonraki çağrı yeni dili görür. **Yalnız UI flow kodunda vardır** — backend ifadelerinde karşılığı `Loc()`'tur (`platform_guide('workflow')`) | `t('home.welcome')` |
82
108
  | `log(...)` | console (proxy'leri temizler) |
109
+ | `Functions` | **Kullanıcı fonksiyonları** (`function_create`): `Functions.toplamHesapla(fiyat, adet)` — uygulama kapsamlılar her sayfada, sayfa kapsamlılar yalnız kendi sayfasında. **Yalnız tarayıcı**; sunucuda bu ad alanı yoktur (2026-09-10, `WF-030`) |
110
+
111
+ > **`.map is not a function` bir dizi sözleşmesi sorunu DEĞİL, düşmüş bir adımdır.**
112
+ > Ölçüldü 2026-09-05 (`f09-repro/probe`, yerel kurulum): başarılı bir microservice adımında
113
+ > `Steps.<adım>.data` `[object Array]`'dir, `Array.isArray` true döner ve `.map`/`.filter`/
114
+ > `.concat` çalışır. Adım hata döndüğünde (401, 500, geçersiz parametre) motor aynı alana ucun
115
+ > **hata gövdesini** yazar — o bir nesnedir, dizi metodları yoktur ve
116
+ > `(Steps.x.data || []).map is not a function` tam olarak burada çıkar. 2026-09-05 koşusunda
117
+ > boş kalan şirket filtresinin sebebi buydu: adım korumalı bir uca 401 ile düşmüştü.
118
+ > **Teşhis sırası:** önce `Steps.<adım>.error`'a bak, sonra ifadeyi suçla. Bir dizi bekliyorsan
119
+ > `Array.isArray(Steps.<adım>.data)` ile koru; boş listeye düşmek, hata gövdesi üzerinde
120
+ > dönmekten iyidir.
121
+ >
122
+ > **Patlayan ifade artık sessiz değil (F-09).** Hedef prop yine YAZILMAZ — bozuk bir değeri
123
+ > yazmak durumu kötüleştirir — ama akış bunu yapısal olarak bildirir: `page_screenshot` yanıtı
124
+ > `runtimeErrors` taşır ve hangi komponentin hangi prop'unun yazılamadığını (`element` ·
125
+ > `property`) söyler. Aynı defter hata dönen microservice adımlarını da kaydeder. **Kare
126
+ > "çalışıyor" görünse bile `runtimeErrors` doluysa o adımlar işini YAPMAMIŞTIR.**
83
127
 
84
128
  **Prop'a doğrudan ifade bağlama (`{{ }}`):** akış kurmadan bir prop'u ifadeye bağlamak için
85
129
  prop `type: 'code'` olur, **ifade `ref` alanına `{{ }}` içinde** yazılır, `data` tasarım zamanı
@@ -137,3 +181,4 @@ Karıştırma: `roles_csv` **UI/filtre** tarafının yoludur; backend middleware
137
181
  | `system.` / `file.` / `crypto.` / `convert.` | ✓ | — |
138
182
  | `cookie` | okunur sözlük (`cookie.X`) | `get/set/remove` fonksiyonları |
139
183
  | `await` | — (senkron ifade) | ✓ (`code` adımı) |
184
+ | `Functions.<ad>()` (kullanıcı fonksiyonu) | — (sunucuda yok, `WF-030` block) | ✓ uygulama + o sayfanın sayfa fonksiyonları |
@@ -127,3 +127,12 @@ Platform, npm paketi olmadan servis eder:
127
127
 
128
128
  `external_component_scaffold` bu sözleşmeye uyan bir iskeleti yerel dizine
129
129
  zaten yazar; kit, iskeleti elle düzenlerken referans olarak işinize yarar.
130
+
131
+ ## Backend doğrulama sınırları (EXT-001)
132
+
133
+ `external_component_publish` manifest'i kayıt ucuna gitmeden denetler (block): `protocolVersion`
134
+ 1; `definition.blocks` en az bir blok; `definition.props[].name` DOM/host adı olamaz
135
+ (`attributes`, `children`, `class`, `className`, `id`, `name`, `style`, `slot`, `innerHTML`…) ve
136
+ `zx`/`on` ile başlayamaz; `definition.props[].type` platform sözlüğünden (`text`, `number`,
137
+ `switch`, `dropdown`, `object`, `array`, `views`, `component`…). Slug deseni `^x-[a-z][a-z0-9-]*$`
138
+ ve 2 MB paket sınırı tool'un kendisinde denetlenir. Tam liste: `ngapps://rules/backend-constraints`.
@@ -0,0 +1,262 @@
1
+ # Fonksiyonlar — iki kaynak, tek biçim
2
+
3
+ Studio kullanıcısı (ya da ajan) **parametreli JavaScript fonksiyonları** tanımlar. Backend tek
4
+ aggregate tutar (`GlobalFunction`, `/global-functions`), ajan sözlüğü `function_*` araçlarıdır; ayrım
5
+ **`source`** bayrağıdır ve kaydedildikten sonra değişmez — tarayıcıda `Functions.<ad>()`, sunucuda `<ad>()`:
6
+
7
+ | `source` | Nerede çalışır | Nasıl çağrılır | Kapsam |
8
+ |---|---|---|---|
9
+ | `workflow` | **Sunucu** (Jint): workflow / middleware / automation ifadeleri | çıplak ad `toplamHesapla(10, 3)` | tenant geneli; `applicationId`/`scope`/`pageId` verilmez, `isAsync` olamaz |
10
+ | `studio` | **Tarayıcı**: `{{ }}` prop bağlamaları, UI flow `code` / `function` adımı | `Functions.toplamHesapla(10, 3)` | uygulamaya ait; `applicationId` + `scope` (`application` \| `page`) zorunlu |
11
+
12
+ Kod ve parametre biçimi ikisinde **aynıdır**: gövde düz deyimler (`return fiyat * adet;`),
13
+ parametreler tipli ve sıralı bir liste, `defaultValue`/`required` zinciri aynı. Aynı ad iki kaynakta
14
+ yan yana yaşayabilir — ad alanları farklıdır (`ad()` vs `Functions.ad()`), ikisi ayrı kayıttır.
15
+
16
+ > **`source:'studio'` YALNIZ TARAYICIDA çalışır (2026-09-10).** Sunucu `Functions` diye bir ad
17
+ > alanı tanımaz — sunucu ifadesindeki `Functions.<ad>(…)` çağrısı `Functions is not defined` ile
18
+ > düşer ve gateway ifadeyi `WF-030` ile **istek gitmeden bloklar**. Sunucu için `source:'workflow'`
19
+ > tanımla. Mikroservis ifadeleri hiçbir kaynağı yüklemez.
20
+
21
+ Araçlar: `function_list` · `function_get` · `function_create` · `function_update` · `function_delete`
22
+ (modül `function`; `core` ve `studio` kümelerinde). Örnekler: `ngapps://examples/function-total`
23
+ (iki kaynak), `ngapps://examples/flow-call-function`.
24
+
25
+ ## Ne zaman fonksiyon, ne zaman değil
26
+
27
+ Fonksiyon **şu iki durumda** yazılır:
28
+
29
+ 1. Aynı ifade üç ya da daha çok yerde kopyalanıyor (her `code` adımına, her prop bağlamasına aynı
30
+ hesap) — tek tanım, tek düzeltme noktası.
31
+ 2. Parametreli bir hesap gerekiyor: `toplamHesapla(fiyat, adet)`, `kdvEkle(tutar, oran = 0.2)`.
32
+
33
+ Bir iş kuralı **hem tarayıcıda hem sunucuda** geçerliyse iki kayıt gerekir: `source:'studio'` ve
34
+ `source:'workflow'`, aynı gövdeyle. Kopyayı gizleme — kapatamıyorsan `platform_gap_report` ile bildir.
35
+
36
+ Fonksiyon **yazılmaz**: tek yerde kullanılan ifade için (doğrudan yaz); veri çekmek için
37
+ (uç çağrısı `microservice` adımının işidir, fonksiyon HTTP yapmaz); `system.*` / `file.*` /
38
+ `crypto.*` zaten yapıyorsa (`platform_guide('expressions')`).
39
+
40
+ ## Kaynak ve kapsam seçimi
41
+
42
+ | Seçim | Nerede görünür | Alanlar | Ne zaman |
43
+ |---|---|---|---|
44
+ | `source:'workflow'` | Tenant'ın **her** workflow / middleware / automation ifadesinde | yalnız `name`, `parameters`, `body`, `description` | Sunucu tarafı iş kuralı, hesap, biçimlendirme |
45
+ | `source:'studio'`, `scope:'application'` | Uygulamanın **her sayfasında** (tarayıcı) | `applicationId` | Varsayılan tarayıcı seçimi |
46
+ | `source:'studio'`, `scope:'page'` | **Yalnız o sayfanın** tarayıcı bağlamında | `applicationId` + `pageId` | Gövde sayfaya özgü komponent adlarını / `state.page`'i kullanıyor |
47
+
48
+ Tekillik: workflow adı tenant içinde, studio adı uygulama içinde **kapsamlar arası benzersizdir**
49
+ (K3) — `homepage`'de `hesapla` varsa başka bir sayfada da uygulama düzeyinde de `hesapla` açılamaz;
50
+ platform `422 GlobalFunctionNameAlreadyExists` döner ve mesaj çakışan kapsamı/sayfayı söyler.
51
+ Gölgeleme yoktur. Kaynak/kapsam tutarsızlığını gateway `FN-005` ile istek gitmeden yakalar
52
+ (workflow'a `applicationId`, studio'ya `applicationId`sız, `page` kapsamına `pageId`sız).
53
+
54
+ ## Hangi bağlam nerede çalışır (K4, K7)
55
+
56
+ Fonksiyonun **hedefi yoktur**: gövde nerede çağrılırsa o bağlamda çalışır ve çağıranın tüm
57
+ globallerini kapanış olarak görür. Yanlış bağlamda çağrı çalışma anında `X is not defined` verir;
58
+ lint bunu yakalayamaz, tablo sana kalır:
59
+
60
+ | Gövdede kullanılan ad | `studio` sayfa fonksiyonu | `studio` uygulama fonksiyonu | `workflow` fonksiyonu |
61
+ |---|:-:|:-:|:-:|
62
+ | parametreler (`fiyat`, `adet`) | ✓ | ✓ | ✓ |
63
+ | `state.app.<key>` | ✓ | ✓ | — |
64
+ | `state.page.<key>`, komponent adları, `Page.components` / `Page.properties` / `Page.queryParams` | ✓ | ✓ (**çağrıldığı sayfada varsa** — statik olarak bilinemez) | — |
65
+ | `Page.user`, `Page.authorized(roles)`, `Page.variables` | ✓ | ✓ | — |
66
+ | `Steps`, `self`, `item`, `event` | çağıran akışın bağlamından | çağıran akışın bağlamından | — |
67
+ | `input`, middleware değişkenleri, adım çıktıları (`<adım>.data`), `row` (automation) | — | — | çağıran ifadenin bağlamından |
68
+ | `system.*`, `file.*`, `crypto.*`, `convert.*`, `Now()`, `UtcNow()` | — | — | ✓ |
69
+ | `cookie` | `get/set/remove` | `get/set/remove` | okunur (`cookie.<ad>`) |
70
+ | `await` | `isAsync:true` ise | `isAsync:true` ise | **yok** (FN-004 block) |
71
+ | başka bir fonksiyon | `Functions.b()` ✓ (K15) | `Functions.b()` ✓ | çıplak `b()` ✓ (aynı kaynaktan) |
72
+
73
+ Kural: uygulama fonksiyonunda **sayfaya özgü ad kullanma**; workflow fonksiyonunda **adım adına
74
+ bağlanma** — dinamik veriyi parametre olarak geçir (`Functions.hesapla(state.page.sayac)`,
75
+ `hesapla(input.tutar)`), gerekiyorsa gövdeyi guard'la (`typeof state !== 'undefined'`).
76
+
77
+ ## İmza: parametreler, varsayılan, `required` (K5)
78
+
79
+ Parametreler **bildirimlidir ve sıralıdır**; çağrı **konumsaldır**: `f(a, b)` bildirimin birinci ve
80
+ ikinci parametresine bağlanır, ad eşlemesi yoktur. İki runtime da her fonksiyonu aynı şekilde kurar
81
+ (tek fark ad alanı ve hata öneki):
82
+
83
+ ```js
84
+ globalThis["toplamHesapla"] = function (fiyat, adet) { // studio: Functions.toplamHesapla = function (…)
85
+ if (adet === undefined) adet = 1; // defaultValue ÖNCE
86
+ if (fiyat === undefined) throw new Error('toplamHesapla: "fiyat" is required'); // required SONRA
87
+ try { return fiyat * adet } // gövde
88
+ catch (e) { throw new Error('toplamHesapla: ' + e.message) }
89
+ };
90
+ ```
91
+
92
+ - `defaultValue` yalnız argüman `undefined` kalınca uygulanır; `null` geçmek varsayılanı **tetiklemez**.
93
+ - `required:true` parametreye `defaultValue` da verilirse varsayılan kazanır, hata hiç fırlamaz.
94
+ - `type` (`text` · `number` · `boolean` · `date` · `object` · `array` · `any`) yalnız Studio
95
+ imzası ve autocomplete içindir; çalışma zamanı tip denetlemez, `"10"` string olarak gelir.
96
+ - Fazla argüman yok sayılır; eksik argüman `undefined` → varsayılan → `required` hatası zinciri.
97
+ - İmza gösterimi (yanıtlardaki `signature`): studio `Functions.toplamHesapla(fiyat, adet = 1)`,
98
+ workflow `toplamHesapla(fiyat, adet = 1)`; zorunlu olmayan ve varsayılansız parametre `ad?` yazılır.
99
+
100
+ ## Tanımlama: `function_create`
101
+
102
+ ```jsonc
103
+ // sunucu
104
+ { "source": "workflow",
105
+ "name": "toplamHesapla", "description": "fiyat × adet; adet verilmezse 1",
106
+ "parameters": [ { "name": "fiyat", "type": "number", "required": true },
107
+ { "name": "adet", "type": "number", "defaultValue": 1 } ],
108
+ "body": "return fiyat * adet;" }
109
+
110
+ // tarayıcı
111
+ { "source": "studio", "applicationId": "<app id>", "scope": "application",
112
+ "name": "toplamHesapla", "description": "fiyat × adet; adet verilmezse 1",
113
+ "isAsync": false,
114
+ "parameters": [ … aynı liste … ],
115
+ "body": "return fiyat * adet;" }
116
+ ```
117
+
118
+ Gövde **düz deyimlerdir** — `function (…) { }` sarmalı ya da arrow yazılmaz; `return` serbesttir,
119
+ dönüşsüz gövde `undefined` döner. Platform gövdeyi kaydetmeden **ayrıştırır** (yürütmez):
120
+ sözdizimi hatası `422 GlobalFunctionBodyInvalid` ile ve ayrıştırıcı mesajıyla döner. Yanıt
121
+ `signature` ve `hint` (çağrı biçimleri) taşır. İstek gitmeden denetlenenler:
122
+
123
+ | Kural | Ne | Sonuç |
124
+ |---|---|---|
125
+ | FN-001 | Ad JS tanımlayıcısı değil ya da ayrılmış sözcük; studio'da `Functions`, workflow'da motor global adı (`system`, `input`, `Now`…); parametre adı geçersiz | **block** — platform da 422 verirdi |
126
+ | FN-002 | Aynı parametre adı iki kez | **block** — 422 `GlobalFunctionParameterNameDuplicate` |
127
+ | FN-003 | Gövde kendini çağırıyor (`Functions.<ad>(` / çıplak `<ad>(`) | warn — durma koşulu yoksa sonsuz özyineleme |
128
+ | FN-004 | `source:'workflow'` + `isAsync:true` | **block** — motor senkron, 422 `GlobalFunctionAsyncNotAllowed` |
129
+ | FN-004 | studio: `isAsync:true` ama `await` yok · `isAsync:false` ama `await` var | warn — ilki gereksiz async (inline `[object Promise]`), ikincisi **derlenmeyen gövde**: fonksiyon atlanır |
130
+ | FN-005 | Kaynak/kapsam tutarsız: workflow'a `applicationId`/`scope`/`pageId`; studio'ya `applicationId` ya da `scope` yok; `page` kapsamına `pageId` yok; `application` kapsamına `pageId` var | **block** — platform 422 |
131
+
132
+ Studio kaydı sonrası bağlı sayfaların çalışma paketi `Pages.Updated` ile yeniden kurulur (B-11):
133
+ `/dev` yolu yeni gövdeyi hemen, `/view` yolu önbellek tazelenince gösterir. Workflow kaydı önbellek
134
+ taşımaz; sonraki koşu yeni gövdeyi görür.
135
+
136
+ ## İfadeden çağrı: `{{ }}` ve `code` adımı (studio)
137
+
138
+ ```jsonc
139
+ // prop bağlaması — page_schema_patch set_binding
140
+ { "op": "set_binding", "target": "txt_toplam", "prop": "content", "expression": "{{ Functions.toplamHesapla(num_fiyat.value, num_adet.value) }}" }
141
+ ```
142
+
143
+ ```js
144
+ // UI flow code adımı (args.value) — await serbest
145
+ const toplam = Functions.toplamHesapla(10, 3);
146
+ state.page.sonuc = toplam;
147
+ ```
148
+
149
+ - Hata gövdeden yayılır ve `Functions.<ad>: <mesaj>` ile öneklenir; prop bağlamasında `runCode`
150
+ hatayı yutar, prop **yazılmaz** ve `page_screenshot` `runtimeErrors` taşır (PAGE-020/021).
151
+ - `isAsync:true` fonksiyonu `{{ }}` içinde çağırma: dönüş Promise'dir, ekranda `[object Promise]`
152
+ görünür. Async fonksiyon `code` adımında `await Functions.x()` ile ya da `function` adımıyla çağrılır.
153
+ - `flow_create`/`flow_update` yazımında gateway her `Functions.<ad>(` çağrısını uygulamanın studio
154
+ fonksiyon listesiyle karşılaştırır (FLOW-025, uyarı): bilinmeyen ad, başka sayfanın sayfa
155
+ fonksiyonu, bildirimden fazla argüman, setter/condition ifadesinde async fonksiyon.
156
+
157
+ ## UI flow `function` adımı ("Call function", K9)
158
+
159
+ ```jsonc
160
+ { "stepId": "hesapla", "name": "hesapla", "type": "function", "kind": "normal",
161
+ "args": { "functionId": "<function_list id>", "functionName": "toplamHesapla",
162
+ "parameters": [
163
+ { "name": "fiyat", "value": { "type": "property", "ref": { "source": "component", "element": "num_fiyat", "property": "value" } } },
164
+ { "name": "adet", "value": { "type": "static", "ref": 3 } } ] },
165
+ "branches": [ { "name": "always", "nextStepId": "yaz" } ] }
166
+ ```
167
+
168
+ - `functionId` **zorunlu**, uygulamada var olmalı ve bir **studio** fonksiyonu olmalı (backend
169
+ `422 GlobalFunctionNotFound` — workflow fonksiyonu adıma bağlanamaz; gateway FLOW-024 ile istek
170
+ gitmeden bloklar). Runtime fonksiyonu **önce id** ile çözer, `functionName` yalnız gösterim ve
171
+ yedektir — yeniden adlandırma akışı kırmaz.
172
+ - `parameters[].name` bildirimdeki adla eşleşir; `value` şekli `microservice` adımıyla aynı
173
+ (`static` · `property` · `storage` · `state` · `variable` · `code` · `page` · `item`). Eksik
174
+ zorunlu parametre adımı düşürür, tanınmayan ad sessizce düşer (FLOW-024 ikisini de uyarır).
175
+ - Çıktı `Steps.<adımAdı>.data`; hata `Steps.<adımAdı>.error.message` (nesne — `microservice`
176
+ adımının dize hatasından farklı). Dal adı `always`; hata yolu `errorSteps` ile aynı mekanizma.
177
+ - Sonucu ekrana yazmak için sonraki `setter` iteratee'si `storage` tipiyle `mapping.source:
178
+ "hesapla.data"` okur (adım **adı**, stepId değil) — tam gövde `ngapps://examples/flow-call-function`.
179
+ - Akışı olaya bağlamak ayrı adımdır: `page_schema_patch set_event { target, event:'click', eventValue:<flow id> }`.
180
+ - `end` adımı koyma; son adımın dalı `nextStepId: null` ile biter (FLOW-023).
181
+
182
+ ## Sunucuda ne kullanılır: `source:'workflow'`
183
+
184
+ Bir hesabı workflow / middleware / automation ifadesinden çağırman gerekiyorsa
185
+ `function_create source:'workflow'` ile tanımla ve **çıplak adla** çağır:
186
+
187
+ ```js
188
+ // workflow code adımı (rule.expression)
189
+ return { toplam: toplamHesapla(input.fiyat, 2) };
190
+ ```
191
+
192
+ ```js
193
+ // automation koşulu
194
+ toplamHesapla(row.fiyat, row.adet) > 1000
195
+ ```
196
+
197
+ - Tenant kapsamlıdır: tanımlandığı andan sonra her uygulamanın her workflow ifadesinde görünür,
198
+ her koşuda DB'den yüklenir (önbellek yok). Gövde bağlamdan bağımsız olmalı — dinamik veriyi
199
+ parametre olarak geçir.
200
+ - `workflow_preview` ile doğrula: `return toplamHesapla(3, 2)` → `data: 5`.
201
+ - İfadede `Functions.<ad>(…)` yazarsan gateway **istek gitmeden bloklar** (`WF-030`); zorlarsan
202
+ Jint `Functions is not defined` fırlatır ve adım hata yoluna girer.
203
+ - Mikroservis alan/filtre ifadeleri hiçbir kaynağı yüklemez — orada fonksiyon yok.
204
+
205
+ ## Güncelleme ve silme
206
+
207
+ - `function_update` platforma **tam gövde** gönderir; gateway mevcut kaydı okuyup vermediğin alanları
208
+ doldurur — yalnız `body` göndermen yeter. `source`/`applicationId`/`scope`/`pageId` değişmez. Ayrı
209
+ patch aracı yoktur: fonksiyonun tek büyük alanı gövdedir.
210
+ - **Yanıt kimin etkileneceğini söyler:** `dependents` (kullanan flow/workflow adları) ve
211
+ `signatureChange` (ad ya da parametre ad/sırası değiştiyse eski → yeni; tip, varsayılan ve gövde
212
+ imzayı değiştirmez). İkisi birden doluysa `warnings[]` gelir — çağrı konumsaldır (K5), `function`
213
+ adımı parametreyi ada göre eşler; güncelleme yine yapılır (K12), silme ise engellenir. Uyarı
214
+ aldıysan çağıran ifadeleri gözden geçir, `dependency_graph(module:'global-function')` listeyi verir.
215
+ - **Yeniden adlandırma çağıranlara yazılır (2026-09-11):** platform yeni adı aynı işlemde çağıranlara
216
+ taşır; yanıt `renamedReferences` ile kaç kaydın yazıldığını söyler. Studio kaynağında `Functions.<eskiAd>`
217
+ başvuruları (akış adımları, `function` adımının `functionName`'i, `code` bağlamaları, diğer fonksiyon
218
+ gövdeleri) yazılır; düz metin (`static`) prop'lar kod değildir, değişmez. Workflow kaynağında
219
+ `<eskiAd>(…)` çağrıları (workflow ifadeleri, otomasyon koşulları, workflow fonksiyonu gövdeleri)
220
+ yazılır; eski ad yeni adın yazılamadığı bir yerde kalırsa — çağrı dışı kullanım (değişken, nesne
221
+ anahtarı) ya da ham sorgu ifadesi (`isExpression: true` `rawQuery`; içindeki SQL çoğunlukla JS metnidir)
222
+ — platform **400** `CantRenameUsedGlobalFunction` ile reddeder ve hiçbir şey yazmaz. Düz SQL
223
+ (`isExpression: false`) kullanım sayılmaz, yazılmaz. Fonksiyonun kendi gövdesindeki çağrılar
224
+ (özyineleme) da yeni adı alır. Tablo adımı alan ifadeleri taramaya girmez, onları elle düzelt.
225
+ - `function_delete`: gateway önce bağımlılık grafiğini okur ve kullanan flow/workflow varsa isteği
226
+ göndermez (409, liste). Studio kaynağında platform silmeyi **engellemez** (K12); bilinçli silme için
227
+ `acknowledgeDependents: true`. Workflow kaynağında platform **400** `CantDeleteUsedGlobalFunction`
228
+ ile reddeder, `acknowledgeDependents` bunu geçemez.
229
+ - Uygulama silinince studio fonksiyonları cascade silinir; deploy ve şablon iki kaynağı da taşır
230
+ (`function` adımlarının `functionId`'si kurulumda yeniden eşlenir, workflow kaynağı ada göre upsert).
231
+
232
+ ## Tuzaklar
233
+
234
+ - **Yanlış kaynak:** sunucu ifadesinde `Functions.x(` → `WF-030` block; tarayıcı ifadesinde çıplak
235
+ workflow adı → `x is not defined`. Aynı hesap iki dünyada gerekiyorsa iki kayıt.
236
+ - **Async inline:** `{{ Functions.veriGetir() }}` → `[object Promise]`. Async fonksiyon yalnız
237
+ `code`/`function` adımından; workflow kaynağı async olamaz.
238
+ - **Sayfa fonksiyonu başka sayfada yok:** `Functions.x is not a function`. Ortak kural uygulama
239
+ kapsamına.
240
+ - **Ad çakışması 422:** studio'da uygulama içinde kapsamlar arası, workflow'da tenant içinde;
241
+ mesaj çakışan kapsamı/sayfayı söyler.
242
+ - **Ayrılmış adlar:** studio'da `Functions` (K1: komponent adı da olamaz, PAGE-009); workflow'da
243
+ motor globalleri (`system`, `input`, `request`, `Now`, `crypto`…). `Functions` workflow kaynağında
244
+ serbesttir — sunucuda o ad alanı yok.
245
+ - **Önekli hata:** gövde hatası `Functions.<ad>: <mesaj>` (studio) ya da `<ad>: <mesaj>` (workflow)
246
+ olarak gelir; `Steps.<adım>.error.message` ya da `runtimeErrors`'ta bu öneki ara.
247
+ - **Mobil yok** (K11): `apps/mobile` runtime'ı `Functions`'ı boş nesne kurar.
248
+ - **Önbellek:** `/view` yolu eski gövdeyi birkaç saniye gösterebilir; `/dev` yolu anlıktır.
249
+ - **Parametre konumsal:** `parameters` sırasını değiştirmek mevcut çağrıların anlamını değiştirir;
250
+ `function` adımları ada göre eşlendiği için etkilenmez.
251
+
252
+ ## Doğrulama
253
+
254
+ 1. `function_list` → kaynak, imza ve id doğru mu (`source` süzgeciyle iki listeyi ayrı gör).
255
+ 2. Studio: `page_runtime_get` özeti `appFunctions` / `pageFunctions` imzalarını taşır — sayfa paketi
256
+ fonksiyonu gördü mü (önbellek tazelenmiş mi).
257
+ 3. Studio: `page_screenshot` `actions` ile butona tıkla, kareyi ve `actionsReport[].flowRuns`'ı oku;
258
+ ifade patladıysa `runtimeErrors`.
259
+ 4. Workflow: `workflow_preview` ile çıplak adla koştur (`return toplamHesapla(3, 2)`); sonuç
260
+ `data`'da.
261
+ 5. Nerede kullanıldığı: `dependency_graph(module:'global-function', id)` — iki kaynakta da
262
+ `{ flows, workflows }` döner (workflow kaynağında `flows` boş).
@@ -7,21 +7,41 @@ Bağımlılıklar bu sırayı zorunlu kılar; atlama:
7
7
  ```
8
8
  1. project_create (application zorunlu: ilk application projeyle birlikte açılır;
9
9
  application slug'ı ORG GENELİNDE tekildir — 'web' büyük olasılıkla
10
- doludur, 409'da project_list ile mevcut slug'ları tara)
10
+ doludur, 409'da project_list ile mevcut slug'ları tara.
11
+ DİL: gateway create'ten sonra projenin dillerini kurar — verirsen
12
+ languages/defaultLanguage'ı, vermezsen tek dillik ['en'] tohumunu
13
+ (PRJ-003). Ürünün dili farklıysa BURADA yaz; dilsiz projede yazılan
14
+ çeviriler runtime'da ham anahtar olarak çizilir, bkz.
15
+ platform_guide('translation'))
11
16
  2. project_get (environment id'leri + application id burada)
12
- 3. datasource_list (her projede built-in datasource hazır gelir — çoğu iş için yeterli;
13
- dış DB gerekiyorsa datasource_test_connection → datasource_create)
17
+ 3. datasource_list (built-in datasource PROJEYLE BİRLİKTE doğar: project_create ayrı bir
18
+ veritabanı, her environment için ayrı bir şema ve o veritabanına bağlı
19
+ built-in datasource açar. Entity'lerini oraya aç — listede
20
+ isBuiltIn: true olan kayıt odur, silinemez.
21
+ TEMİZ BİR İSİM ALANI İSTİYORSAN YENİ PROJE AÇ, yeni datasource değil:
22
+ tek datasource içinde önek/şema ayırmanın yolu YOK.
23
+ datasource_create YALNIZ kullanıcı kendi veritabanını verdiğinde
24
+ çağrılır ('host/port/kullanıcı/parola şunlar'); built-in'in parolası
25
+ hiçbir tool'dan okunamaz ve okunması gerekmez. Dış bir DB'ye kurulan
26
+ entity users'a ilişki KURAMAZ — kimlik gerektiren her uygulama
27
+ built-in'de kurulur, bkz. platform_guide('entity'))
14
28
  4. entity_list (ÖNCE BAK: platform her projeye hazır entity'ler açar — users (kimlik:
15
29
  (applicationId'siz) email/password/first_name/last_name), roles, user_roles, permissions.
16
30
  applicationId VERİRSEN bunlar listede GÖRÜNMEZ. Ürünün "müşteri" /
17
31
  "öğrenci" / "üye" kavramı için sıfırdan bir kimlik tablosu açmadan önce
18
- users'ı gör — bkz. platform_guide('entity') §'Hazır entity'ler')
32
+ users'ı gör — bkz. platform_guide('entity') §'Hazır entity'ler'.
33
+ ROL: role_create diye bir tool YOK ve olmamalı — roles sıradan bir
34
+ entity'dir. Projeyle gelen roller yetmiyorsa yol entity_get('roles') +
35
+ kendi microservice ucun; sayfaya bağlama page_create roleIds ile)
19
36
  5. entity_create (applicationIds Studio'nun application bazlı entity listesi içindir —
20
37
  boşsa satır uçları ÇALIŞIR ama entity Studio listesinde görünmez;
21
38
  önce ilişkisiz gövdeler, sonra update/patch ile ilişki alanları —
22
39
  bkz. platform_guide('entity'))
23
40
  6. row_create (test verisi; alan tanımlarını row_list ile doğrula)
24
- 7. dto_list / dto_create (workflow/automation'ın parameterDtoId/returnDtoId sözleşmeleri;
41
+ 7. dto_list / dto_create — çocuk alanın `type` değeri **`"string"`**'tir; `"text"` yazmak sessizce
42
+ `object`'e çevrilir ve DTO bozuk kurulur (ölçüldü 2026-09-05, teşhis platformun kendi ürettiği
43
+ bir DTO'yu okuyarak yapıldı). Şablon için var olan bir DTO'yu `dto_get` ile alın.
44
+ (workflow/automation'ın parameterDtoId/returnDtoId sözleşmeleri;
25
45
  platform entity başına DTO üretir — önce dto_list ile ara)
26
46
  8. workflow_create (type: 'middleware' — YALNIZ ihtiyaç varsa; bkz. aşağıdaki karar tablosu.
27
47
  Kuruyorsan guard + 'user' değişkeni; uçlara middlewareIds ile
@@ -31,6 +51,11 @@ Bağımlılıklar bu sırayı zorunlu kılar; atlama:
31
51
  sonra execute+debug)
32
52
  10. workflow_create / (bkz. platform_guide('workflow'); branch bağlantıları + returnDtoId —
33
53
  automation_create returnDtoId'siz workflow 'unready' kalır; automation/middleware muaf)
54
+ 10b. function_create (İSTEĞE BAĞLI, uygulama düzeyinde: 3+ yerde tekrarlanacak hesap ya da hem
55
+ tarayıcıda hem sunucuda geçerli iş kuralı varsa ŞİMDİ tanımla — sayfalar
56
+ ifadelerde Functions.<ad>(…) ile, akışlar 'function' adımıyla çağırır;
57
+ sayfaya özgü fonksiyon (scope:'page') sayfa açıldıktan sonra gelir.
58
+ Kurallar platform_guide('functions'))
34
59
  11. layout_create (header/sidebar + MUTLAKA bir 'slot' — slot'suz layout'a bağlı sayfa
35
60
  boş görünür; bkz. platform_guide('page') Kural 5)
36
61
  12. page_create + … (İŞ BURADA BİTMEZ: her kaydın yönetim ekranı, kimlik varsa giriş
@@ -51,8 +76,17 @@ kilitler:
51
76
  2. O workflow'un ucu, kimlik kurulduğu için `middlewareIds` ile auth middleware'ine bağlıdır.
52
77
  3. Auth middleware'i token'ı **çerezten** okur; ortada henüz kullanıcı yoktur, dolayısıyla token
53
78
  da yoktur.
54
- 4. **Yeni projede `users` tablosu BOŞ gelir** — `organization_sync_users` Studio operatörünü
55
- otomatik kopyalamaz.
79
+ 4. **Yeni projede `users` tablosu BOŞ gelir.** Studio operatörü (`admin@…`) organizasyon
80
+ kullanıcısıdır, uygulamanın kullanıcısı DEĞİLDİR; kimse onu otomatik kopyalamaz.
81
+
82
+ **Bu bir platform boşluğudur, kısa yolu yoktur.** İlk kullanıcıyı açmanın desteklenen tek yolu
83
+ aşağıdaki bootstrap desenidir: geçici bir uç aç, kullanıcıyı yaz, ucu hemen sil. Bakım/migration
84
+ uçlarını (`/organizations/sync-users` gibi `Sync*` uçları) **kullanma** — onlar ürün yüzeyinin
85
+ parçası değildir, özellik geliştirirken veri düzeltmek için yazılmışlardır ve kaldırılmaktadırlar.
86
+ Gateway de onları araç olarak yayınlamaz.
87
+
88
+ Bu tur, kimlik kuran her yeni projede ödenmek zorunda: iki koşuda da (09-02 ve 09-04) `users`
89
+ boş bulundu ve ikisi de bu deseni elle kurdu.
56
90
 
57
91
  **Bootstrap deseni** (crm koşumunda uygulandı):
58
92
 
@@ -107,3 +141,44 @@ koda baktığını gizlemek yerine raporlamak.
107
141
  - microservice → `microservice_execute`, beklenmedik sonuçta `microservice_debug`
108
142
  - workflow → `workflow_preview`; automation → `automation_trigger` + `automation_histories`
109
143
  - "API 200 döndü" tek başına bitti saymaz; politika bulgularını (`policyFindings`) oku ve gereğini yap
144
+
145
+
146
+ ## Yazdıktan sonra `silentlyDropped` alanına bak
147
+
148
+ Platformun bir alanı **hatasız yutması** bu depodaki en pahalı hata sınıfı: çağrı 200 döner,
149
+ `appliedPatch` uygulandığını söyler, `*_get` değeri geri verir ve o alan hiç işe yaramaz.
150
+ 2026-09-05 koşusunda kaybedilen sürenin çoğu sekiz böyle çağrıdan geldi.
151
+
152
+ Gateway yazma tool'larında gönderdiğin gövdeyi kaydedilenle karşılaştırır ve farkı yanıta
153
+ `silentlyDropped` olarak koyar (`microservice_*`, `query_*`, `flow_*`, `dto_*`, `workflow_*`,
154
+ `layout_create`, `page_schema_patch`). Boş değilse o alan **kaydedilmemiştir**:
155
+
156
+ ```jsonc
157
+ "silentlyDropped": [
158
+ "steps[stepId=sync_filters].args.expression: gönderilen \"state.page.month = …\" ↔ kaydedilen yok"
159
+ ]
160
+ ```
161
+
162
+ Diff dizi öğelerini indeksle değil KİMLİKLE eşler (`stepId`, `elementId`, `name`, `id`), çünkü
163
+ platform diziyi kendi sırasında geri döndürür. Diff üretilemeyen tek durum, yanıtın kayıt değil
164
+ kabul gövdesi olmasıdır; o zaman alan hiç görünmez ve doğrulamayı `*_get` ile kendin yaparsın.
165
+
166
+ ## `unmappedMembers`: anahtarın komutta HİÇ olmadığını söyler
167
+
168
+ İki kanal aynı yanıtta çıkabilir ve **kanıt güçleri farklıdır**:
169
+
170
+ - `silentlyDropped` bir SEZGİSELDİR: gönderdiğin gövdeyi kaydedilenle karşılaştırır. Platform bir
171
+ alanı başka adla saklarsa ya da id'yi yeniden atarsa yanlış alarm verebilir.
172
+ - `unmappedMembers` OTORİTERDİR: o anahtar gönderdiğin komutun şemasında **yoktur**. Platform onu
173
+ hata vermeden yok sayar, yani yazdığını sandığın değer hiç kaydedilmez.
174
+
175
+ ```jsonc
176
+ "unmappedMembers": ["indexes[0].isUnique"]
177
+ ```
178
+
179
+ Bu satırı gördüğünde alanı silme — **doğru adı bul**. Şema `ngapps://schemas/<Komut>` altındadır
180
+ (ör. `ngapps://schemas/UpdateEntityCommand`) ve gerçek maliyeti ölçülmüştür: `unique` yerine
181
+ `isUnique` yazılan bir index UNIQUE OLMADAN kurulur ve çağrı 200 döner.
182
+
183
+ Kanal yalnız senin yazdığın anahtarları bildirir; gateway'in bir kaydı okuyup geri yazarken
184
+ taşıdığı alanlar (`slug`, `datasourceId`, `audit` gibi) burada görünmez.
@@ -12,10 +12,22 @@ kutusu layout modülünde süzülmez — tüm katalog kullanılabilir.
12
12
 
13
13
  **2. Şema alanının adı `schema` değil `views`.** (LAY-001)
14
14
 
15
- **3. Micro-op hattı YOKTUR.** `page_schema_patch`'in layout karşılığı yok (backend'de
16
- `PATCH /layouts/.../schema` ucu yok). Değişiklik `layout_update` ile yazılır; gateway kaydı
17
- önce okur ve yalnız verdiğin alanları değiştirir, `views` göndermezsen ağaç korunur.
18
- Okumak için `layout_schema_get` (summary kipi hedef bulmak için yeterlidir).
15
+ **3. Micro-op ucu yok, ama `PATCH /layouts/{app}/{id}` var.** `page_schema_patch`'in birebir
16
+ karşılığı yoktur (`PATCH /layouts/.../schema` ucu yok); onun yerine platform genel bir JSON Patch
17
+ ucu verir ve `layout_patch` onu kullanır: layout'u okur, JSON Patch'i ve kendi normalizasyonlarını
18
+ uygular, doğrulamadan geçirir ve **farkı** `{ baseVersion, ops }` olarak yazar — tam gövde PUT'u
19
+ atılmaz. Böylece tek bir başlık düzeltmesi için 12 düğümlük ağacı yeniden göndermezsin (ölçüm:
20
+ 09-04 koşusu Y-25). Yol İNDEKS yerine SEÇİCİ alır:
21
+ `/views/0/children[elementId=baslik]/props/content/data`.
22
+
23
+ **Sürüm ve 409.** Okunan kaydın `version` alanı `baseVersion` olarak gider. Sen okuduktan sonra
24
+ başka biri yazdıysa platform **409** döner ve HİÇBİR op uygulanmaz; doğru tepki "aynı op'ları
25
+ tekrar göndermek" değil, `layout_schema_get` ile yeniden okuyup patch'i güncel hâle göre kurmaktır.
26
+ `version` bir **string**tir (mikrosaniye cinsinden zaman damgası, JavaScript'in güvenli tam sayı
27
+ sınırının üstünde) — sayıya çevirme, olduğu gibi geri gönder. `expectedUpdatedAt` verirsen gateway
28
+ ayrıca istek gitmeden önce yerel bir kontrol daha yapar. Tam ağacı kendin yazacaksan `layout_update`;
29
+ `views` göndermezsen mevcut ağaç korunur. Okumak için `layout_schema_get` (summary kipi hedef bulmak
30
+ için yeterlidir).
19
31
 
20
32
  **4. TEK slot.** Sayfa şeması **her** slot'a ayrı ayrı kopyalanır — iki slot, sayfayı iki
21
33
  kez çizer ve `elementId`'leri tekrarlar. (LAY-002 / LAY-006)
@@ -45,7 +57,9 @@ runtime hem Studio tuvali bölgeleri 12 kolonluk ızgarayla yerleştirir.
45
57
  **7. Mobilde flex YIĞILMAZ.** Runtime'ın mobil kuralı yalnız ızgara özelliklerini ezer.
46
58
  Telefonda alt alta düşmesi gereken satırı `layout:'grid'` ile kur; `layout:'flex'` +
47
59
  `direction:'row'` telefonda da yan yana kalır (375px'te ölçüldü: ızgara çocukları 375/375px
48
- alt alta, flex çocukları 49/310px yan yana).
60
+ alt alta, flex çocukları 49/310px yan yana). Not: `wrap` varsayılanı artık açık (2026-09-01) —
61
+ sığmayan çocuk alt satıra SARAR ama bu ızgara yığılması değildir; dar ölçülü çocuklar yan
62
+ yana kalmaya devam eder.
49
63
 
50
64
  **8. Doğrulama tek yerden:** `page_runtime_get`. Layout'un kendi serve URL'i yoktur —
51
65
  gerçek çıktıyı, layout'a bağlı bir sayfanın runtime paketinde görürsün (slot yerleşimi
@@ -67,9 +81,12 @@ container isWrapper:true heightType:'fill' layout:'flex' direction:'row' gap:
67
81
  └ slot heightType:'fill' block w12 y6
68
82
  ```
69
83
 
70
- - **Genişlik kolon payıdır:** yan menü `w:2` = 12'de 2 → 1440px tasarım genişliğinde 240px.
71
- Sabit piksel istiyorsan `appearance.widthPx: 240` (yalnız flex çocuğunda okunur; ızgara
72
- kabında okunmaz).
84
+ - **Genişlik `appearance.widthType`'tan gelir (2026-09-01); kolon payı fallback'tir.**
85
+ Yan menü için `widthType: 'fixed'` + `widthString: "240px"` (serbest CSS uzunluğu:
86
+ `"50%"`, `"10vw"`, `calc(...)` de geçer; yalnız flex kabın çocuğunda okunur, mutlak
87
+ ızgara kabında okunmaz). `'fill'` kabın tüm genişliğini alır, `'auto'` içeriğe oturur;
88
+ `widthType` HİÇ yazılmazsa `w:2` = 12'de 2 → 1440px tasarım genişliğinde 240px payı
89
+ geçerlidir. String yalnız `'fixed'` modda okunur — tek başına `widthString` ölüdür.
73
90
  - **Yükseklik `fill`'dir**, `size.h` değil: kök ekranı doldurur, yan menü ve içerik sütunu
74
91
  kökün bıraktığını, slot da üst şeritten artanı alır. Slot'un grid satırı ayrıca açık
75
92
  uçludur (`y / auto`), yani sayfa uzadıkça slot uzar.
@@ -115,6 +132,29 @@ bağlantı nesnesi ya da tam yol).
115
132
  // flex anlamının devreye girmemesi.
116
133
  ```
117
134
 
135
+ ## Çeviri: header/sidebar etiketini anahtara bağlamak
136
+
137
+ Layout'un `views` ağacındaki bir etiketi çeviriye bağlamak için **bütün ağacı yeniden yazma**.
138
+ `layout_patch` `set_prop_type` micro-op'unu tanır ve prop'un tipini yerinde değiştirir:
139
+
140
+ ```jsonc
141
+ { "op": "set_prop_type", "target": "app_header_title", "prop": "content",
142
+ "propType": "translation", "ref": "layout.header.title" }
143
+ ```
144
+
145
+ - Anahtar **`ref`'te** yaşar, `data`'da değil — runtime `data`'yı her turda çözümlenmiş değerle
146
+ ezer. `ref` boşsa gateway isteği göndermeden reddeder.
147
+ - Mevcut statik metin `data`'da yedek olarak KALIR, böylece Studio canvas'ında boş kutu görünmez.
148
+ - `set_prop_type` ile JSON Patch aynı `ops` listesinde karışık verilebilir; micro-op'lar önce
149
+ uygulanır, sonra patch yolları çözülür.
150
+ - Aynı op sayfa tarafında `page_schema_patch` ile çalışır — sözleşme birebir aynıdır. Anahtarları
151
+ `translation_list` ile bulun; fallback zinciri ve `t:` doğrulama mesajı sözleşmesi
152
+ `platform_guide('translation')`'da.
153
+
154
+ > Layout'un diğer micro-op'ları YOKTUR: `add_component`, `remove_component`, `replace_prop` ve
155
+ > arkadaşları yalnız sayfa hattındadır. Layout'ta düğüm eklemek/silmek için JSON Patch ya da
156
+ > `layout_update` kullanılır.
157
+
118
158
  ## Sayfayı layout'a bağlama
119
159
 
120
160
  `page_update` ile `layoutId`. Bağlı sayfanın kendi şeması slot'un içine girer; sayfanın
@@ -140,8 +180,11 @@ bunlardan biri olabilir:
140
180
  (`mapPageLayoutToPreview`), `packages/ng-apps-ui/src/shared/render/render.functions.ts`
141
181
  (`resolveNodeBoxStyle` — slot'un `y / auto` satırı, flex çocuk genişliği),
142
182
  `packages/ng-apps-ui/src/shared/render/RenderComponent.svelte` (mobil media kuralı),
143
- `packages/ng-apps-screen-builder/src/flex-layout.ts` (`getFlexChildStyle` — `widthPx` ve
144
- `heightType:'fill'` dalı; tuval ve runtime aynı fonksiyonu okur),
183
+ `packages/ng-apps-screen-builder/src/flex-layout.ts` (`getFlexChildStyle` — `widthType`
184
+ fill/fixed/auto dalları, `normalizeCssSize` kabul kuralı; tuval ve runtime aynı fonksiyonu okur),
185
+ `apps/studio/src/features/page/components/appearance/appearance-size.functions.ts` (panelin
186
+ mod↔string yazım kuralları), `apps/studio/src/components/screen-builder/quick-stack.functions.ts`
187
+ (Quick Stack iskeleti; `docs/features/quick-stack.md`),
145
188
  `apps/studio/src/features/layout/layout.functions.ts` (`getDefaultLayout` — Kural 5a/5b'deki iskelet),
146
189
  `docs/components/layout-composition.md`, `docs/specs/2026-08-28-free-layout-responsive-design.md`,
147
190
  `docs/issues.md` ARC-031 / BE-002 / CQ-143.