ocab/docs/MODULES-SPEC.md

# Спецификация модулей

> **Внимание!**
>
> Данная спецификация еще не закончена и активно разрабатывается.
> Могут быть значительные изменения (breaking changes).

Каждый модуль представлен в виде папки, содержащей два обязательных файла: info.json и `__init__.py`.

## Метаинформация о модуле (info.json)

Этот файл содержит метаинформацию о модуле в формате JSON. Пример структуры info.json приведён ниже:

```json
{
  "id": "standard.info",
  "name": "Info",
  "description": "Модуль с информацией",
  "author": "OCAB Team",
  "version": "1.0.0",
  "privileged": false,
  "dependencies": {
    "standard.roles": "^1.0.0",
    "standard.database": "^1.0.0"
  }
}
```

- `id`: Уникальный идентификатор модуля.
- `name`: Название модуля.
- `description`: Описание функциональности модуля.
- `author`: Автор модуля.
- `version`: Версия модуля.
- `privileged`: Булево значение, указывающее, является ли модуль привилегированным.
- `dependencies`: Объект, описывающий зависимости модуля от других модулей с указанием версии.

## Режимы выполнения модулей

Непривилегированный режим (`privileged: false`):
- Модуль выполняется в доверенной среде на основе RestrictedPython (это накладывает ряд ограничений);
- Может использовать только определенный набор разрешенных пакетов
- Имеет доступ к пакету `ocab_core.modules_system.public_api` для взаимодействия с ботом.

Привилегированный режим (`privileged: true`):
- Модуль выполняется без ограничений.
- Имеет полный доступ ко всем пакетам.
- Должен использоваться с осторожностью и только для модулей, требующих расширенных прав.

## Жизненный цикл модуля

1. Загрузка метаданных из `info.json`
2. Проверка зависимостей
3. Загрузка кода модуля из `__init__.py`
4. Вызов функции `module_init` (если она есть)

## Взаимодействие между модулями

Модули могут взаимодействовать друг с другом через [API](../src/ocab_core/modules_system/public_api/__init__.py), предоставляемое системой управления модулями.

Например, есть функция `get_module`. Она позволяет получить модуль или предоставляемые им объекты по его идентификатору.