# AGENTS.md

## Проект
Discord-бот на Python (discord.py) для Магнитогорска.
- Команды Discord: `!msg` (повтор текста), `!pogoda` (прогноз погоды)
- Консольные команды: `stop` (остановка бота)

## Запуск
```bash
pip install -r requirements.txt
python bot.py
```

Введите `stop` в терминал для остановки бота.

## Токен
Токен бота хранится в `.env` (переменная `DISCORD_TOKEN`). Получи токен на [Discord Developer Portal](https://discord.com/developers/applications). Шаблон в `.env.example`.

## Конвенции
- Используй TODO-списки для каждого запроса с несколькими шагами.
- Пиши комментарии на русском.
- Обработка ошибок: try/except для всех внешних вызовов (API, БД, файловая система).
- **Никогда не используй эмодзи в тексте или выводах.**

## Архитектура
```
bot.py                  # Точка входа, инициализация бота, console_input()
commands/               # Discord команды (cogs)
  __init__.py           # ALL_COMMANDS — явные импорты
  pogoda.py             # !pogoda — погода с retry + fallback (wttr.in → Open-Meteo)
console_commands/       # Консольные команды
  __init__.py           # ALL_CONSOLE_COMMANDS — явные импорты
  stop.py               # stop — остановка бота
```

### Добавление Discord команды
1. Создать файл `commands/имя.py` с классом, наследующим `commands.Cog`
2. Добавить импорт в `commands/__init__.py`
3. Добавить класс в `ALL_COMMANDS`

### Добавление консольной команды
1. Создать файл `console_commands/имя.py` с функцией `func(stop_event, bot)`
2. Добавить импорт в `console_commands/__init__.py`
3. Добавить функцию в `ALL_CONSOLE_COMMANDS`

## API и внешние сервисы

### Погода (!pogoda)
- **Основной**: `wttr.in` (бесплатный, без ключа)
- **Fallback**: `api.open-meteo.com` (бесплатный, без ключа)
- Retry: 3 попытки с экспоненциальной задержкой при SSL/Connection/Timeout ошибках
- Fallback срабатывает автоматически при неуспешных попытках
- WMO weather codes → русский перевод в `_wmo_to_russian()`

### Конвертации
- Давление: hPa → мм рт. ст. (`* 0.750062`)
- Ветер: км/ч → м/с (`/ 3.6`)
- Погодные описания: английский → русский (`_translate_weather()`)

## Конфигурация
| Переменная | Описание | Где взять |
|------------|----------|-----------|
| `DISCORD_TOKEN` | Токен бота | Discord Developer Portal |

## Зависимости
```txt
discord.py>=2.3.2
python-dotenv>=1.0.0
requests>=2.31.0
```

## Структура данных погоды
Команда `!pogoda` возвращает:
```
[TEMP]   Температура: X°C (ощущается как Y°C)
[DESC]   Описание: Z
[HUMID]  Влажность: X%
[WIND]   Ветер: X м/с
[PRESS]  Давление: X мм рт. ст.
```

## Безопасность
- `.env` в `.gitignore` — токен никогда не должен попадать в репозиторий.
- Используй `.env.example` как шаблон.