улучшена документация

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`. Она позволяет получить модуль или предоставляемые им объекты по его
+идентификатору.