From 1160ecbedcef088943de059671f8f39a2deaea35 Mon Sep 17 00:00:00 2001
From: Toutsu <hegin4@yandex.ru>
Date: Fri, 24 Apr 2026 10:57:47 +0300
Subject: [PATCH] Create wiki page 'GM Guide'

---
 GM-Guide.md | 101 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 101 insertions(+)
 create mode 100644 GM-Guide.md

diff --git a/GM-Guide.md b/GM-Guide.md
new file mode 100644
index 0000000..95fce18
--- /dev/null
+++ b/GM-Guide.md
@@ -0,0 +1,101 @@
+# GM Guide
+
+Руководство описывает текущие пользовательские сценарии бота и web-панели.
+
+## Кто считается ГМом
+
+ГМ группы определяется полем `game_groups.gm_telegram_id`. При первом создании сессии в группе бот сохраняет Telegram ID автора как ГМа. Последующие операции управления проверяют этот ID.
+
+Это значит, что роль ГМа внутри GM-Relay не обязательно равна роли администратора Telegram-группы.
+
+## Создание расписания
+
+Команда:
+
+```text
+/newsession
+Название: Легенды Берега Мечей
+Время: 15.05.2026 19:30
+Время: 22.05.2026 19:00
+Ссылка: https://example.com/join
+```
+
+Поддерживаемые строки:
+
+- `Название:` — общий заголовок пачки игр.
+- `Время:` — дата и время в МСК. Можно указать несколько строк.
+- `Ссылка:` — ссылка для подключения к игре.
+
+Поддерживаемые форматы времени:
+
+- `dd.MM.yyyy HH:mm`
+- `dd.MM.yyyy H:mm`
+- `d.MM.yyyy HH:mm`
+
+Время в прошлом пропускается с предупреждением. Некорректные строки `Время:` тоже пропускаются с предупреждением.
+
+После успешного создания бот публикует общее сообщение расписания с кнопками записи. Если группа является Telegram forum, бот создаёт отдельную тему `Игры: <Название>` и публикует расписание там.
+
+## Запись игроков
+
+Игроки записываются через inline-кнопки вида `На <дата>` в сообщении расписания. При записи бот:
+
+- создаёт или обновляет запись игрока в `players`;
+- добавляет участника в `session_participants` со статусом `Pending`;
+- перерисовывает общее сообщение расписания.
+
+Повторная запись на ту же сессию отклоняется сообщением `Вы уже записаны!`.
+
+## Отмена и удаление
+
+Есть два разных действия:
+
+- `Отменить <дата> (ГМ)` в сообщении расписания меняет статус сессии на `Cancelled` и оставляет её в истории пачки.
+- `/listsessions` показывает будущие сессии; если команду вызывает ГМ, бот добавляет кнопки удаления. Удаление физически удаляет сессию из БД.
+
+Если удалена последняя сессия пачки и для неё была создана forum-тема, бот пытается удалить эту тему.
+
+## Перенос сессии
+
+Перенос запускается кнопкой `⏰ (ГМ)` в сообщении расписания.
+
+Текущий поток:
+
+1. Бот проверяет, что кнопку нажал ГМ.
+2. Создаётся `reschedule_proposals` со статусом `AwaitingTime`.
+3. ГМ пишет новое время обычным сообщением в чат.
+4. Если участников нет, бот переносит сессию сразу.
+5. Если участники есть, бот создаёт голосование.
+6. Любой голос `Против` отклоняет перенос.
+7. Если все участники согласились, бот переносит сессию, сбрасывает RSVP участников в `Pending`, очищает `confirmation_message_id` и `link_message_id`.
+
+## Подтверждение участия
+
+Планировщик проверяет БД раз в минуту. За 24 часа до сессии со статусом `Planned` бот отправляет RSVP-сообщение участникам.
+
+Участники выбирают:
+
+- `Буду` — статус игрока становится `Confirmed`.
+- `Не смогу` — статус игрока становится `Declined`, ГМ получает личное уведомление.
+
+Когда все участники подтвердили участие, сессия переходит в `Confirmed`, группа и ГМ получают уведомления.
+
+## Ссылка на игру
+
+За 5 минут до сессии со статусом `Confirmed` бот отправляет ссылку на подключение и список подтверждённых участников. Повторная отправка защищена полем `link_message_id`.
+
+## Экспорт календаря
+
+Команда `/exportcalendar` отправляет файл `schedule.ics` с будущими сессиями текущей группы, которые находятся в статусе `Planned`. Длительность события в календаре сейчас фиксирована как 4 часа.
+
+## Web-панель
+
+Web UI доступен после входа через Telegram Login Widget.
+
+ГМ может:
+
+- видеть свои Telegram-группы;
+- открыть список предстоящих сессий группы;
+- изменить название, время и ссылку сессии.
+
+При сохранении изменений web-панель обновляет запись в БД, отправляет уведомление в Telegram-группу и пытается перерисовать исходное сообщение расписания пачки.
\ No newline at end of file