# Контракт 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.