init commit
This commit is contained in:
252
README.md
Normal file
252
README.md
Normal file
@@ -0,0 +1,252 @@
|
||||
# Телеграм-бот для розыгрышей
|
||||
|
||||
Телеграм-бот на 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
|
||||
Reference in New Issue
Block a user