@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.
- package/.env.example +2 -2
- package/.env.production.example +9 -1
- package/README.md +14 -38
- package/dist/config.js +36 -3
- package/dist/knowledge/backendConstraints.js +982 -0
- package/dist/knowledge/componentCatalog.js +549 -92
- package/dist/knowledge/componentEvents.js +120 -25
- package/dist/knowledge/coverage.js +43 -0
- package/dist/knowledge/flowGuards.js +30 -0
- package/dist/knowledge/functionGuards.js +134 -0
- package/dist/knowledge/guideSections.js +49 -0
- package/dist/knowledge/hydrate.js +97 -0
- package/dist/knowledge/languageCodes.js +36 -0
- package/dist/knowledge/languages.js +105 -0
- package/dist/knowledge/layoutSummary.js +10 -0
- package/dist/knowledge/localization.js +51 -0
- package/dist/knowledge/normalize.js +500 -16
- package/dist/knowledge/outlines.js +167 -12
- package/dist/knowledge/policy.js +14 -5
- package/dist/knowledge/propTypes.js +80 -0
- package/dist/knowledge/rules.js +961 -44
- package/dist/knowledge/schemaGuard.js +199 -0
- package/dist/knowledge/styleResolve.js +63 -4
- package/dist/observability/trace.js +27 -3
- package/dist/platform/csv.js +123 -0
- package/dist/platform/errors.js +107 -6
- package/dist/platform/http.js +34 -4
- package/dist/platform/patch.js +27 -0
- package/dist/platform/refs.js +104 -0
- package/dist/platform/responses.js +25 -6
- package/dist/platform/screenshot.js +544 -16
- package/dist/platform/secrets.js +40 -0
- package/dist/platform/tokenVault.js +89 -0
- package/dist/platform/writeDiff.js +281 -0
- package/dist/resources/examples/flow-call-function.json +66 -0
- package/dist/resources/examples/function-total.json +70 -0
- package/dist/resources/examples/layout-app-shell.json +1 -1
- package/dist/resources/examples/microfunction-node-sum.json +56 -0
- package/dist/resources/examples/microservice-table-list.json +2 -4
- package/dist/resources/examples/page-dynamic-form.json +3 -3
- package/dist/resources/examples/page-flex-sections.json +99 -0
- package/dist/resources/examples/page-sign-in.json +4 -3
- package/dist/resources/guides/component.md +81 -8
- package/dist/resources/guides/entity.md +712 -20
- package/dist/resources/guides/expressions.md +47 -2
- package/dist/resources/guides/external-component.md +9 -0
- package/dist/resources/guides/functions.md +262 -0
- package/dist/resources/guides/getting-started.md +82 -7
- package/dist/resources/guides/layout.md +53 -10
- package/dist/resources/guides/merge.md +231 -0
- package/dist/resources/guides/microfunction.md +166 -0
- package/dist/resources/guides/microservice.md +287 -15
- package/dist/resources/guides/middleware.md +89 -1
- package/dist/resources/guides/modify-existing.md +23 -0
- package/dist/resources/guides/page.md +402 -49
- package/dist/resources/guides/translation.md +150 -8
- package/dist/resources/guides/view.md +16 -1
- package/dist/resources/guides/workflow.md +199 -28
- package/dist/resources/knowledge.js +5 -0
- package/dist/resources/rules.js +27 -0
- package/dist/resources/schema-fingerprint.json +8 -0
- package/dist/resources/schemas/AnalyzeImportQuery.json +51 -0
- package/dist/resources/schemas/ApplyMergePlanCommand.json +19 -0
- package/dist/resources/schemas/CreateBulkRowCommand.json +36 -0
- package/dist/resources/schemas/CreateDatasourceCommand.json +15 -6
- package/dist/resources/schemas/CreateDiscoveredEntitiesCommand.json +19 -8
- package/dist/resources/schemas/CreateEntityCommand.json +52 -12
- package/dist/resources/schemas/CreateEnvironmentCommand.json +31 -0
- package/dist/resources/schemas/CreateGlobalFunctionCommand.json +95 -0
- package/dist/resources/schemas/CreateImportPlanCommand.json +278 -0
- package/dist/resources/schemas/CreateMergePlanCommand.json +34 -0
- package/dist/resources/schemas/CreateMicrofunctionCommand.json +117 -0
- package/dist/resources/schemas/CreateMicrofunctionRuntimeCommand.json +51 -0
- package/dist/resources/schemas/CreateMicroserviceCommand.json +145 -3
- package/dist/resources/schemas/CreateQueryCommand.json +56 -3
- package/dist/resources/schemas/CreateRowCommand.json +38 -0
- package/dist/resources/schemas/CreateViewCommand.json +13 -10
- package/dist/resources/schemas/CreateWorkflowCommand.json +106 -14
- package/dist/resources/schemas/DataJobDto.json +267 -0
- package/dist/resources/schemas/ExportRowsCommand.json +172 -0
- package/dist/resources/schemas/Filter.json +3 -1
- package/dist/resources/schemas/GetRowsQuery.json +6 -1
- package/dist/resources/schemas/GlobalFunctionDto.json +89 -0
- package/dist/resources/schemas/GlobalFunctionUpdateResultDto.json +249 -0
- package/dist/resources/schemas/ImportAnalysisDto.json +401 -0
- package/dist/resources/schemas/ImportPlanDto.json +260 -0
- package/dist/resources/schemas/ImportSampleDto.json +90 -0
- package/dist/resources/schemas/InvokeMicrofunctionCommand.json +25 -0
- package/dist/resources/schemas/PreviewMicroserviceCommand.json +135 -1
- package/dist/resources/schemas/PreviewQueryCommand.json +5 -2
- package/dist/resources/schemas/PreviewWorkflowCommand.json +45 -9
- package/dist/resources/schemas/ResolveMergeConflictsCommand.json +58 -0
- package/dist/resources/schemas/RevertMergePlanCommand.json +19 -0
- package/dist/resources/schemas/RunImportCommand.json +62 -0
- package/dist/resources/schemas/StepDto.json +34 -3
- package/dist/resources/schemas/UpdateBulkRowCommand.json +36 -0
- package/dist/resources/schemas/UpdateDatasourceCommand.json +15 -6
- package/dist/resources/schemas/UpdateEntityCommand.json +52 -11
- package/dist/resources/schemas/UpdateGlobalFunctionCommand.json +66 -0
- package/dist/resources/schemas/UpdateMicrofunctionCommand.json +121 -0
- package/dist/resources/schemas/UpdateMicrofunctionRuntimeCommand.json +54 -0
- package/dist/resources/schemas/UpdateMicroserviceCommand.json +147 -4
- package/dist/resources/schemas/UpdateQueryCommand.json +13 -3
- package/dist/resources/schemas/UpdateRowCommand.json +40 -0
- package/dist/resources/schemas/UpdateViewCommand.json +15 -10
- package/dist/resources/schemas/UpdateWorkflowCommand.json +106 -14
- package/dist/server.js +17 -1
- package/dist/tools/access.js +3 -3
- package/dist/tools/activities.js +40 -0
- package/dist/tools/applications.js +1 -1
- package/dist/tools/automations.js +76 -34
- package/dist/tools/common.js +55 -0
- package/dist/tools/components.js +16 -7
- package/dist/tools/datasources.js +83 -21
- package/dist/tools/dependencies.js +1 -1
- package/dist/tools/deployments.js +34 -2
- package/dist/tools/dtos.js +25 -12
- package/dist/tools/entities.js +113 -28
- package/dist/tools/environments.js +52 -0
- package/dist/tools/externalComponents.js +9 -3
- package/dist/tools/files.js +57 -42
- package/dist/tools/flows.js +205 -13
- package/dist/tools/folders.js +7 -2
- package/dist/tools/functions.js +331 -0
- package/dist/tools/globalFunctions.js +63 -0
- package/dist/tools/importSchemas.js +79 -0
- package/dist/tools/imports.js +241 -0
- package/dist/tools/layouts.js +103 -29
- package/dist/tools/merges.js +113 -0
- package/dist/tools/microfunctions.js +155 -0
- package/dist/tools/microservices.js +270 -40
- package/dist/tools/organizations.js +5 -6
- package/dist/tools/pages.js +421 -104
- package/dist/tools/platformInfo.js +155 -11
- package/dist/tools/projects.js +183 -33
- package/dist/tools/queries.js +32 -10
- package/dist/tools/revisions.js +94 -0
- package/dist/tools/rows.js +484 -50
- package/dist/tools/screenWrite.js +68 -0
- package/dist/tools/screens.js +28 -0
- package/dist/tools/templates.js +32 -5
- package/dist/tools/translations.js +24 -8
- package/dist/tools/views.js +20 -10
- package/dist/tools/workflows.js +56 -21
- 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'ı).
|
|
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`
|
|
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 (
|
|
13
|
-
|
|
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
|
|
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
|
|
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
|
|
16
|
-
`PATCH /layouts/.../schema` ucu yok)
|
|
17
|
-
|
|
18
|
-
|
|
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
|
|
71
|
-
|
|
72
|
-
|
|
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` — `
|
|
144
|
-
|
|
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.
|