first commit

README.md

@@ -0,0 +1,65 @@
+# ShbDiscordBot
+
+Paper-плагин со встроенным Discord-ботом для привязки Discord к Minecraft и выдачи LuckPerms permissions по ролям.
+
+## Как работает привязка
+
+1. Участник настроенного Discord-сервера пишет боту в личных сообщениях `/auth`.
+2. Бот выдаёт одноразовый шестизначный код на 10 минут.
+3. Игрок выполняет на Minecraft-сервере `/link <код>`.
+4. Плагин проверяет обе стороны и сохраняет `discordId` через ShbUtils Core API.
+
+Существующие связи не перезаписываются. Незавершённые коды хранятся только в памяти и после рестарта исчезают.
+
+## Сборка и установка
+
+```bash
+./gradlew test shadowJar
+```
+
+Установите `build/libs/ShbDiscordBot-1.0.jar` и LuckPerms на Paper-сервер. Обычный `*-plain.jar` не является готовым артефактом для установки.
+
+В [Discord Developer Portal](https://discord.com/developers/applications):
+
+1. Создайте bot application.
+2. Включите privileged intent **Server Members Intent**.
+3. Пригласите бота в guild со scopes `bot` и `applications.commands`.
+4. Разрешите участникам сервера отправлять боту личные сообщения.
+
+Запустите сервер один раз, заполните `plugins/ShbDiscordBot/config.yml` и перезапустите его. Реальные `discord.token` и `api.internal-secret` нельзя публиковать или коммитить.
+
+## Конфигурация ролей
+
+```yaml
+role-sync:
+  interval-seconds: 300
+  max-concurrent-requests: 4
+  mappings:
+    "123456789012345678":
+      - "group.vip"
+      - "server.chat.color"
+    "234567890123456789":
+      - "server.fly"
+```
+
+После успешной привязки, добавления роли и раз в пять минут плагин добавляет отсутствующие nodes игроку. Удаление Discord-роли не снимает ранее выданные permissions.
+
+После изменения любых настроек выполните из консоли или от имени оператора:
+
+```text
+/sdb reload
+```
+
+Команда сначала проверяет новый конфиг, затем полностью переподключает Discord-бота и API-клиент, пересоздаёт периодическую задачу и немедленно запускает синхронизацию ролей. Незавершённые шестизначные коды при этом аннулируются. Встроенная Paper-команда `/reload` намеренно не переопределяется.
+
+Полный локальный справочник ShbUtils API находится в [docs/API.md](docs/API.md). Правила для следующих разработчиков и агентов — в [AGENTS.md](AGENTS.md).
+
+## Если бот не видит guild
+
+Сообщение `Discord-бот не видит настроенный guild` означает, что авторизация прошла, но Discord не вернул настроенный сервер для этого bot token.
+
+- Скопируйте ID сервера через Discord Developer Mode и проверьте `discord.guild-id`.
+- Убедитесь, что `discord.token` принадлежит тому же application, которого приглашали на сервер.
+- Проверьте список `Видимые guild` в логе: он показывает guild IDs, доступные боту.
+- Если список пуст, пригласите именно bot installation со scopes `bot` и `applications.commands`, а не только user installation.
+- Включите **Server Members Intent** до повторного запуска плагина.