Диалоговая система персонализированных рекомендаций мест отдыха

Система для персонализированных рекомендаций мест отдыха и развлечений с поддержкой UGC, рейтинговой системой и интеграцией LLM.

🎯 Основные возможности

• Диалог с LLM для естественного поиска мест
• Персонализированные рекомендации на основе предпочтений
• UGC: отзывы, рейтинги, фото
• Автоматический парсинг внешних источников
• Система модерации контента
• Векторный поиск по описаниям и отзывам
• Геопоиск по координатам

🏗️ Архитектура

• Frontend: Next.js 14 (React, TypeScript, Tailwind CSS)
• Backend: FastAPI (Python 3.11+)
• База данных: PostgreSQL 16 + pgvector
• Кэш/Очереди: Redis 7, Celery + Beat
• LLM: Google Gemini API / OpenAI API
• Парсинг: Playwright, BeautifulSoup, Telethon

📋 Требования

• Docker и Docker Compose
• (Опционально) Python 3.11+ и Node.js 18+ для локальной разработки

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

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

git clone https://github.com/eugenesuv/Python-project.git

2. Настройка переменных окружения

Создайте файл .env в корне проекта:

# Windows
copy .env.example

# Linux/Mac
cp .env.example

Отредактируйте .env и заполните необходимые ключи:

# Обязательно измените!
SECRET_KEY=your-secret-key-here-minimum-32-characters

# LLM - выберите один из провайдеров
# Gemini (рекомендуется, бесплатный) - https://makersuite.google.com/app/apikey
GEMINI_API_KEY=your-gemini-api-key
GEMINI_MODEL=gemini-1.5-flash
LLM_PROVIDER=gemini

# Или OpenAI - https://platform.openai.com/api-keys
# OPENAI_API_KEY=your-openai-api-key
# OPENAI_MODEL=gpt-4o-mini
# LLM_PROVIDER=openai

# Telegram (опционально, для парсинга каналов) - https://my.telegram.org
TELEGRAM_API_ID=
TELEGRAM_API_HASH=

3. Запуск через Docker Compose

docker-compose up -d

Подождите 1-2 минуты, пока все контейнеры запустятся.

4. Применение миграций БД

docker-compose exec backend alembic upgrade head

5. Создание расширения pgvector

docker-compose exec postgres psql -U postgres -d recommendations_db -c "CREATE EXTENSION IF NOT EXISTS vector;"

6. Добавление тестовых данных (опционально)

Для быстрого старта можно добавить 5 тестовых мест:

docker-compose exec backend python scripts/add_test_data.py

7. Парсинг мест из внешних источников

Для заполнения базы данных реальными местами запустите парсинг:

docker-compose exec backend python parse_places.py

Этот скрипт:

• Парсит места из KudaGo API, Яндекс.Карт и других источников
• Добавляет места в базу данных
• Автоматически проверяет дубликаты
• Нормализует данные

Примечание: Парсинг может занять несколько минут. Рекомендуется запускать после первого запуска проекта.

8. Создание администратора

docker-compose exec backend python scripts/create_admin.py

Следуйте инструкциям для создания первого администратора.

9. Открытие приложения

• Frontend: http://localhost:3000
• Backend API: http://localhost:8000
• API Документация (Swagger): http://localhost:8000/docs

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

Поиск мест

1. Откройте http://localhost:3000/places
2. Используйте фильтры: категории, ценовой диапазон, рейтинг
3. Или используйте чат для естественного поиска

Чат с помощником

1. На главной странице введите запрос, например:

   • "Хочу бар с джазом в субботу"
   • "Найди рестораны итальянской кухни"
   • "Где можно недорого поесть?"

2. Система найдет подходящие места и даст рекомендации

Регистрация и отзывы

1. Зарегистрируйтесь на http://localhost:3000/signup
2. Войдите в систему
3. Откройте любое место
4. Оставьте отзыв с рейтингом

Модерация (для модераторов/админов)

1. Войдите как модератор или администратор
2. Откройте http://localhost:3000/moderation
3. Просматривайте и обрабатывайте очередь модерации

🛠️ Разработка

Локальная разработка (без Docker)

Backend

cd backend
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt
uvicorn main:app --reload

Frontend

cd frontend
npm install
npm run dev

Запуск тестов

cd backend
pytest tests/ -v

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

.
├── backend/              # FastAPI приложение
│   ├── app/
│   │   ├── api/         # API эндпоинты
│   │   ├── models/      # SQLAlchemy модели
│   │   ├── schemas/     # Pydantic схемы
│   │   ├── services/    # Бизнес-логика
│   │   └── core/        # Конфигурация, безопасность
│   ├── tasks/           # Celery задачи
│   ├── scripts/         # Утилиты и скрипты
│   ├── tests/           # Тесты
│   └── alembic/         # Миграции БД
├── frontend/            # Next.js приложение
│   ├── app/             # App Router
│   ├── components/       # React компоненты
│   └── lib/             # Утилиты
├── docs/                # Документация
├── docker-compose.yml   # Docker конфигурация
└── README.md

🔧 Конфигурация

Основные настройки в файле .env:

• SECRET_KEY - секретный ключ для JWT (обязательно измените!)
• GEMINI_API_KEY или OPENAI_API_KEY - ключ для LLM
• TELEGRAM_API_ID и TELEGRAM_API_HASH - для парсинга Telegram (опционально)
• DATABASE_URL - строка подключения к БД
• REDIS_URL - строка подключения к Redis

📚 API Документация

После запуска доступна интерактивная документация:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

🧪 Тестирование

Проект включает комплексные тесты:

• Unit-тесты для сервисов
• Integration-тесты для API
• Security-тесты
• Performance-тесты

Запуск всех тестов:

cd backend
pytest tests/ -v --cov=app

🐛 Решение проблем

Контейнеры не запускаются

docker-compose logs
docker-compose ps

База данных не подключается

docker-compose exec postgres psql -U postgres -d recommendations_db -c "SELECT 1;"

Парсинг не работает

• Проверьте интернет-соединение
• Убедитесь, что внешние источники доступны
• Проверьте логи: docker-compose logs celery_worker

📝 Лицензия

MIT