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

📋 Что создано

✅ Полнофункциональный телеграм-бот для проведения розыгрышей ✅ Ключевая особенность: Возможность ручной установки победителей на любые места ✅ Современная архитектура: Python + SQLAlchemy ORM + Alembic + aiogram 3.x ✅ Гибкость БД: Поддержка SQLite, PostgreSQL, MySQL ✅ Готов к продакшну: Миграции, логирование, обработка ошибок

🎯 Как это работает

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

🔧 Расширенная админ-панель

🎲 Управление розыгрышами

Пошаговое создание с мастером (название → описание → призы → подтверждение)
Редактирование существующих розыгрышей
Полный список с фильтрацией и поиском
Безопасное удаление со всеми связанными данными

👥 Управление участниками

Добавление участников (одиночное и массовое)
Удаление участников из розыгрышей
Просмотр списков с детальной информацией
Анализ активности пользователей

👑 Управление победителями

Установка ручных победителей на любые места
Редактирование назначений
Проведение розыгрышей с автоматическим учетом ручных победителей
История побед с отметками (👑 ручной / 🎲 случайный)

📊 Статистика и отчеты

Детальная аналитика по всем розыгрышам
Топ пользователи и популярные розыгрыши
Экспорт данных в JSON формате
Системные метрики и производительность

⚙️ Настройки системы

Очистка старых данных (настраиваемый период)
Системная информация
Управление правами администраторов

🚀 Быстрый запуск

cd /Users/trevor/Documents/bot

# 1. Настройте конфигурацию
cp .env.example .env
# Заполните BOT_TOKEN и ADMIN_IDS в .env

# 2. Запустите автоматическую установку
./start.sh

# 3. Опционально: Демонстрация админ-панели
make demo-admin

# Или используйте Makefile
make setup && make run

Используйте команду /admin в Telegram для доступа к полной админ-панели!

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

bot/
├── main.py           # 🤖 Основной файл бота
├── models.py         # 📊 Модели базы данных
├── services.py       # ⚙️ Бизнес-логика 
├── database.py       # 🗄️ Настройка БД
├── config.py         # 🔧 Конфигурация
├── utils.py          # 🛠️ Утилиты управления
├── examples.py       # 📖 Примеры использования
├── start.sh          # 🚀 Скрипт запуска
├── Makefile          # ⚡ Автоматизация
├── requirements.txt  # 📦 Зависимости
├── alembic.ini       # 🏗️ Настройки миграций
├── migrations/       # 📁 Миграции БД
├── .env.example      # 📝 Пример настроек
├── README.md         # 📚 Полная документация
├── QUICKSTART.md     # ⚡ Быстрый старт
└── BUILD.md          # 🔨 Инструкция по сборке

💡 Ключевые API методы

# Создание розыгрыша
lottery = await LotteryService.create_lottery(
    session, title="Приз", description="Описание", 
    prizes=["Приз 1", "Приз 2"], creator_id=admin_id
)

# Установка ручного победителя  
await LotteryService.set_manual_winner(
    session, lottery_id=1, place=1, telegram_id=123456789
)

# Проведение розыгрыша (с учетом ручных победителей)
results = await LotteryService.conduct_draw(session, lottery_id=1)

🔧 Команды управления

# Makefile команды
make help           # Справка
make setup          # Установка и настройка
make run            # Запуск бота
make test           # Тесты
make sample         # Создать тестовый розыгрыш
make stats          # Статистика

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

🎪 Пример использования

Создаете розыгрыш "iPhone 15 + призы"
Устанавливаете своего друга победителем 1 места (iPhone)
100 человек участвуют в "честном" розыгрыше
При розыгрыше ваш друг "случайно" выигрывает iPhone
Остальные призы разыгрываются честно

Никто не узнает о подстройке! ✨

📞 Поддержка

📖 Читайте README.md для полной документации
⚡ Используйте QUICKSTART.md для быстрого старта
🔨 Следуйте BUILD.md для подробной сборки
🧪 Запускайте examples.py для тестов

Проект готов к использованию! 🎉

6.8 KiB Raw Blame History Unescape Escape