# Other

# ТЗ 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): <span>https://github.com/angular/angular/blob/main/CONTRIBUTING.md#commit-message-header</span>
- Пример: `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)

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

```yaml
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) — опционально**

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

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

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

```

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

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

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

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