Το πλαίσιο του προτύπου

Όταν παράγετε κώδικα, το Restorm περνά ολόκληρο το σχέδιό σας στο πρότυπο με τη μορφή ενός αντικειμένου ctx. Τα μοντέλα σας, τα enums σας, οι διαδρομές σας και κυρίως οι προθέσεις τους (searchable, PII, cache, και όλο το λειτουργικό προφίλ του μοντέλου: όγκος, προφίλ πρόσβασης, κίνηση, φρεσκάδα, ευαισθησία, διατήρηση) είναι εκεί — ένα πρότυπο τα διαβάζει για να αποφασίσει τι να παράξει. Δεν χρειάζεται μια μεταβλητή γι’ αυτό: οι πληροφορίες που έχετε ήδη εισαγάγει στο σχέδιο είναι άμεσα διαθέσιμες.

Η μορφή του 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

Οι αναφορές γίνονται με το όνομα (ποτέ με εσωτερικό αναγνωριστικό): property.enum είναι το όνομα του enum, property.references.model το όνομα του στοχευόμενου μοντέλου, model.inherits το όνομα του γονέα. Σε ένα μοντέλο, το properties[] παραθέτει τις δικές του ιδιότητες (για τη δήλωση του τύπου) και το allProperties[] τις δικές του + κληρονομημένες, ισοπεδωμένες ιδιότητες (για ένα πλήρες στιγμιότυπο: δεδομένα παραδείγματος, στήλες SQL, σώμα αιτήματος).

Ανάγνωση μιας σημαίας: ο χρυσός κανόνας

Οι δυαδικές (boolean) σημαίες είναι παρούσες στο ctx μόνο όταν είναι ενεργοποιημένες. Η μηχανή αποδίδει σε StrictUndefined: πρέπει επομένως να ελέγξετε την παρουσία του κλειδιού, ποτέ την τιμή του.

{# ✅ σωστό — ελέγχουμε την παρουσία #}
{% if 'searchable' in p %}INDEX({{ p['name'] }}){% endif %}

{# ❌ λάθος — εγείρει σφάλμα όταν η σημαία απουσιάζει #}
{% if p.searchable %}…{% endif %}

Μόνο τα property.required (boolean) και route.auth (απαρίθμηση) είναι πάντοτε παρόντα. Οι άλλες δυαδικές σημαίες είναι «παρόν = αληθές»· τα πεδία με τιμή (όγκος, λειτουργικό προφίλ, cache…) φέρουν την τιμή τους όταν είναι συμπληρωμένα, και απουσιάζουν αλλιώς — ίδιος κανόνας παρουσίας.

Σε μια ιδιότητα	Σε ένα μοντέλο	Σε μια διαδρομή
readOnly · writeOnly · nullable	timestamps · softDelete (boolean)	idempotent · deprecated (boolean)
unique · searchable · immutable · pii	Λειτουργικό προφίλ (τιμές): volumetry · accessPattern · traffic · freshness · sensitivity · retention	cacheSeconds (αριθμός) · pagination (αντικείμενο)

Οι τιμές του λειτουργικού προφίλ ενός μοντέλου: 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

Προσπελάστε πάντα τα κλειδιά με γραφή αγκύλης (p['name'], route['vars']): το πλαίσιο περνιέται ως απλά λεξικά (dictionaries), οπότε το example.values θα καλούσε τη μέθοδο values του λεξικού αντί για το κλειδί σας. Δείτε τους κανόνες φορητότητας.

Παράδειγμα: αποθήκευση σε cache των δεδομένων με υψηλή ζήτηση ανάγνωσης

Δύο περιπτώσεις, ανάλογα με το αν η πληροφορία υπάρχει ήδη στο σχέδιο ή όχι.

α) Το σχέδιο φέρει ήδη την πληροφορία

Αν έχετε συμπληρώσει μια διάρκεια cache σε μια διαδρομή, φτάνει στο route['cacheSeconds']· το route['idempotent'] σας λέει ότι είναι ασφαλές να αποθηκευτεί σε cache (μόνο ανάγνωση):

{% 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 %}

β) Η «υψηλή ζήτηση ανάγνωσης» είναι εγγενές πεδίο του μοντέλου

Δεν χρειάζεται μεταβλητή: η «υψηλή ζήτηση ανάγνωσης» είναι άμεσα το προφίλ πρόσβασης του μοντέλου. Στις ρυθμίσεις του μοντέλου, ομάδα Λειτουργικό προφίλ, επιλέγετε Κυρίαρχη ανάγνωση — το πρότυπο το διαβάζει στο model['accessPattern']. Συνδυάστε το με το model['freshness'] (ανοχή στη φρεσκάδα) για να αποφασίσετε αν πρέπει να αποθηκευτεί σε cache, και για πόσο χρόνο:

{% 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 ενεργό ({{ ttl }}s)
{% endif %}
{% endfor %}

Παρατηρήστε τον έλεγχο != 'strong': ένα μοντέλο με κυρίαρχη ανάγνωση αλλά με ισχυρή συνέπεια δεν πρέπει να αποθηκεύεται σε cache. Αυτό ακριβώς είναι το νόημα του να έχετε τις δύο προθέσεις δίπλα δίπλα στο σχέδιο.

Κρατήστε τις μεταβλητές παραγωγής για αυτό που το σχέδιο δεν φέρει ήδη (μια ρύθμιση που αφορά το ίδιο το πρότυπο): οι επιχειρησιακές προθέσεις — όγκος, προφίλ πρόσβασης, κίνηση, φρεσκάδα, ευαισθησία, διατήρηση — είναι εγγενή πεδία του μοντέλου.

Το πλήρες συμβόλαιο

Αυτό το πλαίσιο είναι εκδοσιοποιημένο (ctx['contextVersion']) και περιγράφεται εξαντλητικά από ένα JSON-Schema που παραδίδεται στο αποθετήριο της εφαρμογής (docs/contributing/design-codegen-context.schema.json) — αντιγράψτε το στο πρότυπό σας ώστε το CI του να επικυρώνει το πλαίσιο αναφοράς. Ένας πράκτορας τεχνητής νοημοσύνης λαμβάνει το ίδιο συμβόλαιο εν κινήσει μέσω του εργαλείου MCP get_design_template_contract.