HELPER Discord Bot
← К списку Wiki
SHOP CORE // ECONOMY STOREFRONT // PURCHASE APPROVAL FLOW

HELPER SHOP МАГАЗИН И ЭКОНОМИКА /SHOP_SETUP / CATALOG / STAFF REVIEW / AUTO DELIVERY / FORUM ITEMS

Shop превращает активность игроков в полноценную экономику сервера: пользователь копит баллы, открывает витрину, выбирает товар, получает цену с учётом репутации, отправляет заявку, а staff одобряет или отклоняет покупку. После одобрения HELPER списывает баланс, пишет историю, отправляет DM и при необходимости автоматически выдаёт роль или доступ к каналу.

Показать картинки Путь игрока Staff-проверка
4главные команды
60spurchase cooldown
10ssite sync loop
1hdelivery cleanup
Catalogкатегории, товары, цена, склад
Approval✅ одобрить / ❌ отклонить / 📜 история
Deliverymanual / role / channel_access
Reputationскидка или наценка от кармы
Forumтовары отдельными постами
// MODULE_PURPOSE

Что делает Shop Core

Магазин — это связка экономики, каталога товаров, проверки покупок, личных дел и автоматической выдачи. Владелец сервера настраивает витрину, категории и товары, игроки покупают за баллы, а staff контролирует каждую заявку. Покупка не списывает баланс сразу: деньги уходят только после решения staff.

01

Витрина

Публичная плашка с баннером и кнопками: Каталог, Профиль, Репутация, Управление.

02

Каталог

Категории товаров, страницы по 5 товаров и select-меню до 25 пунктов.

03

Заявка

Проверка баланса, скидки, склада, лимита и pending-заявок перед отправкой staff.

04

Выдача

После одобрения: manual note, role delivery или channel access с таймером.

// VISUAL_GUIDE

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

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

01 / setupПервичная настройка
🛠️
slash command/shop_setup

Настроить магазин

Админ выбирает канал магазина, канал проверки, лог-канал, роли модераторов и ForumChannel личных дел.

/shop_setup #магазин #проверка-покупок #логи @Staff forum
Сохранить настройки и развернуть витрину
02 / storefrontПубличная витрина
🛒
#магазинHELPER SHOP

🛒 СЕМЕЙНЫЙ МАГАЗИН HELPER

Каталог товаров, заявки на покупку, staff-решение и автологирование.

SHOP BANNER
🛍️ Каталог
👤 Профиль
🎭 Репутация
⚙️ Управление
03 / categoriesПриватный выбор категории
ephemeral25 categories
📁 Роли5 товаров
select
📁 Привилегии8 товаров
select
📁 Доступы к каналам3 товара
select
📁 Ивент-награды2 товара
select
04 / item pageКарточки товаров

📦 Роли

Страница 1/2 • Баланс игрока: 4850 🏆

💎 VIP 30 дней~~2500~~ → 2125 🏆 `-15%` • склад 7
🎭 Цветная роль900 🏆 • лимит 1 на игрока
🔐 Private Room5000 🏆 • доступ к каналу
Выберите товар для покупки...
05 / review requestЗаявка staff-команде
📨
#проверка-покупокНОВАЯ ПОКУПКА

🛒 Новая заявка на покупку

Staff видит покупателя, товар, цену, скидку, баланс до/после и snapshot товара.

Покупатель@Sasi
ТоварVIP 30 дней
Цена2125 🏆
Баланс4850 → 2725
✅ Одобрить
❌ Отклонить
📜 История
06 / approvedОдобрение и выдача

✅ Покупка одобрена

Баланс списан, транзакция записана, игрок получил DM, а товар отправлен в delivery pipeline.

approve_purchase_atomic → deliver_item → log_event
07 / rejectedОтклонение

❌ Покупка отклонена

Staff указывает причину в modal. Баллы не списываются, игрок получает DM с причиной отказа.

Причина: товар временно недоступен / заявка ошибочная
08 / forum itemФорумный товар
ForumChannelShopForumItemView
💎 VIP 30 днейотдельная тема с описанием, ценой и картинкой
thread
🛒 Купить товарpersistent button custom_id shop_forum_buy_btn_v1
button
Disabled modeесли магазин выключен, кнопка красная и disabled
off
// DISCORD_COMMANDS

Команды Discord

Главные команды оставлены короткими. Обычные игроки работают через кнопки витрины, а администрация — через slash-команды и приватную ShopAdminView.

setup/shop_setup
/shop_setup shop_channel:#магазин check_channel:#проверка log_channel:#логи moderator_role:@Staff forum_channel:📂・личные-дела

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

redeploy/shop_deploy
/shop_deploy

Принудительно обновляет витрину по текущим настройкам сайта, panel_hash и SHOP_MESSAGE_ID.

private admin/shop_admin
/shop_admin

Открывает приватную панель управления: товары, баланс, статусы и карма/скидки.

history/shop_history
/shop_history user:@Player

Показывает историю покупок пользователя. Если user не указан — показывает свою историю.

// PLAYER_FLOW

Путь игрока от баланса до покупки

1Balance

баллы

2Catalog

категории

3Item

цена/скидка

4Request

staff review

5Approve

списание

6Delivery

товар

profile button👤 Профиль

👤 Профиль магазина

Показывает баланс, общий опыт, текущий статус и сколько осталось до следующего ранга.

Баланс4850 🏆
Опыт12400 🏆
Статус💎 Мастер
Следующий💎 Предел
reputation button🎭 Репутация

🎭 Репутация и экономика

Если ReputationCog доступен, магазин показывает статус, points и скидку/наценку текущего игрока.

get_discount(user_id, guild_id)
safe checksПроверки перед заявкой
priceцена должна быть больше 0.
stockесли склад указан и он 0 — товар распродан.
max_per_userлимит одобренных покупок на игрока.
pending_countне больше 2 активных заявок одновременно.
balanceбаланс должен покрывать итоговую цену.
purchase cooldown60 секунд между покупками.
ephemeral uxКанал не засоряется

Все меню приватные

Категории, страницы товаров, профиль и статус репутации отправляются ephemeral, поэтому публичная витрина остаётся чистой.

ephemeral catalog / profile / reputation
// STAFF_REVIEW

Проверка покупки staff-командой

В канал проверки приходит embed с заявкой и persistent view. Staff может одобрить, отклонить или открыть историю покупок игрока. Обработка защищена правами администратора или ролями модераторов магазина.

✅

Одобрить

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

❌

Отклонить

Открывает RejectPurchaseModal с причиной отказа, не списывает баланс и отправляет DM.

📜

История

Показывает последние 8 покупок пользователя для контекста решения.

2.5s

Cooldown

Кнопки проверки защищены от быстрых повторных нажатий.

review cardЧто содержит заявка
buyerпокупатель и его ID.
category / itemкатегория и название товара.
original_price / priceисходная цена и итоговая цена со скидкой.
discount_percentскидка или наценка от репутации.
item_snapshotкопия товара на момент покупки.
message_idID staff-сообщения как ключ заявки.
old buttonsLegacy removed buttons

Старые кнопки безопасно закрыты

Если в Discord остались старые custom_id, они не ломают систему: бот отвечает, что новая staff-панель — ✅ / ❌ / 📜.

LegacyRemovedShopButtonsView
// DELIVERY_FLOW

Выдача товара после одобрения

После approval магазин пытается выдать товар автоматически. Если тип ручной или что-то не найдено, заявка всё равно фиксируется, а staff получает понятное предупреждение.

manualmanual

Ручная выдача

Для нестандартных товаров staff выдаёт награду вручную. Бот пишет manual_required и сохраняет историю покупки.

delivery_status = manual_required
rolerole

Выдача роли

Бот ищет role_id, выдаёт роль игроку и при duration_days записывает таймер снятия.

member.add_roles(role)
channel_accesschannel_access

Доступ к каналу

Бот ставит permission overwrite для игрока: view/send/connect, а при сроке сохраняет старые права.

channel.set_permissions(member)
expirationСрок действия

delivery_cleanup_loop

Раз в час бот проверяет item_deliveries и снимает временные роли или возвращает старые права канала.

expires_at → active = 0
// ADMIN_PANEL

Админ-панель экономики

ShopAdminView открывается приватно и доступна только администраторам сервера. Через неё можно управлять товарами, балансом, статусами магазина и интеграцией репутации.

buttonsShopAdminView
admin onlyephemeral
📦 Товарыдобавить, изменить или удалить товар
goods
💰 Балансначислить или снять баллы вручную
balance
⭐ Статусыранги магазина по total_earned
ranks
🎭 Карма / скидкипереход к настройкам ReputationCog
karma
goods modalДобавление товара

GenericModal: Добавление товара

Категория: Роли / Привилегии
Название товара: VIP 30 дней
Цена: 2500
Тип: manual / role / channel_access
Target ID: role_id или channel_id
balance modalБаланс игрока

Helper: Баланс игрока

Админ указывает ID пользователя, сумму и причину. Операция записывается в transactions и personal thread.

add_bal(user_id, guild_id, amount)
stockСклад и лимиты
stockограниченный остаток товара.
max_per_userлимит одобренных покупок на игрока.
duration_daysсрок роли или доступа.
forum_thread_idсвязь товара с форумной темой.
// DASHBOARD_SETTINGS

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

Dashboard хранит конфигурацию в data/shop_settings.json. При сохранении меняется panel_hash или ставится deploy_requested, а site_sync_loop каждые 10 секунд обновляет витрину без дублей.

channelsКаналы и роли
SHOP_CHANNEL_IDканал публичной витрины.
CHECK_CHANNEL_IDзакрытый канал проверки покупок.
LOG_CHANNEL_IDканал логов экономики.
FORUM_CHANNEL_IDфорум личных дел игроков.
FOR_MODER_ROLE_IDSроли staff, которым можно обрабатывать покупки.
SHOP_FORUM_CHANNEL_IDфорум-каталог товаров.
storefrontОформление витрины
SHOP_TITLEзаголовок embed.
SHOP_DESCRIPTIONописание витрины.
SHOP_COLORцвет embed-линии.
SHOP_BANNERбаннер витрины.
SHOP_FOOTERнижняя подпись.
button_textтексты кнопок Каталог / Профиль / Репутация / Управление.
json previewshop_settings.json
data/shop_settings.json
{ "123456789": { "SHOP_CHANNEL_ID": "111", "CHECK_CHANNEL_ID": "222", "LOG_CHANNEL_ID": "333", "FORUM_CHANNEL_ID": "444", "FOR_MODER_ROLE_IDS": ["555"], "SHOP_MESSAGE_ID": "666", "last_shop_channel_id": "111", "SHOP_ITEMS": { "Роли": { "VIP 30 дней": { "price": 2500, "type": "role", "role_id": "777", "duration_days": 30, "stock": 7, "max_per_user": 1 } } }, "deploy_requested": true } }
syncsite_sync_loop

10 секунд

Loop нормализует настройки, смотрит module_states, сравнивает panel_hash, считает deploy_attempts и вызывает deploy_shop_panel.

deploy_requested / hash changed / module changed
// ITEM_TYPES

Типы товаров

Товар может быть просто ручной наградой, Discord-ролью или доступом к каналу. Все типы хранятся в SHOP_ITEMS и попадают в item_snapshot при покупке.

MAN

manual

Ручная выдача staff. Подходит для премий, нестандартных услуг и игровых наград.

ROLE

role

Бот выдаёт Discord-роль по role_id. При duration_days записывает снятие в item_deliveries.

CHAN

channel_access

Бот выдаёт доступ к каналу, сохраняет старые overwrites и восстанавливает их после срока.

validationnormalize_item_data
priceцена не может быть отрицательной.
descописание ограничено 1000 символами.
image_urlтолько http/https.
typemanual / role / channel_access.
target idrole_id или channel_id в зависимости от типа.
stock / max_per_userчисловые лимиты.
delivery messagesЧто пишет бот
manual_requiredstaff выдаёт товар вручную.
deliveredроль или доступ выданы успешно.
delivery_failedроль/канал/пользователь не найден или нет прав.
had_beforeесли роль уже была, при истечении бот не снимет её.
// FORUM_CATALOG

Форумный каталог товаров

Shop умеет публиковать товары отдельными темами в ForumChannel. Это удобно для серверов, где каждый товар должен иметь картинку, описание, цену и отдельную кнопку покупки.

forum threadТема товара
💎
forum postVIP 30 дней

💎 VIP 30 дней

Описание товара, цена, тип выдачи, срок действия и картинка товара.

PRODUCT IMAGE
🛒 Купить товар
sync behaviorОбновление форума
SHOP_FORUM_CHANNEL_IDфорум-каталог товаров.
forum_thread_idсвязь товара с темой.
forum_message_idсообщение с embed и кнопкой.
build_shop_forum_item_embedготовит карточку товара.
ShopForumItemViewpersistent-кнопка покупки.

Форум нужно выбрать отдельно

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

// PROFILE_HISTORY

Личные дела и история покупок

Shop хранит balance, total_earned и thread_id игрока. При логировании покупки бот пытается найти или создать личное дело в ForumChannel, затем пишет туда операцию и добавляет кнопку перехода в общий лог.

personal threadЛичное дело игрока
ForumChannelthread_id
👤 Личное дело: Sasiсоздаётся при первом событии экономики
thread
🛒 Покупка VIP-2125 🏆 · одобрено staff
purchase
💰 Начисление+500 🏆 · причина: ивент
balance
history command/shop_history

📜 История покупок

Показывает последние операции покупки: статус, товар, цена, кто обработал и когда.

build_purchase_history_embed
// DATABASE_MAP

Что хранится в базе

Основная база экономики — data/shop.db. Таблицы привязаны к guild_id и user_id, поэтому несколько серверов не смешивают балансы, покупки и личные дела.

sqliteshop.db
👤
usersbalance, total_earned, thread_id
🛒
purchase_requestsзаявки, status, price, DM flags
💰
transactionsистория начислений и списаний
⏳
item_deliveriesвременные роли/доступы
⚡
indexespending, history, tx, deliveries
🧊
WALSQLite journal
purchase rowpurchase_requests
message_idключ заявки и staff-сообщения.
item_snapshotкопия товара на момент покупки.
statuspending / approved / rejected и другие состояния.
processed_byкто принял решение.
delivery_statusитог выдачи товара.
dm_* flagsстатусы отправки DM игроку.
// SAFE_DISABLED

Если магазин выключен

Отключение через module_states.json не удаляет товары, балансы, покупки и историю. Новые покупки блокируются, публичная витрина становится красной, а форумные кнопки покупки отключаются.

disabled storefrontЧто видит игрок
🔌
safe stateShop disabled

🔌 Магазин отключён

Администратор отключил магазин в панели управления. Новые покупки недоступны, но данные не удалены.

🔌 МАГАЗИН ОТКЛЮЧЁН
module aliasesКлючи состояния
shopосновной ключ.
economyalias экономики.
store / marketанглийские alias.
магазин / экономикарусские alias.
after enableвитрина и кнопки снова активны.
// DEVELOPER_MAP

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

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

Экспортирует ShopCog как публичный cog модуля.

cog.py

ShopCog: команды, deploy, delivery, cleanup loops, интеграция репутации и логирование.

database.py

SQLite users, purchase_requests, transactions, item_deliveries и атомарные операции.

views.py

ShopMainView, CategoryPaginationView, PurchaseApprovalView, ShopAdminView, ShopForumItemView.

settings.py

normalize_shop_config, panel_hash, module_states, SHOP_ITEMS и deploy-флаги.

embeds.py / modals.py

Витрина, purchase embeds, история, forum item и RejectPurchaseModal.

loopsФоновые циклы
🔁
site_sync_loop10 секунд
🧹
cache_cleanup30 секунд
⌛
purchase_cleanup6 часов
📦
delivery_cleanup1 час
🧊
price cache15 секунд
👤
status cache15 секунд
approval logicПокупка → решение
create_purchase_requestсоздаёт pending-заявку после выбора товара.
approve_purchase_atomicатомарно списывает баланс и меняет статус.
process_purchase_approvalзапускает delivery и отправляет DM/логи.
process_purchase_rejectionсохраняет reject_reason и пишет игроку.
delete_purchase_review_messageудаляет карточку проверки после обработки.
deploy logicWeb → Discord
panel_hashсравнение ключевых полей витрины.
SHOP_MESSAGE_IDID опубликованной витрины.
last_shop_channel_idканал последнего deploy.
deploy_attemptsзащита от бесконечных попыток.
MAX_DEPLOY_ATTEMPTS5 попыток перед last_deploy_error.
// TROUBLESHOOTING

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

Игрок нажал товар, но заявка не создаётся

Проверьте CHECK_CHANNEL_ID, права бота писать embed и то, что товар имеет price больше 0.

Пишет “недостаточно средств”

Баланс берётся из users.balance в shop.db. Проверьте начисления через админ-панель или transactions.

Товар распродан

Если stock задан и равен 0, покупка блокируется. Увеличьте stock на сайте или через админку.

Staff не может одобрить

Проверку проходят администраторы или роли из FOR_MODER_ROLE_IDS / FOR_MODER_ROLE_ID.

Роль не выдалась после одобрения

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

Форумный товар не покупается

Проверьте SHOP_FORUM_CHANNEL_ID, forum_thread_id/forum_message_id и активность модуля shop.

Витрина не обновилась после сайта

Проверьте deploy_requested, deploy_attempts, last_deploy_error, SHOP_CHANNEL_ID и SHOP_MESSAGE_ID.

История не появилась в личном деле

Нужен FORUM_CHANNEL_ID с типом ForumChannel и права бота создавать публикации.

// WIKI_NAVIGATION

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

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

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