Kontekst predloška

Kada generirate kod, Restorm predaje cijeli vaš dizajn predlošku u obliku objekta ctx. Vaši modeli, enumi, rute i prije svega njihove namjere (searchable, PII, cache i cijeli operativni profil modela: volumetrija, profil pristupa, promet, svježina, osjetljivost, zadržavanje) su tamo — predložak ih čita kako bi odlučio što generirati. Za to nije potrebna varijabla: informacije koje ste već unijeli u dizajn izravno su dostupne.

Oblik ctx

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

Reference se rade po nazivu (nikada po internom identifikatoru): property.enum je naziv enuma, property.references.model naziv ciljanog modela, model.inherits naziv roditelja. Na modelu properties[] navodi njegova vlastita svojstva (za deklaraciju tipa), a allProperties[] svojstva vlastita + naslijeđena, spljoštena (za potpunu instancu: podaci primjera, SQL stupci, tijelo zahtjeva).

Čitanje zastavice: zlatno pravilo

Booleove zastavice prisutne su u ctx samo kada su aktivirane. Engine iscrtava u StrictUndefined: stoga je potrebno testirati prisutnost ključa, nikada njegovu vrijednost.

{# ✅ ispravno — testiramo prisutnost #}
{% if 'searchable' in p %}INDEX({{ p['name'] }}){% endif %}

{# ❌ pogrešno — baca pogrešku kada zastavica nedostaje #}
{% if p.searchable %}…{% endif %}

Samo su property.required (booleova) i route.auth (enumeracija) uvijek prisutne. Ostale booleove zastavice su „prisutno = istinito“; polja s vrijednošću (volumetrija, operativni profil, cache…) nose svoju vrijednost kada su popunjena, a inače nedostaju — isto pravilo prisutnosti.

Na svojstvu	Na modelu	Na ruti
readOnly · writeOnly · nullable	timestamps · softDelete (booleove)	idempotent · deprecated (booleove)
unique · searchable · immutable · pii	Operativni profil (vrijednosti): volumetry · accessPattern · traffic · freshness · sensitivity · retention	cacheSeconds (broj) · pagination (objekt)

Vrijednosti operativnog profila modela: 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

Ključevima uvijek pristupajte zapisom u uglatim zagradama (p['name'], route['vars']): kontekst se predaje kao obični rječnici, pa bi example.values pozvao metodu values rječnika umjesto vašeg ključa. Vidi pravila prenosivosti.

Primjer: cachiranje podataka s velikom potražnjom za čitanjem

Dva slučaja, ovisno o tome postoji li informacija već u dizajnu ili ne.

a) Dizajn već nosi tu informaciju

Ako ste na ruti popunili trajanje cachea, ono stiže u route['cacheSeconds']; route['idempotent'] govori vam da je sigurno za cachiranje (samo za čitanje):

{% 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) „Velika potražnja za čitanjem“ je nativno polje modela

Nije potrebna varijabla: „velika potražnja za čitanjem“ izravno je profil pristupa modela. U postavkama modela, grupa Operativni profil, birate Dominacija čitanja — predložak to čita u model['accessPattern']. Kombinirajte to s model['freshness'] (tolerancija na svježinu) kako biste odlučili treba li cachirati i na koliko dugo:

{% 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 aktiviran ({{ ttl }}s)
{% endif %}
{% endfor %}

Primijetite test != 'strong': model s dominacijom čitanja, ali s jakom konzistentnošću ne smije se cachirati. To je cijela svrha imati obje namjere jednu uz drugu u dizajnu.

Rezervirajte varijable generiranja za ono što dizajn već ne nosi (postavka specifična za predložak): poslovne namjere — volumetrija, profil pristupa, promet, svježina, osjetljivost, zadržavanje — su nativna polja modela.

Potpuni ugovor

Ovaj je kontekst verzioniran (ctx['contextVersion']) i iscrpno opisan JSON-Schemom isporučenom u repozitoriju aplikacije (docs/contributing/design-codegen-context.schema.json) — kopirajte ga u svoj predložak kako bi njegov CI validirao referentni kontekst. AI agent dobiva isti ugovor u hodu putem MCP alata get_design_template_contract.