HELPER Discord Bot
← К списку Wiki
REPORTS CORE // STAFF WORK LOGS // APPROVAL FLOW

HELPER REPORTS РАБОЧИЕ ОТЧЁТЫ /REPORTS_SETUP / WORK CATALOG / SHOP POINTS / PERSONAL THREADS

Reports — это не жалобы на игроков, а система фиксации работы staff-команды. Сотрудник открывает Каталог работ, выбирает выполненную задачу, прикрепляет доказательства, куратор проверяет карточку, а HELPER начисляет баллы через ShopCog, пишет лог и ведёт личное дело в ForumChannel.

Показать картинки Путь отчёта Настройка сайта
25работ в select-menu
5ssite sync loop
30mcooldown cleanup
Forumличные дела staff
Terminal/reports_setup публикует плашку
CatalogREPORT_TYPES до 25 пунктов
Approval✅ Одобрить / ❌ Отклонить
RewardShopCog.add_bal начисляет баллы
CaseForumChannel хранит личные дела
// MODULE_PURPOSE

Что делает Reports

Модуль фиксирует выполненную работу staff-сотрудников. Владелец сервера задаёт виды работ и награды, сотрудник отправляет доказательства, куратор подтверждает или отклоняет, а бот аккуратно обновляет личное дело и общий лог. Это отдельная система от жалоб/репортов на игроков.

01

Терминал

Публичная плашка с кнопками “Каталог работ” и “Админ-панель”.

02

Каталог

До 25 видов работ: название, emoji и количество баллов.

03

Проверка

Куратор видит proof, комментарий и кнопки approve/reject.

04

Личное дело

После одобрения лог сохраняется в ForumChannel и начисляются баллы.

// VISUAL_GUIDE

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

Ниже весь путь в визуальных блоках: setup, терминал, каталог, modal доказательств, карточка проверки, approve/reject, личное дело, admin-panel и disabled-state.

01 / setupПервый запуск
💬
slash command/reports_setup

Настроить систему рабочих отчётов

Администратор выбирает terminal, check, log, ForumChannel и роль куратора.

/reports_setup #staff-work #reports-check #work-logs Forum @Curator
✅ Система отчётов настроена
02 / terminalРабочий терминал
💼
#staff-workREPORT TERMINAL

💼 ТЕРМИНАЛ ФИКСАЦИИ РАБОТЫ

Добро пожаловать в систему автоматизированного приема отчётов.

CUSTOM REPORT BANNER
📂 Доступных работ12
Forumвыбран
📂 Каталог работ
⚙️ Админ-панель
03 / catalogПриватный каталог
ephemeralmax 25REPORT_TYPES
📦 ДропНаграда: 50 баллов
select
💰 ПремияНаграда: 100 баллов
select
🎙️ ОбзвонНаграда: 75 баллов
select
🧾 Проверка анкетыНаграда: 40 баллов
select
04 / submit modalProof modal
📝
SubmitReportModalОтчёт: Дроп

Поля формы

Доказательства / ссылка: https://imgur.com/a/proof
Комментарий: Дроп закрыт, участники отмечены
Отправить в канал проверки
05 / review cardКанал проверки
🔎
#reports-checkПРОВЕРКА ОТЧЁТА

🔎 ПРОВЕРКА ОТЧЁТА

Карточка содержит сотрудника, тип работы, ожидаемую награду, ссылку на proof и footer с безопасными ID.

Сотрудник@NightStaff
Тип работы📦 Дроп
Награда+50 баллов
Proofоткрыть материалы
✅ Одобрить
❌ Отклонить
06 / approvedОдобрение

🎉 Отчёт одобрен!

Сотрудник получает DM, баллы начисляются через ShopCog, а лог уходит в общий канал и личное дело.

ShopCog.add_bal(user_id, guild_id, points)
07 / rejectedОтклонение

❌ Отчёт отклонён

Куратор указывает причину в RejectReasonModal, бот отправляет DM сотруднику и удаляет карточку проверки.

Причина: отсутствует скриншот окончания мероприятия
08 / personal caseЛичное дело
ForumChannelthread per user
👤 Личное дело: NightStaffthread создан автоматически
forum
📈 ФИКСАЦИЯ РАБОТЫДроп · +50 баллов · выполнено
log
📈 ФИКСАЦИЯ РАБОТЫПремия · +100 баллов · выполнено
case
// DISCORD_COMMANDS

Команды Discord

Команды настройки доступны администраторам. Обычный staff работает через кнопки терминала и proof-modal.

setup/reports_setup
/reports_setup terminal_channel:#staff-work check_channel:#reports-check log_channel:#work-logs forum_channel:Личные-дела mod_role:@Curator

Первичная настройка: канал терминала, скрытый канал проверки, канал логов, форум личных дел и роль куратора.

redeploy/reports_deploy
/reports_deploy

Обновляет опубликованную плашку по текущим настройкам сайта или JSON.

terminal buttonsКаталог / Админ-панель
ReportTerminalView 📂 persistent_catalog_v3 ⚙️ persistent_admin_v3

Каталог видят сотрудники, админ-панель доступна кураторам или администраторам.

approval buttonsApprove / Reject
ReportApprovalView ✅ report_btn_approve_v2 ❌ report_btn_reject_v2

Куратор проверяет карточку отчёта, начисляет баллы или отправляет причину отказа.

// REPORT_FLOW

Путь отчёта от работы до баллов

1Terminal

плашка

2Catalog

выбор

3Modal

proof

4Review

куратор

5Reward

ShopCog

6Case

Forum/log

A

Ephemeral UX

Каталог и админ-панель не засоряют канал, потому что отправляются приватно.

B

Safe footer

Карточка проверки хранит guild_id, user_id и points в footer, чтобы approval не зависел от текста.

C

Graceful reward

Если ShopCog недоступен, отчёт всё равно одобряется, но бот показывает предупреждение.

// STAFF_FLOW

Что видит сотрудник

open catalogОткрыть каталог

📂 Каталог работ

Сотрудник нажимает кнопку, получает приватный select-menu и выбирает выполненную задачу.

ReportTerminalView.catalog
empty catalogЕсли каталог пуст

❌ Каталог работ пуст

Так происходит, если REPORT_TYPES не настроен или все работы имеют points <= 0.

Обратитесь к администрации
submit proofДоказательства

✅ Отчёт отправлен

После отправки modal отчёт уходит в REPORT_CHECK_CHANNEL и ждёт решения куратора.

Ожидайте начисления
cooldownАнтиспам

⏳ Подождите

Кнопка каталога имеет cooldown 5 секунд на пользователя, чтобы не спамить меню.

5 sec / user
// CURATOR_FLOW

Что делает куратор

01

Проверяет proof

Открывает ссылку на материалы, читает комментарий и сравнивает с правилами сервера.

02

Одобряет

Кнопка ✅ начисляет points, создаёт лог и отправляет DM сотруднику.

03

Отклоняет

Кнопка ❌ открывает RejectReasonModal с причиной отказа.

04

Управляет каталогом

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

admin panelПанель управления
curator onlytimeout 300
➕ Добавить работуReportAddModal: name, emoji, points
modal
📝 Изменить работуselect item → ReportAddModal
edit
🗑️ Удалить работуselect item → update settings
delete
Cooldown2 секунды на кнопки админ-панели
safe
staff accessКто может проверять
administratorадминистратор проходит всегда.
REPORT_MOD_ROLESнесколько ролей кураторов.
REPORT_MOD_ROLEстарое одиночное поле для совместимости.
aliasesmoderator_role_ids / staff_role_ids / access_role_ids.
// PERSONAL_CASES

Личные дела и начисление

После одобрения бот создаёт или находит личную тему сотрудника в ForumChannel, отправляет туда лог и сохраняет thread id через ShopCog, если метод set_thread доступен.

reward contractShopCog
add_bal(user_id, guild_id, points)основной контракт HELPER.
named paramsподдерживаются user/guild/amount сигнатуры.
no guessingнеизвестные positional-сигнатуры не угадываются.
false resultесли начисление не сработало, отчёт всё равно фиксируется с предупреждением.
forum threadForumChannel

👤 Личное дело: NightStaff

Если ForumChannel выбран, бот создаёт thread и пишет туда все одобренные отчёты сотрудника.

get_or_create_personal_thread()
log cardФиксация работы

📈 ФИКСАЦИЯ РАБОТЫ

Сотрудник: @NightStaff
Тип: Дроп
Награда: +50 баллов
Автоначисление: 🟢 выполнено

Перейти в личное дело
fallbackЕсли forum не выбран

⚠️ Форум личных дел не выбран

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

REPORT_FORUM_CHANNEL пустой
// DASHBOARD_SETTINGS

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

Dashboard пишет настройки в data/reports_settings.json. Cog каждые 5 секунд нормализует настройки, проверяет deploy_requested и редактирует старый терминал по REPORT_MESSAGE_ID.

channelsКаналы и роли
REPORT_TERMINAL_CHANNELканал, где стоит терминал staff-отчётов.
REPORT_CHECK_CHANNELскрытый канал проверки новых отчётов.
REPORT_LOG_CHANNELобщий лог одобренных отчётов.
REPORT_FORUM_CHANNELDiscord ForumChannel для личных дел.
REPORT_MOD_ROLESнесколько ролей кураторов.
REPORT_MOD_ROLElegacy одиночная роль.
terminal visualОформление терминала
custom_title / REPORT_TITLEзаголовок embed.
custom_descriptionописание под заголовком.
custom_button_textтекст кнопки каталога.
custom_footerfooter плашки.
custom_colorцвет embed-линии.
custom_banner / REPORT_BANNERбаннер терминала.
json previewreports_settings.json
data/reports_settings.json
{ "123456789": { "REPORT_TERMINAL_CHANNEL": "111", "REPORT_CHECK_CHANNEL": "222", "REPORT_LOG_CHANNEL": "333", "REPORT_FORUM_CHANNEL": "444", "REPORT_MOD_ROLES": ["555", "666"], "REPORT_MESSAGE_ID": "777", "last_terminal_channel_id": "111", "REPORT_TYPES": { "Дроп": {"emoji": "📦", "points": 50}, "Премия": {"emoji": "💰", "points": 100} }, "deploy_requested": true } }
sync loopsite_sync_loop

5 секунд

Loop нормализует настройки, отслеживает mtime module_states.json, сбрасывает cache и вызывает deploy_or_update_terminal.

deploy_requested → msg.edit(**payload)
// WORK_CATALOG

Каталог работ

REPORT_TYPES — это словарь “название → emoji + points”. Пустые, некорректные и нулевые работы отбрасываются нормализацией, а Discord Select показывает максимум 25 вариантов.

defaultsСтартовые работы
DEFAULT_REPORT_TYPES
📦 Дроп50 баллов
default
💰 Премия100 баллов
default
Customлюбые серверные работы через сайт или admin-panel
add
normalizeПравила нормализации
nameобрезается до 100 символов.
emojiпо умолчанию 📌, максимум 10 символов.
pointsдолжно быть больше 0.
REPORT_TYPES_JSONможет мигрировать в REPORT_TYPES.
selectберёт первые 25 работ.
examplesИдеи работ
🛡️ Патруль35 баллов за проверку территории.
🎙️ Обзвон75 баллов за проведённое интервью.
🧾 Проверка анкеты40 баллов за обработку заявок.
🎮 Ивент120 баллов за проведённое мероприятие.
admin editРедактирование в Discord

ReportAddModal

Один modal используется и для добавления, и для изменения: название работы, emoji, количество баллов.

Название: Патруль
Эмодзи: 🛡️
Баллы: 35
// BANNERS_VISUAL

Баннеры и визуал

terminal bannerReports banner
STAFF WORK LOGS
REPORTS TERMINAL
CATALOG / PROOF / APPROVAL
banner keysVisual Core keys
reportsбаннер терминала.
app_approveбаннер DM при одобрении.
app_rejectбаннер DM при отказе.
on_banner_updatedавтоматически обновляет опубликованные терминалы.
// SAFE_DISABLED

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

Отключение через module_states.json не удаляет настройки, каталог, логи или личные дела. Терминал получает красный embed и disabled-кнопку, а ProtectedView блокирует новые действия.

disabled terminalЧто видит staff
🔌
safe stateReports disabled

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

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

🔌 ОТЧЁТЫ ОБЕСТОЧЕНЫ
state aliasesКлючи состояния
reportsосновной ключ.
reportкороткий alias.
work_reports / work-reportsalias рабочих отчётов.
reportingдополнительная совместимость.
рабочие_отчетырусский alias.
// DEVELOPER_MAP

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

filesФайлы и данные
REPORTS_SETTINGS_FILE

data/reports_settings.json — каналы, роли, каталог, оформление, message_id и deploy.

MODULES_FILE

data/module_states.json — включение/выключение reports.

cog.py

ReportsCog, site_sync_loop, /reports_setup, /reports_deploy, terminal payload и ShopCog reward.

views.py

ReportTerminalView, ReportsAdminView, SubmitReportModal, ReportApprovalView и ReportsDisabledView.

settings.py / utils.py

нормализация REPORT_TYPES, JSON cache, role ids, proof formatting и safe channel resolving.

constantsГлавные константы
💼
DEFAULT_TITLEтерминал
📂
DEFAULT_BUTTONКаталог работ
📦
DEFAULT_TYPESДроп / Премия
🔁
SYNC5 секунд
⚠️
DEPLOY5 попыток
📋
SELECT25 options
terminal syncWeb → Discord
normalize_all_report_settings_if_neededпишет JSON только при реальных изменениях.
module_states_changedотслеживает mtime module_states.json.
deploy_or_update_terminaledit старого сообщения или send нового.
REPORT_MESSAGE_IDID опубликованного терминала.
last_terminal_channel_idнужно для переноса панели между каналами.
approval logicПроверка отчёта
extract_safe_dataдостаёт user_id, report_type, points и guild_id из embed.
_check_staffпроверяет куратора или администратора.
add_shop_balanceначисляет баллы через ShopCog.
get_or_create_personal_threadсоздаёт/находит личное дело.
RejectReasonModalотправляет причину отказа в DM.
// TROUBLESHOOTING

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

Отчёт не отправляется в проверку

Проверьте REPORT_CHECK_CHANNEL и права бота писать сообщения, embed и attachments в скрытый канал проверки.

Staff не видит каталог

Каталог пустой, если REPORT_TYPES не настроен или все работы имеют points <= 0.

Куратор не может одобрить

Проверьте REPORT_MOD_ROLES / REPORT_MOD_ROLE. Администратор сервера проходит проверку автоматически.

Баллы не начислились

Проверьте, загружен ли ShopCog и поддерживает ли он add_bal(user_id, guild_id, points) или понятную именованную сигнатуру.

Личное дело не создано

Нужен Discord ForumChannel. Если выбран обычный канал или у бота нет прав create threads, тема не появится.

Сайт сохранил, но плашка не обновилась

Проверьте deploy_requested, REPORT_TERMINAL_CHANNEL, REPORT_MESSAGE_ID, last_terminal_channel_id и права бота редактировать сообщение.

// WIKI_NAVIGATION

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

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

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