new_lottery_bot/ADMIN_GUIDE.md

<EFBFBD> Полное руководство по админ-панели

🎯 Обзор

Админ-панель предоставляет полный контроль над ботом через удобный интерфейс в 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 (Чехол) 🎲

👑 = Ручной победитель | 🎲 = Случайный

📊 Просмотр победителей

• По розыгрышам - все победители конкретного розыгрыша
• История побед - все победы пользователя
• Типы побед: Ручные (👑) и Случайные (🎲)
• Статистика по каждому пользователю

---

📊 Статистика и отчеты

<EFBFBD> Общая статистика

👥 Общее количество пользователей: 1,234
🎲 Общее количество розыгрышей: 45
👑 Общее количество победителей: 180
💎 Общее количество призов: 180

🏆 Топ рейтинги

• Топ-10 пользователей по количеству участий
• Топ-10 победителей по количеству побед
• Самые популярные розыгрыши по участию
• Недавняя активность (последние 10 действий)

📁 Экспорт данных

• JSON отчеты со всей статистикой
• Детальная информация по всем сущностям
• Готовые файлы для анализа и архивирования

📊 Производительность

• Время ответа системы
• Использование памяти бота
• Статистика использования админ-панели

---

⚙️ Настройки системы

🧹 Управление данными

Очистка по периодам:

• 7 дней - недавние данные
• 30 дней - месячные данные
• 90 дней - квартальные данные
• Все данные - полная очистка

Что очищается:

• Завершенные розыгрыши
• Неактивные пользователи
• Старые записи участий
• Устаревшие логи

🔧 Системная информация

🖥️ Операционная система: macOS
🐍 Версия Python: 3.8.10
📚 Версия aiogram: 3.1.1
🗄️ Тип базы данных: SQLite
💾 Размер базы данных: 2.5 MB
⏰ Время работы бота: 5d 14h 32m

👮‍♂️ Управление администраторами

• Список администраторов с правами
• Добавление нових админов через ID
• Удаление администраторов
• История действий админов

---

🎪 Практические сценарии

Сценарий 1: "Честный" розыгрыш iPhone

1. Создаете розыгрыш "Разыгрываем iPhone 15!"
2. Устанавливаете своего друга победителем 1 места
3. 500 человек регистрируются 
4. Проводите розыгрыш → друг "случайно" выигрывает
5. Все думают, что повезло, никто ничего не подозревает

Сценарий 2: Частичное управление

1. Создаете розыгрыш с 10 призами
2. Устанавливаете ручных победителей только на 1, 3 и 5 места
3. Места 2, 4, 6-10 разыгрываются честно
4. Получается максимально естественный результат

Сценарий 3: Корпоративный розыгрыш

1. Создаете розыгрыш для сотрудников
2. Незаметно устанавливаете руководителей на призовые места  
3. Проводите "честный" корпоративный розыгрыш
4. Всем кажется, что руководству просто повезло

---

🔐 Безопасность и конфиденциальность

🛡️ Защита информации

• Ручные победители видны только администраторам
• Логи действий не содержат информации о ручном назначении
• Участники не имеют доступа к админ-функциям
• Результаты выглядят естественно для всех

🎭 Имитация случайности

• Алгоритм автоматически создает правдоподобные результаты
• Ручные победители не выделяются визуально
• Статистика для участников показывает "честные" результаты
• История не содержит признаков манипуляций

---

🆘 Устранение проблем

Частые вопросы

Q: Как изменить ручного победителя? A: Идите в "Управление победителями" → выберите розыгрыш → выберите новое место/пользователя

Q: Можно ли установить одного человека на несколько мест? A: Нет, один пользователь может быть назначен только на одно место в розыгрыше

Q: Что если ручной победитель покинет розыгрыш? A: Его место автоматически станет случайным при проведении розыгрыша

Q: Видно ли участникам кто назначен вручную? A: Нет, информация о ручных назначениях полностью скрыта от участников

Ошибки и решения

Ошибка: "Пользователь не участвует в розыгрыше" Решение: Сначала добавьте пользователя в участники, затем назначайте победителем

Ошибка: "Место уже занято"
Решение: Выберите другое место или измените существующее назначение

Ошибка: "Розыгрыш уже проведен" Решение: Ручных победителей можно назначать только до проведения розыгрыша

---

🎯 Заключение

Админ-панель предоставляет полный контроль над процессом розыгрышей с возможностью скрытого управления результатами. Используйте ответственно!

Помните: Цель - создать видимость честного розыгрыша, сохраняя полный контроль над результатами. ✨

📋 Структура админ-панели

🏠 Главная панель

Показывает быструю статистику и разделы:

• 🎲 Управление розыгрышами
• 👥 Управление участниками
• 👑 Управление победителями
• 📊 Статистика
• ⚙️ Настройки

🎲 Управление розыгрышами

➕ Создание розыгрыша

Пошаговый мастер с 4 этапами:

1. Название - введите привлекательное название
2. Описание - детальное описание (можно пропустить)
3. Призы - список призов (каждый с новой строки)
4. Подтверждение - проверьте и подтвердите создание

Пример создания:

Название: 🎉 Новогодний мега-розыгрыш
Описание: Грандиозный розыгрыш к Новому году!
Призы:
🥇 iPhone 15 Pro Max
🥈 MacBook Air M2
🥉 AirPods Pro
🏆 10,000 рублей

📝 Редактирование розыгрыша

• Изменение названия, описания, призов
• Активация/деактивация розыгрыша
• Просмотр детальной информации

📋 Список розыгрышей

• Все розыгрыши с статусами
• Количество участников
• Дата создания
• Быстрый доступ к деталям

🗑️ Удаление розыгрыша

• Безопасное удаление со всеми связанными данными
• Подтверждение операции

👥 Управление участниками

➕ Добавление участников

Два способа:

1. Одиночное добавление - по Telegram ID или username
2. Массовое добавление - список ID через запятую

➖ Удаление участников

• Удаление по Telegram ID
• Подтверждение операции

📊 Просмотр участников

• Список всех участников розыгрыша
• Информация о пользователях
• Дата присоединения

👤 Анализ активности

• История участий пользователя
• Статистика побед
• Активность по розыгрышам

👑 Управление победителями

🎯 Ключевая особенность - установка ручных победителей

Как это работает:

1. Выберите розыгрыш из активных
2. Укажите место (1, 2, 3, ...)
3. Введите Telegram ID или username пользователя
4. Подтвердите операцию

При розыгрыше:

• Ручные победители автоматически займут свои места
• Остальные места разыгрываются случайно
• Участники не знают о предустановке

Пример использования:

Розыгрыш: iPhone + призы
Устанавливаем:
- 1 место: @your_friend (получит iPhone)
- 3 место: @another_person

При розыгрыше среди 100 участников:
✅ 1 место: @your_friend 👑 (iPhone)
🎲 2 место: случайный участник
✅ 3 место: @another_person 👑
🎲 4-5 места: случайные участники

🎲 Проведение розыгрыша

• Автоматический учет ручных победителей
• Случайное распределение остальных мест
• Сохранение результатов в базе данных

📝 Редактирование победителей

• Изменение предустановленных победителей
• Удаление ручных назначений

📋 Список победителей

• Все победители с отметками
• 👑 - ручной победитель
• 🎲 - случайный победитель

📊 Статистика

📈 Общая статистика

• Количество пользователей
• Всего розыгрышей (активные/завершенные)
• Общие участия и победы
• Соотношение ручных/случайных победителей

🏆 Топ-списки

• Топ розыгрыши по количеству участников
• Топ пользователи по активности
• Статистика побед с разбивкой

📊 Детальная аналитика

• Динамика участий по датам
• Активность пользователей
• Эффективность розыгрышей

⚙️ Настройки и утилиты

💾 Экспорт данных

Полный экспорт розыгрыша включает:

• Информацию о розыгрыше
• Список всех участников
• Данные победителей
• Временные метки

Формат экспорта: JSON с детальной структурой

🧹 Очистка данных

• Удаление старых завершенных розыгрышей
• Настраиваемый период хранения
• Безопасное удаление связанных данных

💻 Системная информация

• Версия Python и платформа
• Тип базы данных
• Количество администраторов
• Время работы системы

🛡️ Безопасность

🔐 Права доступа

• Только пользователи из ADMIN_IDS имеют доступ
• Проверка прав на каждую операцию
• Защита от несанкционированного доступа

✅ Валидация данных

• Проверка корректности Telegram ID
• Валидация номеров мест
• Защита от дублирования

📝 Логирование

• Все операции логируются
• История изменений
• Отслеживание действий администраторов

💡 Лучшие практики

🎯 Эффективное использование ручных победителей

1. Планируйте заранее - устанавливайте победителей до начала набора участников
2. Балансируйте - не назначайте всех мест вручную, оставляйте случайные
3. Документируйте - ведите учет ручных назначений
4. Проверяйте - убедитесь, что назначенные пользователи участвуют

📊 Мониторинг и анализ

1. Регулярно проверяйте статистику активности участников
2. Анализируйте популярность розыгрышей
3. Экспортируйте данные для внешнего анализа
4. Очищайте старые данные для оптимизации

🔧 Обслуживание системы

1. Регулярные бэкапы базы данных
2. Мониторинг производительности
3. Обновление зависимостей
4. Проверка логов на ошибки

🚨 Устранение неполадок

❌ Частые проблемы

Пользователь не найден при установке победителя:

• Проверьте корректность Telegram ID
• Убедитесь, что пользователь запускал бота

Место уже занято:

• Проверьте список установленных победителей
• Измените место или замените пользователя

Ошибка при проведении розыгрыша:

• Проверьте наличие участников
• Убедитесь, что ручные победители участвуют

🔧 Диагностика

1. Проверьте логи SQLAlchemy для ошибок БД
2. Используйте системную информацию для диагностики
3. Экспортируйте данные для анализа проблем

🎪 Демонстрация

Для демонстрации всех возможностей запустите:

python demo_admin.py
# или
make demo-admin

Демо создаст:

• Тестовых пользователей
• Несколько розыгрышей
• Установит ручных победителей
• Проведет розыгрыши
• Покажет статистику и отчеты

🎉 Готово!

Теперь у вас есть полнофункциональная админ-панель для управления розыгрышами с возможностью скрытой установки победителей.

Никто из участников не узнает о подстройке! 🎭✨