> ## Documentation Index
> Fetch the complete documentation index at: https://ziva.zeleza.ru/llms.txt
> Use this file to discover all available pages before exploring further.

# Лучшие практики

> Проверенные подходы к построению TUI на базе Ziva

# Лучшие практики Ziva

Собрали рекомендации, которые помогают командам внедрять Ziva в продакшн-проекты: от структуры кода до отладки на встроенных устройствах.

## Архитектура и организация кода

* Выносите создание задач в фабрики или методы слоёв, чтобы очереди оставались читаемыми.
* Группируйте задачи по этапам и используйте отдельные очереди для каждого этапа (сбор данных → проверка → применение). Это упрощает тестирование и повторное использование.
* Сохраняйте ссылки на задачи, чьи значения понадобятся позже. После `queue.Run()` они продолжают хранить состояние.
* Вызывайте `ziva.AutoConfigure()` и настройку языка (`SetDefaultLanguage`, `SetLanguage`) в `main()`, прежде чем создавать очереди.

## Работа с очередями

* Используйте `WithTasksNumbered(true, "[%02d]")` для длинных сценариев — пользователи быстрее ориентируются в списке.
* Отключайте итоговую сводку (`WithOutSummary()`), если протокол ведётся в отдельном лог-файле, и наоборот добавляйте `WithSummaryFunction`, когда нужно показать ключевые результаты.
* Не забывайте про `WithTimeout*()` в headless-средах (CI, SSH). Указывайте значение по умолчанию, безопасное для сценария.
* Для динамических сценариев создавайте отдельный `Queue`, формируйте список задач и запускайте его после основной очереди.

## Валидация и ввод

* Описывайте требования через `Description()` — Ziva показывает подсказку под полем.
* Комбинируйте встроенные валидаторы фабрики `DefaultValidators` с собственными типами. Для сложных правил создавайте композиции и покрывайте их тестами.
* Если поле может быть пустым, используйте `WithAllowEmpty(true)` и валидатор, корректно обрабатывающий пустую строку (например, `OptionalEmail`).
* Для сетевых проверок (дубликаты в CRM, доступность сервиса) добавляйте `FuncTask` сразу после ввода и отображайте краткий итог.

## Стили и локализация

* Настраивайте цвета ошибок через `ziva.SetErrorColor`, если бренд требует собственную палитру. После экспериментов вызывайте `ResetErrorColors()`.
* На ограниченных терминалах объединяйте `EnableEmbeddedMode()` и `EnableASCIIMode()` — это гарантирует читаемый вывод.

## Производительность и встроенные устройства

* Ограничивайте историю завершённых задач переменной окружения `ZIVA_MAX_COMPLETED_TASKS`.
* Следите за памятью через `ZIVA_MEMORY_PRESSURE_THRESHOLD` и периодически очищайте кэш строк `ziva.ClearInternCache()` в долго живущих CLI.
* Для больших списков используйте `WithViewport(...)` — так интерфейс не «прыгает» и остаётся отзывчивым.
* Разделяйте операции на небольшие `FuncTask`, чтобы прогресс отображался чаще и пользователь понимал, что происходит.

## Тестирование и отладка

* Покрывайте фабрики задач unit-тестами: создавайте задачу, эмулируйте сообщения (`Update`) и проверяйте финальный результат.
* Поднимайте демонстрационные очереди в `examples/` и запускайте их вручную — скриншоты и GIF можно получать через `ziva.WithClearScreen(false)`.
* Логируйте ошибки вне Ziva (через `log`/`zap`), особенно когда очередь останавливается из-за `WithStopOnError(true)`. Это ускоряет диагностику.

## Контрольный список перед релизом

* [ ] Проверены все таймауты и значения по умолчанию.
* [ ] Задачи сгруппированы по этапам, вывод адаптирован под ширину терминала.
* [ ] Валидация покрывает негативные сценарии, сложные правила протестированы.
* [ ] Цвета и локализация соответствуют требованиям бренда/рынка.
* [ ] Встроенные устройства протестированы с `AutoConfigure()` и embedded-режимом.

Следуйте этим рекомендациям вместе с примерами из раздела «Примеры», чтобы строить устойчивые и дружелюбные TUI на базе Ziva.