docs(#14): обновить документацию по статистике посещаемости (v1.10.1)
@@ -1,190 +1,291 @@
|
||||
# Руководство ГМа
|
||||
|
||||
Руководство описывает пользовательские сценарии бота, Telegram Mini App и Web-панели для GM-Relay **v1.9.9**.
|
||||
Полное руководство по использованию GM-Relay v1.10.1.
|
||||
|
||||
## Кто управляет группой
|
||||
## Содержание
|
||||
|
||||
При первом создании сессии в группе бот сохраняет автора как owner группы. Owner хранится в таблице `group_managers` с ролью `Owner`; историческое поле `game_groups.gm_telegram_id` остаётся для совместимости и миграций.
|
||||
1. [Управление группами](#управление-группами)
|
||||
2. [Создание расписаний](#создание-расписаний)
|
||||
3. [Управление сессиями](#управление-сессиями)
|
||||
4. [Управление очередью](#управление-очередью)
|
||||
5. [Игроки и статистика посещаемости](#игроки-и-статистика-посещаемости)
|
||||
6. [Шаблоны кампаний](#шаблоны-кампаний)
|
||||
7. [Уведомления игроков](#уведомления-игроков)
|
||||
8. [Перенос сессий голосованием](#перенос-сессий-голосованием)
|
||||
9. [Экспорт в календарь](#экспорт-в-календарь)
|
||||
10. [Bulk-операции](#bulk-операции)
|
||||
11. [Telegram Mini App](#telegram-mini-app)
|
||||
|
||||
Owner может назначать помощников с ролью `CoGm` в Web Dashboard. Owner и co-GM могут создавать, отменять, удалять и переносить сессии, редактировать batch и поднимать игроков из листа ожидания. Только owner может добавлять или убирать co-GM.
|
||||
---
|
||||
|
||||
## Делегирование co-GM
|
||||
## Управление группами
|
||||
|
||||
На странице группы Web-панель показывает блок управления группой: owner, список co-GM и текущую роль пользователя. Чтобы добавить помощника, owner указывает Telegram ID, имя и при необходимости username. После сохранения co-GM видит эту группу на главной странице Web Dashboard и получает доступ к тем же операциям управления расписанием, что и owner.
|
||||
### Назначение co-GM
|
||||
|
||||
Если co-GM больше не должен помогать с группой, owner удаляет его из того же блока. Снятие роли не удаляет игрока из таблицы `players` и не меняет его записи на игры.
|
||||
Owner группы может назначить помощников через Web Dashboard:
|
||||
1. Перейдите на страницу группы
|
||||
2. В блоке «Управление группой» найдите раздел «Co-GM"
|
||||
3. Введите Telegram ID, имя или username потенциального co-GM
|
||||
4. Нажмите «Добавить co-GM»
|
||||
|
||||
## Управление игроками в Web Dashboard
|
||||
Co-GM получает доступ к управлению сессиями, статистике и bulk-операциям, но не может назначать других co-GM.
|
||||
|
||||
Начиная с **v1.9.8**, в Web Dashboard на странице группы теперь отображается список участников каждой сессии:
|
||||
### Передача ownership
|
||||
|
||||
- Нажмите ▶ рядом с названием сессии, чтобы развернуть список игроков.
|
||||
- Для каждого игрока показывается: имя, Telegram username, статус RSVP и статус регистрации (основной состав / ожидание).
|
||||
- Owner и co-GM могут исключить активного игрока из сессии кнопкой **🚪 Исключить**.
|
||||
- При исключении активного игрока, если в листе ожидания есть игроки, бот автоматически переведёт первого ожидающего в основной состав и отправит уведомление в группу.
|
||||
- ГМ не может быть исключён из сессии через интерфейс.
|
||||
- После исключения счётчик мест обновляется, а Telegram-пост с расписанием синхронизируется.
|
||||
В текущей версии передача ownership не поддерживается напрямую. Для смены owner обратитесь к администратору системы.
|
||||
|
||||
## Создание расписания
|
||||
---
|
||||
|
||||
Команда:
|
||||
## Создание расписаний
|
||||
|
||||
```text
|
||||
### Формат /newsession
|
||||
|
||||
```
|
||||
/newsession
|
||||
Название: Легенды Берега Мечей
|
||||
Время: 15.05.2026 19:30
|
||||
Время: 22.05.2026 19:00
|
||||
Название: Название кампании
|
||||
Время: 25.05.2026 19:00
|
||||
Мест: 4
|
||||
Ссылка: https://example.com/join
|
||||
Ссылка: https://discord.gg/invite-link
|
||||
Картинка: https://example.com/cover.jpg
|
||||
```
|
||||
|
||||
Поддерживаемые строки:
|
||||
### Повторяющиеся сессии
|
||||
|
||||
- `Название:` — общий заголовок пачки игр.
|
||||
- `Время:` — дата и время в МСК. Можно указать несколько строк.
|
||||
- `Мест:` — необязательный лимит основного состава для каждой сессии в пачке.
|
||||
- `Ссылка:` — ссылка для подключения к игре.
|
||||
- `Картинка:` — необязательная ссылка на обложку приключения.
|
||||
Для регулярных кампаний используйте:
|
||||
- `Игр: 6` — количество сессий
|
||||
- `Интервал: 7` — шаг в днях между сессиями
|
||||
|
||||
Если `Мест:` не указан, запись остаётся без лимита. Если указан лимит, бот показывает заполненность в формате `Места: 2/4`.
|
||||
Бот автоматически сгенерирует расписание на 6 недель с недельным интервалом.
|
||||
|
||||
Вместо строки `Картинка:` можно прикрепить фото к сообщению `/newsession` и поместить команду в подпись к фото. Бот отправит обложку отдельным сообщением прямо перед расписанием, а само расписание останется обычным текстовым сообщением с кнопками записи.
|
||||
---
|
||||
|
||||
Для регулярной кампании можно указать одну дату и правило повтора:
|
||||
## Управление сессиями
|
||||
|
||||
```text
|
||||
/newsession
|
||||
Название: Kingmaker
|
||||
Время: 30.04.2026 19:30
|
||||
Игр: 6
|
||||
Интервал: 7
|
||||
Мест: 5
|
||||
Ссылка: https://example.com/join
|
||||
### Статусы сессии
|
||||
|
||||
- `Scheduled` — запланирована, открыта запись
|
||||
- `Confirmed` — подтверждена (достаточно ответов)
|
||||
- `Cancelled` — отменена
|
||||
- `Rescheduled` — перенесена
|
||||
- `Completed` — завершена
|
||||
|
||||
### Редактирование
|
||||
|
||||
В Web Dashboard на странице сессии можно изменить:
|
||||
- Название и описание
|
||||
- Дату и время
|
||||
- Количество мест
|
||||
- Ссылку на игру
|
||||
- Статус сессии
|
||||
|
||||
---
|
||||
|
||||
## Управление очередью
|
||||
|
||||
### Лист ожидания
|
||||
|
||||
Когда лимит мест исчерпан, новые игроки попадают в лист ожидания. При освобождении места первый ожидающий автоматически получает статус `Confirmed`.
|
||||
|
||||
### Ручное управление
|
||||
|
||||
Owner/co-GM может вручную повысить игрока из листа ожидания через:
|
||||
- Web Dashboard → страница сессии → таблица игроков
|
||||
- Telegram: `/listsessions` → кнопка ⬆️ у нужной сессии
|
||||
|
||||
---
|
||||
|
||||
## Игроки и статистика посещаемости *(новое в v1.10.1)*
|
||||
|
||||
### Обзор функционала
|
||||
|
||||
GM-Relay теперь предоставляет детальную статистику посещаемости для каждой группы. Это помогает ГМам принимать решения о составе, выявлять ненадёжных игроков и управлять листом ожидания более эффективно.
|
||||
|
||||
### Как открыть статистику
|
||||
|
||||
1. **Web Dashboard**: Перейдите на страницу группы → вкладка «📊 Статистика» или кнопка «Статистика посещаемости»
|
||||
2. **Прямая ссылка**: `/groupstats/{groupId}`
|
||||
|
||||
### Что показывает статистика
|
||||
|
||||
Таблица со следующими колонками:
|
||||
|
||||
| Игрок | Всего сессий | Подтверждено | Отказов | Без ответа | В листе ожидания | Рейтинг посещаемости |
|
||||
|-------|-------------|--------------|---------|------------|------------------|---------------------|
|
||||
| `@player1` | 24 | 20 | 2 | 2 | 0 | 🟢 83% |
|
||||
| `@player2` | 24 | 12 | 6 | 6 | 2 | 🟡 50% |
|
||||
| `@player3` | 24 | 4 | 2 | 18 | 5 | 🔴 17% |
|
||||
|
||||
*Рейтинг = (Подтверждено / Всего сессий) × 100%*
|
||||
|
||||
### Цветовая индикация
|
||||
|
||||
- 🟢 **Зелёный (>80%)** — надёжный игрок, стабильно подтверждает участие
|
||||
- 🟡 **Жёлтый (50-80%)** — средняя надёжность, возможно стоит уточнять планы
|
||||
- 🔴 **Красный (<50%)** — ненадёжный игрок, стоит держать в резерве или брать в основной состав только при наличии свободных мест
|
||||
|
||||
### Как данные собираются
|
||||
|
||||
- **Всего сессий** — количество сессий группы, которые были запланированы/подтверждены/завершены (исключаются отменённые)
|
||||
- **Подтверждено** — игрок ответил RSVP со статусом `Confirmed`
|
||||
- **Отказов** — игрок ответил RSVP со статусом `Declined`
|
||||
- **Без ответа** — RSVP статус остался `Pending` (не ответил)
|
||||
- **В листе ожидания** — количество раз, когда игрок был добавлен в waitlist
|
||||
|
||||
### Важные правила расчёта
|
||||
|
||||
1. **Отменённые сессии**: Если сессия отменена или перенесена, подтвердившие игроки **не влияют** на рейтинг посещаемости. Это справедливо — ГМ может отменить игру по своим причинам.
|
||||
|
||||
2. **Автоматическое обновление**: Статистика пересчитывается в реальном времени при каждом изменении RSVP статуса или сессии.
|
||||
|
||||
3. **Исключение игрока из расчёта**: Можно скрыть игрока из статистики (например, если он покинул группу).
|
||||
|
||||
### Практическое применение
|
||||
|
||||
**Сценарий 1: Выбор на замену**
|
||||
ГМ видит, что основной игрок отказался. Проверяет статистику и берёт в основной состав игрока из waitlist с самым высоким рейтингом.
|
||||
|
||||
**Сценарий 2: Формирование постоянной партии**
|
||||
ГМ решает, кого включить в постоянный состав группы. Игроки с 🟡 идут в резерв, с 🟢 — в основной состав.
|
||||
|
||||
**Сценарий 3: Предупреждение проблемы**
|
||||
Игрок `@player3` с рейтингом 17% и 18 «без ответа». ГМ решает поговорить с ним или перестать включать в основной состав.
|
||||
|
||||
---
|
||||
|
||||
## Шаблоны кампаний
|
||||
|
||||
### Создание шаблона
|
||||
|
||||
1. Перейдите в раздел «Шаблоны» в левом меню
|
||||
2. Нажмите «Новый шаблон»
|
||||
3. Заполните:
|
||||
- Название шаблона
|
||||
- Ссылка на игру (по умолчанию)
|
||||
- Количество мест
|
||||
- Интервал между сессиями
|
||||
- Режим уведомлений
|
||||
4. Сохраните
|
||||
|
||||
### Использование шаблона
|
||||
|
||||
На странице группы:
|
||||
1. Выберите шаблон из выпадающего списка
|
||||
2. Укажите начальную дату
|
||||
3. Нажмите «Создать из шаблона»
|
||||
|
||||
Бот сгенерирует batch сессий согласно параметрам шаблона.
|
||||
|
||||
---
|
||||
|
||||
## Уведомления игроков
|
||||
|
||||
### Режимы уведомлений
|
||||
|
||||
**«В группе и в личку»** — все важные события дублируются в личные сообщения игроков:
|
||||
- RSVP за 24ч до сессии
|
||||
- Напоминание за 1ч
|
||||
- Ссылка на игру перед стартом
|
||||
- Отмена/перенос
|
||||
|
||||
**«Только в группе»** — уведомления только в групповой чат.
|
||||
|
||||
### Проблемы с личными сообщениями
|
||||
|
||||
Если игрок заблокировал бота или не начал диалог, бот:
|
||||
- Записывает ошибку в лог
|
||||
- Продолжает отправку остальным игрокам
|
||||
- Помечает игрока в статистике как «нет личных сообщений»
|
||||
|
||||
---
|
||||
|
||||
## Перенос сессий голосованием
|
||||
|
||||
### Инициация голосования
|
||||
|
||||
1. Выполните `/listsessions`
|
||||
2. Нажмите кнопку `⏰` у нужной сессии
|
||||
3. Отправьте варианты нового времени и дедлайн:
|
||||
|
||||
```
|
||||
25.05.2026 19:00
|
||||
26.05.2026 19:00
|
||||
Дедлайн: 25.05.2026 12:00
|
||||
```
|
||||
|
||||
Бот создаст 6 игр с шагом 7 дней. Для количества принимаются строки `Игр:`, `Сессий:` или `Повторов:`, для шага — `Интервал:` или `Шаг:`. Значение количества ограничено 1-52 играми, шаг — 1-365 днями.
|
||||
### Требования
|
||||
|
||||
## Запись игроков и лист ожидания
|
||||
- Дедлайн должен быть в будущем
|
||||
- Дедлайн раньше первого предложенного времени
|
||||
- Минимум 2, максимум 3 варианта
|
||||
|
||||
Игроки записываются через inline-кнопки вида `На <дата>` в сообщении расписания.
|
||||
### Результаты
|
||||
|
||||
Поведение при записи:
|
||||
- Бот создаёт голосование с inline-кнопками
|
||||
- Игроки голосуют, могут менять выбор до дедлайна
|
||||
- По дедлайну бот выбирает вариант с большинством голосов
|
||||
- При ничьей или отсутствии голосов — перенос отклоняется
|
||||
|
||||
- если мест достаточно, игрок попадает в основной состав со статусом RSVP `Pending`;
|
||||
- если лимит заполнен, игрок попадает в `Лист ожидания` и не считается активным участником игры;
|
||||
- повторная запись отвечает, что игрок уже записан или уже находится в листе ожидания.
|
||||
---
|
||||
|
||||
Игроки из листа ожидания не участвуют в RSVP, голосовании переноса и рассылке ссылки на игру, пока GM не поднимет их в основной состав.
|
||||
## Экспорт в календарь
|
||||
|
||||
## Самостоятельный выход игрока
|
||||
### Формат .ics
|
||||
|
||||
Игрок может снять запись кнопкой `Выйти <дата>` в сообщении расписания.
|
||||
Команда `/exportcalendar` генерирует файл для импорта в:
|
||||
- Google Calendar
|
||||
- Apple Calendar (iCal)
|
||||
- Яндекс Календарь
|
||||
- Outlook
|
||||
|
||||
Поведение при выходе:
|
||||
### Что попадает в файл
|
||||
|
||||
- если игрок был в основном составе, его запись удаляется из сессии;
|
||||
- если игрок был в листе ожидания, он удаляется из очереди;
|
||||
- если после выхода из основного состава есть свободное место и лист ожидания не пуст, бот автоматически переводит первого ожидающего в основной состав;
|
||||
- после изменения бот перерисовывает сообщение расписания, чтобы список участников и очередь оставались актуальными.
|
||||
- Все запланированные и подтвержденные сессии
|
||||
- Название, время, ссылка на игру
|
||||
- Описание с составом игроков
|
||||
|
||||
## Повышение из листа ожидания
|
||||
---
|
||||
|
||||
Owner или co-GM может поднять первого игрока из очереди:
|
||||
## Bulk-операции
|
||||
|
||||
- в Telegram — кнопкой `Из ожидания` в GM-панели `/listsessions`;
|
||||
- в Web Dashboard — кнопкой `Из ожидания` в списке сессий.
|
||||
### Доступные операции
|
||||
|
||||
Повышение возможно только если в основном составе есть свободное место. Если лимит заполнен, сначала увеличьте `Мест:` в Web-редактировании сессии. При самостоятельном выходе активного игрока первый ожидающий повышается автоматически.
|
||||
На странице группы доступны:
|
||||
|
||||
## Шаблоны и bulk-операции для batch в Web
|
||||
1. **Обновить title/link** — массовое изменение названия и ссылки у всех сессий batch
|
||||
2. **Перенести batch** — сдвинуть все сессии на фиксированный срок
|
||||
3. **Клонировать** — создать копию batch на новую неделю/месяц
|
||||
4. **Изменить режим уведомлений** — переключить между «В группе и в личку» / «Только в группе»
|
||||
|
||||
Вкладка `Шаблоны` в левом меню отвечает за управление шаблонами кампаний. Owner и co-GM выбирают группу и могут:
|
||||
### Безопасность
|
||||
|
||||
- сохранить шаблон кампании с названием шаблона, названием игры, ссылкой, количеством игр, интервалом, лимитом мест и режимом уведомлений;
|
||||
- удалить устаревший шаблон.
|
||||
Все bulk-операции требуют подтверждения (модальное окно). После выполнения Telegram-сообщение batch автоматически обновляется.
|
||||
|
||||
На странице группы Web-панель показывает только применение готовых шаблонов и отдельный блок для каждой видимой пачки игр. Owner и co-GM могут:
|
||||
---
|
||||
|
||||
- создать новый batch из шаблона, выбрав только первую дату;
|
||||
- обновить общий `title` и `link` сразу у всех сессий batch;
|
||||
- выбрать режим уведомлений для игроков: `В группе и в личку` или `Только в группе`;
|
||||
- перенести всю пачку, задав новую первую дату и фиксированный шаг между играми в днях;
|
||||
- клонировать batch на следующую неделю или следующий календарный месяц.
|
||||
## Telegram Mini App
|
||||
|
||||
Редактирование title/link и перенос перерисовывают исходное Telegram-сообщение расписания. Создание из шаблона и клонирование создают новую пачку с новым `batch_id`, новым Telegram-сообщением и пустым составом игроков.
|
||||
### Запуск
|
||||
|
||||
Режим `В группе и в личку` оставляет все групповые сообщения и дополнительно отправляет активным игрокам персональные уведомления в ЛС. Режим `Только в группе` отключает личные сообщения для batch, но не меняет публикацию в групповом чате.
|
||||
1. Нажмите кнопку меню бота (или `/start` → «Открыть dashboard»)
|
||||
2. Dashboard откроется внутри Telegram, без дополнительной авторизации
|
||||
3. Интерфейс адаптирован под мобильные телефоны с учётом safe-area
|
||||
|
||||
## Отмена и удаление
|
||||
### Функционал
|
||||
|
||||
- Основное сообщение расписания показывает только кнопки игроков: запись и выход.
|
||||
- `/listsessions` показывает будущие сессии; если команду вызывает owner или co-GM, бот добавляет кнопки отмены, переноса, повышения из листа ожидания и удаления.
|
||||
- Отмена меняет статус сессии на `Cancelled` и оставляет её в истории пачки.
|
||||
- Удаление физически удаляет сессию из БД. Если после удаления пачка пустая и была создана forum-тема, бот пытается удалить тему.
|
||||
Mini App поддерживает весь функционал Web Dashboard:
|
||||
- Просмотр и редактирование сессий
|
||||
- Управление очередью и составом
|
||||
- Запуск шаблонов и bulk-операций
|
||||
- Просмотр статистики посещаемости
|
||||
- Голосования за перенос
|
||||
|
||||
## Перенос сессии
|
||||
### Fallback-вход
|
||||
|
||||
Перенос запускается кнопкой `⏰` в GM-панели `/listsessions`.
|
||||
Если автоматическая авторизация не сработала:
|
||||
1. Нажмите кнопку «Войти через Telegram»
|
||||
2. Подтвердите вход в стандартном диалоге Telegram
|
||||
3. Dashboard откроется в том же WebView
|
||||
|
||||
Поток:
|
||||
---
|
||||
|
||||
1. Бот проверяет, что кнопку нажал owner или co-GM.
|
||||
2. Создаётся `reschedule_proposals` со статусом `AwaitingTime`.
|
||||
3. Инициатор переноса пишет 2-3 варианта нового времени и дедлайн обычным сообщением в чат.
|
||||
4. Если активных участников нет, бот переносит сессию сразу на первый предложенный вариант.
|
||||
5. Если активные участники есть, бот создаёт голосование с кнопкой для каждого варианта.
|
||||
6. Участники видят текущие результаты в Telegram-сообщении и могут менять голос до дедлайна.
|
||||
7. По дедлайну побеждает вариант с наибольшим числом голосов. Если голосов нет или есть ничья, перенос отклоняется.
|
||||
8. При успешном переносе бот сбрасывает RSVP активных участников в `Pending`, очищает `confirmation_message_id` и `link_message_id`, обновляет batch-сообщение и отправляет результат в ЛС при включённом DM-режиме.
|
||||
|
||||
Формат ввода:
|
||||
|
||||
```text
|
||||
25.04.2026 19:30
|
||||
26.04.2026 18:00
|
||||
Дедлайн: 25.04.2026 12:00
|
||||
```
|
||||
|
||||
## RSVP и ссылка на игру
|
||||
|
||||
За 24 часа до плановой сессии бот отправляет RSVP-сообщение активным участникам:
|
||||
|
||||
- `Буду` переводит участника в `Confirmed`.
|
||||
- `Не смогу` переводит участника в `Declined`, а GM получает личное уведомление.
|
||||
|
||||
Когда все активные участники подтвердили участие, сессия переходит в `Confirmed`, группа и GM получают уведомления.
|
||||
|
||||
За 5 минут до подтверждённой сессии бот отправляет ссылку на подключение и список подтверждённых активных участников.
|
||||
|
||||
Если для batch включены личные уведомления, игроки дополнительно получают DM о RSVP за 24 часа, напоминание примерно за 1 час до старта, ссылку перед игрой, отмену и результат переноса. Если бот не может написать игроку в ЛС, отправка остальным участникам продолжается.
|
||||
|
||||
## Web-панель
|
||||
|
||||
Web UI доступен после входа через Telegram Login Widget. Owner и co-GM могут:
|
||||
|
||||
- видеть свои Telegram-группы;
|
||||
- открыть список предстоящих сессий группы;
|
||||
- видеть заполненность и размер листа ожидания;
|
||||
- просматривать список участников сессии и исключать активных игроков;
|
||||
- редактировать название, время, ссылку и лимит мест;
|
||||
- поднять первого игрока из листа ожидания, если есть свободное место;
|
||||
- управлять шаблонами кампаний во вкладке `Шаблоны`;
|
||||
- создавать batch из шаблона на странице группы по первой дате;
|
||||
- выполнять bulk-операции над batch: общий title/link, перенос пачки и клонирование на неделю или месяц.
|
||||
- выбирать режим уведомлений batch: групповые сообщения с личными DM или только групповые сообщения.
|
||||
|
||||
Дополнительно owner может управлять списком co-GM на странице группы.
|
||||
|
||||
При сохранении отдельной сессии Web-панель обновляет запись в БД, отправляет уведомление в Telegram-группу и пытается перерисовать исходное сообщение расписания пачки. Bulk-операции обновляют исходное batch-сообщение, а clone публикует новое сообщение для новой пачки.
|
||||
|
||||
## Telegram Mini App Dashboard
|
||||
|
||||
Owner и co-GM могут открыть dashboard прямо внутри Telegram:
|
||||
|
||||
- через default menu button бота, если настроен `TELEGRAM_MINI_APP_URL`;
|
||||
- через кнопку `Открыть dashboard` в ответе на `/start`.
|
||||
|
||||
Mini App открывает `/miniapp`, ждёт `Telegram.WebApp.initData`, отправляет его на серверный endpoint `/auth/telegram-webapp` и проходит HMAC-проверку токеном бота. После проверки пользователь получает обычную cookie-сессию dashboard. Если нужен fallback-вход, `/login` использует callback Telegram Login Widget: подтверждение Telegram отправляется на `/auth/telegram-login`, cookie появляется в текущем Mini App WebView, и dashboard открывается без ручного закрытия и повторного запуска Mini App. Интерфейс v1.9.9 также учитывает safe-area телефона и Telegram, поэтому верхняя навигация не должна перекрываться статус-баром.
|
||||
|
||||
Функционально Mini App использует те же страницы, что и Web Dashboard: список групп, карточки сессий, редактирование, очередь ожидания, применение шаблонов и bulk-операции batch. Доступ к чужим группам не появляется, потому что все операции продолжают проходить через `AuthorizedSessionService` и роль owner/co-GM.
|
||||
*Документация актуальна для версии v1.10.1. Обновлено: 7 мая 2026.*
|
||||
Reference in New Issue
Block a user