---
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 **нет встроенной базы данных**.

- **Память:** контроллеры сохраняют данные в стандартных JavaScript-коллекциях `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)