Merged with private/new-module-system

docs/MODULES-SPEC.md

@@ -0,0 +1,60 @@
+# Спецификация модулей
+
+> **Внимание!**
+>
+> Данная спецификация еще не закончена и активно разрабатывается.
+> Могут быть значительные изменения (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`. Она позволяет получить модуль или предоставляемые им объекты по его идентификатору.