tg_bot_language/README.md

# Telegram Бот для изучения языков

Интеллектуальный Telegram бот для изучения английского языка с использованием AI.

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

- 📚 Управление словарным запасом с автоматическим переводом через AI
- ✍️ Ежедневные задания для практики (в разработке)
- 💬 Диалоговая практика с ИИ (в разработке)
- 📊 Статистика прогресса (в разработке)

## Текущая версия (MVP)

**Реализовано:**
- ✅ Команда `/start` - приветствие и регистрация пользователя
- ✅ Команда `/add [слово]` - добавление слов в словарь с AI-переводом
- ✅ Команда `/vocabulary` - просмотр словаря
- ✅ Команда `/help` - справка
- ✅ База данных (PostgreSQL) для хранения пользователей и словарей
- ✅ Интеграция с OpenAI API для перевода слов

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

### 🐳 Docker Compose (рекомендуется)

```bash
# Клонировать репозиторий
git clone http://103.137.249.134:3000/NANDI/tg_bot_language.git
cd tg_bot_language

# Настроить .env
cp .env.example .env
# Отредактируйте .env и добавьте BOT_TOKEN и OPENAI_API_KEY

# Запустить
docker-compose up -d

# Проверить логи
docker-compose logs -f bot
```

📖 Подробная инструкция: [README_DOCKER.md](README_DOCKER.md)

---

### Локальная установка

#### Автоматическая установка (рекомендуется)

```bash
# Клонировать репозиторий
git clone http://103.137.249.134:3000/NANDI/tg_bot_language.git
cd tg_bot_language

# Запустить скрипт установки
./setup.sh

# Отредактировать .env и добавить токены
nano .env

# Активировать виртуальное окружение
source .venv/bin/activate

# Запустить бота
python main.py
```

#### Использование Makefile

```bash
# Установить всё
make install

# Запустить бота
make run

# Показать все команды
make help
```

#### Ручная установка

**1. Клонирование репозитория**

```bash
git clone http://103.137.249.134:3000/NANDI/tg_bot_language.git
cd tg_bot_language
```

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

```bash
python3 -m venv .venv
source .venv/bin/activate
```

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

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

**4. Настройка окружения**

```bash
cp .env.example .env
nano .env  # или любой редактор
```

Заполните необходимые параметры:

```env
BOT_TOKEN=your_telegram_bot_token_here
OPENAI_API_KEY=your_openai_api_key_here
DATABASE_URL=postgresql+asyncpg://botuser:botpassword@localhost:5432/language_bot
DEBUG=True
```

**Получение токенов:**
- Telegram Bot Token: создайте бота через [@BotFather](https://t.me/BotFather)
- OpenAI API Key: получите на [platform.openai.com](https://platform.openai.com/api-keys)

**5. Настройка базы данных**

Запустите PostgreSQL через Docker (рекомендуется):

```bash
# Через Makefile (рекомендуется)
make docker-db

# Или напрямую через docker-compose
docker-compose up -d db

# Или через отдельный dev-compose
docker-compose -f docker-compose.dev.yml up -d
```

Параметры подключения:
- Host: `localhost`
- Port: `15433` (не конфликтует с другими PostgreSQL)
- User: `botuser`
- Password: `botpassword`
- Database: `language_bot`
- URL: `postgresql+asyncpg://botuser:botpassword@localhost:15433/language_bot`

Или установите PostgreSQL локально:

```bash
# macOS
brew install postgresql
createdb language_bot

# Linux
sudo apt install postgresql
sudo -u postgres createdb language_bot
```

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

```bash
# Активировать venv
source .venv/bin/activate

# Запустить
python main.py

# Или через Makefile
make run
```

**Остановка БД:**

```bash
make docker-db-stop
# или
docker-compose stop db
```

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

```
bot_tg_language/
├── bot/
│   ├── handlers/          # Обработчики команд
│   │   ├── start.py       # /start, /help
│   │   └── vocabulary.py  # /add, /vocabulary
│   └── keyboards/         # Клавиатуры (пока не используется)
├── database/
│   ├── models.py          # Модели БД (User, Vocabulary, Task)
│   └── db.py              # Подключение к БД
├── services/
│   ├── ai_service.py      # Сервис для работы с OpenAI
│   ├── user_service.py    # Сервис пользователей
│   └── vocabulary_service.py  # Сервис словаря
├── config/
│   └── settings.py        # Настройки приложения
├── main.py                # Точка входа
├── requirements.txt       # Зависимости
├── .env.example          # Пример конфигурации
└── TZ.md                 # Техническое задание
```

## Использование

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

- `/start` - Начать работу с ботом
- `/add [слово]` - Добавить слово в словарь
- `/vocabulary` - Посмотреть свой словарь
- `/help` - Показать справку

### Пример использования

1. Запустите бота: `/start`
2. Добавьте слово: `/add elephant`
3. Бот переведёт слово через AI и предложит добавить в словарь
4. Подтвердите добавление
5. Просмотрите словарь: `/vocabulary`

## Roadmap

См. [TZ.md](TZ.md) для полного технического задания.

**Следующие этапы:**
- [ ] Ежедневные задания с разными типами упражнений
- [ ] Тематические подборки слов
- [ ] Импорт слов из текста
- [ ] Диалоговая практика с AI
- [ ] Статистика и прогресс
- [ ] Spaced repetition алгоритм

## Технологии

- **Python 3.11+**
- **aiogram 3.x** - Telegram Bot framework
- **SQLAlchemy 2.x** - ORM для работы с БД
- **PostgreSQL** - База данных
- **OpenAI API** - AI для перевода и проверки

## Лицензия

MIT