docs: добавить README.md

2026-05-26 09:24:32 +05:00 · 2026-05-26 09:24:32 +05:00 · 0e11dbe6c1
commit 0e11dbe6c1
parent b8afbfa6b1
1 changed files with 151 additions and 0 deletions
--- a/README.md
+++ b/README.md
@ -0,0 +1,151 @@
+# Discord Bot — Магнитогорск
+
+Discord-бот для Магнитогорска. Команды погоды, новостей и развлечений.
+
+## Установка
+
+```bash
+pip install -r requirements.txt
+```
+
+## Запуск
+
+```bash
+python bot.py
+```
+
+Введите номер команды в терминале или `!команда` в Discord.
+
+## Настройка
+
+1. Скопируйте `.env.example` в `.env`:
+   ```bash
+   cp .env.example .env
+   ```
+
+2. Вставьте токен бота в `.env`:
+   ```env
+   DISCORD_TOKEN=ваш_токен
+   ```
+
+Токен получите на [Discord Developer Portal](https://discord.com/developers/applications).
+
+## Команды Discord
+
+| Команда | Описание |
+|---------|----------|
+| `!pogoda` | Прогноз погоды для Магнитогорска |
+| `!news` | Топ-5 свежих статей по AI с Habr |
+| `!cat` | Случайный котик |
+| `!msg <текст>` | Повторить текст в чате |
+
+## Команды терминала
+
+| Номер | Команда | Описание |
+|-------|---------|----------|
+| 1 | `news` | Топ-5 статей + топ-5 новостей с Habr |
+| 2 | `pogoda` | Прогноз погоды для Магнитогорска |
+| 3 | `cat` | Заглушка: тут должен быть котик |
+| 0 | `stop` | Остановка бота |
+
+## Архитектура
+
+```
+bot.py                  # Точка входа, инициализация бота, console_input()
+commands/               # Discord команды (cogs)
+  __init__.py           # ALL_COMMANDS — явные импорты
+  pogoda.py             # !pogoda — погода с retry + fallback
+  news.py               # !news — новости с Habr
+  cat.py                # !cat — случайный котик
+console_commands/       # Консольные команды
+  __init__.py           # ALL_CONSOLE_COMMANDS — явные импорты
+  stop.py               # stop — остановка бота
+  news.py               # news — новости с Habr
+  pogoda.py             # pogoda — погода в терминале
+  cat.py                # cat — заглушка котика
+```
+
+### Добавление 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()`)
+
+### Новости (!news)
+- **Articles**: `https://habr.com/ru/rss/hubs/artificial_intelligence/articles/top/daily/?fl=ru`
+- **News**: `https://habr.com/ru/rss/hubs/artificial_intelligence/news/top/daily/?fl=ru`
+- Парсинг RSS 2.0 и Atom форматов
+- Извлечение ссылок из `<guid isPermaLink="true">` и авторов из `<dc:creator>`
+- Формат вывода: заголовок → дата → ссылка
+
+### Котики (!cat)
+- **API**: `https://api.thecatapi.com/v1/images/search`
+- Картинка встраивается в Discord Embed
+
+## Структура данных погоды
+
+Команда `!pogoda` возвращает:
+
+```
+[TEMP]   Температура: X°C (ощущается как Y°C)
+[DESC]   Описание: Z
+[HUMID]  Влажность: X%
+[WIND]   Ветер: X м/с
+[PRESS]  Давление: X мм рт. ст.
+```
+
+## Формат дат
+
+Даты форматируются как `дд.мм.гггг` через `datetime.strptime` с форматом `%a, %d %b %Y %H:%M:%S %z`.
+
+## Конфигурация
+
+| Переменная | Описание | Где взять |
+|------------|----------|-----------|
+| `DISCORD_TOKEN` | Токен бота | [Discord Developer Portal](https://discord.com/developers/applications) |
+
+## Зависимости
+
+```txt
+discord.py>=2.3.2
+python-dotenv>=1.0.0
+requests>=2.31.0
+```
+
+## Безопасность
+
+- `.env` в `.gitignore` — токен никогда не должен попадать в репозиторий
+- Используйте `.env.example` как шаблон
+
+## Формат новостей
+
+Каждая новость выводится в формате:
+
+```
+Заголовок статьи
+   дд.мм.гггг   https://habr.com/ru/articles/...
+```
+
+Заголовки обрезаются до 60 символов с суффиксом `...`.
+
+Ссылки отображаются без `<>` и `https://` префикса для предотвращения embed-превью в Discord.