Шаблоны YAML-конфигов для плагинов (сервисов и утилит)

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

1. Универсальный шаблон для всех утилит

Применяется к: Custom Layers, Foundation, Core

yaml

name: "logger"                    # Уникальное имя утилиты (обязательно)
description: "Краткое описание утилиты"
singleton: false                  # (опционально) true если плагин должен быть в единственном экземпляре

dependencies:                     # (опционально, если утилита использует другие утилиты)
  - "logger"                      # Формат: "utility_name" (уникальное имя утилиты)
  - "database"                    # Система автоматически найдет утилиту по имени
  - "cache"                       # Список обязательных утилит

optional_dependencies:            # (опционально) Зависимости, которые могут отсутствовать
  - "tg_bot"                      # Формат: "utility_name" (уникальное имя утилиты)
  - "analytics"                   # Система передаст None если утилита не найдена

settings:                         # (опционально, если есть настройки)
  param_name:
    type: string
    default: "..."
    description: "..."

methods:                          # ОБЯЗАТЕЛЬНО для утилит - публичные методы
  method_name:
    description: "..."
    input:
      param1:
        type: ...
        description: "..."
    output:
      type: ...
      description: "..."

actions:                          # (опционально) Действия для вызова из сценариев
  action_name:
    description: "Описание действия"
    access_rules: ["rule_name"]   # (опционально) Правила доступа для валидации
    public: false                 # (опционально) Доступность в сценариях: true=публичное, false=системное (по умолчанию false)
    input:
      data:                       # ОБЯЗАТЕЛЬНО - блок data с параметрами
        type: object
        properties:
          param1:
            type: ...
            description: "..."
          param2:
            type: ...
            optional: true
            description: "Опциональный параметр"
    output:
      result:                     # ОБЯЗАТЕЛЬНО - результат выполнения
        type: string
        description: "Результат: success, error, timeout, not_found"
      error:                      # Опционально - структура ошибки
        type: object
        optional: true
        description: "Структура ошибки при неудаче"
        properties:
          code:
            type: string
            description: "Код ошибки"
          message:
            type: string
            description: "Сообщение об ошибке"
          details:
            type: array
            optional: true
            description: "Детали ошибки (например, ошибки валидации полей)"
      response_data:              # Опционально - данные ответа (аналог data в API)
        type: object
        properties:
          field1:
            type: integer
            description: "Описание поля 1"
          field2:
            type: string
            replaceable: true  # (опционально) Маркер для полей, которые могут быть подменены через response_key
            description: "Описание поля 2"
features:                         # (опционально, если есть)
  - "..."

2. Services — API методы сервисов

yaml

name: "user_service"              # Уникальное имя сервиса (обязательно)
description: "Краткое описание сервиса"
singleton: false                  # (опционально) true если плагин должен быть в единственном экземпляре

dependencies:                     # (опционально, если сервис использует утилиты)
  - "logger"                      # Формат: "utility_name" (уникальное имя утилиты)
  - "database_service"            # Система автоматически найдет утилиту по имени
  - "hash_manager"                # Утилиты автоматически будут переданы в конструктор
  
optional_dependencies:            # (опционально) Зависимости, которые могут отсутствовать
  - "cache_service"               # Формат: "utility_name" (уникальное имя утилиты)
  - "analytics_service"           # Система передаст None если утилита не найдена
  
settings:                         # (опционально, если есть настройки)
  # Стандартные настройки для сервисов
  processing_interval:            # (рекомендуется для сервисов с циклом обработки)
    type: float
    default: 0.10
    description: "Интервал (в секундах) между итерациями обработки"
  batch_size:                     # (рекомендуется для сервисов с пакетной обработкой)
    type: integer
    default: 50
    description: "Максимальное количество элементов, обрабатываемых за одну итерацию"
  
  # Другие специфичные настройки сервиса
  param_name:
    type: string
    default: "..."
    description: "..."
    
actions:                          # ОБЯЗАТЕЛЬНО для сервисов - действия для сценариев
  create_profile:
    description: "Создание профиля пользователя"
    access_rules: ["system_access"]  # Правила доступа для валидации
    public: true                      # (опционально) true — доступно в общих сценариях; по умолчанию false (системное)
    input:
      data:                       # ОБЯЗАТЕЛЬНО - блок data с параметрами
        type: object
        properties:
          user_id:
            type: integer
            description: "ID пользователя"
          source:
            type: string
            optional: true
            description: "Источник регистрации (опциональный)"
    output:
      result:                     # ОБЯЗАТЕЛЬНО - результат выполнения
        type: string
        description: "Результат: success, error, timeout, not_found"
      error:                      # Опционально - структура ошибки
        type: object
        optional: true
        description: "Структура ошибки при неудаче"
        properties:
          code:
            type: string
            description: "Код ошибки"
          message:
            type: string
            description: "Сообщение об ошибке"
          details:
            type: array
            optional: true
            description: "Детали ошибки (например, ошибки валидации полей)"
      response_data:              # Опционально - данные ответа (аналог data в API)
        type: object
        properties:
          user_id:
            type: integer
            description: "ID пользователя"
          profile_created:
            type: boolean
            description: "Профиль создан успешно"
  
  get_profile:
    description: "Получение профиля пользователя"
    access_rules: ["data_integrity"]  # Правила доступа для валидации
    public: false                     # Явно укажем системное действие (опционально)
    input:
      data:                       # ОБЯЗАТЕЛЬНО - блок data с параметрами
        type: object
        properties:
          user_id:
            type: integer
            description: "ID пользователя"
    output:
      result:                     # ОБЯЗАТЕЛЬНО - результат выполнения
        type: string
        description: "Результат: success, error, timeout, not_found"
      error:                      # Опционально - структура ошибки
        type: object
        optional: true
        description: "Структура ошибки при неудаче"
        properties:
          code:
            type: string
            description: "Код ошибки"
          message:
            type: string
            description: "Сообщение об ошибке"
          details:
            type: array
            optional: true
            description: "Детали ошибки"
      response_data:              # Опционально - данные ответа (аналог data в API)
        type: object
        properties:
          user_id:
            type: integer
            description: "ID пользователя"
          username:
            type: string
            description: "Имя пользователя"
          first_name:
            type: string
            description: "Имя"
          last_name:
            type: string
            description: "Фамилия"

# ℹ️ Секция actions ОБЯЗАТЕЛЬНА для сервисов - описывает действия для сценариев
# ℹ️ Метод run() ОПЦИОНАЛЕН - для фонового запуска сервисов
# ℹ️ Сервисы вызываются через сценарии, передавая параметры в действия
# ℹ️ В input ОБЯЗАТЕЛЬНО использовать блок data с описанием полей внутри
# ℹ️ В output всегда обязателен result, error и response_data опциональны
# ℹ️ error - структурированный объект с полями code, message, details (не строка)
# ℹ️ response_data - аналог data в REST API, содержит возвращаемые данные
# ℹ️ Действия принимают плоский словарь data для универсальности
# ℹ️ Опциональные зависимости позволяют сервисам работать с дополнительными утилитами
# ℹ️ access_rules определяет правила доступа для валидации действий
# ℹ️ public: boolean — пометка доступности в сценариях (по умолчанию false = системное)

features:                         # (опционально, если есть)
  - "..."

Система валидации доступа (access_rules)

Назначение

Поле access_rules определяет правила доступа для валидации действий. Система автоматически проверяет права доступа перед выполнением действия.

Актуальные настройки

Все правила доступа и группы пользователей находятся в action_hub/config.yaml — это центральное место для управления системой валидации доступа.

Доступные правила доступа:

system_access — доступ только для системных операций (управление ботами, тенантами)
data_integrity — доступ для операций с данными (отправка сообщений, валидация)
no_access — действия без ограничений доступа (обработка событий)

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

yaml

actions:
  start_bot:
    description: "Запуск бота"
    access_rules: ["system_access"]  # Только системные операции
    
  send_message:
    description: "Отправка сообщения"
    access_rules: ["data_integrity"]  # Операции с данными
    
  process_event:
    description: "Обработка события"
    access_rules: ["no_access"]  # Без ограничений

Формат ответа действий (output)

Структура ответа

Все действия возвращают единообразный формат ответа:

yaml

output:
  result:                     # ОБЯЗАТЕЛЬНО - статус выполнения
    type: string
    description: "Результат: success, error, timeout, not_found"
  error:                      # Опционально - структура ошибки
    type: object
    optional: true
    properties:
      code:                   # Код ошибки
        type: string
      message:                # Сообщение об ошибке
        type: string
      details:                # Детали ошибки (опционально)
        type: array
        optional: true
  response_data:              # Опционально - данные ответа (аналог data в REST API)
    type: object
    properties: ...

Примеры ответов

Успешный ответ:

json

{
  "result": "success",
  "response_data": {
    "user_id": 123,
    "username": "john_doe"
  }
}

Ответ с ошибкой:

json

{
  "result": "error",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Ошибка валидации входных данных",
    "details": [
      {
        "field": "email",
        "message": "Поле обязательно",
        "type": "value_error.missing"
      }
    ]
  }
}

Особый статус (не ошибка):

json

{
  "result": "not_found"
}

Назначение полей

result — статус выполнения действия. Может быть: success, error, timeout, not_found и другие. Используется в транзишнах для определения дальнейших действий.
error — структурированная информация об ошибке. Содержит код ошибки, сообщение и детали. Формат соответствует стандартам REST API для легкого перехода в будущем.
response_data — данные ответа (только при result=success). Аналог поля data в REST API. Может содержать любую структуру данных.

Коды ошибок (рекомендуемые)

Для поля error.code рекомендуется использовать следующие стандартные коды:

VALIDATION_ERROR — ошибка валидации входных данных (некорректные параметры, отсутствуют обязательные поля)
NOT_FOUND — ресурс не найден (пользователь, бот, тенант и т.д.)
ALREADY_EXISTS — ресурс уже существует (попытка создать дубликат)
PERMISSION_DENIED — недостаточно прав для выполнения операции
INTERNAL_ERROR — внутренняя ошибка сервиса (неожиданные исключения, ошибки БД)
TIMEOUT — превышено время ожидания операции
INVALID_STATE — недопустимое состояние для операции (например, попытка отменить уже оплаченный инвойс)
API_ERROR — ошибка при обращении к внешнему API (GitHub, Telegram и т.д.)
SYNC_ERROR — ошибка синхронизации данных
PARSE_ERROR — ошибка парсинга данных (конфигурации, сценариев и т.д.)

Маркер replaceable

Назначение

Маркер replaceable: true указывает, что поле в response_data может быть подменено через параметр response_key в input действии. Если указан response_key, основное значение возвращается под этим ключом вместо стандартного.

Использование

yaml

output:
  response_data:
    properties:
      main_value:
        type: string
        replaceable: true  # Поле может быть подменено через response_key
        description: "Основное значение"

Пример

yaml

# В config.yaml
output:
  response_data:
    properties:
      user_storage_values:
        type: any
        replaceable: true
        description: "Данные пользователя"

# В сценарии
- action: "get_user_storage"
  params:
    key: "active_tenant_id"
    response_key: "active_tenant_id"  # Значение будет в _cache.active_tenant_id

Общие рекомендации

Не добавляйте пустые или неиспользуемые секции
Документируйте только то, что реально используется другими слоями или пользователями
Следуйте структуре шаблона для своего типа сервиса
При сомнениях — сверяйтесь с этим документом или уточняйте у архитектора
Все сервисы используют единый шаблон для унификации
Соблюдайте иерархию зависимостей, описанную в архитектуре проекта
Используйте plugin_management для управления включением/отключением плагинов
Работа с базой данных происходит через утилиту database_service
Всегда указывайте access_rules для действий сервисов
Используйте маркер replaceable для полей, которые могут быть подменены через response_key

Ключевые различия между утилитами и сервисами

🔧 Утилиты (Utilities)

Секция methods: ОБЯЗАТЕЛЬНА - описывает публичные методы
Секция actions: ОПЦИОНАЛЬНА - описывает действия для вызова из сценариев
Назначение: Вспомогательные компоненты для расширения функционала
Зависимости: Только от других утилит

🚀 Сервисы (Services)

Секция actions: ОБЯЗАТЕЛЬНА - описывает действия для сценариев
Метод run(): ОПЦИОНАЛЕН - для фонового запуска сервисов
Назначение: Основная бизнес-логика приложения (оркестраторы, обработчики событий)
Зависимости: От утилит (не от других сервисов)

Секция dependencies

Назначение

Секция dependencies позволяет автоматически определять и передавать необходимые утилиты в конструктор сервиса или утилиты. Это обеспечивает:

Автоматическую инъекцию зависимостей — утилиты передаются автоматически
Проверку иерархии зависимостей — система проверяет корректность зависимостей
Упрощение регистрации — не нужно вручную указывать зависимости при создании сервиса
Гибкость архитектуры — утилиты можно легко перемещать между уровнями

Формат записи зависимостей

yaml

dependencies:
  - "logger"             # Уникальное имя утилиты
  - "database"           # Система автоматически найдет утилиту по имени
  - "cache"              # Независимо от того, в каком level она находится
optional_dependencies:
  - "tg_bot"             # Опциональная зависимость
  - "analytics"           # Система передаст None если утилита не найдена

Правила зависимостей

Утилиты могут зависеть только от других утилит
Сервисы могут зависеть от утилит
Сервисы НЕ могут зависеть от других сервисов
Циклические зависимости запрещены
Опциональные зависимости НЕ передаются в конструктор если утилита не найдена

Шаблоны YAML-конфигов для плагинов (сервисов и утилит) ​

1. Универсальный шаблон для всех утилит ​

2. Services — API методы сервисов ​

Система валидации доступа (access_rules) ​

Назначение ​

Актуальные настройки ​

Доступные правила доступа: ​

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

Формат ответа действий (output) ​

Структура ответа ​

Примеры ответов ​

Успешный ответ: ​

Ответ с ошибкой: ​

Особый статус (не ошибка): ​

Назначение полей ​

Коды ошибок (рекомендуемые) ​

Маркер replaceable ​

Назначение ​

Использование ​

Пример ​

Общие рекомендации ​

Ключевые различия между утилитами и сервисами ​

🔧 Утилиты (Utilities) ​

🚀 Сервисы (Services) ​

Секция dependencies ​

Назначение ​

Формат записи зависимостей ​

Правила зависимостей ​

Шаблоны YAML-конфигов для плагинов (сервисов и утилит)

1. Универсальный шаблон для всех утилит

2. Services — API методы сервисов

Система валидации доступа (access_rules)

Назначение

Актуальные настройки

Доступные правила доступа:

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

Формат ответа действий (output)

Структура ответа

Примеры ответов

Успешный ответ:

Ответ с ошибкой:

Особый статус (не ошибка):

Назначение полей

Коды ошибок (рекомендуемые)

Маркер replaceable

Назначение

Использование

Пример

Общие рекомендации

Ключевые различия между утилитами и сервисами

🔧 Утилиты (Utilities)

🚀 Сервисы (Services)

Секция dependencies

Назначение

Формат записи зависимостей

Правила зависимостей