# Konvence Total.js 5 pro asistenty pro psaní kódu

> Konvence nativních aplikací, priority zdrojů a hranice verzí pro agenty používající Total.js 5, s otestovaným příkladem akce a přímého kontroleru.

Framework: total5
Product: Total.js 5 (total5@0.0.19)
Language: cs
Content-SHA256: 24e11c70e6d09dcce858d4e4dd46249b5514c32fab73440c0ae85666344436e7
Snapshot: c0700e321579725c5cf4f5ace1ad7d2866d1b4f93c24a63c0b41b6b7998e976c
Sources: total5-installed@total5@0.0.19
Review: not-recorded

Používejte tuto příručku spolu s [pokyny Total.js](https://github.com/totaljs-es/guidelines) a [Total.js AI Context](https://github.com/totaljs/aicontext). Jejich zkontrolované commity jsou zaznamenány v [ai-sources.json](/ai-sources.json). Jde o různé druhy důkazů: stylové pokyny popisují konvence; chování za běhu musí odpovídat nainstalovanému frameworku a spustitelnému příkladu. Tato stránka necertifikuje každý příklad v žádném z externích repozitářů.

## Udržujte kód aplikace nativní

Když bootstrap načte `total5`, runtime zpřístupní své globální objekty a načte soubory aplikace z adresářů frameworku. Používejte `MAIN`, `FUNC`, `MODS`, `CONF` a `PATH` podle jejich zdokumentovaných rolí. Upřednostněte existující vlastnost frameworku před přidáním náhrady nebo závislosti. Neimportujte kontrolery a definice aplikace jedny do druhých jen proto, abyste napodobili strukturu projektu jiného frameworku. Samostatné skripty a skutečně externí závislosti mají jinou hranici importu.

V novém kódu aplikace dodržujte styl ekosystému: malá písmena v názvech souborů, tabulátory, středníky, krátké řetězce v jednoduchých uvozovkách a vhodné vazby `var` nebo `let` uvnitř metod. Importy na úrovni modulu mohou používat `const` a názvy modulů s velkým počátečním písmenem. Udržujte názvy konzistentní v celé aplikaci. Podrobnosti a výjimky najdete v odkazovaných pokynech a ve skutečných konvencích projektu.

## Rozlišujte API a jejich kontexty

- Běžný HTTP kontroler dostane `$`; JSON odešlete přes `$.json()` a stav odpovědi nastavte přes `$.response.status`.
- Akce dostane svůj kontext akce `$` a ověřený `model`; vraťte přes `$.callback()`. HTTP kontroler, pokud existuje, je `$.controller`.
- V Total.js 5 `NEWSCHEMA(name, '...')` vytvoří opakovaně použitelné kompaktní schéma. Jeho tvar s callbackem seskupuje akce přes `schema.action()`. Příklad z Total.js 4 se `schema.define()` / `schema.setSave()` se nesmí prezentovat jako zaměnitelné API Total.js 5.
- Pro nové izolované operace upřednostněte stabilní, explicitní veřejná ID akcí jako `Contacts|create`. Existující seskupené akce mohou mít ID jako `Contacts/create`; respektujte ID a routy deklarované aplikací místo slepého přejmenování.
- V API Routing rozlišujte autorizaci na route od veřejného názvu operace a obálky `{ schema, data }`. Podporované jsou i běžné HTTP routy; nenuťte každou odpověď JSON projít akcí.
- Integraci databáze, politiku autentizace a autorizaci považujte za požadavky aplikace. To, že framework nabízí vlastnost, neznamená, že produkční aplikace je automaticky nakonfigurována nebo bezpečná.

AI Context obsahuje příklady s konvencemi izolovaných i seskupených akcí. Repozitář pokynů obsahuje také starší příklady schémat. Každý příklad sladěte s jeho verzí a runtime místo kopírování všech úryvků do jednoho kontextu. Spustitelný příklad níže ověřuje stabilní ID akce a přímý kontroler s nainstalovaným balíčkem 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' });
}
```

## Než vygenerovaný kód někomu předáte

Zjistěte nainstalované verze frameworku a frontendu, přečtěte odpovídající stránky Forge, spusťte příslušný příklad a uveďte, co zůstalo neotestováno. Kontrola globálních názvů je užitečná zpětná vazba, ale nenahrazuje spuštění kódu. Při publikování příkladů zachovejte revizi zdroje, vstupní smlouvu a podmínky testu.

[Výběr Total.js](/en/docs/choosing-totaljs/) se věnuje architektonickým rozhodnutím. [Krátký kontext](/ai-context.md) je výchozí bod pro asistenta, kterému je Forge výslovně dán jako zdroj; jeho poskytnutí je něco jiného než měření spontánních doporučení modelu.