Команды
=======

Введение
--------

В TeleFlow прикладная логика сосредоточена в командах.

Команда получает ``SessionContext``,
обрабатывает входящий ``Update`` и возвращает ``CommandResult``.

Команда существует только в рамках обработки одного ``Update``.

.. important::

   Экземпляр команды не сохраняется между обновлениями.
   При каждом новом ``Update`` команда создаётся заново
   на основании текущей ``ChatSession``.

Состояние диалога хранится в ``ChatSession``,
а не в экземпляре команды.

---

Модель выполнения
-----------------
Во время обработки одного ``Update`` происходит следующий цикл:

1. Восстанавливается ``ChatSession`` пользователя.
2. Определяется активная команда на основании текущей сессии.
3. Создаётся экземпляр команды.
4. ``UpdateContext`` передаётся в цепочку Interceptor (если они сконфигурированы).
5. Выполняется логика команды.
6. Возвращается ``CommandResult``.

Полученный результат передаётся в цепочку интерпретаторов,
которые определяют дальнейшее поведение системы
(см. :doc:`03-command-result`).

---

Stateless и Stateful команды
----------------------------

Команда может быть Stateless или Stateful.

Stateless
~~~~~~~~~

- не сохраняет состояние между обновлениями;
- ``ChatSession`` не записывается в хранилище;
- подходит для одноразовых действий
  (например, ``/help`` или ``/start``).

Stateful
~~~~~~~~

- сохраняет ``ChatSession``;
- состояние сохраняется в ``IChatSessionStore``;
- применяется для диалогов и многошаговых сценариев.

.. note::

   ``ChatSession`` — это состояние диалога,
   а не бизнес-данные приложения.
   Бизнес-данные следует хранить отдельно.

Подробности о хранении сессий → :doc:`02-chat-session`.

---

Регистрация команд
------------------

Команды настраиваются через ``ConfigureCommandRouters``.

Пример:

.. code-block:: csharp

    services.AddTeleFlowPolling(
        botToken: token,
        teleFlow: options =>
        {
            options.ConfigureCommandRouters(commands =>
            {
                commands.AddSendText("/start", "Hello, World!");
            });
        });

Этот пример регистрирует простейшую Stateless-команду.

Такая команда:

- не использует шаги;
- не сохраняет состояние;
- завершается сразу после выполнения.

---

Многошаговые команды
--------------------

Для диалоговых сценариев используется ``AddMultiStep``.

Пример:

.. code-block:: csharp

   commands.AddMultiStep("/survey", flow =>
   {
       flow.AddTextInput("Введите ваше имя:", async (context, value) =>
       {
           context.ChatSession["name"] = value;
       });

   }, onCompleted: async sp =>
   {
       var sender = sp.GetRequiredService<IMessageSender>();
       await sender.SendMessage("Спасибо за участие.");

       return CommandResult.Exit;
   });

В этом примере:

- ``AddTextInput`` добавляет шаг;
- данные сохраняются в ``ChatSession``;
- после завершения вызывается ``onCompleted``.

Шаги подробно рассматриваются в разделе → :doc:`04-steps`.

---

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

- Состояние диалога → :doc:`02-chat-session`
- Результаты выполнения → :doc:`03-command-result`
- Шаги → :doc:`04-steps`
- Интерсепторы → :doc:`06-interceptors`