refactor

2025-11-16 12:36:02 +09:00
parent 3a25e6a4cb
commit eb3f3807fd
61 changed files with 1438 additions and 1139 deletions
--- a/docs/BUILD.md
+++ b/docs/BUILD.md
@@ -0,0 +1,187 @@
+````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
+
+## ✅ Готово!
+
+Ваш бот для розыгрышей готов к работе! 
+
+**Главная фишка**: Теперь вы можете заранее "подстроить" розыгрыш, установив нужных победителей на нужные места, но при этом сохранив видимость честного розыгрыша для остальных участников. 🎯
+````