feat: pizdec

MODERATION_PLUGIN_CONTRACT.md

@@ -0,0 +1,149 @@
+# Контракт moderation-плагина для AdminMode
+
+Этот документ описывает минимальные команды и поведение отдельного moderation-плагина, необходимого для работы кнопок Mute, Unmute, Kick и Ban в AdminMode 1.2 на Paper 26.1.2.
+
+AdminMode выполняет команды от консоли и передаёт реального модератора отдельным аргументом `actor:<ник>`. Активные баны должны храниться только в стандартном Paper ProfileBanList, иначе BanList и кнопка разбана в AdminMode не увидят их.
+
+## Формат сроков
+
+Плагин обязан принимать как минимум:
+
+- `1h` — один час;
+- `1d` — один день;
+- `7d` — семь дней;
+- `30d` — тридцать дней;
+- `permanent` — бессрочно.
+
+Рекомендуется дополнительно принимать любое положительное значение в формате `<число><s|m|h|d|w|y>`. Нулевые, отрицательные, неизвестные и переполненные значения должны отклоняться без применения наказания.
+
+## Автор наказания
+
+При вызове из AdminMode команды выглядят так:
+
+```text
+mute Steve 1h actor:Moderator флуд
+ban Steve 7d actor:Moderator читы
+kick Steve actor:Moderator нарушение правил
+```
+
+Правила обработки `actor:`:
+
+- учитывать аргумент только когда `CommandSender` является консолью;
+- для команды игрока всегда записывать автором самого игрока;
+- не разрешать игроку подменять автора через `actor:`;
+- убрать `actor:<ник>` из сохраняемой причины.
+
+## Команды
+
+### Mute
+
+```text
+/mute <player> <duration> [actor:<name>] <reason...>
+/unmute <player> [actor:<name>] [reason...]
+```
+
+Из AdminMode команда вызывается по полному Bukkit namespace `moderationcommands:unmute`, чтобы её не перехватывали FlectonePulse и другие плагины с собственной командой `/unmute`. Namespace предполагает, что имя плагина в его `plugin.yml` — `ModerationCommands`.
+
+Обязательное поведение:
+
+- разрешать мутить онлайн- и офлайн-игрока по UUID;
+- хранить UUID, последнее имя, автора, причину, время выдачи и `expiresAt` между перезапусками;
+- автоматически считать временный мут истёкшим;
+- отменять сообщения через Paper `AsyncChatEvent`, пока мут активен;
+- блокировать настраиваемый список чат-команд, минимум `/msg`, `/tell`, `/w`, `/whisper`, `/reply`, `/r` и `/me`;
+- при попытке писать показывать причину и оставшийся срок;
+- `/unmute` должен немедленно снимать активный мут;
+- повторный mute обновляет существующее активное наказание, а не создаёт конфликтующие записи.
+
+Permissions:
+
+```text
+moderation.command.mute
+moderation.command.unmute
+```
+
+AdminMode вызывает `/mute` и `/unmute` из карточки игрока. Кнопка Unmute доступна по отдельному праву и передаёт причину, если модератор её указал.
+
+### Ban
+
+```text
+/ban <player> <duration> [actor:<name>] <reason...>
+/unban <player> [actor:<name>] [reason...]
+```
+
+Обязательное поведение:
+
+- разрешать банить онлайн- и офлайн-профили;
+- разрешать профиль до UUID, не создавать отдельные name-only баны;
+- получать `ProfileBanList` через `Bukkit.getBanList(BanListType.PROFILE)`;
+- добавлять бан через typed ProfileBanList с причиной, `Instant` окончания или `null` для `permanent`, а также фактическим автором;
+- после добавления бана отключать игрока онлайн с сообщением о причине и сроке;
+- `/unban` удаляет тот же профиль из Paper ProfileBanList;
+- не использовать собственный кэш или базу как источник активного бана: AdminMode снимает бан напрямую через `BanEntry.remove()`.
+
+Permissions:
+
+```text
+moderation.command.ban
+moderation.command.unban
+```
+
+Если нужна история, её можно вести отдельным append-only журналом, но актуальный статус всегда нужно проверять в Paper ProfileBanList.
+
+### Kick
+
+```text
+/kick <player> [actor:<name>] <reason...>
+```
+
+Обязательное поведение:
+
+- команда работает только для игрока онлайн;
+- отключает игрока Adventure-компонентом с причиной и именем модератора;
+- не создаёт постоянное наказание;
+- возвращает понятную ошибку, если игрок уже вышел.
+
+Permission:
+
+```text
+moderation.command.kick
+```
+
+## Существующая команда Warn
+
+Warn остаётся в ядре сервера и должен принимать:
+
+```text
+/warn <player> <duration> <reason...>
+```
+
+Минимально поддерживаемые сроки совпадают со списком выше, включая `permanent`. Источник истории, срока и статуса варнов — AdminMode (`plugins/AdminMode/warn-history.json`), поэтому отдельная команда `/unwarn` для интеграции не требуется.
+
+## Возвращаемый результат команд
+
+Все обработчики Bukkit-команд должны:
+
+- возвращать `true`, только если команда распознана и наказание принято;
+- возвращать `false` при неверном синтаксисе, неизвестном сроке или невозможности применить действие;
+- не изменять данные при ошибке валидации;
+- корректно работать от консоли без OP/LuckPerms-проверки;
+- проверять соответствующий permission при вызове игроком.
+
+AdminMode создаёт локальную запись warn только после успешного `dispatchCommand`. Для Mute/Ban/Kick состояние и сообщения об ошибках полностью отвечает moderation-плагин.
+
+## Настройка AdminMode
+
+Стандартные шаблоны `plugins/AdminMode/config.yml`:
+
+```yaml
+moderation_actions:
+  dispatch_as_console: true
+  commands:
+    warn: "warn {target} {duration} {reason}"
+    mute: "mute {target} {duration} actor:{moderator} {reason}"
+    unmute: "moderationcommands:unmute {target} actor:{moderator} {reason}"
+    ban: "ban {target} {duration} actor:{moderator} {reason}"
+    kick: "kick {target} actor:{moderator} {reason}"
+```
+
+После установки moderation-плагина выполните `/adminmode reload` или перезапустите сервер, затем проверьте каждую команду сначала вручную из консоли и только потом через Dialog.