Şablonun bağlamı

Kod ürettiğinizde Restorm, tasarımınızın tamamını şablona bir ctx nesnesi biçiminde iletir. Modelleriniz, enum’larınız, rotalarınız ve özellikle onların niyetleri (searchable, PII, cache ve modelin tüm operasyonel profili: hacim, erişim profili, trafik, tazelik, hassasiyet, saklama) oradadır — bir şablon, ne üreteceğine karar vermek için bunları okur. Bunun için bir değişkene gerek yok: tasarımda zaten girdiğiniz bilgiler doğrudan kullanılabilir.

ctx’nin biçimi

ctx
├─ design        # name, version, description, basePath, defaultAuth, vars
├─ enums[]       # name, description, values[]
├─ models[]      # name, description, inherits, identifier, timestamps, softDelete,
│                # volumetry, accessPattern, traffic, freshness, sensitivity,
│                # retention, properties[], allProperties[], examples[], vars
└─ groups[]      # name, basePath, versionPrefix, headers[], routes[]
     └─ routes[] # method, path, fullPath, params[], body, responses[],
                 # auth, pagination, cacheSeconds, idempotent, deprecated, vars

Referanslar ada göre yapılır (asla dahili bir kimliğe göre değil): property.enum enum’un adı, property.references.model hedeflenen modelin adı, model.inherits üstün (parent) adıdır. Bir modelde properties[] onun kendi özelliklerini listeler (tip bildirimi için) ve allProperties[] kendi + miras alınan, düzleştirilmiş özellikleri listeler (tam bir örnek için: örnek verileri, SQL sütunları, istek gövdesi).

Bir bayrağı okuma: altın kural

Boole (boolean) bayraklar ctx içinde yalnızca etkin olduklarında bulunur. Motor StrictUndefined ile render eder: dolayısıyla anahtarın varlığını test etmek gerekir, asla değerini değil.

{# ✅ doğru — varlığı test ediyoruz #}
{% if 'searchable' in p %}INDEX({{ p['name'] }}){% endif %}

{# ❌ yanlış — bayrak yokken bir hata fırlatır #}
{% if p.searchable %}…{% endif %}

Yalnızca property.required (boole) ve route.auth (numaralandırma) her zaman bulunur. Diğer boole bayraklar «bulunuyor = doğru» şeklindedir; değer taşıyan alanlar (hacim, operasyonel profil, cache…) doldurulduklarında değerlerini taşır, aksi halde yoktur — aynı varlık kuralı.

Bir özellikte	Bir modelde	Bir rotada
readOnly · writeOnly · nullable	timestamps · softDelete (boole)	idempotent · deprecated (boole)
unique · searchable · immutable · pii	Operasyonel profil (değerler): volumetry · accessPattern · traffic · freshness · sensitivity · retention	cacheSeconds (sayı) · pagination (nesne)

Bir modelin operasyonel profilinin değerleri: accessPattern (readHeavy / writeHeavy / balanced / appendOnly), traffic (low / medium / high), freshness (strong / shortCache / longCache), sensitivity (public / internal / confidential / pii), retention (permanent / archivable / ephemeral), volumetry (hundreds / tenThousands / millions).

Note

Anahtarlara her zaman köşeli parantez yazımıyla erişin (p['name'], route['vars']): bağlam basit sözlükler (dictionary) olarak iletilir, dolayısıyla example.values, sizin anahtarınız yerine dict’in values yöntemini çağırır. Bkz. taşınabilirlik kuralları.

Örnek: yüksek okuma talebi olan verileri önbelleğe alma

İki durum, bilginin tasarımda zaten var olup olmamasına göre.

a) Tasarım bilgiyi zaten taşıyor

Bir rota üzerinde bir cache süresi doldurduysanız, o değer route['cacheSeconds'] içinde gelir; route['idempotent'] size onun önbelleğe almanın güvenli (salt okunur) olduğunu söyler:

{% for group in ctx['groups'] %}
{% for route in group['routes'] %}
{% if 'cacheSeconds' in route and 'idempotent' in route %}
// {{ route['method'] }} {{ route['fullPath'] }}
app.use("{{ route['fullPath'] }}", cache({{ route['cacheSeconds'] }}));
{% endif %}
{% endfor %}
{% endfor %}

b) « Yüksek okuma talebi », modelin yerel bir alanıdır

Değişkene gerek yok: « yüksek okuma talebi », doğrudan modelin erişim profilidir. Modelin ayarlarında, Operasyonel profil grubunda, Baskın okuma’yı seçersiniz — şablon bunu model['accessPattern'] içinde okur. Önbelleğe alıp almayacağınıza ve ne kadar süreyle önbelleğe alacağınıza karar vermek için onu model['freshness'] (tazelik toleransı) ile birleştirin:

{% for model in ctx['models'] %}
{% if model['accessPattern'] == 'readHeavy' and model['freshness'] != 'strong' %}
{% set ttl = 3600 if model['freshness'] == 'longCache' else 60 %}
registerCache("{{ model['name'] }}", {{ ttl }});   // cache activé ({{ ttl }}s)
{% endif %}
{% endfor %}

!= 'strong' testine dikkat edin: baskın okumalı ama güçlü tutarlılıktaki bir model önbelleğe alınmamalıdır. İki niyeti tasarımda yan yana tutmanın tüm anlamı da budur.

Üretim değişkenlerini, tasarımın zaten taşımadığı şeyler için (şablona özgü bir ayar) saklayın: iş niyetleri — hacim, erişim profili, trafik, tazelik, hassasiyet, saklama — modelin yerel alanlarıdır.

Tam sözleşme

Bu bağlam sürümlenmiştir (ctx['contextVersion']) ve uygulamanın deposunda teslim edilen bir JSON-Schema tarafından eksiksiz olarak tanımlanır (docs/contributing/design-codegen-context.schema.json) — CI’sinin referans bağlamı doğrulaması için onu şablonunuza kopyalayın. Bir yapay zekâ ajanı, aynı sözleşmeyi anında get_design_template_contract MCP aracıyla elde eder.