docs: Update docs for the correctness (#13)

2026-04-15 00:48:06 +03:00
1 parent 8dba55272c
commit 51a783f93a
@@ -0,0 +1,6 @@
+---
+title: Концепции
+weight: 2
+---
+
+В этом разделе описываются архитектурные принципы, на которых построена Quetza. Понимание этих концепций поможет вам проектировать более надежные и поддерживаемые модули.
@@ -0,0 +1,45 @@
+---
+title: Архитектура и Философия
+weight: 1
+---
+
+**Цель:** Понять основные принципы проектирования, лежащие в основе модульности Quetza.
+
+## Философия проектирования
+
+### Соглашение важнее конфигурации (Convention Over Configuration)
+
+Quetza минимизирует шаблонный код, полагаясь на строгую структуру папок.
+
+- **Никакого центрального реестра:** Сама файловая система _является_ реестром.
+- **Результат:** Вам не нужно обновлять файл конфигурации, чтобы добавить модуль; вы просто создаете папку.
+
+### Композиция важнее наследования (Composition Over Inheritance)
+
+Модули состоят из возможностей (capabilities), а не наследуются от базового класса.
+
+- **Гибкость:** Модули могут использовать любую внутреннюю архитектуру (Функциональную, ООП), пока они экспортируют необходимые интерфейсы.
+
+### Изоляция важнее интеграции (Isolation Over Integration)
+
+Модули не могут напрямую вызывать друг друга.
+
+- **Почему:** Это предотвращает сильную связность (tight coupling).
+- **Преимущество:** Вы можете удалить любой модуль, не сломав остальную часть бота.
+
+## Основные сущности
+
+| Сущность | Роль | Жизненный цикл |
+| :--- | :--- | :--- |
+| **Client** | Локатор сервисов и оркестратор | Синглтон. Руководит всем. |
+| **Module** | Пространство имен для функций | Загружается при запуске. |
+| **Command** | Конечная точка взаимодействия с пользователем | Без состояния (Stateless). Запрос/Ответ. |
+| **Event** | Реактивный наблюдатель (Observer) | Подписывается при запуске. |
+| **Controller** | Менеджер состояния | Сохраняется между взаимодействиями. |
+
+---
+
+**См. также:**
+
+- [Паттерн Service Locator](https://ru.wikipedia.org/wiki/Локатор_служб)
+- [Паттерн Observer](https://ru.wikipedia.org/wiki/Наблюдатель_(шаблон_проектирования))
@@ -0,0 +1,67 @@
+---
+title: Модульная система
+weight: 2
+---
+
+**Цель:** Определить словарь и механизмы основной абстрактной единицы Quetza.
+
+## Системный словарь
+
+### Объявление модуля (Module Declaration)
+
+Файл `module.ts` выступает в качестве манифеста. Это точка входа для обнаружения.
+
+```typescript
+export const name = 'my-module'; // ID
+export const description = '...'; // Документация
+```
+
+### Регистрация команд (Command Registration)
+
+Происходит во время события `ready`.
+
+1. Quetza сканирует все папки `commands/`.
+2. Компилирует `ApplicationCommandData`.
+3. Отправляет (PUT) данные в API Discord.
+
+### Внедрение контроллера (Controller Injection)
+
+Состояние внедряется (injected), а не импортируется.
+
+```typescript
+// Фреймворк вызывает это:
+execute(client, interaction, controller);
+```
+
+- **Зачем?** Позволяет фреймворку управлять жизненным циклом контроллера (синглтон на каждый модуль).
+
+## Философия управления состоянием
+
+### Эфемерность по умолчанию
+
+Quetza **не предоставляет встроенной базы данных**.
+
+- **Память:** Контроллеры хранят состояние в JS объектах `Map` или `Set`.
+- **Перезапуск:** Все состояние теряется при завершении процесса.
+- **Постоянство:** Должно быть реализовано вручную (например, SQLite, Redis) внутри Контроллера.
+
+### Область видимости как ключ
+
+Состояние должно быть ключировано по его границам.
+
+- `Map<GuildID, ...>` - Специфично для сервера (Наиболее частое).
+- `Map<UserID, ...>` - Специфично для пользователя (Боты для личных сообщений - DM).
+
+## Модель обработки ошибок
+
+**Быстрый и дружелюбный отказ (Fail Fast & Friendly).**
+
+- **Валидация:** Проверяйте права/вводы немедленно.
+- **Для пользователя:** "У вас нет прав" (а не "Ошибка: 403").
+- **Изоляция:** Сбой в `/ping` перехватывается сам по себе и не "убивает" бота.
+
+---
+
+**См. также:**
+
+- [Жизненный цикл взаимодействия Discord (Interaction Lifecycle)](https://discord.com/developers/docs/interactions/receiving-and-responding)