# Konwencje Total.js 5 dla asystentów kodowania

> Konwencje aplikacji natywnych, priorytety źródeł i granice wersji dla agentów używających Total.js 5, z przetestowanym przykładem akcji i bezpośredniego kontrolera.

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

Używaj tego przewodnika razem z [wytycznymi Total.js](https://github.com/totaljs-es/guidelines) i [Total.js AI Context](https://github.com/totaljs/aicontext). Ich przejrzane commity są zapisane w [ai-sources.json](/ai-sources.json). To różne rodzaje dowodów: wytyczne stylu opisują konwencje; zachowanie w czasie działania musi zgadzać się z zainstalowanym frameworkiem i wykonywalnym przykładem. Ta strona nie poświadcza każdego przykładu w żadnym z zewnętrznych repozytoriów.

## Utrzymuj kod aplikacji natywny

Gdy bootstrap załaduje `total5`, runtime udostępnia swoje globalne obiekty i ładuje pliki aplikacji z katalogów frameworka. Używaj `MAIN`, `FUNC`, `MODS`, `CONF` i `PATH` zgodnie z ich udokumentowanymi rolami. Preferuj istniejące udogodnienie frameworka, zanim dodasz zamiennik lub zależność. Nie importuj kontrolerów i definicji aplikacji jedne do drugich tylko po to, by naśladować strukturę projektu innego frameworka. Samodzielne skrypty i naprawdę zewnętrzne zależności mają inną granicę importu.

W nowym kodzie aplikacji stosuj styl ekosystemu: nazwy plików małymi literami, tabulatory, średniki, krótkie ciągi w pojedynczych cudzysłowach oraz odpowiednie powiązania `var` lub `let` wewnątrz metod. Importy na poziomie modułu mogą używać `const` i nazw modułów pisanych wielką literą. Utrzymuj spójne nazwy w całej aplikacji. Szczegóły i wyjątki znajdziesz w linkowanych wytycznych i rzeczywistych konwencjach projektu.

## Rozróżniaj API i ich konteksty

- Zwykły kontroler HTTP otrzymuje `$`; wysyłaj JSON przez `$.json()` i ustawiaj status odpowiedzi przez `$.response.status`.
- Akcja otrzymuje swój kontekst akcji `$` i zwalidowany `model`; zwracaj przez `$.callback()`. Kontroler HTTP, jeśli jest, to `$.controller`.
- W Total.js 5 `NEWSCHEMA(name, '...')` tworzy wielokrotnego użytku kompaktowy schemat. Jego forma z callbackiem grupuje akcje przez `schema.action()`. Przykładu z Total.js 4 ze `schema.define()` / `schema.setSave()` nie wolno przedstawiać jako wymiennego API Total.js 5.
- Dla nowych izolowanych operacji preferuj stabilne, jawne publiczne ID akcji, takie jak `Contacts|create`. Istniejące pogrupowane akcje mogą mieć ID takie jak `Contacts/create`; szanuj ID i trasy zadeklarowane przez aplikację zamiast ślepo je zmieniać.
- W API Routing rozróżniaj autoryzację na trasie od publicznej nazwy operacji i koperty `{ schema, data }`. Zwykłe trasy HTTP też są obsługiwane; nie zmuszaj każdej odpowiedzi JSON do przechodzenia przez akcję.
- Integrację z bazą danych, politykę uwierzytelniania i autoryzację traktuj jako wymagania aplikacji. To, że framework ma udogodnienie, nie znaczy, że aplikacja produkcyjna jest automatycznie skonfigurowana lub bezpieczna.

AI Context zawiera przykłady z konwencjami akcji zarówno izolowanych, jak i pogrupowanych. Repozytorium wytycznych zawiera też starsze przykłady schematów. Uzgodnij każdy przykład z jego wersją i runtime zamiast kopiować wszystkie fragmenty do jednego kontekstu. Wykonywalny przykład poniżej sprawdza stabilne ID akcji i bezpośredni kontroler z zainstalowanym pakietem 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' });
}
```

## Zanim przekażesz wygenerowany kod komuś

Ustal zainstalowane wersje frameworka i frontendu, przeczytaj odpowiednie strony Forge, uruchom właściwy przykład i napisz, co pozostaje nieprzetestowane. Sprawdzenie nazw globalnych jest użytecznym sygnałem, ale nie zastępuje uruchomienia kodu. Przy publikowaniu przykładów zachowaj rewizję źródła, kontrakt wejścia i warunki testu.

[Wybór Total.js](/en/docs/choosing-totaljs/) dotyczy decyzji architektonicznych. [Krótki kontekst](/ai-context.md) to punkt wyjścia dla asystenta, któremu Forge wyraźnie podano jako źródło; jego dostarczenie to co innego niż mierzenie spontanicznych rekomendacji modelu.