149 lines
6.9 KiB
Markdown
149 lines
6.9 KiB
Markdown
````markdown
|
||
# 🎲 Телеграм-бот для розыгрышей
|
||
|
||
## 📋 Что создано
|
||
|
||
✅ **Полнофункциональный телеграм-бот** для проведения розыгрышей
|
||
✅ **Ключевая особенность**: Возможность ручной установки победителей на любые места
|
||
✅ **Современная архитектура**: Python + SQLAlchemy ORM + Alembic + aiogram 3.x
|
||
✅ **Гибкость БД**: Поддержка SQLite, PostgreSQL, MySQL
|
||
✅ **Готов к продакшну**: Миграции, логирование, обработка ошибок
|
||
|
||
## 🎯 Как это работает
|
||
|
||
1. **Создаете розыгрыш** с призами через удобную админ-панель
|
||
2. **Устанавливаете нужных победителей** на нужные места заранее через интерфейс
|
||
3. **Участники регистрируются** через бота
|
||
4. **Проводите "честный" розыгрыш** - ваши победители автоматически займут свои места, остальные разыгрываются случайно
|
||
|
||
## 🔧 Расширенная админ-панель
|
||
|
||
### 🎲 Управление розыгрышами
|
||
- **Пошаговое создание** с мастером (название → описание → призы → подтверждение)
|
||
- **Редактирование** существующих розыгрышей
|
||
- **Полный список** с фильтрацией и поиском
|
||
- **Безопасное удаление** со всеми связанными данными
|
||
|
||
### 👥 Управление участниками
|
||
- **Добавление участников** (одиночное и массовое)
|
||
- **Удаление участников** из розыгрышей
|
||
- **Просмотр списков** с детальной информацией
|
||
- **Анализ активности** пользователей
|
||
|
||
### 👑 Управление победителями
|
||
- **Установка ручных победителей** на любые места
|
||
- **Редактирование назначений**
|
||
- **Проведение розыгрышей** с автоматическим учетом ручных победителей
|
||
- **История побед** с отметками (👑 ручной / 🎲 случайный)
|
||
|
||
### 📊 Статистика и отчеты
|
||
- **Детальная аналитика** по всем розыгрышам
|
||
- **Топ пользователи** и популярные розыгрыши
|
||
- **Экспорт данных** в JSON формате
|
||
- **Системные метрики** и производительность
|
||
|
||
### ⚙️ Настройки системы
|
||
- **Очистка старых данных** (настраиваемый период)
|
||
- **Системная информация**
|
||
- **Управление правами** администраторов
|
||
|
||
## 🚀 Быстрый запуск
|
||
|
||
```bash
|
||
cd /Users/trevor/Documents/bot
|
||
|
||
# 1. Настройте конфигурацию
|
||
cp .env.example .env
|
||
# Заполните BOT_TOKEN и ADMIN_IDS в .env
|
||
|
||
# 2. Запустите автоматическую установку
|
||
./start.sh
|
||
|
||
# 3. Опционально: Демонстрация админ-панели
|
||
make demo-admin
|
||
|
||
# Или используйте Makefile
|
||
make setup && make run
|
||
```
|
||
|
||
**Используйте команду `/admin` в Telegram для доступа к полной админ-панели!**
|
||
|
||
## 📁 Структура проекта
|
||
|
||
```
|
||
bot/
|
||
├── main.py # 🤖 Основной файл бота
|
||
├── models.py # 📊 Модели базы данных
|
||
├── services.py # ⚙️ Бизнес-логика
|
||
├── database.py # 🗄️ Настройка БД
|
||
├── config.py # 🔧 Конфигурация
|
||
├── utils.py # 🛠️ Утилиты управления
|
||
├── examples.py # 📖 Примеры использования
|
||
├── start.sh # 🚀 Скрипт запуска
|
||
├── Makefile # ⚡ Автоматизация
|
||
├── requirements.txt # 📦 Зависимости
|
||
├── alembic.ini # 🏗️ Настройки миграций
|
||
├── migrations/ # 📁 Миграции БД
|
||
├── .env.example # 📝 Пример настроек
|
||
├── README.md # 📚 Полная документация
|
||
├── QUICKSTART.md # ⚡ Быстрый старт
|
||
└── BUILD.md # 🔨 Инструкция по сборке
|
||
```
|
||
|
||
## 💡 Ключевые API методы
|
||
|
||
```python
|
||
# Создание розыгрыша
|
||
lottery = await LotteryService.create_lottery(
|
||
session, title="Приз", description="Описание",
|
||
prizes=["Приз 1", "Приз 2"], creator_id=admin_id
|
||
)
|
||
|
||
# Установка ручного победителя
|
||
await LotteryService.set_manual_winner(
|
||
session, lottery_id=1, place=1, telegram_id=123456789
|
||
)
|
||
|
||
# Проведение розыгрыша (с учетом ручных победителей)
|
||
results = await LotteryService.conduct_draw(session, lottery_id=1)
|
||
```
|
||
|
||
## 🔧 Команды управления
|
||
|
||
```bash
|
||
# Makefile команды
|
||
make help # Справка
|
||
make setup # Установка и настройка
|
||
make run # Запуск бота
|
||
make test # Тесты
|
||
make sample # Создать тестовый розыгрыш
|
||
make stats # Статистика
|
||
|
||
# Утилиты
|
||
python utils.py init # Инициализация БД
|
||
python utils.py setup-admins # Установка админов
|
||
python utils.py sample # Тестовый розыгрыш
|
||
python utils.py stats # Статистика
|
||
```
|
||
|
||
## 🎪 Пример использования
|
||
|
||
1. Создаете розыгрыш "iPhone 15 + призы"
|
||
2. Устанавливаете своего друга победителем 1 места (iPhone)
|
||
3. 100 человек участвуют в "честном" розыгрыше
|
||
4. При розыгрыше ваш друг "случайно" выигрывает iPhone
|
||
5. Остальные призы разыгрываются честно
|
||
|
||
**Никто не узнает о подстройке!** ✨
|
||
|
||
## 📞 Поддержка
|
||
|
||
- 📖 Читайте `README.md` для полной документации
|
||
- ⚡ Используйте `QUICKSTART.md` для быстрого старта
|
||
- 🔨 Следуйте `BUILD.md` для подробной сборки
|
||
- 🧪 Запускайте `examples.py` для тестов
|
||
|
||
---
|
||
|
||
**Проект готов к использованию!** 🎉
|
||
```` |