Merged with feat/config-module

docs/DEV.md

@@ -0,0 +1,39 @@
+## Настройка рабочего окружения
+
+Данная инструкция поможет вам настроить рабочее окружение для разработки OCAB.
+
+### Предварительные требования
+
+* **Python 3.12:** OCAB требует Python 3.12.
+* **VSCode:** Рекомендуется использовать VSCode для разработки.
+* **Git:**  У вас должен быть установлен Git для клонирования репозитория.
+
+### Шаги
+
+1. **Клонируйте репозиторий:**
+   ```bash
+   git clone https://gitflic.ru/project/armatik/ocab.git
+   ```
+
+2. **Откройте проект в VSCode:**
+   * Откройте папку `ocab` в VSCode.
+   * VSCode автоматически предложит открыть проект как workspace, используя файл `ocab.code-workspace`.
+     Нажмите "Открыть Workspace", чтобы принять предложение.
+
+3. **Настройте Poetry:**
+   * Установите Poetry, следуя инструкциям на официальном сайте: [https://python-poetry.org/docs/](https://python-poetry.org/docs/).
+   * **Для каждого пакета:**
+     * Перейдите в папку пакета (например, `src/ocab_core`).
+     * Выполните команду `poetry install`, чтобы установить зависимости пакета.
+     * Poetry создаст виртуальное окружение внутри папки пакета (`.venv`).
+
+4. **Активируйте виртуальное окружение:**
+   * Выполните команду `poetry shell` в папке пакета, чтобы активировать виртуальное окружение.
+
+Теперь ваше рабочее окружение настроено, и вы можете начать.
+
+### Дополнительная информация
+
+* Каждый пакет в монорепозитории имеет свой собственный файл `pyproject.toml`, где указаны его зависимости.
+* Poetry автоматически управляет виртуальными окружениями для каждого пакета.
+* Вы можете использовать команду `poetry add <package_name>` для добавления новых зависимостей.

docs/MODULES-SPEC.md

@@ -9,7 +9,7 @@
 
 ## Метаинформация о модуле (info.json)
 
-Этот файл содержит метаинформацию о модуле в формате JSON. Пример структуры info.json приведён ниже:
+Этот файл содержит метаинформацию о модуле в формате JSON. Пример структуры info.json приведен ниже:
 
 ```json
 {
@@ -20,8 +20,26 @@
   "version": "1.0.0",
   "privileged": false,
   "dependencies": {
-    "standard.roles": "^1.0.0",
-    "standard.database": "^1.0.0"
+    "required": {
+      "standard.roles": "^1.0.0",
+      "standard.database": {
+        "version": "^1.0.0",
+        "uses": [
+          "db_api"
+        ]
+      }
+    },
+    "optional": {
+      "external.yandexgpt": "*"
+    }
+  },
+  "pythonDependencies": {
+    "required": {
+      "some_package": "^1.2.3"
+    },
+    "optional": {
+      "another_package": "*"
+    }
   }
 }
 ```
@@ -30,31 +48,60 @@
 - `name`: Название модуля.
 - `description`: Описание функциональности модуля.
 - `author`: Автор модуля.
-- `version`: Версия модуля.
+- `version`: Версия модуля в формате [SemVer](https://semver.org/).
 - `privileged`: Булево значение, указывающее, является ли модуль привилегированным.
-- `dependencies`: Объект, описывающий зависимости модуля от других модулей с указанием версии.
+- `dependencies`: Объект, описывающий зависимости модуля от других **OCAB** модулей.
+    - `required`: Обязательные зависимости. Ключ - идентификатор модуля, значение - версия или объект `DependencyInfo`.
+    - `optional`: Необязательные зависимости. Ключ - идентификатор модуля, значение - версия или объект `DependencyInfo`.
+- `pythonDependencies`: Объект, описывающий зависимости модуля от внешних Python пакетов.
+    - `required`: Обязательные зависимости. Ключ - название пакета, значение - версия.
+    - `optional`: Необязательные зависимости. Ключ - название пакета, значение - версия.
+
+### DependencyInfo
+
+Объект `DependencyInfo` позволяет указать не только версию зависимости, но и список разрешенных к использованию
+атрибутов модуля (`uses`). Если `uses` не указан, то доступ к модулю целиком запрещен.
+
+```json
+{
+  "version": "^1.0.0",
+  "uses": [
+    "db_api"
+  ]
+}
+```
+
+- `version`: Версия модуля.
+- `uses`: Список разрешенных атрибутов модуля.
 
 ## Режимы выполнения модулей
 
-Непривилегированный режим (`privileged: false`):
-- Модуль выполняется в доверенной среде на основе RestrictedPython (это накладывает ряд ограничений);
-- Может использовать только определенный набор разрешенных пакетов
+**Непривилегированный режим** (`privileged: false`):
+- Модуль выполняется в доверенной среде на основе RestrictedPython (это накладывает ряд ограничений).
+- Может импортировать только явно разрешенные модули, указанные в `pythonDependencies`,
+  а также несколько стандартных модулей, необходимых для работы.
 - Имеет доступ к пакету `ocab_core.modules_system.public_api` для взаимодействия с ботом.
 
-Привилегированный режим (`privileged: true`):
+**Привилегированный режим** (`privileged: true`):
 - Модуль выполняется без ограничений.
-- Имеет полный доступ ко всем пакетам.
+- Имеет полный доступ ко всем пакетам, доступным в окружении.
 - Должен использоваться с осторожностью и только для модулей, требующих расширенных прав.
 
 ## Жизненный цикл модуля
 
-1. Загрузка метаданных из `info.json`
-2. Проверка зависимостей
-3. Загрузка кода модуля из `__init__.py`
-4. Вызов функции `module_init` (если она есть)
+1. Загрузка метаданных из `info.json`.
+2. Проверка зависимостей:
+    - Проверяется наличие всех обязательных зависимостей.
+    - Проверяется совместимость версий зависимостей.
+    - Проверяется наличие Python зависимостей.
+3. Загрузка кода модуля из `__init__.py`.
+4. Вызов функции `module_init` (если она есть).
+5. После загрузки всех модулей вызывается функция `module_late_init` (если она есть).
 
 ## Взаимодействие между модулями
 
-Модули могут взаимодействовать друг с другом через [API](../src/ocab_core/modules_system/public_api/__init__.py), предоставляемое системой управления модулями.
+Модули могут взаимодействовать друг с другом через [API](../src/ocab_core/ocab_core/modules_system/public_api/__init__.py),
+предоставляемое системой управления модулями.
 
-Например, есть функция `get_module`. Она позволяет получить модуль или предоставляемые им объекты по его идентификатору.
+Например, есть функция `get_module`. Она позволяет получить модуль или предоставляемые им объекты по его
+идентификатору.