init commit
This commit is contained in:
502
ADMIN_GUIDE.md
Normal file
502
ADMIN_GUIDE.md
Normal file
@@ -0,0 +1,502 @@
|
||||
# <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 отчеты** со всей статистикой
|
||||
- **Детальная информация** по всем сущностям
|
||||
- **Готовые файлы** для анализа и архивирования
|
||||
|
||||
### 📊 Производительность
|
||||
- **Время ответа** системы
|
||||
- **Использование памяти** бота
|
||||
- **Статистика использования** админ-панели
|
||||
|
||||
---
|
||||
|
||||
## ⚙️ Настройки системы
|
||||
|
||||
### 🧹 Управление данными
|
||||
|
||||
**Очистка по периодам:**
|
||||
- **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. **Экспортируйте данные** для анализа проблем
|
||||
|
||||
## 🎪 Демонстрация
|
||||
|
||||
Для демонстрации всех возможностей запустите:
|
||||
|
||||
```bash
|
||||
python demo_admin.py
|
||||
# или
|
||||
make demo-admin
|
||||
```
|
||||
|
||||
Демо создаст:
|
||||
- Тестовых пользователей
|
||||
- Несколько розыгрышей
|
||||
- Установит ручных победителей
|
||||
- Проведет розыгрыши
|
||||
- Покажет статистику и отчеты
|
||||
|
||||
## 🎉 Готово!
|
||||
|
||||
Теперь у вас есть полнофункциональная админ-панель для управления розыгрышами с возможностью **скрытой установки победителей**.
|
||||
|
||||
**Никто из участников не узнает о подстройке!** 🎭✨
|
||||
Reference in New Issue
Block a user