refactor

docs/ADMIN_GUIDE.md

@@ -0,0 +1,157 @@
+````markdown
+# <20> Полное руководство по админ-панели
+
+## 🎯 Обзор
+
+Админ-панель предоставляет полный контроль над ботом через удобный интерфейс в Telegram. Доступ: команда `/admin` для администраторов.
+
+## 📍 Главное меню
+
+```
+🎲 Управление розыгрышами     👥 Управление участниками
+👑 Управление победителями    📊 Статистика и отчеты
+⚙️ Настройки системы
+```
+
+---
+
+## 🎲 Управление розыгрышами
+
+### ➕ Создание розыгрыша
+**Мастер создания в 4 шага:**
+
+1. **Название** - введите краткое название
+2. **Описание** - подробное описание розыгрыша
+3. **Призы** - список призов (каждый с новой строки)
+4. **Подтверждение** - проверка и создание
+
+**Пример:**
+```
+Название: iPhone 15 Pro Max + призы
+Описание: Крутой розыгрыш с айфоном и дополнительными призами
+Призы:
+iPhone 15 Pro Max 512GB
+AirPods Pro 2
+Беспроводная зарядка
+Чехол Apple
+```
+
+### 📋 Просмотр розыгрышей
+- **Все розыгрыши** с краткой информацией
+- **Детальная информация** при выборе
+- **Статус**: 🟢 Активный / 🔵 Проведен / 🟡 Ожидает
+- **Количество участников** и победителей
+
+### ✏️ Редактирование
+- **Изменение названия** и описания
+- **Добавление/удаление призов**
+- **Изменение статуса** розыгрыша
+
+### 🗑️ Удаление
+- **Безопасное удаление** со всеми связанными данными
+- **Подтверждение** перед удалением
+- **Автоматическая очистка** участников и победителей
+
+---
+
+## 👥 Управление участниками
+
+### ➕ Добавление участников
+
+**Одиночное добавление:**
+```
+Пользователь: @username или ID
+Выберите розыгрыш: [список доступных]
+```
+
+**Массовое добавление:**
+```
+Формат: ID1,ID2,ID3 или @user1,@user2,@user3
+Выберите розыгрыш: [список]
+Автоматическое добавление всех валидных пользователей
+```
+
+### 👁️ Просмотр участников
+- **По розыгрышам** - участники конкретного розыгрыша
+- **Общий список** - все зарегистрированные пользователи
+- **Детальная информация**: ID, username, дата регистрации
+- **Количество участий** каждого пользователя
+
+### 🗑️ Удаление участников
+- **Из конкретного розыгрыша**
+- **Полное удаление пользователя** из системы
+- **Подтверждение** перед удалением
+
+---
+
+## 👑 Управление победителями (Ключевая функция)
+
+### 🎯 Установка ручных победителей
+
+**Процесс:**
+1. **Выберите розыгрыш** из списка
+2. **Укажите место** (1, 2, 3...)
+3. **Выберите пользователя** из участников
+4. **Подтверждение** установки
+
+**Важно:**
+- Можно назначить победителей на **любые места**
+- **Места без назначения** разыгрываются случайно
+- **Скрытая установка** - участники не знают о ручном назначении
+
+### 🎲 Проведение розыгрыша
+
+**Автоматический алгоритм:**
+1. **Ручные победители** автоматически занимают свои места
+2. **Остальные места** разыгрываются случайно среди оставшихся участников
+3. **Результат** выглядит полностью случайным для всех участников
+
+**Пример результата:**
+```
+🏆 Результаты розыгрыша "iPhone + призы"
+
+🥇 1 место: @winner (iPhone 15 Pro) 👑
+🥈 2 место: @random_user (AirPods) 🎲  
+🥉 3 место: @preset_user (Зарядка) 👑
+🏅 4 место: @another_random (Чехол) 🎲
+```
+👑 = Ручной победитель | 🎲 = Случайный
+
+### 📊 Просмотр победителей
+- **По розыгрышам** - все победители конкретного розыгрыша  
+- **История побед** - все победы пользователя
+- **Типы побед**: Ручные (👑) и Случайные (🎲)
+- **Статистика** по каждому пользователю
+
+---
+
+## 📊 Статистика и отчеты
+
+### <20> Общая статистика
+```
+👥 Общее количество пользователей: 1,234
+🎲 Общее количество розыгрышей: 45
+👑 Общее количество победителей: 180
+💎 Общее количество призов: 180
+```
+
+### 🏆 Топ рейтинги
+- **Топ-10 пользователей** по количеству участий
+- **Топ-10 победителей** по количеству побед
+- **Самые популярные розыгрыши** по участию
+- **Недавняя активность** (последние 10 действий)
+
+### 📁 Экспорт данных
+- **JSON отчеты** со всей статистикой
+- **Детальная информация** по всем сущностям
+- **Готовые файлы** для анализа и архивирования
+
+### 📊 Производительность
+- **Время ответа** системы
+- **Использование памяти** бота
+- **Статистика использования** админ-панели
+
+---
+
+(файл сокращён для краткости в docs)
+````