📚 Telegram Vocabulary Trainer Bot

Учебный Telegram-бот для изучения иностранных слов. Проект демонстрирует навыки проектирования Telegram-ботов, работы с FSM, SQLAlchemy и разделения бизнес-логики от инфраструктуры.

🔹 Проект ориентирован на GitHub-портфолио

---

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

• 👤 Регистрация пользователей (FSM)
• 🧠 Изучение слов в формате теста (множественный выбор)
• ➕ Добавление пользовательских слов
• ❌ Удаление слов из словаря
• 🔁 Алгоритм повторения на основе времени последнего показа
• 📦 Автоматическое наполнение базовым словарём
• 🔘 Inline-клавиатуры (без reply-кнопок)

---

🧩 Что демонстрирует проект

Архитектура

• Разделение ответственности:
  • Telegram-слой — обработчики и FSM
  • Бизнес-логика — сценарии обучения
  • Data layer — SQLAlchemy ORM
• Модульная структура
• Минимальная связанность компонентов

Технические навыки

• Работа с pyTelegramBotAPI
• Использование FSM (Finite State Machine)
• SQLAlchemy ORM + связи + ограничения
• Проектирование many-to-many моделей
• Работа с транзакциями
• Переменные окружения (python-dotenv)
• Генерация тестовых данных (Faker)

---

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

.
├── bot_main.py        # Точка входа, Telegram-хендлеры
├── bot_connect.py     # Инициализация бота и FSM
├── bot_modules.py     # Бизнес-логика бота
├── db_modules.py      # Работа с базой данных
├── models.py          # SQLAlchemy модели
├── config.py          # Конфигурация и подключение к БД
├── base_words.json    # Базовый словарь
├── requirements.txt   # Зависимости проекта
├── db_tables.png      # Схема БД
├── venv/              # Виртуальное окружение Python
└── README.md

---

🛠 Технологии

• Python 3.10+
• pyTelegramBotAPI — Telegram Bot API
• SQLAlchemy — ORM
• PostgreSQL
• Faker — генерация фейковых вариантов
• python-dotenv — переменные окружения

---

⚙️ Установка и запуск

1. Клонирование

git clone https://github.com/your-username/telegram-vocab-bot.git
cd telegram-vocab-bot

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

python -m venv venv

3. Активация виртуального окружения

• Windows:

venv\Scripts\activate

• macOS/Linux:

source venv/bin/activate

4. Установка зависимостей

pip install --upgrade pip
pip install -r requirements.txt

5. Переменные окружения

Создайте .env файл:

BOT_TOKEN=your_telegram_bot_token
DB_DRIVER=postgresql
DB_HOST=localhost
DB_PORT=5432
DB_LOGIN=your_db_login
DB_PASSWORD=your_db_password
DB_TABLE_NAME=vocab_bot

6. Запуск бота

python bot_main.py

Таблицы создаются автоматически при старте.

---

🤖 Команды бота

Команда	Описание
/start	Запуск бота
/help	Справка
/register	Регистрация
/id	Telegram ID
/change_name	Смена имени
/study	Начать обучение

---

🧠 Алгоритм обучения

• Слово выбирается по принципу давно не показывалось
• Один правильный вариант + несколько фейковых
• После показа обновляется last_shown
• Возможность пропуска и управления словарём
• Словари индивидуальны для пользователей

---