TutorSlot Bot

Телеграм-бот для записи учеников на занятия и управления расписанием; Реализован на Python 3.11 + aiogram 3 + SQLAlchemy + APScheduler с интеграцией Google Calendar

Последние исправления

Исправлены критические проблемы:

• Отмена занятия теперь правильно удаляет событие из Google Calendar
• Изменения времени/даты синхронизируются с календарем
• Изменения контакта отменяют старое приглашение и отправляют новое
• Напоминания приходят точно за 24 часа и 1 час до занятия
• Интеграция с Google Calendar полностью реализована
• События теперь обновляются при изменении имени ученика
• События теперь пересоздаются при любых изменениях, что гарантирует обновление в календаре у всех участников

Запуск проекта

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

   git clone https://github.com/danlikendy/tutorslot_bot_tg_project.git
   cd tutorslot_bot_tg_project

2. Создаём окружение и ставим зависимости:

   python -m venv .venv
   source .venv/bin/activate
   pip install --upgrade pip
   pip install -r requirements.txt

3. Настраиваем переменные окружения в файле .env:

   BOT_TOKEN=ваш_токен_бота
   TZ=Europe/Moscow
   ADMINS=ваши_telegram_id_пользователей
   
   # Google Calendar (обязательно для полной функциональности)
   GOOGLE_CALENDAR_ENABLED=true
   GOOGLE_CALENDAR_ID=primary
   GOOGLE_CREDENTIALS_JSON_PATH=./integrations/credentials.json
   GOOGLE_OAUTH_TOKEN_PATH=./integrations/token.json
   
   # Настройки напоминаний
   REMINDERS_ENABLED=true
   REMIND_OFFSETS_MINUTES=1440,60

4. Настраиваем интеграцию Google Calendar:

   • Скачайте credentials.json из Google Cloud Console;
   • Запустите один раз:

     python -m app.integrations.google_oauth_setup

   • В результате появится token.json.

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

   .venv/bin/python -m app.main

Тестирование

После настройки протестируйте основные функции:

# Проверка прав доступа к Google Calendar (ВАЖНО!)
python scripts/check_permissions.py

# Тест принудительного обновления
python scripts/test_force_update.py

# Тест изменения времени событий
python scripts/test_time_change.py

Проверка прав доступа

Если возникают проблемы с обновлением событий в Google Calendar:

# 1. Проверка прав доступа (ОБЯЗАТЕЛЬНО!)
python scripts/check_permissions.py

# 2. Пересоздание токена (если нужно)
python -m app.integrations.google_oauth_setup

# 3. Повторная проверка прав
python scripts/check_permissions.py

# 4. Тестирование принудительного обновления
python scripts/test_force_update.py

Важно: Если check_permissions.py показывает "UNKNOWN" права, это означает что у бота недостаточно прав для просмотра информации о календаре, но он может создавать события. В этом случае используется тестовое создание события для проверки прав.

Основные команды

Для пользователей

• /start — начать запись (выбор даты и времени);
• /my — показать мои записи;
• /courses — информация и материалы по курсам.

Для администраторов

• /admin — панель управления всеми записями:
  • Просмотр всех слотов;
  • Кнопки Изменить и Отменить для каждой записи.

Временно отключено

• /weekly, /weekly_list, /weekly_del — функционал еженедельных записей (закомментирован).

Права доступа

• Пользователь:
  • Может создавать и просматривать только свои записи;
  • Может отменять только свои записи.
• Админ:
  • Видит все записи;
  • Может изменять/удалять любые записи;
  • Может создавать записи от имени любого пользователя.

Технологии

• aiogram 3 — обработка команд и сообщений;
• SQLAlchemy (async) — работа с базой данных (SQLite);
• APScheduler — напоминания о занятиях;
• Google Calendar API — интеграция календаря (полностью реализована).

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

app/
 ├── bot/handlers/      # обработчики команд
 ├── bot/keyboards/     # клавиатуры
 ├── integrations/      # интеграция с Google API
 ├── scheduler/         # задачи APScheduler
 ├── services/          # бизнес-логика
 ├── storage/           # база данных и модели
 ├── utils/             # утилиты
 └── main.py            # точка входа

scripts/                 # скрипты тестирования

Что нового

• Полная интеграция с Google Calendar - события создаются, обновляются и удаляются автоматически
• Умные напоминания - приходят точно в нужное время
• Синхронизация изменений - все изменения в боте отражаются в календаре
• Улучшенное логирование - подробная информация об операциях и ошибках
• Обработка ошибок - бот продолжает работать даже при проблемах с API
• События корректно обновляются при изменении имени ученика
• Улучшенные настройки событий с цветами и описаниями
• Подробное логирование всех операций обновления
• События теперь пересоздаются при любых изменениях, что гарантирует обновление в календаре у всех участников
• Решена проблема когда изменения не отражались в календаре у организатора и ученика
• Решена проблема дублирования событий - старое событие полностью удаляется, новое создается с правильным временем