trevor/new_lottery_bot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
e0075d91b600650d78ac4626e05811188906c7d8
new_lottery_bot/README.md
Andrew K. Choi e0075d91b6 init commit
2025-11-12 20:57:36 +09:00

9.8 KiB
Raw Blame History

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

Телеграм-бот на 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. Клонирование и установка зависимостей

# Переход в папку проекта
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. Настройка переменных окружения

# Копируйте файл примера
cp .env.example .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. Инициализация миграций базы данных

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

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

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

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

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 (по умолчанию)

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

PostgreSQL

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

MySQL

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

Миграции

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

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

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

Логи

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

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

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

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

Локальное развертывание

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

Docker (опционально)

FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
CMD ["python", "main.py"]

Поддержка

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

Лицензия

MIT License