# Convenciones de Total.js 5 para asistentes de código

> Convenciones de aplicaciones nativas, prioridades de fuentes y límites de versión para agentes que usan Total.js 5, con un ejemplo probado de acción y de controlador directo.

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

Usa esta guía junto con las [directrices de Total.js](https://github.com/totaljs-es/guidelines) y [Total.js AI Context](https://github.com/totaljs/aicontext). Sus commits revisados están registrados en [ai-sources.json](/ai-sources.json). Son tipos de evidencia distintos: la guía de estilo describe convenciones; el comportamiento en tiempo de ejecución debe coincidir con el framework instalado y con un ejemplo ejecutable. Esta página no certifica todos los ejemplos de ninguno de los dos repositorios externos.

## Mantén el código de la aplicación nativo

Una vez que el bootstrap carga `total5`, el runtime expone sus globales y carga los archivos de la aplicación desde los directorios del framework. Usa `MAIN`, `FUNC`, `MODS`, `CONF` y `PATH` según sus funciones documentadas. Prefiere una facilidad existente del framework antes de añadir un reemplazo o una dependencia. No importes controladores y definiciones de la aplicación unos en otros solo para imitar la estructura de proyecto de otro framework. Los scripts independientes y las dependencias genuinamente externas tienen un límite de importación distinto.

Sigue el estilo del ecosistema en el código nuevo de la aplicación: nombres de archivo en minúsculas, tabuladores, puntos y comas, cadenas cortas con comillas simples, y enlaces `var` o `let` apropiados dentro de los métodos. Las importaciones a nivel de módulo pueden usar `const` y nombres de módulo en mayúscula inicial. Mantén los nombres coherentes en toda la aplicación. Para los detalles y las excepciones, usa las directrices enlazadas y las convenciones reales del proyecto.

## Distingue las APIs y sus contextos

- Un controlador HTTP normal recibe `$`; envía JSON con `$.json()` y establece el estado de la respuesta mediante `$.response.status`.
- Una acción recibe su contexto de acción `$` y el `model` validado; devuelve a través de `$.callback()`. El controlador HTTP, cuando existe, es `$.controller`.
- En Total.js 5, `NEWSCHEMA(name, '...')` crea un esquema compacto reutilizable. Su forma con callback agrupa acciones con `schema.action()`. El ejemplo de Total.js 4 con `schema.define()` / `schema.setSave()` no debe presentarse como una API intercambiable de Total.js 5.
- Prefiere IDs de acción públicos, estables y explícitos como `Contacts|create` para operaciones nuevas y aisladas. Las acciones agrupadas existentes pueden tener IDs como `Contacts/create`; respeta los IDs y rutas declarados por la aplicación en lugar de renombrarlos a ciegas.
- En API Routing, distingue la autorización de la ruta del nombre público de la operación y del envoltorio `{ schema, data }`. Las rutas HTTP ordinarias también son compatibles; no fuerces cada respuesta JSON a pasar por una acción.
- Trata la integración con la base de datos, la política de autenticación y la autorización como requisitos de la aplicación. Que el framework tenga una facilidad no significa que una aplicación de producción esté configurada o sea segura automáticamente.

AI Context contiene ejemplos con convenciones de acciones tanto aisladas como agrupadas. El repositorio de directrices también incluye ejemplos de esquemas más antiguos. Concilia cada ejemplo con su versión y con el runtime en lugar de copiar todos los fragmentos en un solo contexto. El ejemplo ejecutable de abajo comprueba un ID de acción estable y un controlador directo usando el paquete instalado de 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' });
}
```

## Antes de entregar código generado a alguien

Identifica las versiones instaladas del framework y del frontend, lee las páginas de Forge correspondientes, ejecuta el ejemplo relevante e indica qué queda sin probar. Una comprobación de nombres globales es un comentario útil, pero no sustituye a ejecutar el código. Conserva la revisión de origen, el contrato de entrada y las condiciones de prueba al publicar ejemplos.

[Elegir Total.js](/en/docs/choosing-totaljs/) trata las decisiones de arquitectura. El [contexto corto](/ai-context.md) es un punto de partida para un asistente al que se le da Forge explícitamente como fuente; proporcionarlo es distinto de medir las recomendaciones espontáneas de un modelo.