HELPER Discord Bot
← К списку Wiki
WELCOME CORE // VERIFICATION GATE // AVATAR CARD RENDERER

HELPER WELCOME ВЕРИФИКАЦИЯ И ПРИВЕТСТВИЕ /WELCOME_SETUP / WELCOME_TEST / WELCOME_ACCEPT / CARD CACHE / SAFE ROLE GATE

Welcome встречает нового участника, отправляет красивую welcome-карточку с аватаром, показывает правила и выдаёт доступ только после нажатия кнопки подтверждения. Система защищает кнопку от чужих кликов через welcome_accept:user_id, проверяет права бота, роль в иерархии Discord и автоматически удаляет старые неподтверждённые сообщения.

Показать картинки Путь новичка Welcome-карточка
/setupwelcome setup
10ssite sync loop
30mcleanup loop
24hcard/message TTL
Joinon_member_join отправляет welcome
Buttoncustom_id привязан к user_id
Rolesпроверка Manage Roles и hierarchy
Cardаватар + username + member count
Safedisabled-view без удаления настроек
// MODULE_PURPOSE

Что делает Welcome Core

Модуль приветствия отвечает за первый контакт с новым участником. Когда человек заходит на сервер, HELPER отправляет в welcome_channel персональное сообщение с кнопкой, карточкой и правилами. После подтверждения бот выдаёт одну или несколько ролей из настроек и заменяет сообщение на success-state.

01

Join event

on_member_join ждёт 1.5 секунды и запускает send_welcome_message.

02

Welcome card

Renderer скачивает аватар, рисует карточку 900×300 и кладёт её в cache.

03

Verify button

Кнопка имеет custom_id welcome_accept:user_id, поэтому чужой участник не подтвердит доступ.

04

Role gate

Бот проверяет Manage Roles, hierarchy, missing roles и выдаёт доступ безопасно.

// VISUAL_GUIDE

Больше информации картинками

Ниже полный сценарий: настройка, welcome-сообщение, карточка, кнопка, чужой клик, выдача ролей, success-сообщение, автоматическая очистка старых pending-сообщений и disabled-state.

01 / setupАдмин вводит /welcome_setup
💬
slash command/welcome_setup

Настроить приветствие и верификацию

Администратор выбирает канал приветствия и роль, которая будет выдаваться после нажатия кнопки.

/welcome_setup welcome_channel:#верификация member_role:@Участник
validate roles → save welcome_settings.json
02 / welcome messageНовичок видит welcome
👋
#верификацияДОБРО ПОЖАЛОВАТЬ

👋 ДОБРО ПОЖАЛОВАТЬ!

@Player, рады видеть тебя на сервере. Чтобы получить доступ, ознакомься с правилами и нажми кнопку.

WELCOME CARD / AVATAR / MEMBER #
✅ ПРИНЯТЬ ПРАВИЛА
03 / rendered cardWelcome-карточка
900×300Pillowcache 24h
Аватарdisplay_avatar 256×256, круглая маска и glow
image
Usernameemoji очищаются для Pillow, текст режется безопасно
text
Member countплашка с номером участника на сервере
count
Accentcard_accent_color или custom_color
style
04 / button checkКнопка только для новичка

welcome_accept:USER_ID

Если кнопку нажал другой участник, бот отвечает: “Это приветствие предназначено для другого участника”.

inter.user.id == target_user_id
05 / role issueВыдача доступа

✅ ВЕРИФИКАЦИЯ ПРОЙДЕНА

Бот выдаёт все настроенные роли, показывает success-embed и удаляет pending-record из welcome_messages.json.

Роль@Участник
Статусaccess granted
Lockguild:user
Recordremoved
06 / duplicate protectionУдаление дублей

prevent_duplicate_welcome

Если пользователь перезашёл, бот находит старое pending-сообщение, удаляет его и отправляет новое.

delete_previous_welcome_message(member)
07 / test commandТест для админа

/welcome_test

Администратор может отправить welcome-сообщение для себя и проверить канал, роль, карточку и кнопку.

send_welcome_message(inter.user)
08 / disabledМодуль выключен

🔌 МОДУЛЬ ВЕРИФИКАЦИИ ОТКЛЮЧЁН

Выдача ролей временно заблокирована. Кнопка заменяется на красный disabled-state.

🔌 ВЕРИФИКАЦИЯ ОБЕСТОЧЕНА
// DISCORD_COMMANDS

Команды Discord

У модуля две админ-команды. Обычные пользователи не используют slash-команды: они просто нажимают кнопку в welcome-сообщении.

setup/welcome_setup
/welcome_setup welcome_channel:#верификация member_role:@Участник

Сохраняет welcome_channel, member_role, member_role_ids, включает защиту от дублей и задаёт очистку старых pending-сообщений через 24 часа.

test/welcome_test
/welcome_test

Отправляет тестовое welcome-сообщение для самого администратора. Удобно проверить картинку, кнопку, роль и disabled-state.

button✅ ПРИНЯТЬ ПРАВИЛА
custom_id = "welcome_accept:{user_id}"

Persistent-кнопка без отдельной View-класса. Обрабатывается listener-ом on_button_click.

errorsКомандные ошибки
MissingPermissions → "Команда доступна только администраторам"

Обе команды требуют Administrator и работают только на сервере.

// WELCOME_FLOW

Путь новичка от входа до роли

1Join

member

2Settings

guild

3Card

render

4Message

pending

5Button

verify

6Role

access

A

Guild-safe

Все настройки берутся из welcome_settings.json по guild_id. Серверы не смешиваются.

B

Verify lock

На время выдачи роли создаётся async lock по ключу guild_id:user_id, чтобы двойной клик не ломал процесс.

C

Success replace

После подтверждения старое welcome-сообщение может быть заменено или удалено, а JSON-record очищается.

// PLAYER_FLOW

Что видит новый участник

first contactКрасивое приветствие

👋 Добро пожаловать

Пользователь видит персональное сообщение: ник, упоминание сервера, правила, баннер и кнопку доступа.

welcome_channel
wrong userЧужая кнопка не работает

❌ Это приветствие предназначено для другого участника

Кнопка содержит ID новичка. Другой пользователь не сможет выдать себе роль через чужое сообщение.

inter.user.id != target_user_id
already verifiedЕсли роль уже есть

✅ Доступ уже активирован

Если пользователь уже имеет все роли, success_embed покажет already_verified и не будет повторно выдавать роли.

already_verified = not roles_to_add
disabledЕсли модуль отключён

🔌 Верификация обесточена

Пользователь получает embed, что выдача ролей временно заблокирована администратором.

welcome_disabled_status_v2
// ADMIN_FLOW

Что делает администратор

01

Выбирает канал

welcome_channel — место, куда бот отправляет welcome-сообщения.

02

Выбирает роли

member_role или member_role_ids — роли доступа после подтверждения.

03

Проверяет права

У бота должен быть Manage Roles, а выдаваемые роли должны быть ниже роли бота.

04

Запускает тест

/welcome_test показывает, как увидит сообщение новый пользователь.

Практический совет

Перед запуском подними роль HELPER выше роли @Участник. Иначе Discord не позволит боту выдать доступ, даже если настройки правильные.

// DASHBOARD_SETTINGS

Настройка на сайте

Dashboard хранит настройки в data/welcome_settings.json. Cog каждые 10 секунд смотрит deploy_requested, сбрасывает deploy attempts, фиксирует last_deploy_at и держит настройки в mtime-cache.

channelsКанал и роли
welcome_channelосновной канал приветствия.
welcome_channel_id / WELCOME_CHANNEL_IDaliases канала.
channel_idlegacy alias канала.
member_roleглавная роль после проверки.
member_role_idsнесколько ролей после проверки.
verified_role_ids / welcome_role_idsaliases ролей.
visual settingsОформление
custom_titleзаголовок welcome embed.
custom_descописание с шаблонами member/guild.
custom_button_textтекст кнопки подтверждения.
custom_footerfooter welcome embed.
custom_colorцвет embed и fallback accent.
custom_banner / welcome_bannerбаннер welcome или BannerManager.
card_accent_coloraccent цвета welcome-карточки.
json previewwelcome_settings.json
data/welcome_settings.json
{ "123456789": { "welcome_channel": "111", "member_role": "222", "member_role_ids": ["222", "333"], "prevent_duplicate_welcome": true, "welcome_cleanup_hours": 24, "custom_title": "👋 ДОБРО ПОЖАЛОВАТЬ!", "custom_button_text": "ПРИНЯТЬ ПРАВИЛА", "custom_color": "#00F0FF", "custom_banner": "https://site/banner.png", "deploy_requested": true } }
module statemodule_states.json
welcomeосновной ключ.
verification / verifyaliases верификации.
verifкороткий alias.
welcome_verificationединый alias.
верификация / приветствиерусские aliases.
// CARD_RENDERER

Welcome-карточка с аватаром

Карточка генерируется через Pillow: фон, glow, сетка, круглый аватар, username, название сервера и номер участника. Renderer использует ProximaNova при наличии, а если шрифты не найдены — системные DejaVu/Liberation.

layoutСтруктура картинки

900×300 px

Левая часть — аватар с cyan glow. Правая — крупный ник, сервер и плашка member count.

AVATAR • USERNAME • MEMBER #0420
CARD_STYLE_VERSION = v4_no_status_single_banner
cacheКэширование
get_avatar_hashhash URL аватара.
get_cache_pathguild/user/avatar_hash/member_count/style_version.
CACHE_TTL_HOURS24 часа.
cleanup_old_cacheудаляет старые картинки пользователя.
render_semaphoreмаксимум 2 render-задачи одновременно.
downloadАватар

aiohttp download

Renderer сначала пытается получить свежий display_avatar через bot.fetch_user, потом скачивает PNG 256×256.

display_avatar.with_size(256).with_static_format("png")
fallbackЕсли картинка не создалась

Без падения модуля

Если аватар не скачался или renderer упал, welcome embed всё равно отправляется без image attachment.

image_buffer = None → send embed only
// ROLE_GATE

Безопасная выдача ролей

Перед выдачей бот собирает roles_to_add, missing_role_ids и all_configured_roles. Если у бота нет Manage Roles или роль выше/равна роли бота, пользователь получает понятную ошибку.

checksПроверки перед add_roles
role_idsдолжны быть настроены, иначе просит /welcome_setup.
member resolveполучает disnake.Member из inter.user или fetch_member.
Manage Rolesбез права выдача невозможна.
role hierarchyвыдаваемые роли должны быть ниже top_role бота.
missing rolesесли часть role_id не найдена, это добавляется в success warning.
success embedПосле проверки

✅ ВЕРИФИКАЦИЯ ПРОЙДЕНА

Текст success_title / success_desc / success_color можно оформить на сайте.

build_success_embed(member, role_mentions, config)
// CLEANUP_AND_CACHE

Очистка старых сообщений и кэша

pending cleanuppending_cleanup_loop

Каждые 30 минут

Loop читает welcome_messages.json, находит pending-сообщения старше welcome_cleanup_hours и удаляет их.

DEFAULT_CLEANUP_HOURS = 24
duplicate cleanupdelete_previous_welcome_message

Защита от дублей

Если prevent_duplicate_welcome включён, бот удаляет старое pending-сообщение этого пользователя перед отправкой нового.

key = guild_id:user_id
cache dirdata/cache/welcome
CACHE_DIRdata/cache/welcome.
CACHE_TTL_HOURS24 часа.
CARD_STYLE_VERSIONv4_no_status_single_banner.
cleanup_old_cacheудаляет старые файлы welcome_card_*.png.
site syncsite_sync_loop

Каждые 10 секунд

Сайт может поставить deploy_requested. Loop сбрасывает флаг и записывает last_deploy_at/last_deploy_error.

MAX_DEPLOY_ATTEMPTS = 5
// MESSAGES_STORE

Что хранится в welcome_messages.json

Эта запись нужна, чтобы удалить старый welcome-дубль или очистить неподтверждённое сообщение через TTL.

json previewwelcome_messages.json
data/welcome_messages.json
{ "123456789:222222222": { "guild_id": 123456789, "user_id": 222222222, "channel_id": 111111111, "message_id": 333333333, "sent_at": 1717440000.0, "state": "pending" } }
state lifecycleЖизненный цикл записи
set_welcome_message_recordпосле отправки welcome.
remove_welcome_message_recordпосле подтверждения или удаления.
replace_welcome_messagesмассовое обновление после cleanup.
JsonCachemtime-cache для чтения без лишних дисковых операций.
// SAFE_DISABLED

Если модуль выключен

Отключение через module_states.json не удаляет welcome_settings.json, welcome_messages.json и кэш карточек. Оно только блокирует выдачу ролей и заменяет кнопку на безопасный красный disabled-state.

disabled buttonЧто видит игрок
🔌
safe stateWelcome disabled

🔌 МОДУЛЬ ВЕРИФИКАЦИИ ОТКЛЮЧЁН

Администратор отключил систему приветствия/верификации в панели управления. Выдача ролей временно заблокирована.

🔌 ВЕРИФИКАЦИЯ ОБЕСТОЧЕНА
safe dataЧто сохраняется
welcome_settings.jsonканал, роли, тексты, баннеры и цвета остаются.
welcome_messages.jsonpending-записи не удаляются из-за выключения.
cache/welcomeготовые карточки остаются до TTL.
after enableпосле включения кнопка снова выдаёт роли.
// DEVELOPER_MAP

Карта технической логики

filesФайлы модуля
__init__.py

Экспортирует WelcomeCog и setup.

cog.py

WelcomeCog, on_member_join, on_button_click, welcome_setup, welcome_test, cleanup loops и BannerManager hook.

renderer.py / cards.py

WelcomeCardRenderer: avatar download/cache и генерация welcome-карточки через Pillow.

settings.py

JsonCache, module state aliases, welcome_settings, welcome_messages и update helpers.

embeds.py / views.py

disabled embed/view, success embed и welcome verify button.

utils.py

parse_bool, safe_int, parse_color, normalize_url, resolve_role_ids, template formatting и cache helpers.

constantsГлавные константы
👋
SETTINGS_FILEwelcome_settings.json
💬
MESSAGES_FILEwelcome_messages.json
🔌
MODULES_FILEmodule_states.json
🖼️
CACHE_DIRcache/welcome
⏱️
CLEANUP24h / 30m loop
⚠️
DEPLOY5 attempts
button logicПроверка кнопки
on_button_clickслушает custom_id welcome_accept:.
target_user_idберётся из custom_id после двоеточия.
verify lockasync lock на guild_id:user_id.
resolve_role_idsподдерживает member_role_ids и legacy aliases.
member.add_rolesвыдача ролей после всех проверок.
banner logicБаннеры
on_banner_updatedреагирует на welcome / verification / verify.
BannerManagerCog.get_bannerберёт баннер, если cog загружен.
custom_bannerлокальный баннер из настроек.
DEFAULT_BANNERfallback https://i.imgur.com/t54TUqH.jpeg.
// TROUBLESHOOTING

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

/welcome_setup не сохраняет настройку

Проверьте, что команда вызвана администратором, канал текстовый, бот может отправлять сообщения и embed, а роль ниже роли бота.

Welcome-сообщение не отправляется

Проверьте welcome_channel / WELCOME_CHANNEL_ID, активность модуля welcome и права бота в канале.

Картинка не появилась

Проверьте загрузку аватара, Pillow/aiohttp и папку data/cache/welcome. Embed может отправиться без картинки, если renderer не смог её создать.

Роль не выдаётся

У бота должно быть Manage Roles, а выдаваемая роль должна быть ниже top_role бота. Также проверьте member_role_ids.

Пользователь нажал чужую кнопку

Это заблокировано: custom_id содержит user_id новичка, и бот сравнивает его с inter.user.id.

Старые welcome-сообщения висят в канале

Проверьте prevent_duplicate_welcome и welcome_cleanup_hours. pending_cleanup_loop работает каждые 30 минут.

После сайта ничего не поменялось

Проверьте deploy_requested, deploy_attempts, last_deploy_error и правильность ключей welcome_settings.json.

Модуль выключен, но настройки остались

Так и должно быть: module_states блокирует выдачу ролей, но настройки, pending-записи и кэш не удаляются.

// WIKI_NAVIGATION

Вернуться к списку Wiki

Ты дошёл до конца страницы Welcome / Verification. Можно вернуться в общий центр документации, открыть Dashboard или подняться наверх к началу этой страницы.

← К списку Wiki Dashboard Наверх ↑