252 lines
9.8 KiB
Markdown
252 lines
9.8 KiB
Markdown
# Телеграм-бот для розыгрышей
|
||
|
||
Телеграм-бот на 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 |