HELPER Discord Bot
← К списку Wiki
REPUTATION CORE // SOCIAL KARMA // ROLE SYNC QUEUE

HELPER REPUTATION СОЦИАЛЬНАЯ КАРМА /REP / KARMA / REP_TOP / RANKS / SHOP DISCOUNTS / SQLITE WAL

Reputation превращает обычные плюсы и минусы в живую социальную экономику сервера. Игроки оценивают друг друга, получают очки влияния, ранги, скидки магазина и Discord-роли. Владелец настраивает ранги через сайт, а HELPER безопасно синхронизирует роли через очередь, не перегружая Discord API.

Показать картинки Путь голоса Ранги и скидки
12hvote cooldown
10ssite sync loop
10krole queue size
5kusers per resync
Votesatomic /rep add-sub в SQLite
Cooldown12 часов на голосующего
Ranksmin / discount / color / role_id
Shopget_discount для экономики
Rolesочередь выдачи и снятия рангов
// MODULE_PURPOSE

Что делает Reputation

Это социальный рейтинг сервера. У каждого пользователя есть очки влияния внутри конкретного guild_id. Игроки могут повышать или понижать репутацию другим участникам, но не себе и не ботам. Ранг влияет на embed-цвет, скидку магазина, силу голоса и роль Discord.

01

Голос

Игрок вызывает /rep и выбирает “Повысить” или “Понизить”.

02

Вес

Система смотрит очки голосующего и считает силу изменения.

03

Ранг

Цель получает новый статус, цвет, скидку и возможную роль.

04

История

Каждый голос сохраняется в reputation_events с итоговыми очками.

// VISUAL_GUIDE

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

Ниже показан полный сценарий: голос, cooldown, социальный паспорт, топ сервера, настройка рангов, очередь ролей, скидка магазина, миграция старой базы и safe disabled-state.

01 / voteИгрок ставит репутацию
💬
slash command/rep

Параметры команды

user: @Alex
действие: Повысить (+) / Понизить (-)
Оценить влияние пользователя
02 / result cardКарточка изменения влияния
🎭
public embedИЗМЕНЕНИЕ ВЛИЯНИЯ

🎭 ИЗМЕНЕНИЕ ВЛИЯНИЯ

Игрок Sasi повысил репутацию Alex. Роль ставится в очередь, если у ранга есть role_id.

Изменение+5 pts
Итог126 pts
Статус🌟 ДОВЕРЕННЫЙ
Синхронизацияqueued
03 / cooldownЕсли голос ещё не восстановился

⏳ Голос восстанавливается

У каждого голосующего есть 12-часовой cooldown, чтобы рейтинг нельзя было накрутить спамом.

Подожди: 8ч 32м
04 / karma passportСоциальный паспорт
📋
/karmaСОЦИАЛЬНЫЙ ПАСПОРТ

📋 СОЦИАЛЬНЫЙ ПАСПОРТ

Показывает статус, очки влияния, экономику и шкалу доверия.

Статус👑 ЛЕГЕНДА
Очки648 pts
ЭкономикаСкидка 30%
Шкала███████████▒▒▒▒
05 / topТоп сервера
/rep_toplimit 1-20guild only
1. @Mira710 pts · 👑 ЛЕГЕНДА
#1
2. @Alex126 pts · 🌟 ДОВЕРЕННЫЙ
#2
3. @Neo48 pts · 🔰 АКТИВНЫЙ
#3
4. @Ghost-25 pts · 🌚 Изгой
low
06 / dashboardНастройка ранга
Dashboardrank editor
Название🌟 ДОВЕРЕННЫЙ
name
Минимум очков101
min
Скидка магазина15%
shop
Роль@Trusted
role_id
07 / role syncОчередь ролей

🎖️ Роль поставлена в очередь

Бот снимет старые роли репутации и выдаст новую, если у него есть Manage Roles и роль ниже роли бота.

role_sync_queue.put_nowait(...)
08 / disabledМодуль отключён

🔌 МОДУЛЬ ОБЕСТОЧЕН

Команды не меняют очки, пока администратор не включит “Социальную Карму” в панели управления.

🔌 РЕПУТАЦИЯ ОТКЛЮЧЕНА
// DISCORD_COMMANDS

Команды Discord

Команды разделены на игровые, пользовательские и административные. Все команды проверяют состояние модуля, работают только на сервере и не смешивают данные разных guild_id.

player vote/rep
/rep user:@Player действие:Повысить

Повышает или понижает социальную репутацию выбранного участника. Нельзя оценивать себя и ботов. Slash cooldown — 5 секунд, а голосовой cooldown — 12 часов.

passport/karma
/karma user:@Player

Показывает социальный паспорт: ранг, очки, скидку/наценку и визуальную шкалу доверия. Если user пустой — показывает профиль вызвавшего.

rating/rep_top
/rep_top limit:10

Показывает топ социальной кармы текущего сервера. Limit ограничен диапазоном от 1 до 20.

self sync/rep_sync_me
/rep_sync_me

Игрок вручную ставит свою текущую роль репутации в очередь. Cooldown команды — 30 секунд.

admin sync/rep_sync_all
/rep_sync_all

Администратор пересинхронизирует роли всех пользователей с репутацией на сервере. Cooldown — 60 секунд на guild.

owner migration/rep_migrate_db
/rep_migrate_db

Owner-команда переносит старую data/reputation.json в SQLite для текущего сервера и ставит пользователей в очередь ролей.

// VOTE_FLOW

Путь голоса от /rep до роли

1/rep

команда

2Checks

self/bot/state

3Cooldown

12 часов

4Weight

1/2/5/10

5DB

atomic tx

6Role

queue sync

A

Atomic vote

Операция делает cooldown, начисление, итоговые очки и audit event внутри одной транзакции.

B

ManagedLock

На пользователя есть безопасный async lock, чтобы параллельные команды не ломали голосование.

C

Queue worker

Выдача ролей вынесена в worker, который проверяет права, hierarchy и делает retry на временных ошибках API.

// PLAYER_FLOW

Что видит обычный игрок

raise influenceПовысить влияние

🤝 Игрок помог серверу

Участник ставит плюс за помощь, активность, полезный ответ или хорошую работу в комьюнити.

/rep @Alex Повысить (+)
lower influenceПонизить влияние

⚠️ Минус за токсичность

Игрок может поставить минус за плохое поведение. Вес минуса зависит от статуса голосующего.

/rep @User Понизить (-)
passportПроверить себя

📋 Мой социальный паспорт

Показывает, какой сейчас статус, сколько очков, есть ли скидка или наценка в магазине.

/karma
sync selfОбновить роль

🎖️ Синхронизация роли

Если роль не обновилась сразу, игрок может вручную поставить себя в очередь через /rep_sync_me.

/rep_sync_me
// ADMIN_FLOW

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

01

Настраивает ранги

Название, минимум очков, скидка/наценка, цвет и role_id для каждого статуса.

02

Ставит роли ниже бота

Роль HELPER должна быть выше ролей репутации, иначе Discord запретит выдачу.

03

Синхронизирует всех

/rep_sync_all ставит в очередь до 5000 пользователей сервера.

04

Следит за экономикой

Скидки рангов влияют на магазин через get_discount.

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

Перед массовой синхронизацией проверь: у бота есть Manage Roles, а все role_id рангов ниже роли бота. Тогда очередь отработает без hierarchy-blocked предупреждений.

// RANK_SYSTEM

Ранги, скидки и вес голоса

По умолчанию модуль уже имеет 5 рангов. Их можно заменить на сайте: изменить пороги, названия, цвета, роль и discount. Отрицательный discount работает как наценка.

-10000

🌚 Изгой

От -10000 очков. Наценка 20%, слабый вес голоса 1. Подходит для негативной репутации.

-20

👤 Прохожий

Базовый статус около нуля. Без скидки, обычный вес голоса.

21

🔰 АКТИВНЫЙ

Первые плюсы доверия. Скидка 5%, игрок уже заметен в социальной системе.

101

🌟 ДОВЕРЕННЫЙ

Стабильная репутация. Скидка 15%, вес голоса 5.

501

👑 ЛЕГЕНДА

Топовый статус. Скидка 30%, вес голоса 10 и отдельная роль.

vote weightВес голоса
points >= 501голос меняет цель на 10 очков.
points >= 101голос меняет цель на 5 очков.
points < 0голос меняет цель на 1 очко.
остальныеголос меняет цель на 2 очка.
discount normalizeСкидка / наценка
0.15скидка 15%.
15сайт может прислать процент — модуль переведёт в 0.15.
-0.20наценка 20% для плохой репутации.
limitзначение ограничено диапазоном -95% до +95%.
// DASHBOARD_SETTINGS

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

Dashboard сохраняет настройки в data/reputation_settings.json. Сайт может отправить ranks списком или ranks_json строкой. Cog каждые 10 секунд применяет deploy_requested, нормализует ранги, сбрасывает флаг и ставит пользователей в очередь ролей.

rank fieldsПоля ранга
nameназвание ранга, например 🌟 ДОВЕРЕННЫЙ.
minминимум очков для получения ранга.
discountскидка или наценка для магазина.
colorцвет embed-карточек в hex.
role_idDiscord-роль, которую нужно выдать за статус.
deploy_requestedфлаг сайта для применения изменений.
json previewreputation_settings.json
data/reputation_settings.json
{ "123456789": { "ranks": [ {"name": "🌚 Изгой", "min": -10000, "discount": -0.20, "color": "#707070", "role_id": ""}, {"name": "🌟 ДОВЕРЕННЫЙ", "min": 101, "discount": 0.15, "color": "#9B59B6", "role_id": "111"}, {"name": "👑 ЛЕГЕНДА", "min": 501, "discount": 0.30, "color": "#F1C40F", "role_id": "222"} ], "deploy_requested": true } }
site syncsite_sync_loop

10 секунд

Loop применяет ranks_json/ranks, ставит last_deploy_at, убирает deploy_requested и запускает queue_guild_role_resync.

apply_site_settings_for_guild → queue roles
module statemodule_states.json
reputationосновной ключ.
rep / karmaкороткие aliases.
social_karmaalias для социальной кармы.
социальная_кармарусский alias.
// ROLE_SYNC_QUEUE

Синхронизация ролей

Роли не выдаются хаотично внутри команд. Модуль ставит задачу в очередь, а отдельный worker обрабатывает её: снимает старые rep-роли, выдаёт нужную, проверяет Manage Roles и hierarchy.

1Rank

current points

2Target

role_id

3Queue

10k max

4Fetch

member

5Check

permissions

6Apply

add/remove

safe checksПроверки перед выдачей
guild existsсервер должен быть в кэше бота.
member existsесли нет в cache, бот пытается fetch_member.
Manage Rolesбез права бот не трогает роли.
role hierarchyроль ранга должна быть ниже роли бота.
retryпри 429/5xx делает повторы с задержкой.
bulk sync/rep_sync_all

🔁 Массовая синхронизация

Берёт пользователей из server_reputation, максимум 5000 на guild, и ставит каждого в очередь.

get_all_user_points(guild_id, 5000)
manual sync/rep_sync_me

🎖️ Обновить свою роль

Игрок сам может поставить role-sync задачу, если недавно поменялся ранг или role_id.

cooldown 30 sec / user
shutdownКорректное завершение

Graceful shutdown

При выгрузке cog перестаёт принимать новые задачи, ждёт очередь до 15 секунд и закрывает SQLite.

role_sync_queue.join()
// DATABASE_MAP

Что хранится в SQLite

Данные репутации хранятся в data/reputation.db с WAL-режимом, foreign_keys и busy_timeout. Все записи разделяются по guild_id и user_id.

tablesОсновные таблицы
📊
server_reputationpoints по guild/user
⏳
vote_cooldownslast_vote голосующего
🧾
reputation_eventsaudit history
⚡
idx_reputation_pointsбыстрый top
🔎
idx_rep_events_targetистория цели
🧊
WALsqlite journal
event rowreputation_events
voter_idкто поставил плюс или минус.
target_idкому изменили репутацию.
actionadd или sub.
changeфактическое изменение: +1/+2/+5/+10 или минус.
target_points_afterочки цели после операции.
created_atвремя голосования в ISO.
// SAFE_DISABLED

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

Отключение через module_states.json не удаляет очки, историю, ранги или роли. Команды просто возвращают disabled embed и не выполняют изменение репутации.

disabled embedЧто видит игрок
🔌
safe stateРепутация отключена

🔌 МОДУЛЬ ОБЕСТОЧЕН

Администратор отключил систему репутации на сайте. Для возобновления включите модуль “Социальная Карма”.

🔌 СОЦИАЛЬНАЯ КАРМА ОБЕСТОЧЕНА
safe dataЧто сохраняется
server_reputationочки пользователей остаются.
reputation_eventsистория голосов не удаляется.
reputation_settings.jsonранги и role_id остаются.
после включениякоманды снова работают, а роли можно пересинхронизировать.
// DEVELOPER_MAP

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

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

ReputationCog, команды, role worker, site_sync_loop, shutdown и integration API.

db.py

ReputationDB, atomic vote, tables, cooldowns, top users и legacy import.

settings.py

normalization ranks/ranks_json, deploy_requested, module state aliases.

utils.py

parse_bool, parse_color, normalize_rank, normalize_discount, disabled_embed и JSON locks.

locks.py

ManagedLock с active_users и безопасным release.

constantsГлавные константы
⏳
COOLDOWN_HOURS12 часов
📦
ROLE_QUEUE10 000 задач
🔁
SITE_SYNC10 секунд
👥
MAX_USERS5000 за resync
🧹
LOCK_GC30 минут
🧊
SHUTDOWN15 секунд
command safeguardsПроверки команд
_ensure_reputation_enabledguild-only и module state.
self voteнельзя оценивать самого себя.
bot voteботы не участвуют в социальной системе.
CommandOnCooldownотдельные slash cooldown для команд.
CooldownActive12-часовой бизнес-cooldown голоса.
migrationrep_migrate_db
OLD_REP_FILEdata/reputation.json.
extract_legacy_users_for_migrationподдерживает несколько старых форматов.
owner-onlyкоманда доступна только владельцу бота.
queue rolesпосле переноса пользователи ставятся в очередь ролей.
// TROUBLESHOOTING

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

Почему игрок не может оценить себя?

Это защита от накрутки. Команда сразу блокирует self-vote и не меняет очки.

Почему бот пишет “голос восстанавливается”?

Бизнес-cooldown одного голоса — 12 часов. Это хранится в vote_cooldowns по guild_id и voter_id.

Почему у разных игроков разный вес голоса?

Вес считается от очков голосующего: легенда влияет сильнее, отрицательный статус слабее.

Почему роль не выдалась?

Проверьте Manage Roles, позицию роли бота и role_id ранга. Если роль выше роли бота, worker пропустит выдачу.

Можно ли сделать свои ранги?

Да. На сайте меняются name, min, discount, color и role_id. После сохранения deploy_requested запускает пересинхронизацию.

Что будет с магазином?

Магазин может запросить get_discount(user_id, guild_id): положительное значение уменьшает цену, отрицательное работает как наценка.

// WIKI_NAVIGATION

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

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

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