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

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

src/gnomik/README.md

@@ -1 +1,37 @@
-# Гномик
+# Gnomик
+
+![Логотип](./docs/gnomik.jpg)
+
+Чат-бот помощник в [ALT Gnome Chat](https://t.me/alt_gnome_chat).
+
+
+ALT Regular Gnome Community - открытое сообщество пользователей операционной системы ALT Regular Gnome.
+
+- [Канал](https://t.me/alt_gnome)
+- [Wiki](https://alt-gnome.wiki)
+
+## Описание
+
+Gnomик - это чат-бот, разработанный на платформе Open Chat AI Bot (OCAB) для Telegram. Он предоставляет различные функции и возможности, помогающие пользователям операционной системы ALT Regular Gnome.
+
+## Функционал
+
+<!--
+TODO: описать функционал
+-->
+
+## Запуск
+
+Запуск бота осуществляется с помощью команды:
+
+```bash
+python -m gnomik
+```
+
+## Конфигурация
+
+Конфигурация бота находится в файле `config.yaml`.
+
+## Модули
+
+Список загружаемых модулей указан в файле `__main__.py`.

src/ocab_core/README.md

@@ -1 +1,23 @@
 # OCAB Core
+
+Это ядро OCAB, содержащее базовые компоненты:
+
+- Система управления модулями.
+- Логирование.
+- Утилиты.
+
+## Система управления модулями
+
+Система управления модулями отвечает за:
+
+- Загрузку модулей.
+- Проверку зависимостей.
+- Предоставление API для взаимодействия между модулями.
+
+## Логирование
+
+Модуль логирования предоставляет функции для записи логов в консоль.
+
+## Утилиты
+
+Модуль утилит содержит вспомогательные функции, например, для форматирования текста.

src/ocab_modules/README.md

@@ -1 +1,12 @@
 # OCAB Modules
+
+OCAB Modules содержит набор модулей для платформы Open Chat AI Bot (OCAB).
+
+## Описание
+
+OCAB - это платформа для создания чат-ботов Telegram. Модули - это расширения, которые добавляют функциональность ботам OCAB.
+
+## Типы модулей
+
+* **Стандартные модули (standard.*):** Предоставляют основные функции, такие как управление пользователями, ролями и настройками.
+* **Дополнительные официальные модули (external.*):** Разработаны командой OCAB и предоставляют расширенные возможности, такие как интеграция с нейросетями, внешними сервисами и API.

src/ocab_modules/ocab_modules/external/create_report_apps/README.md

@@ -0,0 +1,19 @@
+# Модуль Create Report Apps
+
+Модуль `create_report_apps` предназначен для помощи пользователям в создании отчетов об ошибках в приложениях.
+
+## Функциональность
+
+- Задает пользователю ряд вопросов, необходимых для составления отчета.
+- Собирает информацию о системе пользователя.
+- Формирует отчет в текстовом формате.
+
+## Команды
+
+- `/create_report_apps` - запустить процесс создания отчета.
+
+## Использование
+
+1. Отправьте команду `/create_report_apps` боту в личных сообщениях или в групповом чате.
+2. Ответьте на вопросы бота.
+3. Бот сформирует отчет и отправит его вам.

src/ocab_modules/ocab_modules/external/yandexgpt/README.md

@@ -0,0 +1,22 @@
+# Модуль YandexGPT
+
+Модуль `yandexgpt` интегрирует в бота OCAB нейросеть YandexGPT.
+
+## Функциональность
+
+- Позволяет боту отвечать на сообщения пользователей, используя YandexGPT.
+- Строит линию контекста для нейросети, используя историю сообщений.
+
+## Конфигурация
+
+- `yandexgpt::token` - API-ключ для доступа к YandexGPT.
+- `yandexgpt::catalogid` - идентификатор каталога YandexGPT.
+- `yandexgpt::prompt` - системная подсказка для YandexGPT.
+- `yandexgpt::startword` - слова, с которых должно начинаться сообщение, чтобы бот ответил.
+- `yandexgpt::inword` - слова, которые должны быть в сообщении, чтобы бот ответил.
+
+## Использование
+
+1. Настройте конфигурационные параметры модуля.
+2. Отправьте боту сообщение, которое соответствует условиям, указанным в параметрах `startword` и `inword`.
+3. Бот ответит на сообщение, используя YandexGPT.

src/ocab_modules/ocab_modules/standard/admin/README.md

@@ -0,0 +1,20 @@
+# Модуль Admin
+
+Модуль `admin` предоставляет администраторам и модераторам чата инструменты для управления:
+
+## Функциональность
+
+- Удаление сообщений.
+- Получение ID чата.
+
+## Команды
+
+- `/rm` - удалить сообщение, на которое отвечает команда.
+- `/chatID` - получить ID текущего чата.
+
+## Использование
+
+1. Ответьте на сообщение, которое нужно удалить.
+2. Отправьте команду `/rm`.
+
+Чтобы получить ID чата, отправьте команду `/chatID`.

src/ocab_modules/ocab_modules/standard/command_helper/README.md

@@ -0,0 +1,24 @@
+# Модуль Command Helper
+
+Модуль `command_helper` упрощает регистрацию команд бота и управление ими.
+
+## Функциональность
+
+- Регистрация команд бота.
+- Установка команд для пользователей в зависимости от их роли.
+
+## Использование
+
+1. Импортируйте функцию `register_command`.
+2. Вызовите функцию `register_command`, передав ей название команды, ее описание и роль пользователя,
+   которому доступна эта команда.
+
+## Пример
+
+```python
+from ocab_core.modules_system.public_api import get_module
+
+register_command = get_module("standard.command_helper", "register_command")
+
+register_command("my_command", "Описание моей команды", role="ADMIN")
+```

src/ocab_modules/ocab_modules/standard/config/README.md

@@ -0,0 +1,28 @@
+# Модуль Config
+
+Модуль `config` управляет конфигурацией бота.
+
+## Функциональность
+
+- Загрузка конфигурации из файла `config.yaml`.
+- Сохранение конфигурации в файл.
+- Регистрация параметров конфигурации.
+- Получение значений параметров.
+
+## Использование
+
+1. Импортируйте объект `config`.
+2. Вызовите метод `register`, чтобы зарегистрировать параметр конфигурации.
+3. Вызовите метод `get`, чтобы получить значение параметра.
+
+## Пример
+
+```python
+from ocab_core.modules_system.public_api import get_module
+
+config = get_module("standard.config", "config")
+
+config.register("my_parameter", "string", default_value="default")
+
+value = config.get("my_parameter")
+```

src/ocab_modules/ocab_modules/standard/filters/README.md

@@ -0,0 +1,29 @@
+# Модуль Filters
+
+Модуль `filters` предоставляет фильтры для aiogram, которые используются для ограничения доступа к командам
+и обработчикам событий.
+
+## Фильтры
+
+- `ChatModerOrAdminFilter` - пропускает сообщения только от модераторов и администраторов чата.
+- `ChatNotInApproveFilter` - пропускает сообщения только из чатов, не входящих в список разрешенных.
+
+## Использование
+
+Фильтры можно использовать в декораторах `@router.message` и `@router.callback_query`.
+
+## Пример
+
+```python
+from aiogram import Router
+from ocab_core.modules_system.public_api import get_module
+
+ChatModerOrAdminFilter = get_module("standard.filters", "ChatModerOrAdminFilter")
+
+router = Router()
+
+@router.message(ChatModerOrAdminFilter())
+async def admin_command(message: Message):
+    # Обработка команды, доступной только администраторам и модераторам.
+    pass
+```

src/ocab_modules/ocab_modules/standard/fsm_database_storage/README.md

@@ -0,0 +1,13 @@
+# Модуль FSM Database Storage
+
+Модуль `fsm_database_storage` реализует хранение состояний FSM (Finite State Machine) в базе данных.
+
+## Функциональность
+
+- Сохранение состояния FSM в базу данных.
+- Получение состояния FSM из базы данных.
+- Обновление данных состояния FSM.
+
+## Использование
+
+Модуль автоматически регистрирует хранилище состояний FSM при инициализации.

src/ocab_modules/ocab_modules/standard/info/README.md

@@ -0,0 +1,15 @@
+# Модуль Info
+
+Модуль `info` предоставляет информацию о пользователях и чатах.
+
+## Команды
+
+- `/info` - получить информацию о пользователе.
+- `/chatinfo` - получить информацию о чате.
+
+## Использование
+
+Чтобы получить информацию о пользователе, отправьте команду `/info`,
+ответив на сообщение пользователя или указав его тег.
+
+Чтобы получить информацию о чате, отправьте команду `/chatinfo`.

src/ocab_modules/ocab_modules/standard/message_processing/README.md

@@ -0,0 +1,14 @@
+# Модуль Message Processing
+
+Модуль `message_processing` обрабатывает все входящие сообщения.
+
+## Функциональность
+
+- Проверка чата и пользователя на наличие в базе данных.
+- Обновление информации о чате и пользователе.
+- Добавление статистики сообщений.
+- Передача сообщения модулю `yandexgpt`, если оно соответствует условиям.
+
+## Использование
+
+Модуль автоматически обрабатывает все входящие сообщения.

src/ocab_modules/ocab_modules/standard/miniapp/README.md

@@ -0,0 +1,23 @@
+# Модуль Miniapp
+
+Модуль `miniapp` реализует веб-интерфейс для бота, доступный через Telegram Mini Apps.
+
+## Функциональность
+
+- Регистрация страниц веб-интерфейса.
+- Авторизация пользователей через Telegram.
+
+## Использование
+
+1. Импортируйте функцию `register_page`.
+2. Вызовите функцию `register_page`, передав ей название страницы, ее путь, blueprint Dash и префикс.
+
+## Пример
+
+```python
+from ocab_core.modules_system.public_api import get_module
+
+register_page = get_module("standard.miniapp", "register_page")
+
+register_page("Моя страница", "/my_page", my_blueprint, prefix="my_page")
+```

src/ocab_modules/ocab_modules/standard/roles/README.md

@@ -0,0 +1,36 @@
+# Модуль Roles
+
+Модуль `roles` управляет ролями пользователей.
+
+## Роли
+
+- `USER` - обычный пользователь.
+- `MODERATOR` - модератор.
+- `ADMIN` - администратор.
+- `BOT` - бот.
+
+## Функциональность
+
+- Проверка роли пользователя.
+- Получение имени роли по ID.
+- Получение ID роли по имени.
+
+## Использование
+
+1. Импортируйте класс `Roles`.
+2. Создайте экземпляр класса.
+3. Вызовите методы класса для проверки роли пользователя или получения имени роли.
+
+## Пример
+
+```python
+from ocab_core.modules_system.public_api import get_module
+
+Roles = get_module("standard.roles", "Roles")
+
+roles = Roles()
+
+is_admin = await roles.check_admin_permission(user_id)
+
+role_name = await roles.get_role_name(role_id)
+```