🗓️ Бот-расписание для ВКонтакте

Мой первый проект — бот для ведения расписания и домашних заданий в беседах ВКонтакте.
Код хаотичный, но он работает...

📄 Документация проекта: docs/presentation.pptx | docs/report.docx

---

✨ Возможности

• Расписание — заполнение и просмотр расписания на неделю
• Домашние задания — добавление ДЗ к конкретным урокам (до 3 штук на урок)
• Заметки — общие заметки для всей беседы
• Личный кабинет — у каждого пользователя своё расписание и ДЗ, синхронизированное с чатом
• Кнопки и карусели — удобная навигация через интерактивные элементы

---

🚀 Быстрый старт за 10 минут

Шаг 1. Создать сообщество ВКонтакте

1. Перейти на vk.com/groups → "Создать сообщество"
2. Выбрать тип "Беседа" или "Страница" (подойдёт любой)
3. Назвать сообщество, например: "Бот расписание"

Шаг 2. Получить токен сообщества

Токен — это ключ, который позволяет боту управлять сообществом.

1. Открыть Управление сообществом → Работа с API
2. Нажать "Создать ключ"
3. Отметить галочкой права:
   • ✅ Сообщения сообщества
   • ✅ Доступ к сообщениям
   • ✅ Управление беседой (необходимо для кнопок)
4. Скопировать полученный токен — он понадобится в .env файле

Шаг 3. Узнать ID сообщества

ID находится в адресной строке: vk.com/clubXXXXXXXX — число после club и есть ID.

Шаг 4. Добавить бота в беседу

Важно: Боту необходимо выдать права администратора в беседе. Без этого бот не сможет читать сообщения.

Как выдать права:

• В беседе → "Управление" → "Участники" → найти бота (по названию сообщества) → выдать права администратора

Затем в беседе написать:

создать чат
создать аккаунт

Бот ответит:

✅ Ваш чат зарегистрирован.
✅ Ваш аккаунт зарегистрирован.
Перейти в личные сообщения

После этого бот готов к работе! 🎉

Шаг 5. Заполнить расписание

Только администраторы беседы могут заполнять расписание.

бот уроки понедельник Математика Русский Физика Информатика

После этого бот покажет заполненные уроки.

---

⚙️ Установка для разработчика

Требования

• Python 3.8 или выше
• Библиотеки: vk-api, python-dotenv

Установка

# 1. Клонировать репозиторий
git clone https://github.com/codedarlie/vk-homework-bot.git
cd vk-homework-bot

# 2. Установить зависимости
pip install -r requirements.txt

# 3. Создать файл с секретами
cp .env.example .env

# 4. Отредактировать .env — вставить свои токен и ID
nano .env  # или открыть в любом текстовом редакторе

# 5. Запустить бота
python bot.py

Файл .env.example

# Токен сообщества (получить: Управление → Работа с API)
VK_TOKEN=ваш_токен_здесь

# ID сообщества (число после club в ссылке)
GROUP_ID=198765432

# Личный VK ID разработчика (для отладки)
ADMIN_ID=123456789

⚠️ Важно: Файл .env добавлен в .gitignore — не следует загружать его в репозиторий с токеном!

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

vk-homework-bot/
├── bot.py                 # Основной файл бота
├── config.py              # Загрузка переменных из .env
├── .env                   # Секреты (не в git)
├── .env.example           # Пример .env (в git)
├── .gitignore
├── requirements.txt       # Зависимости (vk-api, python-dotenv)
├── server2.db             # База данных SQLite (создаётся автоматически)
└── docs/
    ├── presentation.pptx  # Презентация проекта
    └── report.docx        # Отчёт по проекту

---

📋 Полный список команд

ℹ️ Важно: Бот реагирует только на сообщения в беседах (групповых чатах). В личных сообщениях работают только кнопки.

👑 Администраторы беседы

Команда	Описание	Пример
создать чат	Зарегистрировать беседу в БД	создать чат
удалить чат	Удалить беседу и все данные	удалить чат
бот уроки <день> <список уроков>	Заполнить расписание (макс. 8 уроков)	бот уроки понедельник Математика Русский Физика
бот заменить урок <день> <номер> <новый урок>	Заменить конкретный урок	бот заменить урок понедельник третий Информатика
расписание	Показать расписание	расписание
все домашнее	Показать всё ДЗ	все домашнее
домашнее на завтра	ДЗ на завтра	домашнее на завтра
домашнее на сегодня	ДЗ на сегодня	домашнее на сегодня
домашнее на послезавтра	ДЗ на послезавтра	домашнее на послезавтра
заметки	Показать все заметки	заметки
бот заметка <текст>	Создать заметку	бот заметка Купить молоко
бот удалить заметку <номер>	Удалить заметку (1-5)	бот удалить заметку 2
удалить дз <номер> <урок>	Удалить ДЗ (1-3 — 1 самое давнее)	удалить дз 1 Математика
удалить все дз <урок>	Удалить урок и всё его ДЗ	удалить все дз Математика
показать код	Показать ID беседы	показать код

👤 Обычные пользователи (в беседе)

Команда	Описание	Пример
создать аккаунт	Зарегистрировать свой профиль	создать аккаунт
удалить аккаунт	Удалить свои данные	удалить аккаунт
дз <урок> <текст>	Добавить ДЗ по уроку	дз Математика №345 стр.12
дз личное <текст>	Добавить личное ДЗ	дз личное Позвонить маме
бот заметка <текст>	Создать заметку	бот заметка Важная встреча

📱 Кнопки (доступны в ЛС после регистрации)

В личных сообщениях бота доступно удобное меню с кнопками:

Кнопка	Что делает
Домашнее	Открывает меню ДЗ (на сегодня/завтра/послезавтра/всё)
На завтра	ДЗ на завтрашний день
Расписание	Показывает расписание на неделю (карусель)
Заметки	Показать личные заметки
Другое → Инфо → Команды	Список команд
Удалить	Удалить аккаунт или личные заметки

---

💡 Примеры диалогов

Пример 1. Первый запуск бота в беседе

Администратор: создать чат
Бот: ✅ Ваш чат зарегистрирован.

Администратор: создать аккаунт
Бот: Создание аккаунта...
Бот: ✅ Ваш аккаунт зарегистрирован.
       Перейти в личные сообщения [кнопка]

Администратор: бот уроки понедельник Математика Русский Физика
Бот: ✅ Заполнены уроки чата в день 'Понедельник' :
       Первый Урок: Математика
       Второй Урок: Русский
       Третий Урок: Физика

Пример 2. Добавление ДЗ

Пользователь: дз Математика параграф 10, №345-348
Бот: [01.12]: Домашнее заполнено в базу чата.
       [01.12]: Добавлено домашнее на урок "Математика":
       параграф 10, №345-348

Пример 3. Просмотр ДЗ

При нажатии кнопки "Домашнее" → "На сегодня" бот пришлёт:

ДОМАШНЕЕ ЧАТА

📘 №1 МАТЕМАТИКА
[01.12] параграф 10, №345-348

📘 №2 РУССКИЙ
[29.11] сочинение про зиму

ДОМАШНЕЕ АККАУНТА

📘 №3 ЛИТЕРАТУРА
[01.12] прочитать 3 главу

---

🐛 Частые проблемы и решения

❌ Бот не отвечает в беседе

Причина: Бот не имеет прав администратора.

Решение: В беседе → Управление → Участники → найти бота → выдать права администратора.

❌ Ошибка: "аккаунт не зарегистрирован"

Причина: Не выполненa привязка VK ID к беседе.

Решение: Написать в беседе: создать аккаунт

❌ Команды не работают в личных сообщениях

Причина: Бот написан только для бесед. В ЛС работают только кнопки после регистрации.

❌ Ошибка: "Ваш чат не зарегистрирован"

Решение: Администратор должен выполнить: создать чат

❌ Ошибка: "Вы не являетесь администратором этого чата"

Решение: Некоторые команды доступны только создателю беседы или пользователям с правами администратора.

❌ Бот пишет: "Не хватает места. Удалите ненужные уроки"

Решение: В базе данных ограничение — максимум 30 уроков на чат и 5 личных уроков. Следует удалить ненужные командой удалить все дз <урок>.

---

🗄️ Структура базы данных

Таблица chat_info — данные беседы

• Расписание на каждый день недели (до 8 уроков)
• До 30 уроков с домашними заданиями (до 3 на урок)
• До 5 общих заметок
• Хранится chat_id — идентификатор беседы

Таблица id_info — данные пользователей

Аналогичная структура, но для каждого пользователя отдельно:

• Расписание (синхронизируется с чатом при регистрации)
• Личные уроки (до 5)
• Личные заметки (до 5)