docs(wiki): rewrite GM Guide for v2.7.2

2026-05-21 18:44:02 +03:00
parent 86b60f2ee9
commit a112cd7aaa
2 changed files with 127 additions and 291 deletions
@@ -0,0 +1,127 @@
 # Руководство ГМа
 ## Создание группы
 ### Telegram
 - Напишите боту `/newgroup`.
 - Укажите название группы.
 - Группа создана — вы назначены owner.
 ### Веб-дашборд
 - Зайдите на сайт / откройте Mini App.
 - Нажмите "Создать группу".
 - Укажите название, описание, платформу (Telegram / Discord / обе).
 ## Создание расписания (Batch)
 ### Telegram: `/newsession`
 Формат сообщения:
 ```
 Название: Название кампании
 Ссылка: https://roll20.net/...
 Картинка: https://... (опционально)
 2026-05-25 19:00 5
 2026-05-28 19:00 5
 ```
 - Каждая строка: `YYYY-MM-DD HH:MM max_players`.
 - `max_players` — максимальный состав (0 = без ограничений).
 - `Картинка:` — обложка batch (опционально).
 ### Discord: `/newsession`
 - Slash-команда `/newsession`.
 - Заполните поля: title, dates (через запятую), max-players, link.
 - Бот создаст batch и пришлёт подтверждение.
 ## Публикация расписания
 ### Telegram: `/listsessions`
 - Показывает все сессии группы с inline-кнопками Join/Leave.
 - Можно отменить (`❌`) или удалить (`🗑`) сессию.
 - Можно инициировать перенос (`🔄`).
 ### Discord: `/listsessions`
 - Публикует embed с расписанием и кнопками Join/Leave.
 - При нажатии кнопок schedule message автоматически обновляется.
 ## Управление игроками
 ### Лист ожидания (Waitlist)
 - Когда сессия заполнена — новые игроки попадают в waitlist.
 - При выходе участника первый из waitlist автоматически поднимается в основной состав.
 - В веб-дашборде ГМ может вручную поднять игрока из очереди.
 ### Co-GM
 - Owner может назначить co-GM по Telegram ID в веб-дашборде.
 - Co-GM может: создавать/редактировать сессии, управлять waitlist.
 - Co-GM **не может** назначать других co-GM.
 ## Шаблоны кампаний
 - В веб-дашборде: вкладка `Шаблоны`.
 - Сохраните типовые параметры (title, max-players, link).
 - Запустите новый batch из шаблона в один клик.
 ## Bulk-операции (Web Dashboard)
 - **Обновить title/link**: применить к всему batch.
 - **Сдвинуть даты**: перенести все сессии на +N дней.
 - **Клонировать**: скопировать batch на следующую неделю или месяц.
 ## Переносы (Reschedule Voting)
 ### Как инициировать
 - **Telegram**: в `/listsessions` нажмите `🔄` у сессии.
 - **Discord**: в schedule message нажмите кнопку reschedule.
 ### Как работает
 - Бот предлагает варианты новых дат/времени.
 - Игроки голосуют кнопками.
 - Голосование завершается по дедлайну (обычно через N часов).
 - Побеждает вариант с наибольшим количеством голосов.
 - Schedule message автоматически обновляется.
 ## RSVP (Подтверждения)
 - За 24 часа до сессии бот отправляет запрос подтверждения.
 - **Telegram**: inline-кнопки "Подтвердить" / "Отклонить".
 - **Discord**: кнопки **Confirm** / **Decline**.
 - GM получает итоги RSVP.
 ## Уведомления
 ### Режимы
 - `В группе и в личку` — каждый игрок получает DM + групповое сообщение.
 - `Только в группе` — только групповые сообщения.
 ### Типы уведомлений
 - За 24ч: запрос подтверждения (RSVP).
 - За 1ч: напоминание.
 - За 5 мин: ссылка на игру.
 - Отмена / перенос: уведомление об изменении.
 ## Статистика посещаемости
 - Страница `/group/{id}/stats`.
 - Показывает долю присутствия, пропуски, среднюю явку по каждому игроку.
 - Считается только для завершённых сессий (статус `completed`).
 ## История изменений
 - Страница `/session/{id}/history`.
 - Аудит-лог: время, ссылка, название, участники, статус.
 - Указывается актор и дата изменения.
 ## FAQ для ГМа
 ### Бот не отвечает
 - Проверьте права администратора в группе.
 - Попробуйте `/start`.
 ### Кнопки не работают
 - Нужно право "Manage Messages".
 - Подождите 1–2 минуты — возможно, rate limit.
 ### Mini App не открывается
 - Должен быть HTTPS.
 - Домен должен быть зарегистрирован в BotFather (`/setdomain`).
@@ -1,291 +0,0 @@
 # Руководство ГМа
 Полное руководство по использованию GM-Relay v1.10.1.
 ## Содержание
 1. [Управление группами](#управление-группами)
 2. [Создание расписаний](#создание-расписаний)
 3. [Управление сессиями](#управление-сессиями)
 4. [Управление очередью](#управление-очередью)
 5. [Игроки и статистика посещаемости](#игроки-и-статистика-посещаемости)
 6. [Шаблоны кампаний](#шаблоны-кампаний)
 7. [Уведомления игроков](#уведомления-игроков)
 8. [Перенос сессий голосованием](#перенос-сессий-голосованием)
 9. [Экспорт в календарь](#экспорт-в-календарь)
 10. [Bulk-операции](#bulk-операции)
 11. [Telegram Mini App](#telegram-mini-app)
 ---
 ## Управление группами
 ### Назначение co-GM
 Owner группы может назначить помощников через Web Dashboard:
 1. Перейдите на страницу группы
 2. В блоке «Управление группой» найдите раздел «Co-GM"
 3. Введите Telegram ID, имя или username потенциального co-GM
 4. Нажмите «Добавить co-GM»
 Co-GM получает доступ к управлению сессиями, статистике и bulk-операциям, но не может назначать других co-GM.
 ### Передача ownership
 В текущей версии передача ownership не поддерживается напрямую. Для смены owner обратитесь к администратору системы.
 ---
 ## Создание расписаний
 ### Формат /newsession
 ```
 /newsession
 Название: Название кампании
 Время: 25.05.2026 19:00
 Мест: 4
 Ссылка: https://discord.gg/invite-link
 Картинка: https://example.com/cover.jpg
 ```
 ### Повторяющиеся сессии
 Для регулярных кампаний используйте:
 - `Игр: 6` — количество сессий
 - `Интервал: 7` — шаг в днях между сессиями
 Бот автоматически сгенерирует расписание на 6 недель с недельным интервалом.
 ---
 ## Управление сессиями
 ### Статусы сессии
 - `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
 ```
 ### Требования
 - Дедлайн должен быть в будущем
 - Дедлайн раньше первого предложенного времени
 - Минимум 2, максимум 3 варианта
 ### Результаты
 - Бот создаёт голосование с inline-кнопками
 - Игроки голосуют, могут менять выбор до дедлайна
 - По дедлайну бот выбирает вариант с большинством голосов
 - При ничьей или отсутствии голосов — перенос отклоняется
 ---
 ## Экспорт в календарь
 ### Формат .ics
 Команда `/exportcalendar` генерирует файл для импорта в:
 - Google Calendar
 - Apple Calendar (iCal)
 - Яндекс Календарь
 - Outlook
 ### Что попадает в файл
 - Все запланированные и подтвержденные сессии
 - Название, время, ссылка на игру
 - Описание с составом игроков
 ---
 ## Bulk-операции
 ### Доступные операции
 На странице группы доступны:
 1. **Обновить title/link** — массовое изменение названия и ссылки у всех сессий batch
 2. **Перенести batch** — сдвинуть все сессии на фиксированный срок
 3. **Клонировать** — создать копию batch на новую неделю/месяц
 4. **Изменить режим уведомлений** — переключить между «В группе и в личку» / «Только в группе»
 ### Безопасность
 Все bulk-операции требуют подтверждения (модальное окно). После выполнения Telegram-сообщение batch автоматически обновляется.
 ---
 ## Telegram Mini App
 ### Запуск
 1. Нажмите кнопку меню бота (или `/start` → «Открыть dashboard»)
 2. Dashboard откроется внутри Telegram, без дополнительной авторизации
 3. Интерфейс адаптирован под мобильные телефоны с учётом safe-area
 ### Функционал
 Mini App поддерживает весь функционал Web Dashboard:
 - Просмотр и редактирование сессий
 - Управление очередью и составом
 - Запуск шаблонов и bulk-операций
 - Просмотр статистики посещаемости
 - Голосования за перенос
 ### Fallback-вход
 Если автоматическая авторизация не сработала:
 1. Нажмите кнопку «Войти через Telegram»
 2. Подтвердите вход в стандартном диалоге Telegram
 3. Dashboard откроется в том же WebView
 ---
 *Документация актуальна для версии v1.10.1. Обновлено: 7 мая 2026.*