Car Selection Bot

Telegram-бот для генерации лидов в сфере подбора автомобилей с многошаговой формой в WebApp интерфейсе.

Обзор проекта

Проект состоит из трех основных компонентов:

• Backend: Django REST API для управления лидами
• Frontend: React TypeScript Telegram WebApp с 9-шаговой формой подбора автомобиля
• Telegram Bot: Aiogram-бот, который запускает WebApp

Технологический стек

Backend

• Django 5.2.7
• Django REST Framework
• Aiogram (Telegram Bot Framework)
• SQLite (разработка) / PostgreSQL (production)

Frontend

• React 19
• TypeScript
• Vite
• Material-UI (MUI)
• React Hook Form + Zod validation
• @tma.js/sdk-react (Telegram WebApp SDK)

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

car-selection-bot/
├── backend/
│   ├── config/              # Настройки Django
│   ├── leads/               # Приложение для управления лидами
│   ├── telegram_bot/        # Aiogram бот
│   ├── .env                 # Переменные окружения Django
│   └── .env.bot             # Переменные окружения бота
├── frontend/
│   ├── src/
│   │   ├── components/      # React компоненты
│   │   ├── i18n/           # Переводы
│   │   └── utils/          # Утилиты
│   └── package.json
└── requirements.txt

Инструкция по установке

Требования

• Python 3.10+
• Node.js 18+
• Токен Telegram бота (получить у @BotFather)

Настройка Backend

1. Создайте и активируйте виртуальное окружение:

cd backend
python -m venv venv

# На Linux/Mac:
source venv/bin/activate

# На Windows:
venv\Scripts\activate

2. Установите зависимости:

pip install -r ../requirements.txt

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

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

SECRET_KEY=your-secret-key-here
DEBUG=True
ALLOWED_HOSTS=localhost,127.0.0.1
CORS_ALLOWED_ORIGINS=http://localhost:3000,http://localhost:5173

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

BOT_TOKEN=your-telegram-bot-token
WEBAPP_URL=http://localhost:5173
ADMIN_CHAT_ID=your-telegram-chat-id
BOT_MODE=polling
API_URL=http://localhost:8000/api/v1

4. Выполните миграции:

python manage.py migrate

5. Создайте суперпользователя (опционально, для админ-панели):

python manage.py createsuperuser

6. Запустите Django сервер:

python manage.py runserver

7. Запустите Telegram бота (в отдельном терминале):

cd backend
source venv/bin/activate
python -m telegram_bot.main

Настройка Frontend

1. Установите зависимости:

cd frontend
npm install

2. Запустите development сервер:

npm run dev

Frontend будет доступен по адресу http://localhost:5173

Production сборка

Frontend:

cd frontend
npm run build
npm run preview

Backend (режим Webhook):

• Установите BOT_MODE=webhook в .env.bot
• Укажите ваш домен в WEBAPP_URL
• Используйте production WSGI сервер (gunicorn, uWSGI)

Функциональность

Многошаговая форма подбора автомобиля

WebApp проводит пользователя через 9 шагов:

1. Марка и модель: Выбор производителя и модели автомобиля
2. Цвет кузова: Выбор предпочтительных цветов экстерьера
3. Цвет салона: Выбор цвета интерьера
4. Опции: Выбор функций (кожаный салон, панорамная крыша и т.д.)
5. Бюджет: Установка диапазона цен ($10,000 - $500,000)
6. Диапазон лет: Выбор года выпуска (2015-2024)
7. Приоритеты: Определение важных факторов (цена, состояние, пробег)
8. Заметки: Дополнительные комментарии или требования
9. Контактная информация: Имя и телефон

Управление лидами

• Уникальные ID: Автогенерируемый формат LD-YYYYMMDD-XXX
• Rate Limiting: 10 заявок в час на пользователя
• Валидация: Комплексная валидация всех полей
• Уведомления админу: Опциональные уведомления в Telegram о новых лидах

API Endpoints

Базовый URL: http://localhost:8000/api/v1

Leads (Лиды)

Создание лида

POST /leads
Content-Type: application/json

{
  "tg_user_id": 123456789,
  "contact_name": "Иван Иванов",
  "contact_phone": "+79001234567",
  "brand": "BMW",
  "model": "X5",
  "colors": ["Черный", "Белый"],
  "interior_color": "Бежевый",
  "options": ["Кожаный салон", "Панорамная крыша"],
  "budget_min": 30000,
  "budget_max": 45000,
  "budget_include": ["Налоги", "Регистрация"],
  "year_min": 2020,
  "year_max": 2024,
  "priority": ["price", "condition"],
  "notes": "Ищу семейный внедорожник",
  "source": "telegram"
}

Список лидов

GET /leads?tg_user_id=123456789&limit=10

Получение конкретного лида

GET /leads/{lead_uid}

Rate limit: 10 запросов в час на X-Telegram-User-Id

Команды для разработки

Backend

# Запуск development сервера
python manage.py runserver

# Создание миграций
python manage.py makemigrations

# Применение миграций
python manage.py migrate

# Создание суперпользователя
python manage.py createsuperuser

# Запуск бота (polling режим)
python -m telegram_bot.main

# Django shell
python manage.py shell

Frontend

# Development сервер
npm run dev

# Production сборка
npm run build

# Предпросмотр production сборки
npm run preview

# Проверка кода
npm run lint

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

Настройки Django

Основные настройки в backend/config/settings.py:

• База данных: SQLite (разработка) или PostgreSQL (production)
• CORS: Настроен для локальной разработки
• Логирование: Консоль + файл
• Middleware: Валидация Telegram WebApp данных

Конфигурация бота

Бот поддерживает два режима (устанавливается в .env.bot):

• Polling: Для разработки (по умолчанию)
• Webhook: Для production развертывания

Rate Limiting

Использует django-ratelimit с заголовком X-Telegram-User-Id:

• Создание лида: 10 запросов/час на пользователя

Поддержка переводов

Frontend включает поддержку i18n с русскими переводами. Добавить больше языков можно в:

• frontend/src/i18n/translations.ts
• Используйте хук useTranslation() в компонентах

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

Коллекция для тестирования API доступна по адресу:

backend/Leads_API.postman_collection.json

Импортируйте в Postman для тестирования API endpoints.

Известные проблемы

1. Отсутствующие зависимости в requirements.txt:

   • python-decouple
   • django-ratelimit
   • aiogram
   • python-dotenv

2. Не настроен автоматизированный набор тестов

3. Генерация Lead UID имеет потенциальные race conditions при высокой нагрузке

4. Frontend имеет захардкоженные тестовые значения для разработки вне Telegram

Схема базы данных

Модель Lead

Поле	Тип	Описание
lead_uid	CharField	Уникальный ID (LD-YYYYMMDD-XXX)
tg_user_id	BigIntegerField	Telegram user ID
contact_name	CharField	Имя пользователя
contact_phone	CharField	Номер телефона
brand	CharField	Марка автомобиля
model	CharField	Модель автомобиля
colors	JSONField	Предпочитаемые цвета (массив)
interior_color	CharField	Цвет интерьера
options	JSONField	Выбранные опции (массив)
budget_min	IntegerField	Минимальный бюджет
budget_max	IntegerField	Максимальный бюджет
budget_include	JSONField	Что включает бюджет (массив)
year_min	IntegerField	Минимальный год
year_max	IntegerField	Максимальный год
priority	JSONField	Факторы приоритета (массив)
notes	TextField	Дополнительные заметки
source	CharField	Источник лида
created_at	DateTimeField	Время создания
updated_at	DateTimeField	Время последнего обновления

Админ-панель

Доступ к Django админке: http://localhost:8000/admin после создания суперпользователя.

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

• Просмотр и управление лидами
• Фильтрация по дате, пользователю, источнику
• Поиск по имени, телефону, марке, модели

Рекомендации для production

Для production развертывания:

1. Установите DEBUG=False в настройках Django
2. Используйте PostgreSQL вместо SQLite
3. Настройте правильные ALLOWED_HOSTS и CORS
4. Установите BOT_MODE=webhook для бота
5. Используйте HTTPS для WEBAPP_URL
6. Настройте логирование и мониторинг
7. Используйте переменные окружения для чувствительных данных
8. Разверните с gunicorn/uWSGI + Nginx
9. Включите connection pooling для базы данных
10. Настройте регулярные бэкапы базы данных

Архитектура системы

Поток работы бота

1. Бот отправляет кнопку WebApp через inline клавиатуру (telegram_bot/keyboards/inline.py)
2. Пользователь открывает React WebApp в Telegram
3. Пользователь заполняет 9-шаговую форму с валидацией
4. Frontend отправляет данные на Django API endpoint /api/v1/leads (POST)
5. Бот может уведомить администратора через callback handlers

Архитектура модели Lead

• Генерация уникального ID: Автогенерируемый формат LD-YYYYMMDD-XXX (см. leads/models.py:generate_lead_uid)
• JSON поля: Использует JSONField вместо ArrayField для совместимости SQLite/PostgreSQL
• Массивы: options, priority, budget_include хранятся как JSON массивы
• Валидация: Кастомные валидаторы для бюджета ($10k-$500k), годов (2015-2024), длины строк
• Индексирование: Композитный индекс на tg_user_id + created_at, плюс индивидуальные индексы

Интеграция с Telegram WebApp

• Frontend использует обертку utils/telegram.ts вокруг Telegram WebApp SDK
• Backend валидирует Telegram init data через middleware
• Навигация использует нативную кнопку "Назад" Telegram
• При отправке формы показывается индикатор прогресса Telegram

Структура файлов конфигурации

Backend Environment файлы

• backend/.env: Конфигурация Django (SECRET_KEY, DEBUG, ALLOWED_HOSTS, CORS, токен бота)
• backend/.env.bot: Конфигурация бота, загружается через telegram_bot/config.py
  • BOT_TOKEN: Токен Telegram бота
  • WEBAPP_URL: URL где размещено React приложение
  • ADMIN_CHAT_ID: Telegram chat ID для уведомлений администратора
  • BOT_MODE: 'polling' или 'webhook'
  • API_URL: Базовый URL Backend API (по умолчанию: http://localhost:8000/api/v1)

Лицензия

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Поддержка

Для вопросов и проблем создавайте issue в репозитории.