---
title: Диагностика
weight: 1
---

**Цель:** Определить и устранить распространенные ловушки при разработке Quetza.

## 1. Сбои при обнаружении модулей

**Симптом:** Бот запускается, но ваш модуль игнорируется.
**Причина:** Нарушение соглашений файловой системы.

{{% details title="Чек-лист: Структура директорий" closed="false" %}}

- [ ] Существует ли `src/modules/<name>/`?
- [ ] Экспортирует ли `module.ts` переменную `name`?
- [ ] Находятся ли команды в `commands/` (а не в `cmds/`)?
- [ ] Запустили ли вы `pnpm build`? (Quetza запускается из `dist/`).
      {{% /details %}}

## 2. Проблемы с регистрацией команд

**Симптом:** Команда `/command` не появляется в Discord.

### Глобальная регистрация против регистрации в тестовой гильдии (Guild)

- **Глобальная:** Команды, отправленные в приложение глобально, могут обновляться до 1 часа и подчиняются более строгим ограничениям скорости (rate limits).
- **Тестовая гильдия:** Quetza автоматически отправляет команды в конкретную гильдию в режиме разработки для мгновенного обновления.
  - **Требование:** Убедитесь, что `NODE_ENV=development` и `DEV_GUILD_ID` корректно установлены в вашем `.env`.

### Ограничения скорости (Rate Limits)

Частые обновления глобальных команд могут вызвать ограничения скорости со стороны Discord. Используйте тестовую гильдию для итеративной разработки.

## 3. Ошибки взаимодействия (Interaction Failures)

**Симптом:** «Приложение не отвечает».
**Причина:** Выполнение команды заняло более 3 секунд без отложенного ответа (deferral).

**Решение:**

```typescript
// ПЛОХО
await longRunningTask();
await interaction.reply('Готово'); // Слишком поздно!

// ХОРОШО
await interaction.deferReply();
await longRunningTask();
await interaction.editReply('Готово');
```

## 4. Утечки состояния

**Симптом:** Потребление памяти ботом растет; странности во взаимодействии между серверами.
**Причина:** Хранение состояния глобально вместо уровня гильдии.

**Диагностика:**
Проверьте ваш контроллер.

- ❌ `private player: AudioPlayer;` (Общий для всех!)
- ✅ `private players = new Map<string, AudioPlayer>();` (Разделен по ID гильдии).

## 5. Обработка событий

**Симптом:** События срабатывают несколько раз или не срабатывают вовсе.

- **Несколько раз:** События являются аддитивными. Не зарегистрировали ли вы один и тот же обработчик в двух модулях?
- **Ни разу:** Правильно ли вы экспортировали `name` и `execute`?

> [!TIP]
> **Debug Mode:**
> Включите подробное логирование, чтобы точно увидеть, какие модули и команды загружаются при запуске.