Результат команды
=================

Каждая команда в TeleFlow возвращает ``CommandResult``.

Результат не изменяет ``ChatSession`` напрямую.
Он описывает намерение команды,
а окончательное изменение состояния выполняется
в цепочке интерпретаторов.

Именно через ``CommandResult`` команда управляет:

- завершением выполнения;
- переходом между шагами;
- навигацией к другой команде;
- повторным ожиданием ввода.

---

Базовый тип
-----------

Все результаты наследуются от базового класса:

.. code-block:: csharp

   public abstract class CommandResult
   {
       public static CommandResult Exit => new ExitCommandResult();
   }

Каждый конкретный тип результата
имеет собственную семантику обработки.

---

ExitCommandResult
-----------------

Завершает выполнение текущей команды.

По умолчанию интерпретатор:

- удаляет ``ChatSession``;
- завершает цикл выполнения.

Используется в Stateless-командах
и в завершении Stateful-команд.

---

NavigateCommandResult
---------------------

Инициирует переход к другой команде.

.. code-block:: csharp

   public class NavigateCommandResult : CommandResult
   {
       public string CommandToNavigate { get; init; }
       public NavigateCommandParameters Parameters { get; init; }
   }

Содержит:

- имя целевой команды;
- набор параметров.

Навигация выполняется навигационным интерпретатором.

Алгоритм:

1. Завершается текущая команда.
2. Создаётся новая ``ChatSession``.
3. Создаётся целевая команда через ``ICommandFactory``.
4. Выполняется команда с тем же ``Update``.
5. Полученный результат обрабатывается во внутренней цепочке интерпретаторов.

Фактически создаётся вложенный цикл обработки
без выхода из общего Pipeline.

Подробности механизма → :doc:`06-interceptors`.

---

GoToStatefulResult
------------------

Используется только в Stateful-командах.

.. code-block:: csharp

   public class GoToStatefulResult : CommandResult
   {
       public int GoToStepNumber { get; init; }
       public bool InitializeNextStep { get; init; }
   }

Позволяет:

- изменить номер текущего шага;
- указать, был ли инициализирован следующий шаг.

При обработке:

- ``ChatSession`` обновляется;
- состояние сохраняется в ``IChatSessionStore``.

Используется для переходов внутри диалога.

---

HoldOnStatefulResult
--------------------

Оставляет выполнение на текущем шаге.

.. code-block:: csharp

   public class HoldOnStatefulResult : CommandResult
   {
       public HoldOnReason Reason { get; init; }
       public string? HoldOnMessage { get; init; }
   }

Этот результат:

- не изменяет номер шага;
- не завершает команду;
- не удаляет ``ChatSession``.

Наиболее частые сценарии:

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

Если указано ``HoldOnMessage``,
сообщение отправляется пользователю
в рамках обработки результата.

Ошибки пользовательского ввода
обрабатываются через ``HoldOn``.

Системные исключения
не преобразуются в ``CommandResult``
и пробрасываются как ошибки выполнения.

---

Как выбирать CommandResult
---------------------------

Команда должна возвращать результат,
соответствующий текущей логике выполнения:

- ``Exit`` — завершить команду;
- ``Navigate`` — перейти к другой команде;
- ``GoToStatefulResult`` — изменить шаг;
- ``HoldOnStatefulResult`` — остаться на текущем шаге.

Результат не изменяет состояние напрямую —
он лишь описывает намерение.
Фактическое изменение выполняется интерпретаторами.

---

Связанные разделы
-----------------

- Интерпретаторы → :doc:`06-interceptors`
- Сессия чата → :doc:`02-chat-session`
- Шаги → :doc:`04-steps`