Andrey K. Choi
0623de5046
Some checks reported errors
continuous-integration/drone/push Build encountered an error
- Создана миграция 006_fix_missing_columns.py - Автоматически добавляет отсутствующие столбцы: * participations.account_id с FK на accounts * winners.is_notified, is_claimed, claimed_at - Миграция идемпотентна (безопасна для повторного выполнения) - Добавлен откат (downgrade) функционал - Обновлена документация в README.md - Создан отчет MIGRATION_006_REPORT.md Теперь изменения БД применяются через alembic upgrade head
303 lines
13 KiB
Markdown
303 lines
13 KiB
Markdown
# 🎲 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. Клонирование и установка зависимостей
|
||
|
||
```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 upgrade head
|
||
|
||
# Проверка текущей версии
|
||
alembic current
|
||
|
||
# Просмотр истории миграций
|
||
alembic history
|
||
```
|
||
|
||
**📋 Список миграций:**
|
||
- **001** - Инициализация таблиц
|
||
- **003** - Добавление регистрации и счетов
|
||
- **004** - Добавление claimed_at поля
|
||
- **005** - Добавление системы чата
|
||
- **006** - Исправление отсутствующих столбцов ✨
|
||
|
||
> **Важно**: При развертывании всегда выполняйте `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
|
||
```` |