fix: PageHead header alignment, analytics proxy, and infra improvements (#64)

🤖 Pull request created from `various-fixes` containing PageHead breadcrumbs and navigation alignment fixes, Umami analytics proxy, and infrastructure updates.
2026-10-24 16:52:49 +03:00
1 parent ff5a50bad8
commit 9ee672504f
@@ -3,4 +3,4 @@ title: Концепции
 weight: 2
 ---

-В этом разделе описываются архитектурные принципы, на которых построена Quetza. Понимание этих концепций поможет вам проектировать более надежные и поддерживаемые модули.
+Здесь описаны ключевые архитектурные принципы Quetza. Понимание этих концепций помогает проектировать надёжные и легко поддерживаемые модули.
@@ -1,45 +1,45 @@
 ---
-title: Архитектура и Философия
+title: Архитектура и философия
 weight: 1
 ---

-**Цель:** Понять основные принципы проектирования, лежащие в основе модульности Quetza.
+**Цель:** изучить принципы проектирования, определяющие модульную структуру Quetza.

 ## Философия проектирования

-### Соглашение важнее конфигурации (Convention Over Configuration)
+### Соглашение важнее конфигурации (Convention over Configuration)

-Quetza минимизирует шаблонный код, полагаясь на строгую структуру папок.
+Quetza сокращает шаблонный код за счёт строгой структуры каталогов.

- **Никакого центрального реестра:** Сама файловая система _является_ реестром.
- **Результат:** Вам не нужно обновлять файл конфигурации, чтобы добавить модуль; вы просто создаете папку.
+- **Без центрального реестра:** файловая система сама выступает реестром.
+- **Результат:** чтобы подключить модуль, не нужно редактировать конфигурационные файлы — достаточно создать каталог.

-### Композиция важнее наследования (Composition Over Inheritance)
+### Композиция важнее наследования (Composition over Inheritance)

-Модули состоят из возможностей (capabilities), а не наследуются от базового класса.
+Модули собираются из набора возможностей (capabilities), а не наследуются от базового класса.

- **Гибкость:** Модули могут использовать любую внутреннюю архитектуру (Функциональную, ООП), пока они экспортируют необходимые интерфейсы.
+- **Гибкость:** внутри модуля можно использовать любую архитектуру (функциональную или ООП), если модуль экспортирует обязательные интерфейсы.

-### Изоляция важнее интеграции (Isolation Over Integration)
+### Изоляция важнее интеграции (Isolation over Integration)

-Модули не могут напрямую вызывать друг друга.
+Модули не вызывают друг друга напрямую.

- **Почему:** Это предотвращает сильную связность (tight coupling).
- **Преимущество:** Вы можете удалить любой модуль, не сломав остальную часть бота.
+- **Причина:** исключает сильную связанность (tight coupling).
+- **Преимущество:** любой модуль можно удалить без риска сломать остального бота.

 ## Основные сущности

 | Сущность | Роль | Жизненный цикл |
 | :--- | :--- | :--- |
-| **Client** | Локатор сервисов и оркестратор | Синглтон. Руководит всем. |
-| **Module** | Пространство имен для функций | Загружается при запуске. |
-| **Command** | Конечная точка взаимодействия с пользователем | Без состояния (Stateless). Запрос/Ответ. |
-| **Event** | Реактивный наблюдатель (Observer) | Подписывается при запуске. |
-| **Controller** | Менеджер состояния | Сохраняется между взаимодействиями. |
+| **Client** | Локатор сервисов и оркестратор | Синглтон. Управляет всеми компонентами системы. |
+| **Module** | Пространство имён для функций | Загружается при старте. |
+| **Command** | Точка взаимодействия с пользователем | Без состояния (stateless). Запрос — ответ. |
+| **Event** | Реактивный наблюдатель (observer) | Регистрируется при старте. |
+| **Controller** | Менеджер состояния | Сохраняет состояние между запросами. |

 ---

-**См. также:**
+## См. также

 - [Паттерн Service Locator](https://ru.wikipedia.org/wiki/Локатор_служб)
 - [Паттерн Observer](https://ru.wikipedia.org/wiki/Наблюдатель_(шаблон_проектирования))
@@ -3,13 +3,13 @@ title: Модульная система
 weight: 2
 ---

-**Цель:** Определить словарь и механизмы основной абстрактной единицы Quetza.
+**Цель:** разобрать терминологию и механику работы базовой единицы Quetza — модуля.

-## Системный словарь
+## Терминология

 ### Объявление модуля (Module Declaration)

-Файл `module.ts` выступает в качестве манифеста. Это точка входа для обнаружения.
+Файл `module.ts` служит манифестом и точкой входа при поиске модулей.

 ```typescript
 export const name = 'my-module'; // ID
@@ -18,50 +18,50 @@ export const description = '...'; // Документация

 ### Регистрация команд (Command Registration)

-Происходит во время события `ready`.
+Выполняется при наступлении события `ready`:

-1. Quetza сканирует все папки `commands/`.
-2. Компилирует `ApplicationCommandData`.
-3. Отправляет (PUT) данные в API Discord.
+1. Quetza сканирует каталоги `commands/`.
+2. Формирует структуру `ApplicationCommandData`.
+3. Отправляет данные (PUT-запрос) в API Discord.

 ### Внедрение контроллера (Controller Injection)

-Состояние внедряется (injected), а не импортируется.
+Экземпляр контроллера передаётся аргументом при вызове (injected), а не импортируется модулем напрямую:

 ```typescript
 // Фреймворк вызывает это:
 execute(client, interaction, controller);
 ```

- **Зачем?** Позволяет фреймворку управлять жизненным циклом контроллера (синглтон на каждый модуль).
+- **Зачем:** фреймворк берёт на себя управление жизненным циклом контроллера (один синглтон на модуль).

-## Философия управления состоянием
+## Управление состоянием

 ### Эфемерность по умолчанию

-Quetza **не предоставляет встроенной базы данных**.
+В Quetza **нет встроенной базы данных**.

- **Память:** Контроллеры хранят состояние в JS объектах `Map` или `Set`.
- **Перезапуск:** Все состояние теряется при завершении процесса.
- **Постоянство:** Должно быть реализовано вручную (например, SQLite, Redis) внутри Контроллера.
+- **Память:** контроллеры сохраняют данные в стандартных JavaScript-коллекциях `Map` или `Set`.
+- **Перезапуск:** при остановке процесса всё состояние в памяти сбрасывается.
+- **Постоянное хранение:** если данные нужно сохранять между запусками, подключите внешнюю СУБД (например, SQLite или Redis) внутри контроллера.

 ### Область видимости как ключ

-Состояние должно быть ключировано по его границам.
+Ключи состояния должны соответствовать области его видимости:

- `Map<GuildID, ...>` - Специфично для сервера (Наиболее частое).
- `Map<UserID, ...>` - Специфично для пользователя (Боты для личных сообщений - DM).
+- `Map<GuildID, ...>` — уровень сервера (основной сценарий).
+- `Map<UserID, ...>` — уровень пользователя (боты для личных сообщений, DM).

 ## Модель обработки ошибок

-**Быстрый и дружелюбный отказ (Fail Fast & Friendly).**
+**Быстрый и понятный отказ (Fail Fast & Friendly).**

- **Валидация:** Проверяйте права/вводы немедленно.
- **Для пользователя:** "У вас нет прав" (а не "Ошибка: 403").
- **Изоляция:** Сбой в `/ping` перехватывается сам по себе и не "убивает" бота.
+- **Валидация:** проверяйте права и входные параметры сразу.
+- **Сообщения для пользователя:** «У вас нет прав» вместо сухого кода вроде «Ошибка: 403».
+- **Изоляция:** сбой внутри `/ping` перехватывается локально и не роняет процесс бота.

 ---

-**См. также:**
+## См. также

 - [Жизненный цикл взаимодействия Discord (Interaction Lifecycle)](https://discord.com/developers/docs/interactions/receiving-and-responding)