Плагин управления чатами/PM/упоминаниями для сети Colombino (Paper + Velocity). Цель — единая система чатов с MiniMessage, PlaceholderAPI, антиспамом, логированием и сетевым хранением данных.

• Название плагина: ColombinoChat
• Поддерживаемые версии Paper: 1.20.4+
• Платформа: Paper + Velocity
• Сборка: Uber-Jar (общий артефакт) или один репозиторий с двумя модулями:
  • colombinochat-paper
  • colombinochat-velocity

• Формат путей: example-path-to-something
• Все пользовательские строки (уведомления/ошибки/подсказки) — в messages.yml и поддерживают MiniMessage.

• Conventional Commits по Angular (без scope): https://github.com/angular/angular/blob/main/CONTRIBUTING.md#commit-message-header
• Пример: feat: add mentions cooldown

• CommandAPI не использовать.
• Выбор библиотек (конфиг/БД/миграции) согласовать до старта, но без избыточных зависимостей.

• Scope (уровень чата): область видимости сообщения.
• Network Global: межсерверный чат по сети Velocity.
• Server Global: чат внутри одного Paper-сервера.
• World: чат внутри одного мира (World) на Paper.
• Plot: чат внутри плота PlotSquared (использовать встроенный Plot chat PlotSquared или интеграцию).

Отвечает за:

• Network Global (межсерверный чат)
• Cross-server PM (/pm, /reply)
• Синхронизированный PM ignore (персистентно)
• Хранение/синхронизацию данных через сетевую БД PostgreSQL
• Логи: Network Global, PM, blocked

Отвечает за:

• Server/World/Plot отображение (рендер в чат)
• Форматирование (Adventure/MiniMessage) и PAPI
• Валидацию/антиспам
• Mentions + звук + кулдауны
• Логи Server/World/Plot и blocked

Все данные, требующие хранения и/или синхронизации в сети, должны храниться в PostgreSQL.

• UUID игрока → active-scope / active-channel (если включено сохранение)
• PM ignore-листы (UUID → UUID)
• Оффлайн-упоминания (notifications) с TTL и лимитами

• Везде использовать UUID (ник — только для отображения).

• Пул соединений (например HikariCP) — допускается/рекомендуется.
• Миграции (Flyway/Liquibase или собственный механизм) — согласовать до начала реализации.

1. Network Global — межсерверный (Velocity)
2. Server Global — внутри Paper
3. World — внутри текущего мира
4. Plot — внутри текущего плота (PlotSquared)

Если игрок не находится на плоту:

• A) блокировать отправку + уведомление отправителю
  или
• B) fallback на World или Server (настраивается)

• У игрока есть active-scope (или active-channel-id).
• Настройки:
  • дефолтный scope при входе
  • сохранять ли active-scope в БД (при релоге)
  • синхронизировать ли active-scope в сети (при смене сервера в Velocity)

Минимальный набор:

• /chat network
• /chat server
• /chat world
• /chat plot

Алиасы настраиваемые (пример): /gc, /sc, /wc, /pc.

Команды:

• переключают активный scope
• возвращают подтверждение (MM)

Примеры:

• @network <сообщение>
• @server <сообщение>
• @world <сообщение>
• @plot <сообщение>

Требования:

• возможность задавать любые алиасы тегов/префиксов для каждого scope
• режимы:
  • send-only (без смены active-scope)
  • switch-and-send (сменить active-scope и отправить)

Допускается, что изменение алиасов команд/тегов может не поддерживать hot-reload.

1. Команда (если используется команда отправки)
2. Триггер/префикс в сообщении
3. Активный scope игрока

Во всех текстовых полях с форматированием / hover / click — MiniMessage.

• <username> — ник отправителя
• <message> — сообщение
• <timestamp> — Unix timestamp (host time)

Дополнительно:

• (Network) <source_server_id>
• (Network) <source_server_name> (маппинг ID→DisplayName на стороне Paper)
• (World) <world>
• (Plot) <plot_id> (если доступно)

• Поддержка PAPI плейсхолдеров в местах, где это имеет смысл
• Парсинг PAPI относительно игрока-отправителя

• MM парсится только при permission:
  • colombinochat.message.minimessage
• Без permission — plain text (без MM парсинга)

• Навешивать ClickEvent средствами Adventure.
• Парсинг ссылок только при permission:
  • colombinochat.message.links

Требования:

• при отсутствии http(s):// добавлять https:// (настраиваемо)
• не ограничивать современные TLD (не использовать 2–4 символа)
• опционально: whitelist/blacklist доменов

• Тег по никнейму (например @Nickname), паттерн настраиваем
• Подсветка упоминания задаётся отдельной настройкой (MiniMessage)

• При упоминании игроку воспроизводится звук (настраиваемо)
• Кулдаун на получателя (ms), чтобы исключить спам звуком

Если игрок упомянут, но оффлайн — создать уведомление:

• доставить при следующем входе
• при входе показать "Пока тебя не было: N упоминаний" и/или подсказку команды

Команды:

• /mentions — список уведомлений
• /mentions clear — очистить

Требования:

• Персистентно хранить в PostgreSQL
• TTL (например 7 дней) и лимит на игрока (например 50)

• Комплит никнеймов онлайн игроков сети (Velocity) — по возможности

Команды:

• /pm <игрок> <сообщение> — отправить PM
• /reply <сообщение> (/r) — ответ последнему собеседнику
• /pmignore <игрок> — добавить в игнор
• /pmignore remove <игрок> — убрать из игнора
• /pmignore list — список игнорируемых

Требования:

• Автокомплит никнеймов онлайн игроков сети (Velocity)
• Ignore хранится персистентно в PostgreSQL
• Отдельные форматы для входящих/исходящих PM (MiniMessage)

Опционально:

• звуки на отправку/получение PM (настраиваемо на Paper)
• SocialSpy:
  • /socialspy (toggle)
  • permission colombinochat.socialspy

Конфиг (пример): yaml validation: enabled: true regex: "^[!\"@№;%:?*()_=#$^&\\/\\-—+`~;'<>\u005B\u005D{}|,.a-zA-Zа-яА-ЯёЁҐґЄєЇї0-9\\s]+$"

Требования:

• Валидация применяется к:
  • server/world/plot
  • network (до отправки на прокси)
  • pm
• При блокировке — уведомление отправителю (MM)

Permission bypass:

• colombinochat.validation.bypass

Цель: блокировать спам “почти одинаковыми” сообщениями.

Настройки:

• similarity.enabled
• similarity.threshold-percent (0..100)
• similarity.window-seconds (например 60)
• similarity.max-message-length (лимит на расчёт)

Определение:

• сравнивать текущее сообщение с последним сообщением игрока в пределах window-seconds
• similarity = 1 - (levenshtein / max(len1, len2))
• блокировать, если similarity*100 >= threshold-percent

Нормализация (настраиваемо):

• lower-case
• trim
• collapse spaces
• optional: remove punctuation

Permission bypass:

• colombinochat.similarity.bypass

Формат и ротация логов должны соответствовать формату логов сервера. Хороший пример — дата в имени файла в ISO-формате (YYYY-MM-DD).

• Все сообщения чатов
• Все PM
• Сообщения, заблокированные:
  • validation
  • similarity
  • permissions/прочие фильтры

• Server/World/Plot — на Paper
• Network Global — на Velocity
• PM — на Velocity

Должны быть минимум два потока:

• разрешённые сообщения
• заблокированные сообщения

Пример (точное имя/папка — по стандарту сервера):

• logs/colombinochat/2026-02-22-chat.log
• logs/colombinochat/2026-02-22-chat-blocked.log

Чаты:

• colombinochat.chat.network
• colombinochat.chat.server
• colombinochat.chat.world
• colombinochat.chat.plot

PM:

• colombinochat.pm.send
• colombinochat.pm.reply
• colombinochat.pm.ignore

Сообщения:

• colombinochat.message.minimessage
• colombinochat.message.links

Bypass:

• colombinochat.validation.bypass
• colombinochat.similarity.bypass

Mentions (опционально):

• colombinochat.mentions.bypass

SocialSpy (опционально):

• colombinochat.socialspy

Команда:

• /colombinochat reload

Требования:

• reload перезагружает: форматы, messages, validation, similarity, mentions
• предусмотреть отдельную подкоманду для работы с БД:
  • /colombinochat reload db — переподключение/проверка соединения, обновление кэшей (если используются)
• алиасы команд/регистрация новых команд может требовать рестарт (допускается)

• Работают 4 scope: network/server/world/plot (форматы + триггеры)
• Активный scope переключается и сохраняется согласно настройкам (если включено)
• PM/Reply/Ignore работают по сети Velocity и используют PostgreSQL
• Mentions работают со звуком и кулдауном; оффлайн-упоминания доставляются при входе и хранятся в PostgreSQL
• Validation и Similarity корректно блокируют сообщения + уведомляют отправителя
• Linkify работает только при permission
• Логи пишутся на корректной стороне (paper/velocity), имена/даты соответствуют формату логов сервера, есть blocked лог

A) Реплейсер строк (Text Replacer) — опционально

Фича может быть добавлена позже при необходимости.

Пример конфига:

replacer:
  enabled: true
  mappings:
    ":doge:": "☺"
    ":lol:": "☻"

B) Discord Bridge — отложено

Discord bridge исключён из текущего объёма работ, т.к. требует интеграции с системой верификации и наличия у неё API.

Вернуться к задаче после утверждения:

• модели верификации
• API/протокола взаимодействия бота и прокси
• требований по безопасности и анти-эхо