vNext v0.0.60 Migration Rehberi

Bu rehber, vNext v0.0.60 ile gelen yeni yetenekleri ve mevcut bir domain projesini bu sürüme taşırken atılması gereken adımları anlatır. Sürüm beş ana başlık getiriyor: yeniden kullanılabilir sys-mappings bileşeni ve sandbox'lı custom C# helper'lar, rol bazlı state alias, tutarlı FunctionScope zorunluluğu, Operations & Observability sıkılaştırmaları ve yapılandırılabilir asenkron transition işletimi.

Bu sürümle birlikte bileşen şeması 0.0.46'ya yükseldi. Doğrulama yapmadan önce domain projenizde @burgan-tech/vnext-schema paketini güncelleyin.

Teknik release notları için: Release v0.0.60.

---

1. Mappings Bileşeni & Custom C# Helper'lar

vNext'e yeni bir sistem bileşeni eklendi: sys-mappings (kısaca Mappings). Mapping bileşeni, script mapping kodlarının yeniden kullanılabilir, versiyonlanabilir ve daha verimli kullanılmasını sağlar. Ayrıca plugin özelliği ile 3rd-party kütüphane/DLL'leri embed ederek kullanım sağlar — bu da business case'lerinde sıkça ihtiyaç duyulan ayrı "utilities API" gereksinimini ortadan kaldırır.

Ne değişti

• Geliştiriciler kendi C# yardımcı sınıflarını .csx olarak — tıpkı flow, task ve view'lar gibi — bir bileşen olarak yükleyebilir.
• Bu helper'lar bir flow tanımının mapping'inden referans verilir; runtime önce helper sınıflarını derler, ardından mapping'i bunlara karşı derleyip çalıştırır.
• Helper'lar sandbox altında, içerik hash'i ile cache'lenerek çalıştırılır.

Domain projesi yapılandırması

Bu bölümdeki adımlar mevcut bir domain projesini v0.0.60'a taşırken atılır. Çalışan bir referans için vnext-example reposuna bakın — aşağıdaki yapılandırmanın tamamı orada hazırdır.

1. Mappings/ dizini

Domain bileşen ağacına Mappings/ dizini eklenir. Her mapping bir .json tanım dosyası + src/ altında karşılık gelen bir .csx kaynak dosyasıdır:

├── <domain>/                       # ör. core/
│   ├── Extensions/
│   ├── Functions/
│   ├── Schemas/
│   ├── Tasks/
│   ├── Views/
│   ├── Workflows/
│   └── Mappings/                   # YENİ
│       └── account-opening/        # iş akışı/alan bazlı klasör
│           ├── initial-mapping.json
│           ├── json-helper.json
│           ├── rsa-crypto.json
│           └── src/
│               ├── InitialTransMapping.csx
│               ├── JsonHelper.csx
│               └── RsaCryptoHelper.csx
├── vnext.config.json

2. vnext.config.json

paths ve exports bloklarına mappings eklenir (diğer bileşenlerle aynı hizada):

{
  "domain": "core",
  "paths": {
    "componentsRoot": "core",
    "schemas": "Schemas",
    "workflows": "Workflows",
    "tasks": "Tasks",
    "views": "Views",
    "functions": "Functions",
    "extensions": "Extensions",
    "mappings": "Mappings"
  },
  "exports": {
    "schemas": [],
    "workflows": [],
    "tasks": [],
    "views": [],
    "functions": [],
    "extensions": [],
    "mappings": []
  }
}

3. Domain tooling script'lerine mappings desteği

Domain projesindeki bileşen keşfi test.js, validate.js, setup.js, index.js, build.js script'leri üzerinden yapılır. Bileşen türleri bu script'lerde listelendiği için, mappings'i her birine eklemek gerekir. (Yeni proje şablonlarında bu satırlar zaten gelir; eski projelerde elle eklenir.)

setup.js · index.js · build.js · validate.js — getPathsConfig içindeki defaults paths objesine:

const defaults = {
  componentsRoot: 'core',
  schemas: 'Schemas',
  workflows: 'Workflows',
  tasks: 'Tasks',
  views: 'Views',
  functions: 'Functions',
  extensions: 'Extensions',
  mappings: 'Mappings'        // YENİ
};

index.js — getMappings() getter'ı ve getAvailableTypes dönüşü:

// Get all mappings
getMappings: function() {
  const domainDir = findDomainDirectory();
  if (!domainDir) return {};
  const pathsConfig = getPathsConfig();
  return loadJsonFiles(path.join(domainDir, pathsConfig.mappings));   // YENİ
},

getAvailableTypes: function() {
  const pathsConfig = getPathsConfig();
  return [pathsConfig.schemas, pathsConfig.workflows, pathsConfig.tasks,
          pathsConfig.views, pathsConfig.functions, pathsConfig.extensions,
          pathsConfig.mappings];                                      // YENİ
},

build.js — reference build'deki componentDirs dizisine pathsConfig.mappings eklenir.

validate.js — dört noktada genişletilir:

// requiredExports ve componentGetters dizilerine:
'getMappings',
// vnextDirs ve expectedDirs dizilerine:
pathsConfig.mappings,
// directoryToSchemaType eşlemesine (mapping → 'mapping' şeması):
[pathsConfig.mappings]: 'mapping',

validate.js, mappings dizinini 'mapping' şema tipine eşler; şema @burgan-tech/vnext-schema paketinden (mapping-definition.schema.json) yüklenir — script'e ayrı bir şema dosyası eklemeye gerek yoktur.

test.js — beklenen export/dizin listelerine:

// expected exports ve getters dizilerine:
'getMappings',
// expectedTypes ve expectedDirs dizilerine:
'Mappings',

Mapping objesindeki scripts bloğu

Tüm mapping objelerinde (viewRule, rule, transition mapping, subflow mapping, task mapping, extension/function task mapping) yeni bir scripts objesi tanımlanabilir. scripts.helpers[] bir referans dizisidir (string değil — key/version/domain/flow alanları olan objeler), scripts.allowedAssemblies[] ise o mapping'e özel sandbox izinlerini global temel listenin üzerine ekler:

{
  "mapping": {
    "location": "./src/UserSessionMapping.csx",
    "code": "",
    "encoding": "NAT",
    "scripts": {
      "helpers": [
        {
          "key": "json-helper",
          "version": "1.0.0",
          "domain": "core",
          "flow": "sys-mappings"
        }
      ],
      "allowedAssemblies": [
        "Newtonsoft.Json"
      ]
    }
  }
}

Aynı scripts bloğu flow konfigürasyonuna da (attributes.scripts) eklenebilir:

{
  "attributes": {
    "type": "F",
    "scripts": {
      "helpers": [
        { "key": "rsa-crypto", "version": "1.0.0", "domain": "core", "flow": "sys-mappings" }
      ],
      "allowedAssemblies": [ "System.Security.Cryptography" ]
    }
  }
}

REF encoding

code encoding tipine yeni bir değer eklendi: REF. Bir mapping, kod gömmek yerine bir sys-mappings bileşenine referans verebilir:

{
  "mapping": {
    "encoding": "REF",
    "code": {
      "key": "initial-mapping",
      "version": "1.0.0",
      "flow": "sys-mappings",
      "domain": "core"
    }
  }
}

Kısıt: sys-mappings bileşeninin kendisi REF kullanamaz — referans hedefinin kendisidir, kendine referans veremez.

Sandbox

Helper'lar iki katmanlı derleme zamanı kapısı (reference allow-list + yasaklı API analizörü) ile kısıtlanır ve paylaşımlı, toplanabilir bir AssemblyLoadContext içinde derlenir. allowedAssemblies ile mapping bazında verilen izinler global temel listenin (Scripting:Sandbox:AllowedAssemblies) üzerine eklenir — yani bir flow, herkesin temel listesini genişletmeden yalnızca kendi helper'ının ihtiyacı olan assembly'yi açar.

Migrasyon adımları

1. Domain altında Mappings/ dizinini oluşturun ve vnext.config.json'ın paths + exports bloklarına mappings ekleyin.
2. Bileşen keşfini yapan tooling script'lerini (test.js, validate.js, setup.js, index.js, build.js) yukarıdaki "Domain tooling script'lerine mappings desteği" bölümüne göre güncelleyin.
3. Tekrar eden mapping kodlarını sys-mappings bileşenlerine çıkarın; flow/mapping'lerden scripts.helpers[] ile referans verin. Kodu gömmek yerine paylaşmak için mapping encoding'ini REF yapabilirsiniz.
4. Helper'ınızın baz dışı bir assembly'ye ihtiyacı varsa scripts.allowedAssemblies[] ile tanımlayın. Sandbox ayarları (varsayılan ban listesi, using'ler, referanslar) için Scripting / Sandbox Yapılandırması sayfasına bakın.
5. npm run validate ve npm run build ile yapılandırmayı doğrulayın.

Referans (vnext-example)

Tüm bu yapılandırmanın çalışan hali burgan-tech/vnext-example reposunda hazırdır:

• vnext.config.json — paths.mappings + exports.mappings.
• core/Mappings/account-opening/initial-mapping.json · rsa-crypto.json ve src/ altındaki .csx dosyaları — örnek mapping/helper bileşenleri.
• core/Workflows/account-opening/account-opening-workflow.json — attributes.scripts.helpers ve encoding: "REF" kullanımı.
• Tooling: setup.js · index.js · build.js · validate.js · test.js.

İlgili dokümanlar: Mapping Bileşeni (sys-mappings) · Mapping Rehberi · Scripting / Sandbox Yapılandırması

---

2. State Alias — Rol Bazlı State Görünürlüğü

State Function, client tarafında long-polling ile süreç durumunu döner. Client'ta başlayan bir iş akışı backoffice'e geçtiğinde Fraud, KPS, Limit gibi iç kontrol state'lerine uğrar. Client bu noktada sorgulama yaptığında ham state.key döner — iç süreç adımlarının client'a sızması bir güvenlik açığı oluşturabilir.

Ne değişti

State'lere opsiyonel bir alias[] dizisi tanımlanabilir. Alias, aktör/rol bazlı yapı sayesinde hangi client'ın ne göreceğini belirler; aynı zamanda çoklu-dil (multi-localization) desteği sağlar. İç state kimliği değişmez — alias yalnızca sunum katmanını etkiler; transition'lar, kalıcılık ve iş akışı mantığı aynı state.key üzerinden çalışmaya devam eder.

Her alias öğesi şu alanları taşır:

Alan	Tip	Zorunlu	Açıklama
name	string	Evet	Alias adı. İstek diline uygun bir label bulunamazsa fallback olarak döner.
roles	array	Evet	Bu alias'ın geçerli olduğu roller (minItems: 1). DENY her zaman ALLOW'u geçersiz kılar.
labels	array	Evet	Alias'ın çoklu-dil etiketleri (minItems: 1).

{
  "alias": [
    {
      "name": "Değerlendirme Aşamasında",
      "roles": [
        { "role": "backoffice.operator", "grant": "allow" }
      ],
      "labels": [
        { "label": "Operasyon İncelemesinde", "language": "tr" },
        { "label": "Under Operational Review", "language": "en" }
      ]
    }
  ]
}

Birden fazla iç state aynı dış alias'a eşlenebilir. Çözümleme isteği yapan aktörün rollerini her alias'ın roles listesine göre değerlendirir; eşleşme varsa istek dilindeki label, o dilde label yoksa alias.name döner; hiçbir alias eşleşmezse state.key'e geri düşer.

Migrasyon adımları

1. Client'a sızması istenmeyen iç state'leri belirleyin (ör. Fraud/KPS/Limit).
2. Bu state'lere uygun alias[] tanımları ekleyin; hangi rolün hangi label'ı göreceğini roles + labels ile belirtin.
3. Çok dilli kullanımda her dil için labels girişi ekleyin; rol modeli ve DENY/ALLOW önceliği için Yetkilendirme sayfasına bakın.

İlgili dokümanlar: Workflow → State Alias · Yetkilendirme

---

3. FunctionScope Zorunluluğu ve Tutarlı Yanıt

FunctionScope, fonksiyon çağrısının her iki giriş noktasında (GetFunctionByKeyAsync ve GetFunctionByInstanceAsync) artık tutarlı şekilde uygulanır:

Scope	Kural
D (Domain)	Her zaman çalışır — tüm scope kısıtlarından muaftır.
I (Instance)	Yalnızca bir instance mevcutsa çalışır.
F (Flow)	Bir instance ve fonksiyonun o instance'ın flow'unda tanımlı olması (workflow.Functions) gerekir.

Ne değişti

Eski davranışta scope kısmen uygulanıyordu: guard yalnızca Flow üyeliğini ve yalnızca bir instance varken kontrol ediyordu. Sonuç olarak Instance/Flow kapsamlı fonksiyonlar domain seviyesindeki uçtan kısıtsız çağrılabiliyor, scope hataları ise tesadüfi 404 olarak sızıyor ve rol kapsamı (authorize role evaluation) ele alınmıyordu.

Yeni davranışta authorize rol değerlendirmesi yapılır ve scope/tanım eksikliği veya yetki ihlali durumunda 403 Forbidden (FunctionScopeNotSatisfied) döner.

Migrasyon adımları

1. Fonksiyonlarınızın scope değerlerini gözden geçirin: F kapsamlı bir fonksiyonun ilgili flow'un workflow.Functions listesinde tanımlı olduğundan emin olun.
2. Domain seviyesindeki uçtan Instance/Flow kapsamlı fonksiyon çağıran client'ları güncelleyin.
3. Hata yönetiminde scope ihlallerinin artık 404 değil 403 döndüğünü dikkate alın.

İlgili doküman: Function

---

4. Operations & Observability

publish endpoint'i OpenAPI'de gizlendi

publish endpoint'i varsayılan olarak OpenAPI'de expose ediliyordu. Bu, OpenAPI okunarak API'nin bileşen yükleme bilgisini açığa çıkarıyordu. Endpoint artık API Explorer / OpenAPI çıktısında gizlidir.

Production'da Swagger UI kapalı

Swagger arayüzü production ortamında tüm API host'larında kapatıldı; public production yüzeyi artık API explorer'ı sunmaz.

Migrasyon adımları

1. Production'da Swagger UI'a bağımlı araç/akış varsa bunları kaldırın veya non-production ortamlara taşıyın.
2. publish işlemini OpenAPI üzerinden keşfeden entegrasyonları gözden geçirin; endpoint artık API Explorer'da listelenmez.

---

5. Yapılandırılabilir Asenkron Transition İşletimi

sync=false (asenkron) işletim için durable bir yöntem implemente edildi. Artık asenkron işlemlerde her transition scale edilebilir ve outbox yapısı ile retry edilebilir hale geldi.

Ne değişti

• Continuation'lar inline çalışmak yerine (opsiyonel olarak outbox üzerinden) kuyruğa alınarak dayanıklılık (durability) kazanır.
• Busy durumundaki instance'lara erişim, bir chain ownership token sistemiyle kontrol edilir; eşzamanlı zincirlerin birbirini ezmesi önlenir.
• Heartbeat'i bayatlamış (takılı kalmış) instance'ları otomatik toparlayan bir chain reaper servisi devreye alındı.

Migrasyon adımları

1. sync=true / sync=false davranışı ve karar kriterleri için Async / Sync Yöntemi sayfasına bakın.
2. Bu sürüm, dayanıklılık refactor'ü için EF Core migration'ları içerir — db-migrator image'ı ile şema güncellemesini uygulayın.

İlgili doküman: Async / Sync Yöntemi

---

Özet

• sys-mappings bileşeni + sandbox'lı custom C# helper'lar; scripts.helpers[] (obje referansı) / scripts.allowedAssemblies[] ve REF encoding.
• State alias ile rol bazlı, çoklu-dil state maskeleme (DENY > ALLOW); iç state'ler client'a sızmaz.
• FunctionScope her çağrı yolunda tutarlı; ihlaller artık 403 döner.
• Operations: publish endpoint'i OpenAPI'de gizli, production Swagger kapalı.
• Asenkron transition durable işletim: outbox ile retry, chain ownership token, chain reaper.
• Bileşen şeması 0.0.46'ya yükseldi.

Teknik release notları: Release v0.0.60