Телеграм-бот для студентов ГУАП, который автоматически отслеживает дедлайны в личном кабинете и присылает уведомления. Проект выполнен в рамках учебной практики🎓.

Опробовать: @suai_deadline_bot

Бот предоставляет широкий набор инструментов для управления учебными дедлайнами, делая студенческую жизнь проще и организованнее.

• Автоматический парсинг: Бот подключается к личному кабинету pro.guap.ru и самостоятельно собирает все актуальные дедлайны. Проверка происходит в фоновом режиме раз в час.
• "Умная" синхронизация: При обновлении данных бот не удаляет дедлайны, добавленные пользователем вручную, а также автоматически убирает те, которые сданы и срок которых уже истёк.
• Гибкие уведомления:
  • Ежедневные: Напоминания о дедлайнах, срок которых наступает через 1, 3 или 7 дней. Пользователь может сам выбрать, за сколько дней он хочет получать уведомления.
  • Частые: Возможность настроить получение полного списка дедлайнов каждые N часов (от 1 до 100).

• Просмотр с пагинацией: Все дедлайны отображаются в удобном виде с разбивкой по страницам, чтобы не перегружать чат огромными сообщениями.
• Добавление личных дедлайнов: Пользователь может создавать собственные напоминания, которые не связаны с ЛК ГУАП, с помощью команды /add или через меню.
• Безопасное удаление:
  • Возможность удалить любой дедлайн (как из ЛК, так и личный) с шагом подтверждения, чтобы избежать случайных нажатий.
  • Функция массового удаления всех личных дедлайнов в один клик.

• Информативный профиль: В профиле отображается ФИО пользователя, ссылка на его страницу в ЛК, текущий учебный семестр и статистика по дедлайнам.
• Полный контроль над данными: Пользователь может в любой момент полностью удалить всю свою информацию из базы данных бота (включая зашифрованные учетные данные) с помощью команды /stop или через меню профиля.
• Настройка уведомлений: В специальном меню можно включать/выключать как ежедневные, так и частые уведомления, а также настраивать их параметры.

• Шифрование: Логин и пароль от личного кабинета каждого пользователя хранятся в базе данных в зашифрованном виде с использованием надёжной криптографической библиотеки.
• Приватность: Бот удаляет сообщение с паролем сразу после его отправки пользователем, не оставляя его в истории чата.

1. Клонирование репозитория:

   git clone https://github.com/n1xsi/suai-deadline-bot.git
   cd suai-deadline-bot

2. Создание виртуального окружения:

   • На Windows:

     python -m venv .venv
     .\.venv\Scripts\activate

   • На macOS / Linux:

     python3 -m venv .venv
     source .venv/bin/activate

3. Установление зависимости:

   pip install -r requirements.txt

4. Настройка переменных окружения:

   • Создайте файл .env в корневой папке проекта.
   • Добавьте в него токен вашего telegram-бота и сгенерируйте ключ шифрования:

   BOT_TOKEN="Токен бота из @botfather"
   ENCRYPTION_KEY="Ключ, сгенерированный командой ниже"

   • Для генерации ENCRYPTION_KEY выполните в терминале:

     python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

5. Запуск бота:

   python -m src.bot.main_bot

ℹ️ Примечание о базе данных: При первом успешном запуске бота файл базы данных database.db будет автоматически создан в директории src/database/. Если вы вносите изменения в структуру таблиц в src/database/models.py, вам может потребоваться удалить этот файл, чтобы он был создан заново с новой схемой.

Проект имеет модульную структуру, где каждый компонент отвечает за свою зону ответственности. Это обеспечивает слабую связанность и упрощает поддержку, тестирование и дальнейшее расширение.

suai-deadline-bot/
├── src/                 # Основной пакет с исходным кодом
│   ├── bot/                # Модуль взаимодействия с Telegram (Представление)
│   │   ├── __init__.py
│   │   ├── filters.py      # Пользовательские фильтры для хэндлеров
│   │   ├── handlers.py     # Обработчики команд, сообщений, callback'ов, FSM
│   │   ├── keyboards.py    # Функции для генерации клавиатур (кнопок)
│   │   ├── states.py       # Классы состояний для FSM
│   │   └── main_bot.py     # Точка входа для запуска бота
│   │
│   ├── database/        # Модуль для работы с базой данных (Модель)
│   │   ├── __init__.py
│   │   ├── database.db     # База данных (не в Git)
│   │   ├── engine.py       # Создание движка и сессий SQLAlchemy
│   │   ├── models.py       # Описание таблиц БД (User, Deadline)
│   │   └── queries.py      # Функции с SQL-запросами
│   │
│   ├── parser/          # Модуль парсинга сайта ЛК (Сервис)
│   │   ├── __init__.py
│   │   └── scraper.py      # Логика авторизации и сбора данных
│   │
│   ├── scheduler/        # Модуль для плановых фоновых задач (Сервис)
│   │   ├── __init__.py
│   │   └── tasks.py        # Задачи для APScheduler
│   │
│   └── utils/              # Вспомогательные утилиты
│       ├── __init__.py
│       └── crypto.py       # Функции для шифрования/дешифрования данных
│
├── .env                  # Локальный файл для хранения секретных ключей (не в Git)
├── .gitignore            # Настройки для игнорирования файлов в Git
│
├── LICENSE               # Лицензия проекта
├── README.md             # Файл, который вы сейчас читаете
└── requirements.txt      # Список библиотек для работы проекта

• bot: Слой Представления (View). Отвечает за всё, что видит и с чем взаимодействует пользователь в Telegram.
• database: Слой Модели (Model). Определяет структуру данных и предоставляет интерфейс для работы с ними.
• parser & scheduler: Сервисный слой (Service Layer). Содержит основную бизнес-логику, которая не зависит напрямую от пользователя или БД.
• utils: Вспомогательные модули, используемые разными частями приложения ().
• main_bot.py: Контроллер/Точка входа, который инициализирует и связывает все компоненты вместе.

• Язык: Python 3.12.5
• Асинхронный фреймворк: asyncio
• Telegram Bot API: aiogram 3.x
• База данных: SQLite + SQLAlchemy 2.0 (ORM) + Alembic (миграции)
• Веб-парсинг: Requests + BeautifulSoup4
• Планировщик задач: APScheduler
• Безопасность: cryptography (шифрование учётных данных)

• @f0rgenet - важная помощь с бекендом 🐍🙏
• @oodwyn - тестирование, багрепорты, привнесение фичей ✨

Этот проект распространяется под лицензией MIT. Подробности смотрите в файле LICENSE.