✅ Система разрешений на команды

PBModular включает в себя гибкую систему разрешений, позволяющую контролировать, какие пользователи могут выполнять определенные команды или запускать определенные обработчики. Это включает в себя как определяемые разработчиком настройки по умолчанию, так и переопределение пользователем (владельцем бота).

Роли и Идентификаторы пользователей

Разрешения могут быть предоставлены на основании:

1. Роли: Предопределенные категории пользователей.
   • owner: Владелец бота, определяемый параметром config.owner (может быть именем пользователя или идентификатором пользователя). Владелец неявно имеет доступ ко всем командам, независимо от ограничений.
   • chat_owner: Создатель/владелец чата, в котором используется команда (применяется только в группах/каналах).
   • chat_admins: Администраторы чата, в котором используется команда (применяется только в группах/каналах).
   • all: Любой пользователь (фактически означает отсутствие ограничений на основе роли). Используется в основном для переопределения владельца бота, по умолчанию.
   • Самостоятельные роли: Владелец бота потенциально может определять и назначать пользователям пользовательские роли через основной модуль или управление базой данных, которые затем могут быть использованы в настройках прав. (Подробнее об этом читайте в функциях основного модуля).
2. Специфические пользователи:.
   • @username: Позволяет конкретному пользователю, идентифицированному по его имени пользователя.
   • Идентификатор пользователя: Потенциально разрешает определенный ID пользователя (проверьте детали реализации в __check_role).

Установка разрешений по умолчанию (@allowed_for)

Как разработчик модуля, вы можете установить разрешения по умолчанию, необходимые для использования обработчика, используя декоратор @allowed_for из base.module. Этот декоратор должен быть размещен перед декораторами обработчиков (@command, @callback_query, @message).

• Он принимает один идентификатор роли/пользователя в виде строки или список разрешенных ролей/идентификаторов.
• Если пользователь удовлетворяет любому из условий (соответствует роли в списке, является владельцем бота и т.д.), ему разрешается доступ.
• Если @allowed_for не используется в обработчике, то по умолчанию он будет доступен всем пользователям (если только владелец бота не переопределит его для определенных команд).

Примеры:

# Внутри вашего класса BaseModule или ModuleExtension
from base.module import command, callback_query, allowed_for
from pyrogram import filters

# Команда только для администраторов чата и владельца бота
@allowed_for("chat_admins")
@command("kick", filters=filters.group)
async def kick_cmd(self, client: Client, message: Message):
    """Удаляет пользователя из группы."""
    # ... реализация ...

# Команда, доступная администраторам чата ИЛИ определенному пользователю @someHelperBot
@allowed_for(["chat_admins", "@someHelperBot"])
@command("warn", filters.group)
async def warn_cmd(self, client: Client, message: Message):
    """Предупреждает пользователя."""
    # ... реализация ...

# Запрос обратного вызова только для владельца(ов) бота
@allowed_for("owner")
@callback_query(filters.regex("^admin_action:"))
async def admin_callback(self, client: Client, cb: CallbackQuery):
    """Обрабатывает важные действия администратора с помощью callback."""
    # ... реализация ...

# Команда без особых ограничений (по умолчанию доступна для "всех")
@command("ping")
async def ping_cmd(self, _, message: Message):
    """Простая команда ping."""
    # ... реализация ...

Переопределения владельца бота

Владелец бота обычно имеет команды (предоставляемые основным модулем) для управления разрешениями:

• /allow_cmd <команда> <роль_или_пользователь>: Предоставляет разрешение на определенную команду роли или пользователю.
• /disallow_cmd <команда> <роль_или_пользователь>:отменяет разрешение.
• Эти переопределения обычно хранятся в основной базе данных бота (таблица db.CommandPermission) и имеют приоритет над значениями по умолчанию, установленными @allowed_for для команд.

TIP

• В настоящее время переопределение владельца бота через /allow_cmd обычно применяется только к обработчикам, зарегистрированным с помощью @command. Разрешения, установленные через @allowed_for для обработчиков @callback_query или @message, как правило, не могут быть переопределены через команды бота и остаются фиксированными настройками разработчика.

• Владелец бота всегда обходит проверку разрешений

Используйте @allowed_for с умом, чтобы защитить важные команды, сохраняя при этом доступ к общим функциям. Полагайтесь на документацию и страницы справки, чтобы информировать пользователей о доступности команд.