Colombino Analytics — ТЗ

Проект Plane: пока CREATIVE (отдельный проект аналитики не заведён). Источник: обсуждение 25.08.2026 (retention, ключевые действия, история плотов, Plan). Документ — контракт v1, не экран в Plan.

Плагин-шина ключевых действий игроков. Другие плагины вызывают API, события пишутся в свою PostgreSQL. Plan (stats.binomc.net), DataExtension и отчёт воронки в v1 нет.

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

• Название: ColombinoAnalytics

• Платформа: Paper (Hub, Creative, ивентовые) + Velocity Master

• Сборка: один репозиторий, три модуля:

  • analytics-api — тонкий jar, compileOnly у других плагинов

  • analytics-paper

  • analytics-velocity

• БД: отдельная database PostgreSQL (тот же хост, что Plane/Bookstack, не их схемы и не БД Plan)

• Soft-depend (Paper): PlotSquared, BinoRankup, PlotMark — нет плагина, нет слушателя, API живёт

1) Зачем

Три цели на одном логе. Creative — UGC: активация не «зашёл», а взял слот. Ивентовые режимы (Build Battle и др.) в логе не отдельные продукты, а значение server у захода.

2) Готово когда (v1)

1. Jar analytics-api: другой плагин вызывает track, строка появляется в Postgres. Если analytics не установлен — вызов no-op, не падает.

2. Velocity Master пишет заходы с каноническим именем сервера.

3. Paper Creative пишет плоты, заявки ранга, staff-ревью/рейтинг, марки PlotMark.

4. Paper стоит на Hub и ивентовых бэкендах (API и будущие типы; заходы в v1 пишет прокси).

Не в приёмке v1: DataExtension и страницы Plan, дашборд retention, BlockPlace, плагин на Shadow, TTL/чистка лога, Redis.

3) Термины

4) Архитектура

Почему не таблица в БД Plan: DataExtension не пишет события (4 колонки на игрока, 50 символов в ячейке). Query API — SQLite/MySQL. Заходы со всех серверов не кладём в боевую БД Plan: патчи, /plan db clear и move не знают чужие таблицы; воронки будут конкурировать с вебом.

Поток: Velocity Master и Paper пишут в одну PostgreSQL player_events. Прокси шлёт на Paper plugin message канала colombino:analytics (session_id + канон server). Плот, ранг и марки прокси не слушает.

5) Воронка новичка (как смотрит аналитик)

1. Зашёл в сеть → заход с server=hub

2. Попал на Creative → заход с server=creative

3. Взял плот → plot.claimed ← активация

4. Подал /done → rank.request_submitted (/rankup — только меню, не этот шаг)

5. Заявка закрылась → rank.request_status_changed (APPROVED / REJECTED / WITHDRAWN / DELETED)

6. Получил ранг → rank.granted

Дыра между 3 и 4: PlotSquared не видит «начал строить». Без BlockPlace на своём плоте не отличить «взял и бросил» от «строит третий день». В v1 дыру помечаем, не закрываем.

«Поучаствовал в Build Battle» = заход на ивентовый сервер. Отдельного типа build_battle.joined нет.

6) Каталог событий v1 (закрыт)

Строка: player_uuid, event_type, occurred_at, server, session_id, extra (JSONB строго по типу). Неизвестный тип API отвергает. Свободных строк типов нет.

6.1 Заходы (пишет только Velocity)

Hub → Creative → Hub → Creative в одном визите: по одному session_joined на hub и на creative. Возврат на Creative в той же сессии не пишем.

6.2 Плоты (PlotSquared, Creative)

Активация и история владения. PlayerEnterPlotEvent не пишем. Trusted/members в v1 нет. plot_id — идентификатор из PlotSquared API. width — ширина в блоках.

6.3 Ранг — новичок (BinoRankup)

Слушаем Bukkit API плагина, хуки не выдумываем. categories — как отдаёт Rankup (JSON-массив строк). Имена классов сверить с репозиторием при реализации; смысл событий не менять.

6.4 Ранг — staff (основная метрика команды)

Review без voter_role не пишем: вес голоса в Rankup от роли. Обычный игроковый /rate в лог не идёт (отсекаем на входе).

6.5 Марки (PlotMark, Creative)

См. Метки на плотах — ТЗ. PlotMark вызывает Analytics.track или отдаёт Bukkit-событие с тем же extra.

7) Хранение

Таблица player_events, append-only.

Индексы: (player_uuid, occurred_at DESC); (event_type, occurred_at); (server, event_type, occurred_at); expression (extra->>'plot_id'), (extra->>'request_id'). GIN по всему extra в v1 нет.

Уникальность: first_joined — (player_uuid, event_type, server). session_joined — (session_id, event_type, server) WHERE session_id IS NOT NULL (без WHERE в Postgres несколько NULL не дедупятся). Повтор — ON CONFLICT DO NOTHING. Плот/ранг/марки не дедупим.

TTL сырого лога в v1 нет. Политика хранения — отдельное решение по факту объёма.

8) Кто пишет что

8.1 Velocity Master

• Выдаёт session_id на время пребывания в сети.

• Пишет два типа заходов (§6.1). First: кэш + уникальный индекс (гонка → conflict ignore).

• После коннекта/switch на Paper — plugin message с session_id и каноном server.

8.2 Paper

• Не считает first/session. track() дописывает текущие session_id и server.

• Нет сообщения с прокси — событие пишем, session_id = null. Факт plot.claimed важнее склейки с сессией.

• Состояние: карта UUID → сессия до quit. Тот же session_id при каждом switch.

• Гонка: событие раньше plugin message — допустимо, session_id null.

Shadow: в v1 не ставим. Иначе два источника сессий. Игрок через Shadow = как без прокси.

Не в v1: Redis, слушатели плотов на прокси.

9) API

boolean track(UUID player, String eventType, Map<String, Object> extra)

• Нет paper/velocity плагина на сервере → no-op, false.

• Тип не из каталога или нет обязательных ключей extra → false, warn в лог, в очередь не кладём.

• Успешный enqueue → true (ещё не значит «уже в Postgres»).

Игровой поток только enqueue. Фоновый writer — batch insert. Главный поток JDBC не ждёт.

10) Ошибки

11) Тесты (CI без живого MC)

• Контракт extra: полный набор — ok; дырявый — reject.

• Дедуп first_joined и session_joined.

• rank.rating_submitted: Helper/Mentor/Senior Mentor — пишем; игрок без роли — нет.

• rank.review_submitted без voter_role — нет.

• Запрос-заготовка воронки: цепочка типов по uuid (не UI).

12) Следующие этапы (не v1)

1. DataExtension Plan: счётчики, first/last, урезанная история (лимиты Plan: 4 колонки, 50 символов).

2. Отчёт воронки / retention по когортам (SQL или отдельный сервис).

3. Закрытие дыры «взял плот, не строит».

4. Velocity Shadow, если станет основным входом.

5. TTL/партиции, когда будет ясен объём.

13) Сознательно отвергнутое

• Хранение в БД Plan через Query API.

• DataExtension как «запись в БД» — он не пишет лог.

• build_battle.joined — дубль захода на ивентовый server.

• PlayerEnterPlotEvent — ходьба, не ключ.

• Каждый Paper join без дедупа по network-сессии.

• PostgreSQL через Plan API — не поддерживается (SQLITE / MYSQL only).