new_lottery_bot/ADMIN_PANEL_STRUCTURE.md

# Структура Админ Панели

## Главное меню бота

### Для всех пользователей:
- **🎲 Активные розыгрыши** (`active_lotteries`) - Просмотр всех активных розыгрышей
- **📝 Зарегистрироваться** (`start_registration`) - Регистрация в системе (скрывается для зарегистрированных и админов)

### Для администраторов:
- **⚙️ Админ панель** (`admin_panel`) - Вход в админ панель
- **➕ Создать розыгрыш** (`create_lottery`) - Быстрое создание розыгрыша

---

## Админ панель (`admin_panel`)

### Основные разделы:

#### 1. 🎲 Управление розыгрышами (`admin_lotteries`)
Раздел для полного управления розыгрышами.

**Доступные действия:**
- **➕ Создать розыгрыш** (`admin_create_lottery`) - Создание нового розыгрыша (пошаговый процесс)
- **📝 Редактировать розыгрыш** (`admin_edit_lottery`) - Редактирование существующих розыгрышей
- **🎭 Настройка отображения победителей** (`admin_winner_display_settings`) - Настройка способа отображения победителей (номер счета/имя)
- **📋 Список всех розыгрышей** (`admin_list_all_lotteries`) - Просмотр всех розыгрышей (активные и завершенные)
- **🏁 Завершить розыгрыш** (`admin_finish_lottery`) - Принудительное завершение розыгрыша
- **🗑️ Удалить розыгрыш** (`admin_delete_lottery`) - Удаление розыгрыша из системы

**Состояния (FSM):**
- `lottery_title` - Ввод названия розыгрыша
- `lottery_description` - Ввод описания
- `lottery_prizes` - Ввод списка призов
- `lottery_confirm` - Подтверждение создания

---

#### 2. 👥 Управление участниками (`admin_participants`)
Раздел для управления участниками розыгрышей.

**Доступные действия:**
- **➕ Добавить участника** (`admin_add_participant`) - Добавление одного участника вручную
- **📥 Массовое добавление (ID)** (`admin_bulk_add_participant`) - Массовое добавление по Telegram ID
- **🏦 Массовое добавление (счета)** (`admin_bulk_add_accounts`) - Массовое добавление по номерам счетов
- **➖ Удалить участника** (`admin_remove_participant`) - Удаление одного участника
- **📤 Массовое удаление (ID)** (`admin_bulk_remove_participant`) - Массовое удаление по Telegram ID
- **🏦 Массовое удаление (счета)** (`admin_bulk_remove_accounts`) - Массовое удаление по номерам счетов
- **👥 Все участники** (`admin_list_all_participants`) - Список всех зарегистрированных участников
- **🔍 Поиск участников** (`admin_search_participants`) - Поиск участников по критериям
- **📊 Участники по розыгрышам** (`admin_participants_by_lottery`) - Просмотр участников конкретного розыгрыша
- **📈 Отчет по участникам** (`admin_participants_report`) - Детальный отчет об участии

**Состояния (FSM):**
- `add_participant_lottery` - Выбор розыгрыша для добавления
- `add_participant_user` - Выбор пользователя
- `add_participant_bulk` - Массовый ввод ID
- `add_participant_bulk_accounts` - Массовый ввод счетов
- `remove_participant_lottery` - Выбор розыгрыша для удаления
- `remove_participant_user` - Выбор пользователя для удаления
- `participant_search` - Поиск участников

---

#### 3. 👑 Управление победителями (`admin_winners`)
Раздел для управления победителями розыгрышей.

**Доступные действия:**
- **👑 Установить победителя** (`admin_set_manual_winner`) - Ручная установка победителя (без розыгрыша)
- **📝 Изменить победителя** (`admin_edit_winner`) - Изменение данных победителя
- **❌ Удалить победителя** (`admin_remove_winner`) - Удаление победителя
- **📋 Список победителей** (`admin_list_winners`) - Просмотр всех победителей
- **🎲 Провести розыгрыш** (`admin_conduct_draw`) - Автоматическое проведение розыгрыша

**Состояния (FSM):**
- `set_winner_lottery` - Выбор розыгрыша для установки победителя
- `set_winner_place` - Выбор места (1, 2, 3...)
- `set_winner_user` - Выбор пользователя-победителя

---

#### 4. 📊 Статистика (`admin_stats`)
Раздел с общей статистикой системы.

**Показывает:**
- Количество пользователей
- Количество зарегистрированных пользователей
- Общее количество розыгрышей
- Количество активных розыгрышей
- Количество завершенных розыгрышей
- Общее количество участий

**Кнопки:**
- **🔄 Обновить** (`admin_stats`) - Обновление статистики
- **🔙 Назад** (`admin_panel`) - Возврат в главное меню админ панели

---

#### 5. ⚙️ Настройки (`admin_settings`)
Раздел с настройками системы и утилитами.

**Доступные действия:**
- Настройки отображения
- Управление базой данных
- Экспорт данных
- Системные настройки

---

## Навигация

### Кнопки возврата:
- **🔙 Назад** (`admin_panel`) - Возврат в главное меню админ панели
- **🔙 Назад** (`back_to_main`) - Возврат в главное меню бота

### Кнопки отмены:
- **❌ Отмена** - Отмена текущей операции и возврат в предыдущее меню

---

## Обработка callback'ов

### Главный роутер (`main.py`):
- `admin_panel` - Открытие админ панели (через контроллер)
- `back_to_main` - Возврат в главное меню

### Админ роутер (`admin_panel.py`):
- Все callback'и начинающиеся с `admin_*`
- Вся логика управления розыгрышами, участниками, победителями
- FSM состояния для многошаговых операций

### Порядок подключения роутеров:
1. **router** (main) - команды `/start`, `/help`, основные callback'и
2. **admin_router** - все админские операции
3. **registration_router** - регистрация пользователей
4. **chat_router** (ПОСЛЕДНИЙ) - обработка всех необработанных сообщений

---

## Проверка прав доступа

Все админские handler'ы проверяют права доступа:
```python
if not is_admin(callback.from_user.id):
    await callback.answer("❌ Недостаточно прав", show_alert=True)
    return
```

ID администраторов хранятся в `src/core/config.py` в переменной `ADMIN_IDS`.