# Конвенции на Total.js 5 за асистенти за програмиране

> Конвенции за нативни приложения, приоритети на източниците и граници на версиите за агенти, използващи Total.js 5, с тестван пример за действие и директен контролер.

Framework: total5
Product: Total.js 5 (total5@0.0.19)
Language: bg
Content-SHA256: 2a688741d74b2f1546b791347db959c7d6be936ce5db7e1c95b5117572a862da
Snapshot: c0700e321579725c5cf4f5ace1ad7d2866d1b4f93c24a63c0b41b6b7998e976c
Sources: total5-installed@total5@0.0.19
Review: not-recorded

Използвайте това ръководство заедно с [насоките на Total.js](https://github.com/totaljs-es/guidelines) и [Total.js AI Context](https://github.com/totaljs/aicontext). Прегледаните им commits са записани в [ai-sources.json](/ai-sources.json). Това са различни видове доказателства: насоките за стил описват конвенции; поведението по време на изпълнение трябва да съвпада с инсталирания framework и с изпълним пример. Тази страница не удостоверява всеки пример в нито едно от външните хранилища.

## Дръжте кода на приложението нативен

След като bootstrap зареди `total5`, runtime изважда на показ своите глобални обекти и зарежда файловете на приложението от директориите на frameworkа. Използвайте `MAIN`, `FUNC`, `MODS`, `CONF` и `PATH` според документираните им роли. Предпочитайте съществуваща възможност на frameworkа, преди да добавите заместител или зависимост. Не импортирайте контролерите и дефинициите на приложението един в друг само за да имитирате структурата на проект на друг framework. Самостоятелните скриптове и наистина външните зависимости имат различна граница на импорт.

Следвайте стила на екосистемата в новия код на приложението: малки букви в имената на файлове, табулации, точки и запетаи, къси низове в единични кавички и подходящи обвързвания `var` или `let` вътре в методите. Импортите на ниво модул могат да използват `const` и имена на модули с главна буква. Поддържайте имената последователни в цялото приложение. За подробности и изключения използвайте свързаните насоки и реалните конвенции на проекта.

## Разграничавайте API-тата и техните контексти

- Обикновен HTTP контролер получава `$`; изпращайте JSON с `$.json()` и задавайте статус на отговора чрез `$.response.status`.
- Действие получава своя контекст на действие `$` и валидирания `model`; връщайте чрез `$.callback()`. HTTP контролерът, когато има такъв, е `$.controller`.
- В Total.js 5 `NEWSCHEMA(name, '...')` създава многократно използваема компактна схема. Формата ѝ с callback групира действия със `schema.action()`. Примерът от Total.js 4 със `schema.define()` / `schema.setSave()` не бива да се представя като взаимозаменяемо API на Total.js 5.
- Предпочитайте стабилни, изрични публични ID на действия като `Contacts|create` за нови изолирани операции. Съществуващите групирани действия може да имат ID като `Contacts/create`; уважавайте декларираните от приложението ID и маршрути, вместо да ги преименувате на сляпо.
- В API Routing разграничавайте авторизацията на маршрута от публичното име на операцията и плика `{ schema, data }`. Обикновените HTTP маршрути също се поддържат; не принуждавайте всеки JSON отговор да минава през действие.
- Третирайте интеграцията с база данни, политиката за автентикация и авторизацията като изисквания на приложението. Фактът, че frameworkът има възможност, не означава, че продукционното приложение е автоматично конфигурирано или сигурно.

AI Context съдържа примери както с изолирани, така и с групирани конвенции за действия. Хранилището с насоки включва и по-стари примери за схеми. Съгласувайте всеки пример с неговата версия и runtime, вместо да копирате всеки фрагмент в един контекст. Изпълнимият пример по-долу проверява стабилно ID на действие и директен контролер с инсталирания пакет 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' });
}
```

## Преди да предадете генериран код на някого

Установете инсталираните версии на framework и frontend, прочетете съответните страници на Forge, изпълнете релевантния пример и посочете какво остава нетествано. Проверката на глобални имена е полезна обратна връзка, но не замества изпълнението на код. Запазете изходната ревизия, входния договор и условията на теста при публикуване на примери.

[Избор на Total.js](/en/docs/choosing-totaljs/) разглежда архитектурни решения. [Краткият контекст](/ai-context.md) е отправна точка за асистент, на когото Forge е изрично даден като източник; предоставянето му е различно от измерването на спонтанните препоръки на модел.