ermnvldmr.com/services/docs/content/ru/quetza/troubleshooting/diagnostics.md

title, weight

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).

Решение:

// ПЛОХО
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: Включите подробное логирование, чтобы точно увидеть, какие модули и команды загружаются при запуске.