ККЭПик — Telegram-бот и веб-приложение для учащихся и преподавателей

Краснодарского колледжа электронного приборостроения

---

Возможности

• Рассылка расписания — автоматически при загрузке нового файла (PDF или XLSX)
• Изменения — отправляет только тем, у кого расписание поменялось
• Суббота — в субботнем расписании указывается время каждой пары
• MAX messenger — мониторит групповой чат, скачивает файл и запускает рассылку автоматически
• Inline-режим — поиск расписания прямо из строки ввода Telegram (@bot_name 103-Д9)
• FastAPI — REST API для веб-приложения и мобильного клиента
• Превью-картинка — генерация изображения расписания (включается в config.py)

---

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

KKEP/
├── bot/                     — Telegram-бот + FastAPI
│   ├── main.py              — точка входа
│   ├── config.py            — конфигурация (читает .env)
│   ├── api.py               — FastAPI эндпоинты
│   ├── global_schedules.py  — in-memory кэш расписаний
│   ├── commands/            — обработчики команд (/start, /find, /reset ...)
│   ├── handlers/            — загрузка файлов, inline, рассылка
│   ├── schedules/           — парсеры PDF/XLSX
│   ├── max_bot/             — интеграция с MAX messenger
│   ├── scripts/             — утилиты администратора
│   ├── fonts/               — шрифты для генерации картинок
│   ├── .env.example         — шаблон переменных окружения
│   └── requirements.txt
└── web/                     — веб-приложение (Flask)

---

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

1. Клонировать репозиторий

git clone https://github.com/ВАШ_НИК/kkepik-bot.git
cd kkepik-bot/bot

2. Установить зависимости

pip install -r requirements.txt

или на Windows:

install.bat

3. Создать .env

cp .env.example .env

Заполнить значения в .env:

BOT_TOKEN=токен_продакшн_бота
TEST_BOT_TOKEN=токен_тестового_бота
TEST_MODE=false

ADMINS=123456789,987654321

MAX_WATCH_CHAT_IDS=-1234567890123

4. Запустить

python main.py

---

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

Переменная	Описание
BOT_TOKEN	Токен основного Telegram-бота
TEST_BOT_TOKEN	Токен тестового бота
TEST_MODE	true — тестовый бот + отдельная БД
ADMINS	Telegram user_id администраторов через запятую
MAX_WATCH_CHAT_IDS	ID чатов MAX для мониторинга через запятую

---

Команды бота

Команда	Описание
/start	Регистрация и показ актуального расписания
/find <группа/ФИО> [дата]	Поиск расписания
/reset	Сброс регистрации
/app	Ссылка на веб-приложение
/broadcast	Рассылка студентам (только администраторы)
/broadcast_teachers	Рассылка преподавателям (только администраторы)

Загрузка расписания

Отправьте боту файл .pdf или .xlsx. Имя файла должно содержать:

• дату: 25.02.2026 или 25_02_2026
• тип: ГРУППЫ или ПРЕПОДАВАТЕЛИ

Расписание на 25.02.2026_ГРУППЫ.pdf
25.02.2026 ПРЕПОДАВАТЕЛИ.xlsx

---

MAX messenger

Бот подключается к MAX через pyromax и мониторит указанные чаты. При обнаружении PDF/XLSX с расписанием — скачивает файл и автоматически запускает рассылку в Telegram.

Авторизация выполняется один раз через QR-код. Токен сохраняется в tokens.json.

---

FastAPI — эндпоинты

Сервер запускается на порту 8000 (или 8080 в TEST_MODE).

Метод	Путь	Описание
POST	/schedule/group	Расписание группы
POST	/schedule/teacher	Расписание преподавателя
POST	/schedule/audience	Расписание аудитории
GET	/schedule/download/{type}/{date}	Скачать файл (.xlsx/.pdf)
GET	/groups	Список всех групп
GET	/teachers	Список всех преподавателей
POST	/getUserSchedule/{user_id}	Расписание пользователя по Telegram ID

---

Парсеры расписания

schedules/
├── pdf_to_df.py           ← PDF → DataFrame (посимвольный алгоритм, sg1/sg2)
├── group_schedule.py      ← расписание группы
├── teacher_schedule.py    ← расписание преподавателя
├── audience_schedule.py   ← расписание аудитории
├── parser_all.py          ← списки всех групп / преподавателей
├── schedule_comparator.py ← сравнение: кому изменилось расписание
├── schedule_image.py      ← генерация картинки расписания
├── schedule_mood.py       ← оценка сложности дня (эмодзи)
└── pair_times.py          ← время звонков (будни / суббота)

Структура DataFrame (PDF, 18 колонок)

Колонки	Содержимое
0	Номер пары (ffill)
2, 6, 10, 14	Дисциплина подгруппы 1
3, 7, 11, 15	Аудитория подгруппы 1
4, 8, 12, 16	Дисциплина подгруппы 2
5, 9, 13, 17	Аудитория подгруппы 2

Расписание звонков

Пара	Будни	Суббота
1	8:45–10:05	8:45–10:00
2	10:25–11:45	10:10–11:25
3	12:05–13:25	11:35–12:50
4	13:35–14:55	13:00–14:15

---

База данных

SQLite, таблица users:

Поле	Тип	Описание
user_id	INTEGER	Telegram ID
role	TEXT	Я студент / Я преподаватель
name_or_group	TEXT	Номер группы или ФИО
is_class_teacher	INTEGER	Классный руководитель (0/1)
class_group	TEXT	Группа под руководством

---

Скрипты администратора

Файл	Назначение
scripts/database_statistics.py	Статистика БД
scripts/promote_students.py	Перевод студентов на следующий курс
scripts/promote_class_groups_and_delete_4th.py	Перевод + удаление выпускников
scripts/delete_4th_course_students.py	Удаление студентов 4-го курса
scripts/migrate_db.py	Миграция базы данных

---

Перезапуск

taskkill /F /IM python.exe   # Windows: остановить все процессы python
python main.py               # запустить снова