new_lottery_bot/docs/ADMIN_MANAGEMENT_SYSTEM.md

Система управления администраторами

Описание

Реализована двухуровневая система управления правами администраторов:

1. Главные администраторы (Super Admin) - указаны в переменной ADMIN_IDS в .env

   • Имеют полные права на управление системой
   • Могут назначать и удалять любых администраторов
   • Не могут быть удалены через интерфейс (только через .env)

2. Назначенные администраторы - добавлены через админ-панель

   • Имеют права администратора в боте
   • Не могут управлять другими администраторами
   • Могут быть удалены главными администраторами

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

Иерархия прав

Главный администратор (.env)
  ├─ Может управлять админами (добавлять/удалять)
  ├─ Может управлять розыгрышами
  ├─ Может управлять пользователями
  └─ Полный доступ ко всем функциям
  
Назначенный администратор
  ├─ НЕ может управлять администраторами
  ├─ Может управлять розыгрышами
  ├─ Может управлять пользователями
  └─ Имеет стандартные права админа

Проверочные механизмы

• Функция is_super_admin(user_id) - проверяет, является ли пользователь главным администратором
• Функция is_admin(user_id) - проверяет, является ли пользователь администратором (любого уровня)
• Все операции с администраторами доступны ТОЛЬКО главным администраторам

Доступ в админ-панели

Путь к управлению администраторами:

Админ-панель → ⚙️ Настройки → 👑 Управление админами (опция видна ТОЛЬКО для главных администраторов)

Меню управления администраторами:

1. ➕ Назначить админа

   • Поиск пользователя по Telegram ID или имени
   • Проверка, что пользователь
     • Существует в системе
     • Не является главным администратором (.env)
     • Еще не является администратором
   • Подтверждение перед назначением

2. ➖ Удалить админа

   • Показывает список только назначенных администраторов
   • Главные администраторы (.env) не отображаются и не могут быть удалены
   • Подтверждение перед удалением

3. 📋 Список админов

   • Показывает двухцветный список:
     • 🔴 Главные администраторы (.env) - красные маркеры
     • 🟠 Назначенные администраторы - оранжевые маркеры
   • Для каждого администратора показывается:
     • Имя (если указано)
     • Username (если есть)
     • Telegram ID

Изменение в основной панели

В основной административной панели добавлена кнопка 👑 Управление админами (видна только для главных администраторов).

Технические детали

Состояния (States)

admin_management_action      # Выбор действия
admin_add_search             # Поиск пользователя для назначения
admin_add_confirm            # Подтверждение назначения
admin_remove_select          # Выбор админа для удаления
admin_remove_confirm         # Подтверждение удаления

Обработчики

• manage_admins_menu() - главное меню управления админами
• list_admins_view() - показать список всех администраторов
• add_admin_start() - начать процесс добавления админа
• search_user_for_admin() - поиск и подтверждение пользователя
• confirm_add_admin() - финальное назначение прав админа
• remove_admin_start() - начать процесс удаления админа
• confirm_remove_admin() - финальное удаление прав админа

Данные в БД

В таблице users используется поле:

• is_admin (Boolean, default=False) - флаг, указывающий на то, что пользователь является администратором

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

Пример 1: Назначить админа

1. Главный администратор открывает Админ-панель
2. Нажимает на ⚙️ Настройки
3. Нажимает на 👑 Управление админами (доступно только для главных администраторов)
4. Нажимает на ➕ Назначить админа
5. Вводит Telegram ID пользователя (например, 123456789) или имя
6. Система показывает информацию о пользователе
7. Подтверждает назначение кнопкой ✅ Да, назначить
8. Пользователь получает права администратора

Пример 2: Удалить права админа

1. Главный администратор открывает Админ-панель
2. Нажимает на ⚙️ Настройки
3. Нажимает на 👑 Управление админами
4. Нажимает на ➖ Удалить админа
5. Выбирает администратора из списка назначенных админов
6. Система запрашивает подтверждение
7. После подтверждения администратор теряет права

Пример 3: Просмотра списка администраторов

1. Главный администратор открывает Админ-панель
2. Нажимает на ⚙️ Настройки
3. Нажимает на 👑 Управление админами
4. Нажимает на 📋 Список админов
5. Видит:
   • Главные администраторы из .env (🔴 красные)
   • Назначенные администраторы (🟠 оранжевые)

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

1. Защита главных администраторов

   • Главные администраторы из .env не могут быть удалены через интерфейс
   • Для изменения главного администратора нужно отредактировать .env

2. Ограничение прав

   • Только главные администраторы могут управлять правами
   • Назначенные администраторы полностью исключены из управления

3. Подтверждение критических операций

   • Все операции с администраторами требуют явного подтверждения
   • Система показывает полную информацию перед назначением/удалением

4. Логирование

   • Все операции логируются в системный лог (можно добавить)

Возможные расширения

1. Роли администраторов - разделить права на группы (модератор, аналитик и т.д.)
2. История действий - отслеживать, кто и когда менял права
3. Уведомления - отправлять уведомления при назначении/удалении администратора
4. Экспорт списка админов - возможность скачать список всех администраторов

Обновления код еще раз

В коде реализованы следующие проверки:

# Проверка на главного администратора
def is_super_admin(user_id: int) -> bool:
    return user_id in ADMIN_IDS

# Проверка на любого администратора (главного или назначенного)
def is_admin(user_id: int) -> bool:
    return user_id in ADMIN_IDS

Обе функции используются для управления доступом к различным функциям админ-панели.