🎯 Гайд по системным действиям

Полное описание всех доступных действий с их параметрами и результатами.

📋 Содержание

action_hub (1 действий)
- get_available_actions
event_processor (1 действий)
- process_event
scenario_processor (3 действий)
storage_hub (1 действий)
- sync_tenant_storage
telegram_bot_manager (6 действий)
tenant_hub (6 действий)

action_hub

Описание: Центральный хаб действий для маршрутизации к сервисам

get_available_actions

Описание: Получение всех доступных действий с их метаданными

Входные параметры:

⚙️ Дополнительные параметры

_namespace (string) (опционально) — Кастомный ключ для создания вложенности в _cache. Если указан, данные сохраняются в _cache[_namespace] вместо плоского кэша. Используется для контроля перезаписи при повторных вызовах одного действия. Доступ через {_cache._namespace.field}. По умолчанию данные мержатся напрямую в _cache (плоское кэширование).

Выходные параметры:

result (string) — Результат: success, error
error (object) (опционально) — Структура ошибки
- code (string) — Код ошибки
- message (string) — Сообщение об ошибке
- details (array) (опционально) — Детали ошибки (например, ошибки валидации полей)
response_data (object) — Словарь всех доступных действий с метаданными

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

yaml

# В сценарии
- action: "get_available_actions"
  params:
    # Параметры не требуются

event_processor

Описание: Сервис для обработки событий от пулинга

process_event

Описание: Обработка события от пулинга

Входные параметры:

data (object) — Сырое событие от пулинга

Выходные параметры:

result (string) — Результат: success, error
error (object) (опционально) — Структура ошибки
- code (string) — Код ошибки
- message (string) — Сообщение об ошибке
- details (array) (опционально) — Детали ошибки

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

yaml

# В сценарии
- action: "process_event"
  params:
    data: {}

scenario_processor

Описание: Сервис для обработки событий по сценариям

process_scenario_event

Описание: Обработка события по сценариям

Входные параметры:

event_type (string, обязательное, мин. длина: 1) — Тип события (message, callback_query, etc.)
bot_id (integer, обязательное, мин: 1) — ID бота от которого пришло событие

Выходные параметры:

result (string) — Результат обработки (success/error)
error (object) (опционально) — Структура ошибки
- code (string) — Код ошибки
- message (string) — Сообщение об ошибке
- details (array) (опционально) — Детали ошибки

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

yaml

# В сценарии
- action: "process_scenario_event"
  params:
    event_type: "example"
    bot_id: 123

sync_scenarios

Описание: Синхронизация сценариев тенанта: удаление старых → сохранение новых → перезагрузка кэша

Входные параметры:

tenant_id (integer, обязательное, мин: 1) — ID tenant'а для синхронизации сценариев
scenarios (array (of object)) — Массив сценариев для синхронизации

Выходные параметры:

result (string) — Результат синхронизации (success/partial_success/error)
error (object) (опционально) — Структура ошибки
- code (string) — Код ошибки
- message (string) — Сообщение об ошибке
- details (array) (опционально) — Детали ошибки

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

yaml

# В сценарии
- action: "sync_scenarios"
  params:
    tenant_id: 123
    scenarios: []

sync_tenant_scenarios

Описание: Синхронизация сценариев для тенанта: парсинг scenarios/*.yaml + синхронизация с БД

Входные параметры:

tenant_id (integer, обязательное, мин: 1) — ID тенанта

Выходные параметры:

result (string) — Результат: success, error
error (object) (опционально) — Структура ошибки
- code (string) — Код ошибки
- message (string) — Сообщение об ошибке
- details (array) (опционально) — Детали ошибки

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

yaml

# В сценарии
- action: "sync_tenant_scenarios"
  params:
    tenant_id: 123

storage_hub

Описание: Сервис для управления tenant storage

sync_tenant_storage

Описание: Синхронизация storage для тенанта: парсинг storage/*.yaml + синхронизация с БД

Входные параметры:

tenant_id (integer, обязательное, мин: 1) — ID тенанта

Выходные параметры:

result (string) — Результат: success, error
error (object) (опционально) — Структура ошибки
- code (string) — Код ошибки
- message (string) — Сообщение об ошибке
- details (array) (опционально) — Детали ошибки

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

yaml

# В сценарии
- action: "sync_tenant_storage"
  params:
    tenant_id: 123

telegram_bot_manager

Описание: Сервис управления lifecycle Telegram ботов

get_telegram_bot_info_by_id

Описание: Получение информации о Telegram боте из БД по bot_id (с кэшированием)

Входные параметры:

bot_id (integer, обязательное, мин: 1) — ID бота
force_refresh (boolean, опционально) — Принудительно обновить кэш

⚙️ Дополнительные параметры

_namespace (string) (опционально) — Кастомный ключ для создания вложенности в _cache. Если указан, данные сохраняются в _cache[_namespace] вместо плоского кэша. Используется для контроля перезаписи при повторных вызовах одного действия. Доступ через {_cache._namespace.field}. По умолчанию данные мержатся напрямую в _cache (плоское кэширование).

Выходные параметры:

result (string) — Результат запроса
error (object) (опционально) — Структура ошибки
- code (string) — Код ошибки
- message (string) — Сообщение об ошибке
- details (array) (опционально) — Детали ошибки
response_data (object) — Данные бота из БД
- bot_id (integer) — ID бота
- telegram_bot_id (integer) — ID бота в Telegram
- tenant_id (integer) — ID тенанта
- bot_token (string) — Токен бота
- username (string) — Username бота
- first_name (string) — Имя бота
- is_active (boolean) — Активен ли бот
- bot_command (array) — Команды бота

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

yaml

# В сценарии
- action: "get_telegram_bot_info_by_id"
  params:
    bot_id: 123
    # force_refresh: boolean (опционально)

get_telegram_bot_status

Описание: Получение статуса Telegram бота (пулинг/вебхук, активность)

Входные параметры:

bot_id (integer, обязательное, мин: 1) — ID бота

⚙️ Дополнительные параметры

_namespace (string) (опционально) — Кастомный ключ для создания вложенности в _cache. Если указан, данные сохраняются в _cache[_namespace] вместо плоского кэша. Используется для контроля перезаписи при повторных вызовах одного действия. Доступ через {_cache._namespace.field}. По умолчанию данные мержатся напрямую в _cache (плоское кэширование).

Выходные параметры:

result (string) — Результат запроса
error (object) (опционально) — Структура ошибки
- code (string) — Код ошибки
- message (string) — Сообщение об ошибке
- details (array) (опционально) — Детали ошибки
response_data (object) — Статус бота
- is_polling (boolean) — Идёт ли пулинг
- is_webhook_active (boolean) — Активен ли вебхук
- is_active (boolean) — Активен ли бот
- is_working (boolean) — Работает ли бот (polling или webhook)

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

yaml

# В сценарии
- action: "get_telegram_bot_status"
  params:
    bot_id: 123

set_telegram_bot_token

Описание: Установка токена Telegram бота

Входные параметры:

tenant_id (integer, обязательное, мин: 1) — ID тенанта
bot_token (string|None, опционально) — Токен бота или null для сброса

Выходные параметры:

result (string) — Результат: success, error
error (object) (опционально) — Структура ошибки
- code (string) — Код ошибки
- message (string) — Сообщение об ошибке
- details (array) (опционально) — Детали ошибки

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

yaml

# В сценарии
- action: "set_telegram_bot_token"
  params:
    tenant_id: 123
    # bot_token: string|None (опционально)

start_telegram_bot

Описание: Запуск Telegram бота (polling или webhook)

Входные параметры:

bot_id (integer, обязательное, мин: 1) — ID бота

Выходные параметры:

result (string) — Результат: success, error
error (object) (опционально) — Структура ошибки
- code (string) — Код ошибки
- message (string) — Сообщение об ошибке
- details (array) (опционально) — Детали ошибки

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

yaml

# В сценарии
- action: "start_telegram_bot"
  params:
    bot_id: 123

stop_telegram_bot

Описание: Остановка Telegram бота

Входные параметры:

bot_id (integer, обязательное, мин: 1) — ID бота

Выходные параметры:

result (string) — Результат: success, error
error (object) (опционально) — Структура ошибки
- code (string) — Код ошибки
- message (string) — Сообщение об ошибке
- details (array) (опционально) — Детали ошибки

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

yaml

# В сценарии
- action: "stop_telegram_bot"
  params:
    bot_id: 123

sync_telegram_bot

Описание: Синхронизация Telegram бота для тенанта: парсинг bots/telegram.yaml + создание/обновление бота + синхронизация команд + запуск

Входные параметры:

tenant_id (integer, обязательное, мин: 1) — ID тенанта

⚙️ Дополнительные параметры

_namespace (string) (опционально) — Кастомный ключ для создания вложенности в _cache. Если указан, данные сохраняются в _cache[_namespace] вместо плоского кэша. Используется для контроля перезаписи при повторных вызовах одного действия. Доступ через {_cache._namespace.field}. По умолчанию данные мержатся напрямую в _cache (плоское кэширование).

Выходные параметры:

result (string) — Результат: success, error, not_found
error (object) (опционально) — Структура ошибки
- code (string) — Код ошибки
- message (string) — Сообщение об ошибке
- details (array) (опционально) — Детали ошибки
response_data (object) (опционально) — Данные ответа (bot_id, action)
- bot_id (integer) — ID бота
- action (string) — Выполненное действие

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

yaml

# В сценарии
- action: "sync_telegram_bot"
  params:
    tenant_id: 123

tenant_hub

Описание: Сервис-оркестратор для управления тенантами. Координирует синхронизацию через GitHub, делегирует парсинг и синхронизацию специализированным сервисам

get_bot_id_by_tenant_id

Описание: Получение bot_id бота по tenant_id и типу бота. Запрос к БД, к типу мессенджера не привязан.

Входные параметры:

tenant_id (integer, обязательное, мин: 1) — ID тенанта
bot_type (string, опционально) — Тип бота (telegram, в будущем whatsapp и др.). Пока поддерживается только telegram.

⚙️ Дополнительные параметры

_namespace (string) (опционально) — Кастомный ключ для создания вложенности в _cache. Если указан, данные сохраняются в _cache[_namespace] вместо плоского кэша. Используется для контроля перезаписи при повторных вызовах одного действия. Доступ через {_cache._namespace.field}. По умолчанию данные мержатся напрямую в _cache (плоское кэширование).
_response_key (string) (опционально) — Кастомное имя для основного поля результата (помечено 🔀). Если указано, основное поле будет сохранено в _cache под указанным именем вместо стандартного. Доступ через {_cache.{_response_key}}. Работает только для действий, поддерживающих переименование основного поля.

Выходные параметры:

result (string) — Результат: success, error
error (object) (опционально) — Структура ошибки (NOT_FOUND если у тенанта нет бота данного типа)
- code (string) —
- message (string) —
response_data (object) —
- 🔀 bot_id (integer) — ID бота в БД

Примечание:

🔀 — поле, которое можно переименовать через параметр _response_key для удобного доступа к данным

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

yaml

# В сценарии
- action: "get_bot_id_by_tenant_id"
  params:
    tenant_id: 123
    # bot_type: string (опционально)

get_tenant_status

Описание: Получение статуса тенанта по кэшу: дата последнего обновления, последняя ошибка (без данных о ботах)

Входные параметры:

tenant_id (integer, обязательное, мин: 1) — ID тенанта

⚙️ Дополнительные параметры

_namespace (string) (опционально) — Кастомный ключ для создания вложенности в _cache. Если указан, данные сохраняются в _cache[_namespace] вместо плоского кэша. Используется для контроля перезаписи при повторных вызовах одного действия. Доступ через {_cache._namespace.field}. По умолчанию данные мержатся напрямую в _cache (плоское кэширование).

Выходные параметры:

result (string) — Результат: success
response_data (object) — Данные кэша тенанта
- last_updated_at (string) (опционально) — Дата последнего успешного обновления
- last_failed_at (string) (опционально) — Дата последней ошибки
- last_error (object) (опционально) — Объект последней ошибки (code, message, details)

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

yaml

# В сценарии
- action: "get_tenant_status"
  params:
    tenant_id: 123

get_tenants_list

Описание: Получение списка всех ID тенантов с разделением на публичные и системные

Входные параметры:

⚙️ Дополнительные параметры

_namespace (string) (опционально) — Кастомный ключ для создания вложенности в _cache. Если указан, данные сохраняются в _cache[_namespace] вместо плоского кэша. Используется для контроля перезаписи при повторных вызовах одного действия. Доступ через {_cache._namespace.field}. По умолчанию данные мержатся напрямую в _cache (плоское кэширование).

Выходные параметры:

result (string) — Результат: success, error
error (object) (опционально) — Структура ошибки
- code (string) — Код ошибки
- message (string) — Сообщение об ошибке
- details (array) (опционально) — Детали ошибки
response_data (object) —
- tenant_ids (array (of integer)) — Массив ID всех тенантов
- public_tenant_ids (array (of integer)) — Массив ID публичных тенантов
- system_tenant_ids (array (of integer)) — Массив ID системных тенантов
- tenant_count (integer) — Общее количество тенантов

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

yaml

# В сценарии
- action: "get_tenants_list"
  params:

sync_all_tenants

Описание: Синхронизация всех тенантов (сначала pull из GitHub, потом синхронизация всех)

Входные параметры:

Выходные параметры:

result (string) — Результат: success, partial_success, error
error (object) (опционально) — Структура ошибки
- code (string) — Код ошибки
- message (string) — Сообщение об ошибке
- details (array) (опционально) — Детали ошибки

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

yaml

# В сценарии
- action: "sync_all_tenants"
  params:

sync_tenant

Описание: Синхронизация конфигурации тенанта с базой данных (сначала обновляет из GitHub, затем синхронизирует)

Входные параметры:

tenant_id (integer, обязательное, мин: 1) — ID тенанта для синхронизации

Выходные параметры:

result (string) — Результат: success, error, timeout, not_found
error (object) (опционально) — Структура ошибки
- code (string) — Код ошибки
- message (string) — Сообщение об ошибке
- details (array) (опционально) — Детали ошибки

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

yaml

# В сценарии
- action: "sync_tenant"
  params:
    tenant_id: 123

update_tenant_config

Описание: Обновление конфига тенанта (обновляет БД, инвалидирует кэш). Обновляет только переданные поля, остальные не трогает

Входные параметры:

tenant_id (integer, обязательное, мин: 1) — ID тенанта
ai_token (string|None, опционально) — AI API токен для тенанта (опционально, если не передан - поле не обновляется, если передан null - удаляется)

Выходные параметры:

result (string) — Результат: success, error
error (object) (опционально) — Структура ошибки
- code (string) — Код ошибки
- message (string) — Сообщение об ошибке
- details (array) (опционально) — Детали ошибки

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

yaml

# В сценарии
- action: "update_tenant_config"
  params:
    tenant_id: 123
    # ai_token: string|None (опционально)

🎯 Гайд по системным действиям ​

📋 Содержание ​

action_hub ​

get_available_actions ​

event_processor ​

process_event ​

scenario_processor ​

process_scenario_event ​

sync_scenarios ​

sync_tenant_scenarios ​

storage_hub ​

sync_tenant_storage ​

telegram_bot_manager ​

get_telegram_bot_info_by_id ​

get_telegram_bot_status ​

set_telegram_bot_token ​

start_telegram_bot ​

stop_telegram_bot ​

sync_telegram_bot ​

tenant_hub ​

get_bot_id_by_tenant_id ​

get_tenant_status ​

get_tenants_list ​

sync_all_tenants ​

sync_tenant ​

update_tenant_config ​

🎯 Гайд по системным действиям

📋 Содержание

action_hub

get_available_actions

event_processor

process_event

scenario_processor

process_scenario_event

sync_scenarios

sync_tenant_scenarios

storage_hub

sync_tenant_storage

telegram_bot_manager

get_telegram_bot_info_by_id

get_telegram_bot_status

set_telegram_bot_token

start_telegram_bot

stop_telegram_bot

sync_telegram_bot

tenant_hub

get_bot_id_by_tenant_id

get_tenant_status

get_tenants_list

sync_all_tenants

sync_tenant

update_tenant_config