From 89fe6a35207fb9461778006f01e3a93594c28db8 Mon Sep 17 00:00:00 2001
From: Maxim Slipenko <maxim@slipenko.com>
Date: Wed, 10 Jul 2024 11:56:52 +0300
Subject: [PATCH] =?UTF-8?q?=D0=B4=D0=BE=D0=B1=D0=B0=D0=B2=D0=BB=D0=B5?=
 =?UTF-8?q?=D0=BD=D0=B0=20=D1=81=D0=BF=D0=B5=D1=86=D0=B8=D1=84=D0=B8=D0=BA?=
 =?UTF-8?q?=D0=B0=D1=86=D0=B8=D1=8F=20=D0=BC=D0=BE=D0=B4=D1=83=D0=BB=D0=B5?=
 =?UTF-8?q?=D0=B9?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/MODULES-SPEC.md | 59 +++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 58 insertions(+), 1 deletion(-)

diff --git a/docs/MODULES-SPEC.md b/docs/MODULES-SPEC.md
index c47106c..02f8e7e 100644
--- a/docs/MODULES-SPEC.md
+++ b/docs/MODULES-SPEC.md
@@ -1,3 +1,60 @@
 # Спецификация модулей
 
-Каждый модуль - это Py
+> **Внимание!**
+>
+> Данная спецификация еще не закончена и активно разрабатывается.
+> Могут быть значительные изменения (breaking changes).
+
+Каждый модуль представлен в виде папки, содержащей два обязательных файла: info.json и `__init__.py`.
+
+## Метаинформация о модуле (info.json)
+
+Этот файл содержит метаинформацию о модуле в формате JSON. Пример структуры info.json приведён ниже:
+
+```json
+{
+  "id": "standard.info",
+  "name": "Info",
+  "description": "Модуль с информацией",
+  "author": "OCAB Team",
+  "version": "1.0",
+  "privileged": false,
+  "dependencies": {
+    "standard.roles": "^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, предоставляемое системой управления модулями.
+
+Например, есть `ocab_core.modules_system.public_api.get_module`.
+Функция, которая получает модуль или предоставляемые им объекты по его идентификатору.