No description
  • Python 99.6%
  • Nix 0.4%
Find a file
2026-11-02 12:00:42 +03:00
nhm21bot feat(broadcast): run admin broadcasts in background 2026-11-02 12:00:42 +03:00
tests feat(broadcast): run admin broadcasts in background 2026-11-02 12:00:42 +03:00
.env.example feat(error-reporting): forward runtime errors to admin 2026-10-30 14:38:55 +03:00
.envrc initial commit 2026-09-04 08:55:16 +03:00
.gitignore initial commit 2026-09-04 08:55:16 +03:00
.python-version initial commit 2026-09-04 08:55:16 +03:00
flake.lock initial commit 2026-09-04 08:55:16 +03:00
flake.nix initial commit 2026-09-04 08:55:16 +03:00
LICENSE initial commit 2026-09-04 08:55:16 +03:00
pyproject.toml chore: add The Unlicense to project metadata 2026-09-19 16:19:53 +03:00
README.md feat(practice): add practice schedules and group name resolution 2026-10-30 15:48:21 +03:00
uv.lock initial commit 2026-09-04 08:55:16 +03:00

nhmt21bot

Telegram-бот для автоматического парсинга и рассылки изменений в расписании (замен) с официального сайта НХМТ. Бот парсит страницы замен СПО и НПО, нормализует номера аудиторий и распределяет их по корпусам колледжа (ЦОПП, Кванториум, Главный корпус и т.д.).

Стек технологий

  • Python 3.13+
  • aiogram 3.x для работы с Telegram Bot API
  • BeautifulSoup4 / lxml для парсинга HTML
  • uv для быстрого управления зависимостями
  • Nix для воспроизводимого окружения (опционально)

Установка и локальный запуск

  1. Склонируйте репозиторий:

    git clone https://github.com/rus07tam/nhmt21bot.git
    cd nhmt21bot
    
  2. Настройте конфигурацию:

    cp .env.example .env
    

    Затем откройте файл .env и укажите BOT_TOKEN — токен, полученный от @BotFather.

  3. Установите зависимости проекта с помощью uv:

    uv sync
    
  4. Запустите бота:

    uv run python -m nhm21bot
    

Альтернативный запуск через Nix

Проект поддерживает работу через Nix Flakes. Для входа в настроенное окружение со всеми зависимостями выполните:

nix develop

Либо используйте direnv (конфигурация .envrc уже есть в репозитории).

Конфигурация (.env)

Переменная Описание Значение по умолчанию
BOT_TOKEN Токен Telegram-бота (обязательно)
BASE_URL Базовый URL страницы замен https://zamena.nhmt.ru/zamena
SUFFIX_SPO Относительный путь для замен СПО /spo.php?a=0
SUFFIX_NPO Относительный путь для замен НПО /npo.php?a=0
ADMIN_ID Telegram ID администратора None
SYNC_CRON Интервал проверки сайта в секундах 300
CHATS_DB_FILE Путь к SQLite-базе чатов data/chats.sqlite3

Практика

Бот разбирает раздел практики из таблицы замен: УП (учебная практика) и ПП (производственная практика). Для каждой записи сохраняются группа, период, преподаватели и кабинет. Практика показывается в карточках групп, inline и уведомлениях об изменениях; для преподавателей и кабинетов она выводится в подписи к изображению. Для практики также рассчитывается, через сколько дней она закончится.

Если в таблице замен указано короткое имя группы (31 ИС), бот восстанавливает полный код (24-ИО-028) из nhm21bot/group_directory.json. Это важно для подписок и уведомлений, которые хранятся по полному коду группы.

Хранилище чатов и миграция

Настройки чатов (подписки, напоминания, закрепление) хранятся в SQLite: data/chats.sqlite3. Легаси-файл data/chats.json при первом запуске автоматически мигрируется в SQLite и больше не изменяется.

Миграция безопасная: сначала создаётся временная БД, проверяются PRAGMA integrity_check, PRAGMA foreign_key_check, количество строк и контрольный хэш содержимого, и только потом файл атомарно заменяется. Перед миграцией создаётся копия JSON в data/backups/. При любой ошибке исходный JSON и существующая БД не изменяются.

# Проверить данные и показать отчёт, ничего не записывая
python -m nhm21bot.cli chats migrate --dry-run

# Выполнить миграцию (бот должен быть остановлен)
python -m nhm21bot.cli chats migrate

# Сверить JSON и SQLite (сразу после миграции)
python -m nhm21bot.cli chats verify

# Экспортировать SQLite обратно в старый формат (для отката)
python -m nhm21bot.cli chats export-json --output data/chats.rollback.json

После запуска бота SQLite начнёт принимать новые изменения, поэтому verify будет ожидаемо показывать расхождения с замороженным chats.json.

Для отката на старую версию: остановить бота, при необходимости выполнить export-json, заменить data/chats.json результатом экспорта и запустить старую версию. Перед откатом всегда сохраняйте копию текущей SQLite-базы.

Отчёты об ошибках

Если задан ADMIN_ID, бот отправляет администратору в ЛС отчёты о runtime-ошибках:

  • необработанные исключения aiogram-хендлеров;
  • ошибки фоновых циклов синхронизации и напоминаний;
  • необработанные исключения asyncio-задач;
  • записи уровня ERROR / CRITICAL из логов бота.

Длинные traceback автоматически делятся на несколько сообщений с учётом лимита Telegram в 4096 символов. Если текст слишком большой, полный отчёт отправляется файлом bot-error.txt. Одинаковые ошибки в пределах ERROR_REPORT_COOLDOWN секунд не дублируются.

Настройки:

Переменная Описание По умолчанию
ERROR_REPORTING_ENABLED Включить отправку ошибок админу true
ERROR_REPORT_COOLDOWN Подавление повторов, секунды 60
ERROR_REPORT_MAX_CHUNKS Максимум текстовых частей до отправки файла 8

Для работы отчётов должен быть указан ADMIN_ID. Если админ заблокировал бота, отправка отключается до перезапуска.

Структура проекта

  • nhm21bot/ — исходный код бота.
    • bot/ — хэндлеры и роутеры aiogram.
    • db/ — SQLite-слой, схема и миграция чатов из JSON.
    • cabinets.py — группировка кабинетов с учётом корпуса.
    • practice.py — модель практики, привязка к группам и расчёт оставшихся дней.
    • error_reporting.py — отправка runtime-ошибок администратору.
    • parser/ — логика сбора данных с сайта НХМТ.
    • render/ — генерация изображений или PDF-файлов с расписанием.
    • settings.py — настройки приложения (pydantic-settings).
    • sync.py — фоновая синхронизация и проверка обновлений.
    • cli.py — команды миграции, проверки и экспорта чатов.
  • tests/ — автотесты (pytest).
  • data/ — директория для сохранения временных файлов (создается автоматически).

Лицензия

Проект распространяется под лицензией The Unlicense.