tg_bot_language/README.md

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

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

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

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

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

**Реализовано:**
- ✅ `/start` - регистрация и приветствие пользователя
- ✅ `/add [слово]` - добавление слов в словарь с AI-переводом, транскрипцией и примерами
- ✅ `/vocabulary` - просмотр личного словаря (последние 10 слов)
- ✅ `/task` - интерактивные задания на перевод слов (EN→RU и RU→EN)
- ✅ `/stats` - детальная статистика обучения
- ✅ `/help` - справка по командам
- ✅ Проверка ответов через AI с детальной обратной связью
- ✅ Отслеживание прогресса по каждому слову
- ✅ База данных (PostgreSQL) для хранения данных
- ✅ Docker-развёртывание (полное и только БД)

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

### 🐳 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 алгоритм

## Cloudflare AI Gateway (опционально)

Бот поддерживает использование [Cloudflare AI Gateway](https://developers.cloudflare.com/ai-gateway/) для:

- 🚀 **Кэширование запросов** - экономия до 99% на повторных запросах
- 📊 **Аналитика** - детальная статистика использования AI
- 💰 **Контроль расходов** - мониторинг стоимости запросов
- 🛡️ **Безопасность** - защита API ключей и rate limiting

**Настройка:**

1. Создайте Gateway на [dash.cloudflare.com](https://dash.cloudflare.com/) → AI → AI Gateway
2. Добавьте в `.env`:
```env
CLOUDFLARE_ACCOUNT_ID=ваш_account_id
CLOUDFLARE_GATEWAY_ID=gpt
```

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

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

- **Python 3.11+**
- **aiogram 3.x** - Telegram Bot framework
- **SQLAlchemy 2.x** - ORM для работы с БД
- **PostgreSQL** - База данных
- **OpenAI API** - AI для перевода и проверки
- **Cloudflare AI Gateway** - кэширование и мониторинг AI запросов (опционально)

## Лицензия

MIT