sno-quiz/DEVELOPMENT.md

🚀 Разработка и тестирование всей системы

📋 Что запускаем:

1. Backend (Go) - API сервер на порту 8080
2. Frontend (React) - Веб-приложение на порту 5173
3. Bot (Python) - Telegram бот

🔧 Предварительные настройки

1. Backend

cd backend
cp .env.example .env
# Настройте .env:
# - DATABASE_URL=postgres://user:password@localhost:5432/quiz_app?sslmode=disable
# - REDIS_URL=redis://localhost:6379/0
# - SECRET_KEY=your-very-secret-key
# - PORT=8080

2. Frontend

cd frontend
cp .env.example .env
# Настройте .env:
# - VITE_API_BASE_URL=http://localhost:8080/api

3. Bot

cd bot
cp .env.example .env
# Настройте .env:
# - BOT_TOKEN=ваш_токен_бота
# - BACKEND_API_URL=http://localhost:8080
# - FRONTEND_URL=http://localhost:5173
# - BOT_USERNAME=ваш_бот_юзернейм
# - ADMIN_USER_IDS=ваш_telegram_id

🚀 Запуск системы

Вариант 1: Ручной запуск (рекомендуется для разработки)

Откройте 3 отдельных терминала:

Терминал 1 - Backend:

cd backend
go run cmd/server/main.go

Должен увидеть: Server running on port 8080

Терминал 2 - Frontend:

cd frontend
pnpm install
pnpm dev

Должен увидеть: Local: http://localhost:5173/

Терминал 3 - Bot:

cd bot
pip install -r requirements.txt
python bot.py

Должен увидеть: Starting bot @YourBotUsername

Вариант 2: Одновременный запуск (с помощью tmux)

# Создайте новую tmux сессию
tmux new-session -s quiz-app

# Разделите окно на 3 панели
tmux split-window -h
tmux split-window -v

# В каждой панели запустите свой компонент
# Верхняя левая: Backend
cd backend && go run cmd/server/main.go

# Верхняя правая: Frontend
cd frontend && pnpm dev

# Нижняя: Bot
cd bot && python bot.py

# Переключение между панелями: Ctrl+B + стрелки
# Отключиться от сессии: Ctrl+B + D
# Подключиться обратно: tmux attach -t quiz-app

Вариант 3: С помощью Docker Compose (если настроено)

docker-compose up -d

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

1. Проверка Backend API

curl http://localhost:8080/health
# Должен вернуть статус 200

2. Проверка Frontend

Откройте в браузере: http://localhost:5173

3. Проверка Bot

Найдите вашего бота в Telegram: @YourBotUsername Отправьте команду /start

🎫 Тестирование QR-кодов

Шаг 1: Создайте тестового администратора

1. Получите ваш Telegram User ID: @userinfobot
2. Добавьте его в bot/.env: ADMIN_USER_IDS=ваш_id

Шаг 2: Сгенерируйте QR-коды через бота

/admin
→ Генерировать QR-коды
→ Выберите тип: reward
→ Введите сумму: 50
→ Получите токены

Шаг 3: Протестируйте сканирование

1. Откройте фронтенд: http://localhost:5173
2. Перейдите на страницу QR-сканера
3. Создайте QR-код с одним из токенов
4. Отсканируйте его через приложение

Шаг 4: Проверьте интеграцию

• QR-код должен быть успешно отсканирован
• Должны появиться звезды на балансе
• В backend должны появиться записи о сканировании

🔍 Отладка

Проверьте логи:

# Backend логи (в терминале)
# Tail логи если запущено как сервис
tail -f /var/log/quiz-app/backend.log

# Frontend логи (в консоли браузера)
# Откройте DevTools → Console

# Bot логи (в терминале)

Общие проблемы:

1. Порт занят: lsof -i :8080 и kill -9 PID
2. Backend не запущен: Frontend не сможет подключиться к API
3. Bot не запущен: Telegram команды не будут работать
4. База данных: Убедитесь, что PostgreSQL и Redis запущены

📱 Тестирование на мобильном

Доступ к локальному серверу с телефона:

1. Wi-Fi сеть: телефон и компьютер должны быть в одной сети
2. IP адрес: ifconfig или ipconfig чтобы узнать IP
3. Настройте .env файлы:

   # Frontend .env
   VITE_API_BASE_URL=http://192.168.1.100:8080/api
   
   # Bot .env
   BACKEND_API_URL=http://192.168.1.100:8080
   FRONTEND_URL=http://192.168.1.100:5173
   

Telegram Web App:

1. Откройте бота в Telegram
2. Нажмите на кнопку "Открыть Викторины"
3. Должно открыться веб-приложение

✅ Проверочный чеклист

• Backend запущен на порту 8080
• Frontend запущен на порту 5173
• Bot запущен и отвечает на команды
• База данных PostgreSQL работает
• Redis работает
• QR-коды генерируются через бота
• QR-коды сканируются через фронтенд
• Баллы начисляются за сканирование
• Викторины работают корректно
• Магазин призов функционирует

🛑 Остановка

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

# В каждом терминале нажмите Ctrl+C

Через tmux:

tmux kill-session -t quiz-app

Через Docker:

docker-compose down

🚨 Частые проблемы

Backend не стартует:

• Проверьте PostgreSQL и Redis: brew services list
• Проверьте порты: lsof -i :8080
• Проверьте .env файл

Frontend не видит API:

• Проверьте VITE_API_BASE_URL в .env
• Убедитесь, что backend запущен
• Проверьте CORS настройки в backend

Bot не работает:

• Проверьте BOT_TOKEN
• Убедитесь, что бот не заблокирован
• Проверьте права доступа к API

QR-коды не сканируются:

• Проверьте права доступа к камере
• Убедитесь, что backend API доступен
• Проверьте формат токенов