new_lottery_bot/README.md

🎲 Telegram Lottery Bot

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

🌟 Ключевые особенности

• 🎲 Создание и управление розыгрышами - Полный жизненный цикл
• 👑 Ручная установка победителей - На любое место
• 🎯 Автоматический розыгрыш - С учетом заранее установленных победителей
• 📊 Управление участниками - Через номера счетов или Telegram ID
• 🔧 Расширенная админ-панель - Полный контроль всех процессов
• 💾 Поддержка PostgreSQL и SQLite - Гибкая настройка БД
• 📈 Детальная статистика - Полные отчеты и аналитика
• 🧹 Утилиты обслуживания - Очистка и оптимизация
• 🐳 Docker поддержка - Легкая контейнеризация
• 🚀 CI/CD pipeline - Автоматическое развертывание
• 📦 Модульная архитектура - Простое расширение функциональности

🛠 Технологический стек

• Python 3.12+ - Основной язык
• aiogram 3.16 - Telegram Bot API
• SQLAlchemy 2.0.36 - ORM для работы с БД
• Alembic 1.14 - Система миграций
• PostgreSQL / SQLite - База данных
• Docker & Docker Compose - Контейнеризация
• Prometheus & Grafana - Мониторинг
• Drone CI - Непрерывная интеграция

Архитектура проекта

lottery_bot/
├── src/                          # Основной код приложения
│   ├── __init__.py
│   ├── core/                     # Ядро приложения
│   │   ├── __init__.py
│   │   ├── config.py             # Конфигурация
│   │   ├── database.py           # Подключение к БД
│   │   ├── models.py             # Модели SQLAlchemy
│   │   └── services.py           # Бизнес-логика
│   ├── handlers/                 # Обработчики событий
│   │   ├── __init__.py
│   │   ├── account_handlers.py   # Обработка счетов
│   │   ├── account_services.py   # Сервисы счетов
│   │   └── admin_panel.py        # Админ-панель
│   ├── utils/                    # Утилиты
│   │   ├── __init__.py
│   │   ├── account_utils.py      # Работа со счетами
│   │   ├── admin_utils.py        # Админ утилиты
│   │   ├── async_decorators.py   # Асинхронные декораторы
│   │   ├── task_manager.py       # Управление задачами
│   │   └── utils.py              # Общие утилиты
│   └── display/                  # Компоненты отображения
│       ├── __init__.py
│       ├── conduct_draw.py       # Проведение розыгрыша
│       ├── demo_admin.py         # Демонстрация админки
│       ├── simple_draw.py        # Простой розыгрыш
│       └── winner_display.py     # Отображение победителей
├── tests/                        # Тесты
├── docs/                         # Документация
├── scripts/                      # Скрипты
├── data/                         # Данные
├── migrations/                   # Миграции БД
├── monitoring/                   # Конфигурация мониторинга
├── main.py                       # Точка входа
├── requirements.txt              # Python зависимости
├── Dockerfile                    # Docker образ
├── docker-compose.yml            # Docker Compose
├── .drone.yml                    # CI/CD pipeline
└── Makefile                      # Команды сборки
├── 📋 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 upgrade head

# Проверка текущей версии
alembic current

# Просмотр истории миграций
alembic history

📋 Список миграций:

• 001 - Инициализация таблиц
• 003 - Добавление регистрации и счетов
• 004 - Добавление claimed_at поля
• 005 - Добавление системы чата
• 006 - Исправление отсутствующих столбцов ✨

Важно: При развертывании всегда выполняйте 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 с внешним PostgreSQL

Бот настроен для работы с внешним PostgreSQL сервером.

Быстрый старт:

1. Настройте внешнюю PostgreSQL БД (см. EXTERNAL_DB_SETUP.md)

2. Отредактируйте .env.prod:

DATABASE_URL=postgresql+asyncpg://user:password@your_db_host:5432/lottery_bot
BOT_TOKEN=your_bot_token
ADMIN_IDS=123456789,987654321

3. Запустите бота:

docker-compose up -d

4. Примените миграции:

docker exec -it lottery_bot alembic upgrade head

Подробная документация: EXTERNAL_DB_SETUP.md

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