diff --git a/%D0%A0%D1%83%D0%BA%D0%BE%D0%B2%D0%BE%D0%B4%D1%81%D1%82%D0%B2%D0%BE-%D0%93%D0%9C%D0%B0.md b/%D0%A0%D1%83%D0%BA%D0%BE%D0%B2%D0%BE%D0%B4%D1%81%D1%82%D0%B2%D0%BE-%D0%93%D0%9C%D0%B0.md index 90bea0e..db22e08 100644 --- a/%D0%A0%D1%83%D0%BA%D0%BE%D0%B2%D0%BE%D0%B4%D1%81%D1%82%D0%B2%D0%BE-%D0%93%D0%9C%D0%B0.md +++ b/%D0%A0%D1%83%D0%BA%D0%BE%D0%B2%D0%BE%D0%B4%D1%81%D1%82%D0%B2%D0%BE-%D0%93%D0%9C%D0%B0.md @@ -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.* \ No newline at end of file