# Инструкция по сборке

Этот документ описывает ключевые принципы и архитектурные паттерны для создания надежных, масштабируемых и поддерживаемых сценариев. Следование этим рекомендациям поможет минимизировать ошибки, упростить отладку и улучшить качество взаимодействия с пользователем.

## 1. Базовые принципы проектирования

### Точка входа (Entry Point)

Каждый активный сценарий должен иметь как минимум один триггер на первом шаге (состоянии), чтобы система могла его запустить в ответ на действие пользователя. Это может быть интент, сущность или другой системный триггер.

> **Исключение:** Вспомогательные (модульные) сценарии, которые вызываются исключительно через реакцию «Переход», могут не иметь триггеров на первом шаге.

### Обработка ответов и ветвление

Для обработки ответов пользователя и создания ветвлений на любом шаге сценария необходимо добавить соответствующие триггеры.

{% hint style="warning" %}
**Всегда предусматривайте Fallback-логику** На каждом шаге, где ожидается ввод от пользователя, **обязательно** добавляйте триггер «Прочее» (Fallback). Он обрабатывает все случаи, которые не соответствуют другим триггерам на этом шаге (нераспознанные фразы, неожиданные интенты). Это гарантирует, что бот не перестанет отвечать и корректно обработает любую ситуацию.
{% endhint %}

### Глобальные переходы (триггер «Выход»)

Триггер «Выход» позволяет перехватить управление и перейти в другой сценарий, даже если текущий сценарий ожидает другого ответа. Это полезно для обработки глобальных команд, таких как «Помощь» или «Спасибо».

{% hint style="warning" %}
**Опасность зацикливания:** Неправильное использование триггера «Выход» может привести к бесконечным циклам между сценариями. Тщательно тестируйте эту логику.
{% endhint %}

## 2. Ключевые архитектурные паттерны

### Модульные сценарии

Для повторяющейся логики (например, авторизация, сбор обратной связи, перевод на оператора) создавайте отдельные, **модульные сценарии**. Вызывайте их из других сценариев с помощью реакции «Переход».

{% hint style="info" %}
**Преимущества модульности:**

* **DRY (Don't Repeat Yourself):** Избегание дублирования кода.
* **Централизованное управление:** Для изменения логики достаточно отредактировать один сценарий, и изменения применятся везде.
* **Читаемость:** Основные сценарии не перегружаются вспомогательной логикой.
  {% endhint %}

### Безопасный перевод на оператора

Перевод на оператора всегда должен завершаться реакцией «Стоп». Она отправляет команду `terminate`, которая формально завершает сессию бота и передает управление.

> Для стандартизации этого процесса рекомендуется выносить логику перевода (включая сообщение о переводе и саму реакцию «Стоп») в отдельный модульный сценарий.

## 3. Жизненный цикл сценария

Управление сценариями включает в себя три основных действия:

* **Клонирование:** Используйте для безопасного тестирования новых гипотез, сниппетов или логики, не затрагивая рабочую версию сценария.
* **Архивация:** Временно отключает сценарий. Пользователь не сможет в него попасть. При архивации сценария убедитесь, что его триггеры на первом шаге также заархивированы или переданы другому сценарию.
* **Удаление:** Полностью удаляет сценарий. Используйте с осторожностью во время плановых чисток проекта.

{% hint style="warning" %}
**Рассинхронизация интента и сценария:** Если заархивировать сценарий, но оставить его интент на первом шаге активным, NLU-модель распознает интент, но не найдет сценария для его обработки. Это приведет к тому, что бот не ответит.
{% endhint %}

## 4. Стандартные сниппеты проекта

Многие проекты используют стандартный набор сниппетов для решения типовых задач.

* `check_if_first_message`: Обычно размещается в начале сценария «Старт». Определяет, является ли сообщение первым в диалоге, и отправляет приветствие. Может содержать логику подавления повторных приветствий.
* `was_terminated`: Проверяет, был ли диалог недавно переведен на оператора. Помогает избежать повторных переводов, если пользователь пишет сразу после завершения разговора со специалистом.
* `Distributor`: Сниппет для предварительной обработки текста. Может использоваться для очистки сообщения от спецсимволов или для маршрутизации запроса в зависимости от его содержимого.
* `snippet_language`: Определяет язык сообщения (например, латиницу). Позволяет отфильтровывать сообщения на языках, для которых не настроена логика.

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

**Дебаг-чат — ваш основной инструмент.** Перед каждым релизом тщательно проверяйте все изменения в дебаг-чате. Это помогает выявить:

* Конфликты триггеров (один интент используется в нескольких активных сценариях).
* Пропущенные реакции (например, забыли добавить «Стоп»).
* Ошибки в логике сниппетов.
* Некорректную работу заархивированных компонентов.