# Konvencie Total.js 5 pre asistentov na písanie kódu

> Konvencie natívnych aplikácií, priority zdrojov a hranice verzií pre agentov používajúcich Total.js 5, s otestovaným príkladom akcie a priameho kontroléra.

Framework: total5
Product: Total.js 5 (total5@0.0.19)
Language: sk
Content-SHA256: 133d6bfaa967fa3d34b9fc5f3b04aa2ec72859119c750792104a290a1e4f4838
Snapshot: c0700e321579725c5cf4f5ace1ad7d2866d1b4f93c24a63c0b41b6b7998e976c
Sources: total5-installed@total5@0.0.19
Review: not-recorded

Používajte túto príručku spolu s [pokynmi Total.js](https://github.com/totaljs-es/guidelines) a [Total.js AI Context](https://github.com/totaljs/aicontext). Ich skontrolované commity sú zaznamenané v [ai-sources.json](/ai-sources.json). Ide o rôzne druhy dôkazov: štýlový návod opisuje konvencie; správanie za behu musí zodpovedať nainštalovanému frameworku a spustiteľnému príkladu. Táto stránka necertifikuje každý príklad v žiadnom z externých repozitárov.

## Udržujte kód aplikácie natívny

Keď bootstrap načíta `total5`, runtime sprístupní svoje globálne objekty a načíta súbory aplikácie z adresárov frameworku. Používajte `MAIN`, `FUNC`, `MODS`, `CONF` a `PATH` podľa ich zdokumentovaných úloh. Uprednostnite existujúcu vlastnosť frameworku pred pridaním náhrady alebo závislosti. Neimportujte kontroléry a definície aplikácie jedny do druhých iba preto, aby ste napodobnili štruktúru projektu iného frameworku. Samostatné skripty a skutočne externé závislosti majú inú hranicu importu.

V novom kóde aplikácie dodržiavajte štýl ekosystému: malé písmená v názvoch súborov, tabulátory, bodkočiarky, krátke reťazce v jednoduchých úvodzovkách a vhodné väzby `var` alebo `let` vo vnútri metód. Importy na úrovni modulu môžu používať `const` a názvy modulov s veľkým začiatočným písmenom. Udržiavajte názvy konzistentné v celej aplikácii. Detaily a výnimky nájdete v odkazovaných pokynoch a v skutočných konvenciách projektu.

## Rozlišujte API a ich kontexty

- Bežný HTTP kontrolér dostane `$`; JSON odošlite cez `$.json()` a stav odpovede nastavte cez `$.response.status`.
- Akcia dostane svoj kontext akcie `$` a overený `model`; vráťte cez `$.callback()`. HTTP kontrolér, ak existuje, je `$.controller`.
- V Total.js 5 `NEWSCHEMA(name, '...')` vytvorí opakovane použiteľnú kompaktnú schému. Jej tvar s callbackom zoskupuje akcie cez `schema.action()`. Príklad z Total.js 4 so `schema.define()` / `schema.setSave()` sa nesmie prezentovať ako zameniteľné API Total.js 5.
- Pre nové izolované operácie uprednostnite stabilné, explicitné verejné ID akcií ako `Contacts|create`. Existujúce zoskupené akcie môžu mať ID ako `Contacts/create`; rešpektujte ID a routy deklarované aplikáciou namiesto slepého premenovania.
- V API Routing rozlišujte autorizáciu na route od verejného názvu operácie a obálky `{ schema, data }`. Podporované sú aj bežné HTTP routy; nenúťte každú odpoveď JSON prejsť cez akciu.
- Integráciu databázy, politiku autentifikácie a autorizáciu považujte za požiadavky aplikácie. To, že framework ponúka vlastnosť, neznamená, že produkčná aplikácia je automaticky nakonfigurovaná alebo bezpečná.

AI Context obsahuje príklady s konvenciami izolovaných aj zoskupených akcií. Repozitár pokynov obsahuje aj staršie príklady schém. Každý príklad zosúlaďte s jeho verziou a runtime namiesto kopírovania všetkých úryvkov do jedného kontextu. Spustiteľný príklad nižšie overuje stabilné ID akcie a priamy kontrolér s nainštalovaným balíkom Total.js 5.

```js definitions/contacts.js
NEWACTION('Contacts|create', {
	input: '*name:String',
	action: function($, model) {
		$.callback({ id: UID(), name: model.name });
	}
});
```

```js controllers/contacts.js
exports.install = function() {
	ROUTE('GET /hello/', hello);
	ROUTE('POST /contacts/ --> *Contacts|create');
};

function hello($) {
	$.json({ hello: 'world' });
}
```

## Pred odovzdaním vygenerovaného kódu niekomu

Zistite nainštalované verzie frameworku a frontendu, prečítajte zodpovedajúce stránky Forge, spustite príslušný príklad a uveďte, čo zostalo neotestované. Kontrola globálnych názvov je užitočná spätná väzba, ale nenahrádza spustenie kódu. Pri publikovaní príkladov zachovajte revíziu zdroja, vstupnú zmluvu a podmienky testu.

[Výber Total.js](/en/docs/choosing-totaljs/) sa venuje architektonickým rozhodnutiam. [Krátky kontext](/ai-context.md) je východiskový bod pre asistenta, ktorému je Forge výslovne daný ako zdroj; jeho poskytnutie je niečo iné než meranie spontánnych odporúčaní modelu.