# Телеграм-бот для розыгрышей

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

## Особенности

- 🎲 Создание и управление розыгрышами
- 👑 Ручная установка победителей на любое место
- 🎯 Автоматический розыгрыш с учетом заранее установленных победителей
- 📊 Управление участниками
- 🔧 **Расширенная админ-панель** с полным контролем
- 💾 Поддержка SQLite и PostgreSQL через SQLAlchemy ORM
- 📈 Детальная статистика и отчеты
- 💾 Экспорт данных
- 🧹 Утилиты очистки и обслуживания

## Технологии

- **Python 3.8+**
- **aiogram 3.1+** - для работы с Telegram Bot API
- **SQLAlchemy 2.0** - ORM для работы с базой данных
- **Alembic** - миграции базы данных
- **python-dotenv** - управление переменными окружения
- **asyncpg** - асинхронный драйвер для PostgreSQL
- **aiosqlite** - асинхронный драйвер для SQLite

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

```
bot/
├── 📋 main.py              # Основной файл бота с интерфейсом
├── 🔧 admin_panel.py       # Расширенная админ-панель
├── 🛠️ admin_utils.py       # Утилиты для админки
├── 🔧 config.py            # Настройки и конфигурация
├── 🗄️ database.py          # Подключение к базе данных
├── 📊 models.py            # Модели данных (User, Lottery, etc.)
├── ⚙️ services.py          # Бизнес-логика и API
├── 🛠️ utils.py             # Утилиты для управления
├── 📖 examples.py          # Примеры использования API
├── 🎪 demo_admin.py        # Демонстрация админ-панели
├── 🚀 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
```

## Установка и настройка

### 1. Клонирование и установка зависимостей

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

# Создание виртуального окружения
python -m venv venv

# Активация виртуального окружения
# На macOS/Linux:
source venv/bin/activate
# На Windows:
# venv\Scripts\activate

# Установка зависимостей
pip install -r requirements.txt
```

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

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

# Отредактируйте .env файл
```

Заполните `.env` файл:

```env
# Получите токен у @BotFather в Telegram
BOT_TOKEN=your_bot_token_here

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

# Для PostgreSQL (раскомментируйте и настройте)
# DATABASE_URL=postgresql+asyncpg://username:password@localhost/lottery_bot_db

# ID администраторов (ваш Telegram ID)
ADMIN_IDS=123456789

# Уровень логирования
LOG_LEVEL=INFO
```

### 3. Инициализация миграций базы данных

```bash
# Инициализация Alembic
alembic init migrations

# Создание первой миграции
alembic revision --autogenerate -m "Initial migration"

# Применение миграций
alembic upgrade head
```

### 4. Запуск бота

```bash
python main.py
```

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

### Для обычных пользователей:

1. **Запуск бота**: `/start`
2. **Просмотр розыгрышей**: Кнопка "🎲 Активные розыгрыши"
3. **Участие в розыгрыше**: Выбрать розыгрыш → "🎫 Участвовать"
4. **Мои участия**: Кнопка "📝 Мои участия"

### Для администраторов:

1. **🔧 Расширенная админ-панель**: Кнопка "🔧 Админ-панель"
   - 🎲 **Управление розыгрышами**: создание, редактирование, удаление
   - 👥 **Управление участниками**: добавление, удаление, массовые операции
   - 👑 **Управление победителями**: установка предопределенных победителей
   - 📊 **Статистика**: детальная аналитика по всем розыгрышам
   - ⚙️ **Настройки**: системная информация, экспорт, очистка

2. **Создание розыгрыша**: Пошаговый мастер с подтверждением
3. **Установка ручных победителей**: Выбор места и пользователя
4. **Проведение розыгрыша**: Автоматический учет ручных победителей
5. **Экспорт и отчеты**: Полная статистика и экспорт данных

### Ключевая особенность - ручная установка победителей:

1. Используйте "👑 Установить победителя"
2. Выберите розыгрыш
3. Укажите место (1, 2, 3, ...)
4. Введите Telegram ID пользователя
5. При проведении розыгрыша этот пользователь автоматически займет указанное место

## Модели данных

### User (Пользователи)
- `telegram_id` - Telegram ID пользователя
- `username`, `first_name`, `last_name` - Данные пользователя
- `is_admin` - Флаг администратора

### Lottery (Розыгрыши)
- `title` - Название
- `description` - Описание
- `prizes` - Список призов (JSON)
- `manual_winners` - Ручно установленные победители (JSON)
- `is_active`, `is_completed` - Статусы

### Participation (Участие)
- Связь пользователя с розыгрышем

### Winner (Победители)
- Результаты розыгрыша с указанием места и приза

## API методы сервисов

### UserService
- `get_or_create_user()` - Получить или создать пользователя
- `set_admin()` - Установить права администратора

### LotteryService
- `create_lottery()` - Создать розыгрыш
- `set_manual_winner()` - Установить ручного победителя
- `conduct_draw()` - Провести розыгрыш с учетом ручных победителей

### ParticipationService
- `get_participants_count()` - Количество участников

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

Благодаря SQLAlchemy ORM, легко переключаться между разными базами данных:

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

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

### MySQL
```env
DATABASE_URL=mysql+aiomysql://username:password@localhost/database_name
```

## Миграции

```bash
# Создать новую миграцию после изменения моделей
alembic revision --autogenerate -m "Description of changes"

# Применить миграции
alembic upgrade head

# Откатить последнюю миграцию
alembic downgrade -1
```

## Логи

Бот ведет логи всех операций. Уровень логирования настраивается через переменную `LOG_LEVEL`.

## Безопасность

- Права администратора контролируются через `ADMIN_IDS` в `.env`
- Все операции с базой данных асинхронные
- Валидация входных данных на всех уровнях

## Развертывание

### Локальное развертывание
Следуйте инструкциям по установке выше.

### Docker (опционально)
```dockerfile
FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
CMD ["python", "main.py"]
```

## Поддержка

Для получения помощи или сообщения об ошибках создайте issue в репозитории проекта.

## Лицензия

MIT License