📔 Journal Bot

Telegram бот для студентов ПИ ДГТУ с доступом к электронному журналу успеваемости

Warning

🚧 Проект находится в активной разработке

Бот пока не доступен для публичного использования. Следите за обновлениями!

📖 О проекте

Journal Bot — это Telegram бот для студентов Политеха, который предоставляет удобный доступ к электронному журналу успеваемости edu-tpi.donstu.ru прямо в мессенджере. Проект построен на современном асинхронном стеке технологий с использованием профессиональной архитектуры для обеспечения безопасности, производительности и масштабируемости.

🎯 Основные возможности

• 📊 Просмотр оценок - получайте актуальную информацию об оценках по всем дисциплинам
• 🔔 Уведомления - автоматические алерты о появлении новых оценок в электронном журнале
• 📈 Статистика - анализ успеваемости: средний балл, динамика по предметам, посещаемость
• 📅 Фильтрация - просмотр оценок за выбранный период или по конкретной дисциплине
• 📄 Экспорт данных - выгрузка таблиц с оценками в Excel для дальнейшего анализа
• 🔐 Безопасность - шифрование учетных данных edu-tpi в защищенной базе PostgreSQL
• 🔄 Авто-синхронизация - регулярное обновление данных из электронного журнала

🔧 Фишки

• 🔐 Безопасность - все данные хранятся в защищенной базе данных PostgreSQL
• 🎨 Админ-панель - удобный веб-интерфейс на Flask-Admin для управления
• 📊 Аналитика - интеграция с Amplitude, PostHog или Google Analytics
• 📈 Мониторинг - Prometheus + Grafana для отслеживания производительности
• 🐛 Отслеживание ошибок - интеграция с Sentry
• 🌍 Интернационализация - поддержка нескольких языков

👥 Для кого этот бот

Journal Bot создан для студентов ПИ ДГТУ, которые хотят:

• Быстро проверять оценки без входа в веб-версию журнала
• Получать мгновенные уведомления о новых оценках
• Отслеживать свою академическую успеваемость
• Экспортировать данные для личного анализа

🔒 Безопасность и конфиденциальность

• Все учетные данные от edu-tpi шифруются с использованием Fernet (симметричное шифрование)
• Пароли хранятся в зашифрованном виде в защищенной базе данных PostgreSQL
• Ключи шифрования хранятся отдельно в переменных окружения
• Регулярное обновление зависимостей для устранения уязвимостей
• Rate limiting для защиты от злоупотреблений

📋 Требования

• Python 3.10 или выше
• PostgreSQL 15+
• Redis 7+
• Аккаунт в системе edu-tpi.donstu.ru
• Telegram Bot Token (получить у @BotFather)

🎮 Основные команды бота

• /start - Начать работу с ботом
• /login - Авторизация в системе edu-tpi
• /grades - Показать все оценки за текущий семестр
• /stats - Статистика успеваемости и посещаемости
• /sync - Принудительная синхронизация с журналом
• /settings - Настройки уведомлений и параметров
• /logout - Выход из системы

🚧 Дорожная карта

• Базовая авторизация и синхронизация с edu-tpi
• Просмотр оценок и фильтрация по предметам
• Система уведомлений о новых оценках
• Статистика и аналитика успеваемости
• Экспорт данных в Excel/PDF
• Графики динамики успеваемости
• Напоминания о предстоящих экзаменах
• Интеграция с расписанием занятий
• Поддержка других вузов

⚠️ Дисклеймер

Этот бот является неофициальным инструментом и не связан с официальной системой edu-tpi.donstu.ru или администрацией ДГТУ. Используйте на свой страх и риск. Разработчики не несут ответственности за сохранность учетных данных и точность отображаемой информации.

🚀 Быстрый старт

С использованием Docker (рекомендуется)

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

git clone https://github.com/goxa2020/journal_bot.git
cd journal_bot

2. Создайте .env файл на основе .env.example:

cp .env.example .env

3. Настройте переменные окружения в .env файле (как минимум BOT_TOKEN, настройки БД и Redis)

4. Запустите сервисы:

docker compose up -d --build

Локальный запуск (может не работать на windows)

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

uv sync --frozen --all-groups

2. Запустите необходимые сервисы (PostgreSQL и Redis)

3. Настройте .env файл

4. Примените миграции:

uv run alembic upgrade head

5. Запустите бота:

uv run python -m bot

6. Запустите админ-панель (опционально):

uv run gunicorn -c admin/gunicorn_conf.py

🔧 Технологический стек

Backend

• Python 3.10+ - основной язык разработки
• aiogram - асинхронный фреймворк для Telegram Bot API
• SQLAlchemy 2.0 - ORM для работы с базой данных
• Alembic - система миграций базы данных
• Pydantic V2 - валидация данных

Databases & Cache

• PostgreSQL - основная база данных
• Redis - кеширование и FSM
• PGBouncer - connection pooling для PostgreSQL

DevOps

• Docker & Docker Compose - контейнеризация
• uv - современный менеджер пакетов Python
• GitHub Actions - CI pipeline
• pre-commit - git hooks для качества кода

Monitoring & Analytics

• Prometheus - сбор метрик
• Grafana - визуализация метрик
• Sentry - отслеживание ошибок
• Amplitude/PostHog - продуктовая аналитика

Admin Panel

• Flask-Admin - административный интерфейс
• AdminLTE - UI для админ-панели
• Gunicorn - WSGI сервер

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

journal_bot/
├── bot/                # Основной код бота
│   ├── handlers/         # Обработчики команд и событий
│   ├── keyboards/        # Клавиатуры (inline и reply)
│   ├── database/         # Модели и работа с БД
│   ├── middlewares/      # Промежуточные обработчики
│   ├── services/         # Бизнес-логика
│   ├── locales/          # Файлы локализации
│   └── core/             # Настройки и конфигурация
├── admin/              # Админ-панель
├── migrations/         # Миграции Alembic
├── configs/            # Конфигурации для мониторинга
├── scripts/            # Вспомогательные скрипты
├── docker-compose.yml  # Docker Compose конфигурация
├── Dockerfile          # Dockerfile для бота
├── Makefile            # Make команды
└── pyproject.toml      # Зависимости и настройки проекта

⚙️ Конфигурация

Основные переменные окружения в .env:

Переменная	Описание
BOT_TOKEN	Токен Telegram бота
DB_HOST, DB_PORT, DB_USER, DB_PASS, DB_NAME	Настройки PostgreSQL
REDIS_HOST, REDIS_PORT, REDIS_PASS	Настройки Redis
ADMIN_HOST, ADMIN_PORT	Настройки админ-панели
SENTRY_DSN	DSN для Sentry (опционально)
AMPLITUDE_API_KEY	API ключ Amplitude (опционально)

Полный список переменных смотрите в файле .env.example

🛠️ Разработка

Установка pre-commit hooks

uv run pre-commit install

Создание новой миграции

uv run alembic revision --autogenerate -m "описание изменений"

Применение миграций

uv run alembic upgrade head

Make команды

make help           \# Показать все доступные команды
make lint           \# Запустить линтеры
make format         \# Форматировать код
make migrate        \# Применить миграции

📊 Мониторинг

После запуска через Docker Compose доступны:

• Grafana: http://localhost:3000
• Prometheus: http://localhost:9090
• Админ-панель: http://localhost:8000

🤝 Вклад в проект

Буду рад вашему вкладу! Если у вас есть предложения по улучшению:

1. Сделайте Fork репозитория
2. Создайте ветку для новой функции (git checkout -b feature/amazing-feature)
3. Зафиксируйте изменения (git commit -m 'Add amazing feature')
4. Отправьте в ветку (git push origin feature/amazing-feature)
5. Откройте Pull Request

📝 Лицензия

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

📬 Контакты

Автор: goxa2020

---

Сделано с ❤️ для вашего удобства