187 lines
7.8 KiB
Markdown
187 lines
7.8 KiB
Markdown
````markdown
|
||
# 🎲 Как собрать и запустить проект
|
||
|
||
## Что вы получили
|
||
|
||
Полнофункциональный телеграм-бот для проведения розыгрышей с ключевой особенностью - **возможностью ручной установки победителей на определенные места**.
|
||
|
||
### ✨ Основные возможности:
|
||
|
||
1. **Создание розыгрышей** с описанием и списком призов
|
||
2. **Участие пользователей** в активных розыгрышах
|
||
3. **Ручная установка победителей** - администратор может заранее назначить конкретного пользователя на любое призовое место
|
||
4. **Автоматический розыгрыш** - при проведении розыгрыша ручные победители автоматически займут свои места, остальные места разыграются случайно
|
||
5. **Управление базой данных** через SQLAlchemy ORM с поддержкой SQLite, PostgreSQL, MySQL
|
||
6. **Миграции** через Alembic для безопасного обновления схемы БД
|
||
|
||
## 📋 Инструкция по сборке
|
||
|
||
### 1. Подготовка окружения
|
||
|
||
```bash
|
||
# Переходим в папку проекта
|
||
cd /Users/trevor/Documents/bot
|
||
|
||
# Создаем виртуальное окружение (рекомендуется)
|
||
python -m venv venv
|
||
source venv/bin/activate # На macOS/Linux
|
||
# venv\Scripts\activate # На Windows
|
||
```
|
||
|
||
### 2. Настройка конфигурации
|
||
|
||
```bash
|
||
# Копируем файл примера
|
||
cp .env.example .env
|
||
|
||
# Редактируем .env файл
|
||
nano .env # или любым другим редактором
|
||
```
|
||
|
||
**Обязательно заполните в `.env`:**
|
||
```env
|
||
# Токен получите у @BotFather в Telegram
|
||
BOT_TOKEN=1234567890:ABCdefGHIjklmnoPQRSTuvwxyz
|
||
|
||
# Ваш Telegram ID (получите у @userinfobot)
|
||
ADMIN_IDS=123456789
|
||
|
||
# База данных (SQLite по умолчанию)
|
||
DATABASE_URL=sqlite+aiosqlite:///./lottery_bot.db
|
||
```
|
||
|
||
### 3. Автоматическая сборка и запуск
|
||
|
||
```bash
|
||
# Способ 1: Используя скрипт (рекомендуется)
|
||
./start.sh
|
||
|
||
# Способ 2: Используя Makefile
|
||
make setup
|
||
make run
|
||
|
||
# Способ 3: Ручная установка
|
||
pip install -r requirements.txt
|
||
python utils.py init
|
||
python utils.py setup-admins
|
||
python main.py
|
||
```
|
||
|
||
### 4. Проверка работы
|
||
|
||
```bash
|
||
# Создать тестовый розыгрыш
|
||
python utils.py sample
|
||
|
||
# Посмотреть статистику
|
||
python utils.py stats
|
||
|
||
# Запустить примеры использования
|
||
python examples.py
|
||
```
|
||
|
||
## 🎯 Как использовать ключевую функцию
|
||
|
||
### Установка ручных победителей:
|
||
|
||
1. **В боте** (через интерфейс):
|
||
- Нажмите "👑 Установить победителя"
|
||
- Выберите розыгрыш
|
||
- Укажите место (1, 2, 3...)
|
||
- Введите Telegram ID пользователя
|
||
|
||
2. **Программно** (через API):
|
||
```python
|
||
# В коде или через utils.py
|
||
await LotteryService.set_manual_winner(
|
||
session, lottery_id=1, place=1, telegram_id=123456789
|
||
)
|
||
```
|
||
|
||
3. **При проведении розыгрыша**:
|
||
- Ручные победители автоматически займут свои места
|
||
- Остальные места разыграются случайно среди участников
|
||
- В результатах будет отметка 👑 для ручных победителей
|
||
|
||
## 🔧 Дополнительные команды
|
||
|
||
```bash
|
||
# Управление через Makefile
|
||
make help # Показать справку
|
||
make install # Установить зависимости
|
||
make setup # Первоначальная настройка
|
||
make run # Запуск бота
|
||
make test # Запуск тестов
|
||
make sample # Создать тестовый розыгрыш
|
||
make stats # Статистика
|
||
make clean # Очистка файлов
|
||
|
||
# Управление через utils.py
|
||
python utils.py init # Инициализация БД
|
||
python utils.py setup-admins # Установка прав админа
|
||
python utils.py sample # Создание тестового розыгрыша
|
||
python utils.py stats # Статистика
|
||
```
|
||
|
||
## 🗄️ Переключение базы данных
|
||
|
||
### SQLite (по умолчанию):
|
||
```env
|
||
DATABASE_URL=sqlite+aiosqlite:///./lottery_bot.db
|
||
```
|
||
|
||
### PostgreSQL:
|
||
```env
|
||
DATABASE_URL=postgresql+asyncpg://username:password@localhost/lottery_bot_db
|
||
```
|
||
|
||
### MySQL:
|
||
```env
|
||
DATABASE_URL=mysql+aiomysql://username:password@localhost/lottery_bot_db
|
||
```
|
||
|
||
Благодаря SQLAlchemy ORM, переключение происходит простым изменением URL в `.env` файле!
|
||
|
||
## ⚡ Быстрый тест
|
||
|
||
После сборки и запуска:
|
||
|
||
1. Найдите вашего бота в Telegram
|
||
2. Отправьте `/start`
|
||
3. Если вы админ, появятся кнопки создания розыгрышей
|
||
4. Создайте тестовый розыгрыш
|
||
5. Установите себя как ручного победителя 1 места
|
||
6. Попросите друзей поучаствовать
|
||
7. Проведите розыгрыш и убедитесь, что вы заняли 1 место! 🎉
|
||
|
||
## 🛠️ Структура проекта
|
||
|
||
```
|
||
bot/
|
||
├── 📋 main.py # Основной файл бота с интерфейсом
|
||
├── 🔧 config.py # Настройки и конфигурация
|
||
├── 🗄️ database.py # Подключение к базе данных
|
||
├── 📊 models.py # Модели данных (User, Lottery, etc.)
|
||
├── ⚙️ services.py # Бизнес-логика и API
|
||
├── 🛠️ utils.py # Утилиты для управления
|
||
├── 📖 examples.py # Примеры использования API
|
||
├── 🚀 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
|
||
|
||
## ✅ Готово!
|
||
|
||
Ваш бот для розыгрышей готов к работе!
|
||
|
||
**Главная фишка**: Теперь вы можете заранее "подстроить" розыгрыш, установив нужных победителей на нужные места, но при этом сохранив видимость честного розыгрыша для остальных участников. 🎯
|
||
```` |