FE Partnership Helper

Discord-бот для контроля над партнёрствами на вашем сервере.

Если не знаете, что такое партнёрство в СНГ-сегменте Discord, значит вам этот бот не нужен.

Возможности:

• Подсчёт партнёрств, в том числе за период оффлайна бота (боту не страшны отключения) и за всё время существования сервера (подсчёт старых партнёрств)
• Статистика по кол-ву партнёрств у конкретных сотрудников и у всего отдела в целом (включая красивые графики)
• Проверка соблюдения условий партнёрства, доступных боту (валидность ссылки-приглашения, кол-во участников, кулдаун)
• Можно установить условие "сервер может публиковаться только 1 раз в день" со сбросом в 00:00 по произвольному часовому поясу (например, МСК)
• Чёрный список вашего сервера
• Привязка партнёра к тексту, отслеживание партнёров и оповещение об их выходах.
• Оповещения партнёра об успешном партнёрстве со списком его серверов.
• Простая поверхностная кастомизация (изменение цветов эмбедов, картинок, эмодзи, некоторых фрагментов текста).

Бот создан @dtkdtk (DS: @dtkdtk0) для проекта 『FE』Federal Empire. Эта версия предназначается для одного сервера, и использовать этого бота на нескольких вы просто не сможете. Автор надеется, что вы самостоятельно развернёте этого бота на своём хостинге и будете пользоваться его трудом в своё удовольствие.

Если вам пригодился этот код, и он сделал ваш сервер лучше, — пожалуйста, поставьте ⭐ звёздочку этому репозиторию, если у вас есть аккаунт в GitHub.

FE_Partnership_Helper_DEMO.webm

Базовая настройка бота

ВНИМАНИЕ! Если у вас возникают проблемы на ЭТОМ этапе, не пишите мне и разбирайтесь самостоятельно.

Также напоминаю про существование бесплатных ИИ (DeepSeek, Qwen, ...), которые могут вам помочь.

Ставим платформу NodeJS

Этот бот работает на платформе NodeJS, и вы должны установить её на свой компьютер, чтобы запустить бота.

Скачать её можно здесь: https://nodejs.org/en/download . Нас интересует второй способ скачивания: Or get a prebuilt Node.js. Скачиваем, устанавливаем как любую другую программу, перезагружаем ПК.

Далее, открываем командную строку (поищите в интернете, как это сделать), и проверяем, что у нас всё успешно установлено. Нужно вписать 2 команды и проверить, что они выполняются успешно:

node -v
npm -v

Они должны выдать их версии (что-то типо этого; цифры могут немного не совпадать):

v24.1.0
11.6.4

Если выдаёт какую-то ошибку, добро пожаловать в гугл. Разберитесь сами, это несложно.

Хостинг

Чтобы бот работал 24/7, вам нужен хостинг, либо оставляйте свой компьютер на ночь. На телефон вы бота НЕ поставите, если вы не андроид хакер.

В данном гайде мы рассмотрим скачивание на обычный компьютер.

Скачиваем код бота

Для тех, кто не умеет работать с Git:

1. Зелёная кнопка <> Code, нажимаете и выбираете Download ZIP.
2. Создаёте где-нибудь папку для бота, называйте как хотите.
3. Извлекаете туда содержимое скачанного ZIP-файла.

Для умельцев: git clone

Далее, переименовываете файл .env.example в просто .env (да, это его название а не расширение).

И после этого, настраиваем бота в этом .env файле

Создаём аккаунт бота и генерируем токен

В Интернете полно гайдов, как создать аккаунт бота и получить его токен. Только параллельно с этим рассказывают, как написать его код, что нам не нужно (у нас код готов). Вот хороший текстовый гайд:

https://ru.guide.disnake.dev/prerequisites/creating-your-application

Обратите внимание: Вам обязательно нужна поддержка слеш-команд, поэтому указывать скоуп application.commands при создании ссылки на бота обязательно! А также, нужно выдать боту все интенты (intents) на странице Bot.

Однако, если Discord не починили баг, у вас может не быть кнопки "Copy" возле токена при его ПЕРВОМ создании, а будет лишь кнопка "Reset" (странно: а как я его в первый раз скопирую, если для этого его надо сбросить). В таком случае, сбросьте токен (на кнопку Reset) и потом только он появится. Скопируйте его и не теряйте.

Скопированный токен вставьте в параметр BOT_SECRET_TOKEN файла .env.

Если у вас украли аккаунт бота (если вы случайно слили его токен, то есть ключ от него), первым делом зайдите на тот же портал разработчика и сбросьте токен бота.

Настройка конфигурации бота

Все настройки бота находятся в файле .env. Скопируйте файл .env.example и переименуйте его в просто .env.

ВНИМАНИЕ! В .env у вас ПРИМЕР настроек, чтобы вы поняли, что куда совать. Читайте вдумчиво все комментарии. Все ID надо поменять.

О том, что и как настраивать, написано в следующем параграфе гайда. Но комментариев в .env должно хватить.

Запуск бота

Для пользователей Windows: Запускайте файл start.bat, откроется консоль бота. Рекомендую читать, что бот туда пишет. Чтобы остановить бота, просто закройте окно консоли.

Если вы хотите ускорить старт бота (и вы уже запускали start.bat когда-либо), используйте fast-start.bat.

Для пользователей MacOS: вам не повезло. Придётся самостоятельно разбираться, как запустить NodeJS-приложение на вашем компьютере. Для пользователей Linux: сами виноваты, что ставили пингвина. У вас не должно быть проблем с запуском NodeJS-приложения. Разбирайтесь сами.

Немного о конфигурации бота (файл .env)

В файле присутствуют понятные комментарии. Стоит лишь прояснить "права ролей".

Права ролей

Нужно настроить права (в боте) каждой из ролей.

Чтобы дать роли какие-либо права, нужно добавить в конфиг переменную вида...:

ROLE_ЗдесьАйди_PERMISSIONS = ЗдесьПрава

, где (ну логично же), ЗдесьАйди это ID роли, а ЗдесьПрава это список прав через запятую.

Права:

• партнёрство :: публиковать партнёрства
• смотреть_чужую_стату :: смотреть чужую статистику через /био-делегата
• смотреть_стату_отдела :: смотреть статистику отдела через /стата-делегации
• управлять_партнёрством :: изменять партнёра любого сервера через /редактировать-партнёрство, а также возможность обходить обязательные условия партнёрства. Обычно данное право также сопровождается правом управлять сообщениями в канале партнёрств.
• управлять_чс :: добавлять/удалять сервера из ЧС через /редактировать-партнёрство
• админ :: все вышеперечисленные права, а также права на все команды админа/разработчика. Этот уровень прав также имеют участники с правом Администратора.

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

ROLE_1338111583955456092_PERMISSIONS = админ
ROLE_1338110939974860880_PERMISSIONS = управлять_чс, управлять_партнёрством, смотреть_стату_отдела, смотреть_чужую_стату, партнёрство
ROLE_1338110006775513148_PERMISSIONS = управлять_партнёрством, смотреть_стату_отдела, смотреть_чужую_стату партнёрство
ROLE_1338110149352489044_PERMISSIONS = партнёрство

Файл bot-resources.json

Здесь лежат все "ресурсы", используемые ботом для оформления его ответов / сообщений. Обычно не требуется никаких настроек там. Однако, если хотите кастомизировать бота под свой проект, всегда пожалуйста.

Если удаляете оттуда рекламу, будьте добры поставить ⭐ этому репозиторию на Гитхабе.

Никаких объяснений, никакой документации к этому файлу не прилагается. По названиям полей понятно, за что они отвечают. Если что, это файл формата JSON, и он отличается от вашего .env, а ещё тут более строгие требования к оформлению. Если бот по непонятным причинам крашится после изменений в этом файле, проверьте соответствие формату JSON (посмотрите сами, погуглите, используйте ИИ). Вдруг вы кавычки где-нибудь не закрыли. Такое бывает.

Насчёт button_icons

В качестве значения принимается любой Unicode-эмодзи (например, 😀). Discord-коды НЕ принимаются (такие как :smile:, например); кроме кодов кастомных эмодзи (именно эмодзи вашего сервера, например: <:MyEmoji:128830189374873232>).

Немного о том, как работает бот

Учёт партнёрств

Бот автоматически проверяет партнёрства в канале, указанном в конфиге (параметр PARTNERSHIP_CHANNELS_ID). Проверяются следующие условия:

• Действительность ссылки-приглашения
• Является ли ссылка-приглашение временной?
• Количество участников (параметр REQUIREMENT_MINIMAL_MEMBERS, необяз.)
• Публиковался ли текст сегодня? (параметр REQUIREMENT_ONCE_PER_DAY, необяз.; можно настроить часовой пояс параметром TIMEZONE_UTC_OFFSET)
• Не добавлен ли сервер в ЧС

Если этот текст не проходит по условиям, бот упоминает делегата и просит удалить это партнёрство (с указанием причины) в течение 3 минут. Если делегат не удаляет этот текст самостоятельно, то его удаляет бот, отправляя уведомление в ЛС делегату (или в стафф-чат, если ЛС закрыто; настроить стафф-чат можно параметром STAFF_CHANNEL_ID).

Если у делегата есть право админ (или управлять_партнёрством), он может проигнорировать несоблюдение обязательных условий, нажав на кнопку "Игнорировать" под меню с ошибкой.

Следующие условия можно сделать мягкими (необязательными, но рекомендуемыми), через следующие параметры (установив значение TRUE - мягко, FALSE - обяз):

• Ссылка постоянная : SOFT_REQ_PERMANENT_INVITE (по умолчанию TRUE)
• Количество участников : SOFT_REQ_MINIMAL_MEMBERS (по умолчанию FALSE)
• Текст не публиковался сегодня : SOFT_REQ_ONCE_PER_DAY (по умолчанию FALSE)

При их несоблюдении текст НЕ удаляется, но в меню под ним будет предупреждение о несоблюдении мягких условий.

Если текст не проходит по любым условиям (и обязательным, и мягким), то меню под текстом будет с упоминанием делегата (чтобы тот обратил внимание). Иначе — без.

Если бот был оффлайн, то при его восстановлении он проверит последние 100 непроверенных партнёрств и удалит те из них, которые не проходят по условиям (разумеется, отправив уведомления в ЛС делегатам).

Счётчик партнёрств учитывает удаление партнёрств. Когда партнёрство удаляется самим делегатом / админом, счётчик партнёрств делегата уменьшается на 1.

Меню под партнёрством

Когда партнёрство публикуется, бот может ответить на него либо ошибкой (с указанием её причины), либо меню сервера. В этом меню будет основная информация о сервере (название, ID, кол-во участников, аватарка).

..а также, в этом меню можно назначить (привязать) партнёра (если он на сервере). Здесь есть правило: партнёр должен быть привязан ко всем его текстам. Если к тексту уже привязан партнёр, это всё равно не мешает привязать нового.

Оповещения партнёров в ЛС

Партнёрам приходят оповещения об успешном заключении партнёрства, с указанием всех их серверов.

Если у партнёра несколько серверов, то оповещения группируются. Без разницы, в каком порядке делегат публикует тексты и привязывает партнёра, важно, чтобы он делал это достаточно быстро и между каждыми привязками партнёра было не больше 30 секунд (это можно переопределить через параметр PARTNER_ALERTS_BATCH_DURATION).

Удаление старых текстов

Если не указано иного, старые тексты серверов удаляются (чтобы не засорять канал партнёрств), как только публикуется новый текст. Это значит, что в канале партнёрств будет висеть только один текст каждого сервера — самый актуальный (то есть последний опубликованный).

Однако, бот просматривает только последние 100 сообщений в канале, поэтому если старый текст где-то затерялся, он не будет удалён.

Эту функцию можно отключить, установив параметр DELETE_OLD_TEXTS на FALSE (по умолчанию / если не указан, то он TRUE).

Первоначальное (полноценное) сканирование

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

Если установить параметр GENERAL_SCAN_DELETE_UNFETCHED на TRUE, бот будет удалять ещё и все сообщения с недействительными ссылками.

Сканирование устойчиво к перезагрузкам бота; можете смело останавливать / перезагружать бота в это время.

Изменение / просмотр данных партнёрства; занесение в ЧС

Можно изменить данные партнёрства (в данный момент только партнёра, представляющего этот сервер) или просмотреть последние данные о сервере (название, кол-во участников, ID), с помощью команды /редактировать-партнёрство <цель>

Для этого нужно иметь ссылку-приглашение на сервер или ID этого сервера (и указать их в "цели"). Также, с этим сервером должно быть заключено партнёрство.

Через эту же команду можно занести указанный сервер в чёрный список (ЧС), чтобы с ним нельзя было заключить партнёрство. Если у вас есть право на занесение в ЧС, у вас будет кнопка в меню редактирования партнёрства.

Статистика делегата и всего отдела

Есть 2 команды для просмотра статистики:

• /био-делегата [юзер] :: просмотр своей статистики (если не указан юзер), или статистики указанного делегата (если у вас есть на это право).
• /стата-делегации :: просмотр статистики всего отдела (сумма статистик всех делегатов). Только если у вас есть на это право.

В статистиках есть лежачий график, помогающий визуально проанализировать изменение количества партнёрств.

Кастомизация бота на свой вкус

Если вы хотите поменять какие-либо эмодзи в боте, цвета, картинки, футеры, — можете открыть файл bot-resources.json и подредактировать там значения.

Логирование (логи)

Бот ведёт запись всех партнёрств, изменений, событий, и сбрасывает эти логи в папку logs.

Старые логи, которым больше 30 дней, автоматически удаляются. Вам они, вероятно, не нужны. Максимальный возраст логов (в сутках) можно переопределить через параметр LOGS_LIFE_DURATION. По умолчанию, 30. Если хотите, чтобы логи не удалялись, установите этот параметр на -1.

Рекомендую иногда просматривать важные события. Важные это те, которые помечены "level":"warn" (важные/предупреждения) или "level":"error" (ошибки). Используйте поиск (CTRL+F) в вашем любимом блокноте, ибо вручную читать всё это невозможно. Напоминаю, что каждое сообщение (строка) лога содержит много информации, но прежде всего вас интересует самая последняя — "msg":"ЗДЕСЬ_ЧЕЛОВЕЧЕСКОЕ_СООБЩЕНИЕ". А те, что ДО неё, это параметры и доп.данные: кто, когда и где.

Техническая помощь

Поломки и ошибки бота

Никто не застрахован от ошибок. Тем не менее, этот бот хорошо протестирован, и проблем возникнуть не должно.

Если у вас возникнут технические неполадки или вы заметите ошибку в боте, пишите мне в Discord: @dtkdtk0.

База данных и её перенос

База данных это просто несколько файлов в специальном JSON-формате NeDB.

Каждые (ровно) 24 часа с момента запуска бота, база автоматически само-сжимается для экономии места. Также, сжимается она и при запуске бота.

Если вы хотите перенести базу данных на хост, другой ПК, в другое расположение, — скопируйте папку database и всё. Больше ничего не требуется.

Если у вас в папке внезапно появились файл(ы) с расширением .db~, я вас поздравляю: У вас очень редкая ошибка сохранения БД. Напишите мне (DS: @dtkdtk0) и я вам помогу.

Также, рекомендую хоть иногда но делать резервные копии БД, чтобы сгладить горечь потери данных.

Юридическая информация

Автор этого кода — @dtkdtk. Вы можете свободно его копировать, использовать, модифицировать, но вы не можете присваивать себе авторство. Подробнее...

Copyright (c) 2025 dtkdtk, MIT License.