# Convențiile Total.js 5 pentru asistenții de programare

> Convenții pentru aplicații native, priorități ale surselor și limite de versiune pentru agenții care folosesc Total.js 5, cu un exemplu testat de acțiune și de controler direct.

Framework: total5
Product: Total.js 5 (total5@0.0.19)
Language: ro
Content-SHA256: 3a4bb3051b02280e1137aa02025c33bc86cea717768d634976af4f62a7979d8f
Snapshot: c0700e321579725c5cf4f5ace1ad7d2866d1b4f93c24a63c0b41b6b7998e976c
Sources: total5-installed@total5@0.0.19
Review: not-recorded

Folosește acest ghid împreună cu [ghidurile Total.js](https://github.com/totaljs-es/guidelines) și [Total.js AI Context](https://github.com/totaljs/aicontext). Commit-urile lor revizuite sunt înregistrate în [ai-sources.json](/ai-sources.json). Sunt tipuri diferite de dovezi: ghidul de stil descrie convenții; comportamentul la rulare trebuie să concorde cu framework-ul instalat și cu un exemplu executabil. Această pagină nu certifică fiecare exemplu din niciunul dintre depozitele externe.

## Păstrează codul aplicației nativ

După ce bootstrap-ul încarcă `total5`, runtime-ul își expune globalele și încarcă fișierele aplicației din directoarele framework-ului. Folosește `MAIN`, `FUNC`, `MODS`, `CONF` și `PATH` conform rolurilor lor documentate. Preferă o facilitate existentă a framework-ului înainte de a adăuga un înlocuitor sau o dependență. Nu importa controlerele și definițiile aplicației unele în altele doar pentru a imita structura de proiect a altui framework. Scripturile independente și dependențele cu adevărat externe au o altă limită de import.

Urmează stilul ecosistemului în codul nou al aplicației: nume de fișiere cu litere mici, taburi, puncte și virgulă, șiruri scurte între ghilimele simple și legări `var` sau `let` potrivite în interiorul metodelor. Importurile la nivel de modul pot folosi `const` și nume de module cu majusculă. Păstrează numele consecvente în toată aplicația. Pentru detalii și excepții, folosește ghidurile legate și convențiile reale ale proiectului.

## Distinge API-urile și contextele lor

- Un controler HTTP obișnuit primește `$`; trimite JSON cu `$.json()` și setează starea răspunsului prin `$.response.status`.
- O acțiune primește contextul acțiunii `$` și `model`-ul validat; returnează prin `$.callback()`. Controlerul HTTP, când există, este `$.controller`.
- În Total.js 5, `NEWSCHEMA(name, '...')` creează o schemă compactă reutilizabilă. Forma ei cu callback grupează acțiunile cu `schema.action()`. Exemplul din Total.js 4 cu `schema.define()` / `schema.setSave()` nu trebuie prezentat ca un API interschimbabil din Total.js 5.
- Preferă ID-uri publice de acțiune stabile și explicite, precum `Contacts|create`, pentru operații noi și izolate. Acțiunile grupate existente pot avea ID-uri precum `Contacts/create`; respectă ID-urile și rutele declarate de aplicație în loc să le redenumești orbește.
- În API Routing, distinge autorizarea pe rută de numele public al operației și de învelișul `{ schema, data }`. Rutele HTTP obișnuite sunt de asemenea acceptate; nu forța fiecare răspuns JSON să treacă printr-o acțiune.
- Tratează integrarea bazei de date, politica de autentificare și autorizarea ca cerințe ale aplicației. Faptul că framework-ul are o facilitate nu înseamnă că o aplicație de producție este configurată sau sigură automat.

AI Context conține exemple cu convenții de acțiuni atât izolate, cât și grupate. Depozitul de ghiduri include și exemple mai vechi de scheme. Reconciliază fiecare exemplu cu versiunea și runtime-ul lui în loc să copiezi fiecare fragment într-un singur context. Exemplul executabil de mai jos verifică un ID de acțiune stabil și un controler direct folosind pachetul Total.js 5 instalat.

```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' });
}
```

## Înainte de a preda cod generat cuiva

Identifică versiunile instalate ale framework-ului și frontend-ului, citește paginile Forge potrivite, execută exemplul relevant și spune ce rămâne netestat. O verificare a numelor globale este un feedback util, dar nu înlocuiește executarea codului. Păstrează revizia sursei, contractul de intrare și condițiile de test când publici exemple.

[Alegerea Total.js](/en/docs/choosing-totaljs/) tratează deciziile de arhitectură. [Contextul scurt](/ai-context.md) este un punct de pornire pentru un asistent căruia Forge i s-a dat explicit ca sursă; furnizarea lui este diferită de măsurarea recomandărilor spontane ale unui model.