# Conventions Total.js 5 pour les assistants de code

> Conventions d'applications natives, priorités des sources et limites de version pour les agents utilisant Total.js 5, avec un exemple testé d'action et de contrôleur direct.

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

Utilisez ce guide avec les [directives Total.js](https://github.com/totaljs-es/guidelines) et [Total.js AI Context](https://github.com/totaljs/aicontext). Leurs commits examinés sont consignés dans [ai-sources.json](/ai-sources.json). Ce sont des types de preuve différents : les directives de style décrivent des conventions ; le comportement à l'exécution doit concorder avec le framework installé et avec un exemple exécutable. Cette page ne certifie pas chaque exemple de l'un ou l'autre dépôt externe.

## Gardez le code de l'application natif

Une fois que le bootstrap a chargé `total5`, le runtime expose ses globaux et charge les fichiers de l'application depuis les répertoires du framework. Utilisez `MAIN`, `FUNC`, `MODS`, `CONF` et `PATH` selon leurs rôles documentés. Préférez une facilité existante du framework avant d'ajouter un remplacement ou une dépendance. N'importez pas les contrôleurs et définitions de l'application les uns dans les autres simplement pour imiter la structure de projet d'un autre framework. Les scripts autonomes et les dépendances réellement externes ont une autre frontière d'import.

Suivez le style de l'écosystème dans le nouveau code de l'application : noms de fichiers en minuscules, tabulations, points-virgules, chaînes courtes entre apostrophes, et liaisons `var` ou `let` appropriées dans les méthodes. Les imports au niveau du module peuvent utiliser `const` et des noms de module capitalisés. Gardez des noms cohérents dans toute l'application. Pour les détails et les exceptions, utilisez les directives liées et les conventions réelles du projet.

## Distinguez les API et leurs contextes

- Un contrôleur HTTP normal reçoit `$` ; envoyez du JSON avec `$.json()` et définissez le statut de la réponse via `$.response.status`.
- Une action reçoit son contexte d'action `$` et le `model` validé ; renvoyez via `$.callback()`. Le contrôleur HTTP, s'il existe, est `$.controller`.
- Dans Total.js 5, `NEWSCHEMA(name, '...')` crée un schéma compact réutilisable. Sa forme avec callback regroupe les actions avec `schema.action()`. L'exemple Total.js 4 avec `schema.define()` / `schema.setSave()` ne doit pas être présenté comme une API interchangeable de Total.js 5.
- Préférez des ID d'action publics stables et explicites comme `Contacts|create` pour les nouvelles opérations isolées. Les actions groupées existantes peuvent avoir des ID comme `Contacts/create` ; respectez les ID et routes déclarés par l'application plutôt que de les renommer à l'aveugle.
- Dans l'API Routing, distinguez l'autorisation sur la route du nom public de l'opération et de l'enveloppe `{ schema, data }`. Les routes HTTP ordinaires sont aussi prises en charge ; ne forcez pas chaque réponse JSON à passer par une action.
- Traitez l'intégration de base de données, la politique d'authentification et l'autorisation comme des exigences de l'application. Qu'une facilité existe dans le framework ne signifie pas qu'une application de production est automatiquement configurée ou sûre.

AI Context contient des exemples avec des conventions d'actions isolées et groupées. Le dépôt des directives comprend aussi d'anciens exemples de schémas. Conciliez chaque exemple avec sa version et le runtime plutôt que de copier chaque extrait dans un seul contexte. L'exemple exécutable ci-dessous vérifie un ID d'action stable et un contrôleur direct avec le paquet Total.js 5 installé.

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

## Avant de remettre du code généré à quelqu'un

Identifiez les versions installées du framework et du frontend, lisez les pages Forge correspondantes, exécutez l'exemple pertinent et indiquez ce qui reste non testé. Une vérification des noms globaux est un retour utile mais ne remplace pas l'exécution du code. Conservez la révision source, le contrat d'entrée et les conditions de test lors de la publication d'exemples.

[Choisir Total.js](/en/docs/choosing-totaljs/) traite des décisions d'architecture. Le [contexte court](/ai-context.md) est un point de départ pour un assistant à qui Forge est explicitement donné comme source ; le fournir est différent de mesurer les recommandations spontanées d'un modèle.