new_lottery_bot/BUILD.md

🎲 Как собрать и запустить проект

Что вы получили

Полнофункциональный телеграм-бот для проведения розыгрышей с ключевой особенностью - возможностью ручной установки победителей на определенные места.

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

1. Создание розыгрышей с описанием и списком призов
2. Участие пользователей в активных розыгрышах
3. Ручная установка победителей - администратор может заранее назначить конкретного пользователя на любое призовое место
4. Автоматический розыгрыш - при проведении розыгрыша ручные победители автоматически займут свои места, остальные места разыграются случайно
5. Управление базой данных через SQLAlchemy ORM с поддержкой SQLite, PostgreSQL, MySQL
6. Миграции через Alembic для безопасного обновления схемы БД

📋 Инструкция по сборке

1. Подготовка окружения

# Переходим в папку проекта
cd /Users/trevor/Documents/bot

# Создаем виртуальное окружение (рекомендуется)
python -m venv venv
source venv/bin/activate  # На macOS/Linux
# venv\Scripts\activate   # На Windows

2. Настройка конфигурации

# Копируем файл примера
cp .env.example .env

# Редактируем .env файл
nano .env  # или любым другим редактором

Обязательно заполните в .env:

# Токен получите у @BotFather в Telegram
BOT_TOKEN=1234567890:ABCdefGHIjklmnoPQRSTuvwxyz

# Ваш Telegram ID (получите у @userinfobot)  
ADMIN_IDS=123456789

# База данных (SQLite по умолчанию)
DATABASE_URL=sqlite+aiosqlite:///./lottery_bot.db

3. Автоматическая сборка и запуск

# Способ 1: Используя скрипт (рекомендуется)
./start.sh

# Способ 2: Используя Makefile
make setup
make run

# Способ 3: Ручная установка
pip install -r requirements.txt
python utils.py init
python utils.py setup-admins  
python main.py

4. Проверка работы

# Создать тестовый розыгрыш
python utils.py sample

# Посмотреть статистику
python utils.py stats

# Запустить примеры использования
python examples.py

🎯 Как использовать ключевую функцию

Установка ручных победителей:

1. В боте (через интерфейс):

   • Нажмите "👑 Установить победителя"
   • Выберите розыгрыш
   • Укажите место (1, 2, 3...)
   • Введите Telegram ID пользователя

2. Программно (через API):

   # В коде или через utils.py
   await LotteryService.set_manual_winner(
       session, lottery_id=1, place=1, telegram_id=123456789
   )
   

3. При проведении розыгрыша:

   • Ручные победители автоматически займут свои места
   • Остальные места разыграются случайно среди участников
   • В результатах будет отметка 👑 для ручных победителей

🔧 Дополнительные команды

# Управление через Makefile
make help           # Показать справку
make install        # Установить зависимости
make setup          # Первоначальная настройка  
make run            # Запуск бота
make test           # Запуск тестов
make sample         # Создать тестовый розыгрыш
make stats          # Статистика
make clean          # Очистка файлов

# Управление через utils.py
python utils.py init          # Инициализация БД
python utils.py setup-admins  # Установка прав админа
python utils.py sample        # Создание тестового розыгрыша
python utils.py stats         # Статистика

# Работа с миграциями
alembic revision --autogenerate -m "описание изменений"
alembic upgrade head

🗄️ Переключение базы данных

SQLite (по умолчанию):

DATABASE_URL=sqlite+aiosqlite:///./lottery_bot.db

PostgreSQL:

DATABASE_URL=postgresql+asyncpg://username:password@localhost/lottery_bot_db

MySQL:

DATABASE_URL=mysql+aiomysql://username:password@localhost/lottery_bot_db

Благодаря SQLAlchemy ORM, переключение происходит простым изменением URL в .env файле!

⚡ Быстрый тест

После сборки и запуска:

1. Найдите вашего бота в Telegram
2. Отправьте /start
3. Если вы админ, появятся кнопки создания розыгрышей
4. Создайте тестовый розыгрыш
5. Установите себя как ручного победителя 1 места
6. Попросите друзей поучаствовать
7. Проведите розыгрыш и убедитесь, что вы заняли 1 место! 🎉

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

bot/
├── 📋 main.py              # Основной файл бота с интерфейсом
├── 🔧 config.py            # Настройки и конфигурация
├── 🗄️ database.py          # Подключение к базе данных
├── 📊 models.py            # Модели данных (User, Lottery, etc.)
├── ⚙️ services.py          # Бизнес-логика и API
├── 🛠️ utils.py             # Утилиты для управления
├── 📖 examples.py          # Примеры использования API
├── 🚀 start.sh             # Скрипт быстрого запуска
├── 📦 requirements.txt     # Зависимости Python
├── ⚙️ Makefile             # Автоматизация команд
├── 📝 .env.example         # Пример конфигурации
├── 🚫 .gitignore           # Игнорируемые файлы
├── 📚 README.md            # Полная документация
├── ⚡ QUICKSTART.md        # Быстрый старт
├── 🏗️ alembic.ini          # Конфигурация миграций
└── 📁 migrations/          # Файлы миграций БД
    ├── env.py              # Настройка миграций
    ├── script.py.mako      # Шаблон миграций
    └── versions/           # Версии миграций
        └── 001_initial_migration.py

✅ Готово!

Ваш бот для розыгрышей готов к работе!

Главная фишка: Теперь вы можете заранее "подстроить" розыгрыш, установив нужных победителей на нужные места, но при этом сохранив видимость честного розыгрыша для остальных участников. 🎯