Skip to main content

ТЗ Colombino Chat

ColombinoChat — ТЗ

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

0) Техническая информация

  • Название плагина: ColombinoChat

  • Поддерживаемые версии Paper: 1.20.4+

  • Платформа: Paper + Velocity

  • Сборка: Uber-Jar (общий артефакт) или один репозиторий с двумя модулями:

    • colombinochat-paper

    • colombinochat-velocity

1) Гайдлайны

1.1 YAML

  • Формат путей: example-path-to-something

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

1.2 Git / коммиты

  • Conventional Commits по Angular (без scope): https://github.com/angular/angular/blob/main/CONTRIBUTING.md#commit-message-header

  • Пример: feat: add mentions cooldown

1.3 Стек библиотек

  • CommandAPI не использовать.

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

2) Термины

  • Scope (уровень чата): область видимости сообщения.

  • Network Global: межсерверный чат по сети Velocity.

  • Server Global: чат внутри одного Paper-сервера.

  • World: чат внутри одного мира (World) на Paper.

  • Plot: чат внутри плота PlotSquared (использовать встроенный Plot chat PlotSquared или интеграцию).

3) Архитектура и зоны ответственности

3.1 Velocity (прокси)

Отвечает за:

  • Network Global (межсерверный чат)

  • Cross-server PM (/pm, /reply)

  • Синхронизированный PM ignore (персистентно)

  • Хранение/синхронизацию данных через сетевую БД PostgreSQL

  • Логи: Network Global, PM, blocked

3.2 Paper (бекенд)

Отвечает за:

  • Server/World/Plot отображение (рендер в чат)

  • Форматирование (Adventure/MiniMessage) и PAPI

  • Валидацию/антиспам

  • Mentions + звук + кулдауны

  • Логи Server/World/Plot и blocked

4) Хранение данных (обязательное)

4.1 Общее правило

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

4.2 Что хранить в БД (минимум)

  • UUID игрока → active-scope / active-channel (если включено сохранение)

  • PM ignore-листы (UUID → UUID)

  • Оффлайн-упоминания (notifications) с TTL и лимитами

4.3 Идентификаторы

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

4.4 БД-слой

  • Пул соединений (например HikariCP) — допускается/рекомендуется.

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

5) Уровни чата (Scopes)

5.1 Обязательные scopes

  1. Network Global — межсерверный (Velocity)

  2. Server Global — внутри Paper

  3. World — внутри текущего мира

  4. Plot — внутри текущего плота (PlotSquared)

5.2 Поведение Plot scope

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

  • A) блокировать отправку + уведомление отправителю
    или

  • B) fallback на World или Server (настраивается)

6) Переключение чатов и триггеры

6.1 Активный чат (state)

  • У игрока есть active-scope (или active-channel-id).

  • Настройки:

    • дефолтный scope при входе

    • сохранять ли active-scope в БД (при релоге)

    • синхронизировать ли active-scope в сети (при смене сервера в Velocity)

6.2 Команды переключения

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

  • /chat network

  • /chat server

  • /chat world

  • /chat plot

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

Команды:

  • переключают активный scope

  • возвращают подтверждение (MM)

6.3 Триггеры в сообщениях (send-only / switch-and-send)

Примеры:

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

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

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

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

Требования:

  • возможность задавать любые алиасы тегов/префиксов для каждого scope

  • режимы:

    • send-only (без смены active-scope)

    • switch-and-send (сменить active-scope и отправить)

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

6.4 Приоритет обработки

  1. Команда (если используется команда отправки)

  2. Триггер/префикс в сообщении

  3. Активный scope игрока

7) Форматирование сообщений

7.1 MiniMessage в конфигурации

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

7.2 Плейсхолдеры (встроенные)

  • &lt;username&gt; — ник отправителя

  • &lt;message&gt; — сообщение

  • &lt;timestamp&gt; — Unix timestamp (host time)

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

  • (Network) <source_server_id>

  • (Network) <source_server_name> (маппинг ID→DisplayName на стороне Paper)

  • (World) &lt;world&gt;

  • (Plot) <plot_id> (если доступно)

7.3 PlaceholderAPI

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

  • Парсинг PAPI относительно игрока-отправителя

8) MiniMessage в сообщениях игроков и ссылки

8.1 MM в сообщении игрока

  • MM парсится только при permission:

    • colombinochat.message.minimessage

  • Без permission — plain text (без MM парсинга)

8.2 Автокликабельные ссылки (linkify)

  • Навешивать ClickEvent средствами Adventure.

  • Парсинг ссылок только при permission:

    • colombinochat.message.links

Требования:

  • при отсутствии http(s):// добавлять https:// (настраиваемо)

  • не ограничивать современные TLD (не использовать 2–4 символа)

  • опционально: whitelist/blacklist доменов

9) Система упоминаний (Mentions)

9.1 Упоминания

  • Тег по никнейму (например @Nickname), паттерн настраиваем

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

9.2 Звук и кулдаун

  • При упоминании игроку воспроизводится звук (настраиваемо)

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

9.3 Оффлайн-упоминания (Notifications)

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

  • доставить при следующем входе

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

Команды:

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

  • /mentions clear — очистить

Требования:

  • Персистентно хранить в PostgreSQL

  • TTL (например 7 дней) и лимит на игрока (например 50)

9.4 Автокомплит

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

10) Cross-server PM (Личные сообщения)

Команды:

  • /pm <игрок> <сообщение> — отправить PM

  • /reply <сообщение> (/r) — ответ последнему собеседнику

  • /pmignore <игрок> — добавить в игнор

  • /pmignore remove <игрок> — убрать из игнора

  • /pmignore list — список игнорируемых

Требования:

  • Автокомплит никнеймов онлайн игроков сети (Velocity)

  • Ignore хранится персистентно в PostgreSQL

  • Отдельные форматы для входящих/исходящих PM (MiniMessage)

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

  • звуки на отправку/получение PM (настраиваемо на Paper)

  • SocialSpy:

    • /socialspy (toggle)

    • permission colombinochat.socialspy

11) Валидация сообщений (Regex)

Конфиг (пример):

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

Требования:

  • Валидация применяется к:

    • server/world/plot

    • network (до отправки на прокси)

    • pm

  • При блокировке — уведомление отправителю (MM)

Permission bypass:

  • colombinochat.validation.bypass

12) Фильтрация однотипных сообщений (Levenshtein Similarity)

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

Настройки:

  • 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

13) Логирование

13.1 Требование по формату и именованию

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

13.2 Что логировать

  • Все сообщения чатов

  • Все PM

  • Сообщения, заблокированные:

    • validation

    • similarity

    • permissions/прочие фильтры

13.3 Где логировать

  • Server/World/Plot — на Paper

  • Network Global — на Velocity

  • PM — на Velocity

13.4 Минимальная структура

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

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

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

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

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

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

14) Permissions (минимум)

Чаты:

  • 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

15) Hot Reload

Команда:

  • /colombinochat reload

Требования:

  • reload перезагружает: форматы, messages, validation, similarity, mentions

  • предусмотреть отдельную подкоманду для работы с БД:

    • /colombinochat reload db — переподключение/проверка соединения, обновление кэшей (если используются)

  • алиасы команд/регистрация новых команд может требовать рестарт (допускается)

16) Acceptance Criteria (готовность)

  • Работают 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/протокола взаимодействия бота и прокси

  • требований по безопасности и анти-эхо

 

No comments to display

Back to top