new_lottery_bot/docs/BUILD.md

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

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

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

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

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

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

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

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

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

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

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

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

**Обязательно заполните в `.env`:**
```env
# Токен получите у @BotFather в Telegram
BOT_TOKEN=1234567890:ABCdefGHIjklmnoPQRSTuvwxyz

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

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

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

```bash
# Способ 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. Проверка работы

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

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

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

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

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

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

2. **Программно** (через API):
```python
# В коде или через utils.py
await LotteryService.set_manual_winner(
    session, lottery_id=1, place=1, telegram_id=123456789
)
```

3. **При проведении розыгрыша**:
   - Ручные победители автоматически займут свои места
   - Остальные места разыграются случайно среди участников
   - В результатах будет отметка 👑 для ручных победителей

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

```bash
# Управление через 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         # Статистика
```

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

### SQLite (по умолчанию):
```env
DATABASE_URL=sqlite+aiosqlite:///./lottery_bot.db
```

### PostgreSQL:
```env  
DATABASE_URL=postgresql+asyncpg://username:password@localhost/lottery_bot_db
```

### MySQL:
```env
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

## ✅ Готово!

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

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