Skip to content

Director — Координатор и Мозг навигации

Director — это центральный архитектурный компонент codex-bot. Если Оркестраторы — это рабочие инструменты, то Директор — это прораб, который знает, куда отправить пользователя, какие данные ему передать и как подготовить для этого почву.

Он создается динамически для каждого входящего апдейта и сопровождает запрос на всем пути: от мидлвари до отправки сообщения.

🧠 Smart Resolver (Умная навигация)

Это механизм, превращающий вашего бота в Backend-driven систему. Вместо того чтобы прописывать логику переходов (if response == "banned": ...) в каждом хендлере, вы делегируете это Директору.

Концепция Конверта (Envelope)

Директор ожидает данные в формате «Конверта», где метаданные навигации отделены от бизнес-данных:

{
    "meta": {
        "__next_scene__": "banned"  # Инструкция для Директора
    },
    "payload": {
        "reason": "spam",           # Полезные данные для оркестратора
        "until": "2025-01-01"
    }
}

Применение в коде

Метод director.resolve(data) анализирует этот конверт. Если в meta найден ключ редиректа, Директор: 1. Останавливает текущий поток логики. 2. Выполняет переход (set_scene) на новую фичу. 3. Передает ей очищенный payload.

🛡 Перехватчики (Transition Guards)

Директор поддерживает Guards — это цепочка проверок, которые выполняются перед входом в любую фичу. Это стандартный механизм для реализации Access Control (RBAC), проверки подписок или любых других ограничений.

Принцип работы:

  1. Директор берет список гардов из container.transition_guards.
  2. Каждый гард вызывает метод check_access.
  3. Если гард возвращает UnifiedViewDTO — переход блокируется, и пользователю отправляется этот DTO (например, экран «Доступ запрещен»).
  4. Если гард возвращает True — проверка считается пройденной.

🚀 Глубокая логика set_scene

Метод set_scene — это процесс синхронизации контекста и защиты приложения:

  1. Защита от циклов: Директор ограничивает количество последовательных перенаправлений (MAX_REDIRECTS = 5). Это предотвращает бесконечные циклы редиректов.
  2. Поиск Оркестратора: Извлечение инстанса целевой фичи из DI-контейнера.
  3. Выполнение Guards: Проверка прав доступа перед запуском логики фичи.
  4. Атомарное управление FSM: Синхронизация состояния (state) пользователя в хранилище с требуемым состоянием оркестратора.
  5. Автоматическое Оборачивание: Если оркестратор вернул сырые данные или ViewResultDTO, Директор автоматически преобразует их в UnifiedViewDTO.
  6. Обогащение контекста (Session Enrichment): Директор автоматически проставляет в исходящий DTO технические параметры:
    • session_key — идентификатор сессии пользователя.
    • context_id — идентификатор контекста (чата).
    • trigger_message_id — ID сообщения, вызвавшего действие (используется для редактирования/удаления интерфейса).

🛠 Абстракция сессий

Директор полностью абстрагирован от конкретного мессенджера: - session_key: Уникальный ключ субъекта (например, ID пользователя). - context_id: Уникальный ключ пространства (например, ID чата).

Такая структура позволяет использовать одну и ту же бизнес-логику для Telegram, Discord или Web-виджетов.

🧭 Пример использования

# Инициализация (обычно происходит в middleware)
director = Director(
    container=container,
    state=fsm_context,
    session_key=event.from_user.id,
    context_id=event.chat.id
)

# Переход на другую фичу вручную
view = await director.set_scene(
    feature="profile",
    payload={"tab": "settings"}
)