From e668e4756b6007d7076e67a7cd5a1ecf92f3b787 Mon Sep 17 00:00:00 2001 From: Toutsu Date: Mon, 27 Apr 2026 14:25:42 +0300 Subject: [PATCH] docs: update wiki for 1.6.0 co-gm delegation --- ...%82%D0%B5%D0%BA%D1%82%D1%83%D1%80%D0%B0.md | 8 ++++-- ...B0-%D0%B4%D0%B0%D0%BD%D0%BD%D1%8B%D1%85.md | 23 +++++++++++++-- ...8B%D0%B9-%D1%81%D1%82%D0%B0%D1%80%D1%82.md | 10 +++---- ...%82%D1%8B%D0%B2%D0%B0%D0%BD%D0%B8%D0%B5.md | 10 +++---- ...%80%D0%B0%D0%B1%D0%BE%D1%82%D0%BA%D0%B0.md | 2 +- ...81%D1%82%D0%B2%D0%BE-%D0%93%D0%9C%D0%B0.md | 28 +++++++++++++------ Home.md | 13 +++++---- 7 files changed, 62 insertions(+), 32 deletions(-) diff --git a/%D0%90%D1%80%D1%85%D0%B8%D1%82%D0%B5%D0%BA%D1%82%D1%83%D1%80%D0%B0.md b/%D0%90%D1%80%D1%85%D0%B8%D1%82%D0%B5%D0%BA%D1%82%D1%83%D1%80%D0%B0.md index 9ea881c..c45e1d7 100644 --- a/%D0%90%D1%80%D1%85%D0%B8%D1%82%D0%B5%D0%BA%D1%82%D1%83%D1%80%D0%B0.md +++ b/%D0%90%D1%80%D1%85%D0%B8%D1%82%D0%B5%D0%BA%D1%82%D1%83%D1%80%D0%B0.md @@ -61,14 +61,15 @@ Blazor Server-приложение использует cookie auth и Telegram - `TelegramAuthService` валидирует HMAC-SHA256 подпись Telegram Login Widget и `auth_date`. - `SessionService` читает и обновляет группы/сессии через Dapper, включая bulk-операции по `batch_id`. - `SessionService` сохраняет режим уведомлений batch и дублирует Web-уведомления в ЛС, если включён `GroupAndDirect`. +- `SessionService` читает `group_managers`, проверяет роли `Owner`/`CoGm` и сохраняет назначения co-GM. - `BatchSchedulePlanner` задаёт детерминированные правила fixed-interval переноса и clone-смещения batch. -- `AuthorizedSessionService` проверяет, что текущий Telegram ID является ГМом группы. +- `AuthorizedSessionService` проверяет, что текущий Telegram ID является owner или co-GM группы; owner-only операции делегирования проходят через отдельную проверку роли. Основные страницы: - `/login` — вход через Telegram. -- `/` — список групп ГМа. -- `/group/{GroupId}` — будущие сессии группы и batch bulk-операции. +- `/` — список групп, где пользователь owner или co-GM. +- `/group/{GroupId}` — управляющие группы, будущие сессии и batch bulk-операции. - `/session/edit/{SessionId}` — редактирование названия, времени и ссылки. ## Общий домен @@ -78,6 +79,7 @@ Blazor Server-приложение использует cookie auth и Telegram - `SessionStatus`: `Planned`, `ConfirmationSent`, `Confirmed`, `Cancelled`. - `RsvpStatus`: `Pending`, `Confirmed`, `Declined`. - `SessionNotificationMode`: `GroupAndDirect`, `GroupOnly`. +- `GroupManagerRole`: `Owner`, `CoGm`. - `MoscowTime`: парсинг и форматирование МСК (`UTC+3`). - `SessionBatchRenderer`: единый renderer для Telegram-сообщения пачки сессий. diff --git a/%D0%91%D0%B0%D0%B7%D0%B0-%D0%B4%D0%B0%D0%BD%D0%BD%D1%8B%D1%85.md b/%D0%91%D0%B0%D0%B7%D0%B0-%D0%B4%D0%B0%D0%BD%D0%BD%D1%8B%D1%85.md index f2e81e4..6b88439 100644 --- a/%D0%91%D0%B0%D0%B7%D0%B0-%D0%B4%D0%B0%D0%BD%D0%BD%D1%8B%D1%85.md +++ b/%D0%91%D0%B0%D0%B7%D0%B0-%D0%B4%D0%B0%D0%BD%D0%BD%D1%8B%D1%85.md @@ -1,6 +1,6 @@ # База данных -GM-Relay **v1.5.0** использует PostgreSQL. Изменения схемы управляются DbUp-миграциями, встроенными в `GmRelay.Bot` как embedded resources. +GM-Relay **v1.6.0** использует PostgreSQL. Изменения схемы управляются DbUp-миграциями, встроенными в `GmRelay.Bot` как embedded resources. ## Миграции @@ -13,6 +13,7 @@ GM-Relay **v1.5.0** использует PostgreSQL. Изменения схем - `V005__add_batch_message_id.sql` — поле `sessions.batch_message_id` для редактирования исходного сообщения расписания. - `V006__add_session_capacity_waitlist.sql` — лимит мест `sessions.max_players`, статус участника `session_participants.registration_status`, время постановки в очередь `session_participants.created_at` и индексы для waitlist. - `V007__add_session_notification_mode.sql` — режим уведомлений `sessions.notification_mode`, отметка обработки T-1h reminder `sessions.one_hour_reminder_processed_at` и индекс для одночасовых напоминаний. +- `V008__add_group_managers.sql` — таблица `group_managers` для ролей `Owner` и `CoGm`; миграция переносит текущих GM из `game_groups.gm_telegram_id` в owner-записи. ## Основные таблицы @@ -34,11 +35,27 @@ Telegram-группы, где организуются игры. - `telegram_chat_id` — уникальный Telegram chat ID. - `name` — актуальное название Telegram-чата. -- `gm_telegram_id` — Telegram ID GM для этой группы. +- `gm_telegram_id` — Telegram ID первого owner для совместимости с ранними версиями и миграциями; новая проверка доступа идёт через `group_managers`. + +### group_managers + +Таблица управляющих группой. Она поддерживает несколько пользователей с правами управления одной Telegram-группой. + +Важные поля: + +- `group_id` и `player_id` — уникальная пара группы и пользователя. +- `role` — `Owner` или `CoGm`. +- `added_by_player_id` — кто назначил co-GM; для owner-записей из миграции может быть `NULL`. +- `created_at` — время назначения роли. + +Индексы: + +- `ix_group_managers_group_role` ускоряет выбор управляющих группы и проверку owner. +- `ix_group_managers_player` ускоряет список групп, доступных пользователю в Web Dashboard. ### game_group_members -Таблица связи группы и игроков. Сейчас основная проверка роли GM идёт через `game_groups.gm_telegram_id`; таблица остаётся базовой схемой для группового membership. +Таблица связи группы и игроков. Она остаётся базовой схемой для группового membership; права управления вынесены в `group_managers`. ### sessions diff --git a/%D0%91%D1%8B%D1%81%D1%82%D1%80%D1%8B%D0%B9-%D1%81%D1%82%D0%B0%D1%80%D1%82.md b/%D0%91%D1%8B%D1%81%D1%82%D1%80%D1%8B%D0%B9-%D1%81%D1%82%D0%B0%D1%80%D1%82.md index da1d7f4..c926ee9 100644 --- a/%D0%91%D1%8B%D1%81%D1%82%D1%80%D1%8B%D0%B9-%D1%81%D1%82%D0%B0%D1%80%D1%82.md +++ b/%D0%91%D1%8B%D1%81%D1%82%D1%80%D1%8B%D0%B9-%D1%81%D1%82%D0%B0%D1%80%D1%82.md @@ -1,6 +1,6 @@ # Быстрый старт -Эта страница описывает минимальный запуск текущей версии GM-Relay **v1.5.0**. +Эта страница описывает минимальный запуск текущей версии GM-Relay **v1.6.0**. ## Требования @@ -41,8 +41,8 @@ docker compose up -d Compose поднимает: - `db`: PostgreSQL 17 Alpine, БД `gmrelay_db`, пользователь `gmrelay`. -- `bot`: образ `git.codeanddice.ru/toutsu/gmrelay-bot:1.5.0`. -- `web`: образ `git.codeanddice.ru/toutsu/gmrelay-web:1.5.0`. +- `bot`: образ `git.codeanddice.ru/toutsu/gmrelay-bot:1.6.0`. +- `web`: образ `git.codeanddice.ru/toutsu/gmrelay-web:1.6.0`. Web UI будет доступен на `http://localhost:8080`, если `GMRELAY_WEB_PORT` не переопределён. @@ -73,5 +73,5 @@ dotnet run --project src/GmRelay.AppHost - `/help` должен показать формат `/newsession`, включая необязательную строку `Мест:`. - В сообщении расписания у активной сессии должны быть кнопки записи и `Выйти`. - Web-панель должна перенаправлять неавторизованного пользователя на `/login`. -- После входа через Telegram GM видит только группы, где он записан как `gm_telegram_id`. -- На странице группы GM видит блоки batch-операций: общий title/link, перенос всей пачки и клонирование batch. +- После входа через Telegram пользователь видит группы, где он назначен owner или co-GM. +- На странице группы owner видит блок управления co-GM, а owner/co-GM видят batch-операции: общий title/link, режим уведомлений, перенос всей пачки и клонирование batch. diff --git a/%D0%A0%D0%B0%D0%B7%D0%B2%D1%91%D1%80%D1%82%D1%8B%D0%B2%D0%B0%D0%BD%D0%B8%D0%B5.md b/%D0%A0%D0%B0%D0%B7%D0%B2%D1%91%D1%80%D1%82%D1%8B%D0%B2%D0%B0%D0%BD%D0%B8%D0%B5.md index d782c13..5313c90 100644 --- a/%D0%A0%D0%B0%D0%B7%D0%B2%D1%91%D1%80%D1%82%D1%8B%D0%B2%D0%B0%D0%BD%D0%B8%D0%B5.md +++ b/%D0%A0%D0%B0%D0%B7%D0%B2%D1%91%D1%80%D1%82%D1%8B%D0%B2%D0%B0%D0%BD%D0%B8%D0%B5.md @@ -1,6 +1,6 @@ # Развёртывание -Текущий production-like способ запуска GM-Relay **v1.5.0** — Docker Compose из `compose.yaml`. +Текущий production-like способ запуска GM-Relay **v1.6.0** — Docker Compose из `compose.yaml`. ## Сервисы Docker Compose @@ -15,13 +15,13 @@ `bot`: -- образ: `git.codeanddice.ru/toutsu/gmrelay-bot:1.5.0`; +- образ: `git.codeanddice.ru/toutsu/gmrelay-bot:1.6.0`; - запускается после успешного healthcheck сервиса `db`; - переменные окружения: `ConnectionStrings__gmrelaydb`, `Telegram__BotToken`. `web`: -- образ: `git.codeanddice.ru/toutsu/gmrelay-web:1.5.0`; +- образ: `git.codeanddice.ru/toutsu/gmrelay-web:1.6.0`; - запускается после успешного healthcheck сервиса `db`; - переменные окружения: `ConnectionStrings__gmrelaydb`, `Telegram__BotToken`, `Telegram__BotUsername`; - порт: `${GMRELAY_WEB_PORT:-8080}:8080`; @@ -92,14 +92,14 @@ docker compose down -v ## Поведение миграций -Бот применяет DbUp-миграции при старте до обработки Telegram updates. В версии `1.5.0` добавлена миграция `V007__add_session_notification_mode.sql` для режима уведомлений batch и отметки T-1h reminder. После обновления стоит проверить логи `bot`, чтобы убедиться, что миграции применились без ошибок. +Бот применяет DbUp-миграции при старте до обработки Telegram updates. В версии `1.6.0` добавлена миграция `V008__add_group_managers.sql`: она создаёт `group_managers` и переносит текущих GM в роль `Owner`. После обновления стоит проверить логи `bot`, чтобы убедиться, что миграции применились без ошибок. ## Безопасность - При старте бот логирует PostgreSQL connection string через `SecretRedactor`, чтобы не раскрывать пароль. - Web-cookie настроены как `HttpOnly`, `SecurePolicy.Always`, `SameSite.Strict`, со sliding expiration на 7 дней. - Web-ответы добавляют заголовки `X-Content-Type-Options`, `X-Frame-Options`, `Referrer-Policy` и `Permissions-Policy`. -- Доступ к данным групп и сессий проверяется сравнением Telegram ID пользователя с `game_groups.gm_telegram_id`. +- Доступ к данным групп и сессий проверяется через `group_managers`: owner и co-GM могут управлять расписанием, а назначать co-GM может только owner. ## Чеклист обновления diff --git a/%D0%A0%D0%B0%D0%B7%D1%80%D0%B0%D0%B1%D0%BE%D1%82%D0%BA%D0%B0.md b/%D0%A0%D0%B0%D0%B7%D1%80%D0%B0%D0%B1%D0%BE%D1%82%D0%BA%D0%B0.md index 19abce3..6f44086 100644 --- a/%D0%A0%D0%B0%D0%B7%D1%80%D0%B0%D0%B1%D0%BE%D1%82%D0%BA%D0%B0.md +++ b/%D0%A0%D0%B0%D0%B7%D1%80%D0%B0%D0%B1%D0%BE%D1%82%D0%BA%D0%B0.md @@ -26,7 +26,7 @@ dotnet run --project src/GmRelay.AppHost `Directory.Build.props` задаёт: -- `Version`: `1.5.0`. +- `Version`: `1.6.0`. - `TargetFramework`: `net10.0`. - `LangVersion`: `preview`. - `Nullable`: `enable`. 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 ad5bdc4..f314f95 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,10 +1,18 @@ # Руководство ГМа -Руководство описывает пользовательские сценарии бота и Web-панели для GM-Relay **v1.5.0**. +Руководство описывает пользовательские сценарии бота и Web-панели для GM-Relay **v1.6.0**. -## Кто считается ГМом +## Кто управляет группой -GM группы определяется полем `game_groups.gm_telegram_id`. При первом создании сессии в группе бот сохраняет Telegram ID автора как GM. Последующие операции управления проверяют этот ID. +При первом создании сессии в группе бот сохраняет автора как owner группы. Owner хранится в таблице `group_managers` с ролью `Owner`; историческое поле `game_groups.gm_telegram_id` остаётся для совместимости и миграций. + +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 больше не должен помогать с группой, owner удаляет его из того же блока. Снятие роли не удаляет игрока из таблицы `players` и не меняет его записи на игры. ## Создание расписания @@ -53,7 +61,7 @@ GM группы определяется полем `game_groups.gm_telegram_id` ## Повышение из листа ожидания -GM может поднять первого игрока из очереди: +Owner или co-GM может поднять первого игрока из очереди: - в Telegram — кнопкой `Из ожидания (ГМ)` в сообщении расписания; - в Web Dashboard — кнопкой `Из ожидания` в списке сессий. @@ -62,7 +70,7 @@ GM может поднять первого игрока из очереди: ## Bulk-операции для batch в Web -На странице группы Web-панель показывает отдельный блок для каждой видимой пачки игр. GM может: +На странице группы Web-панель показывает отдельный блок для каждой видимой пачки игр. Owner и co-GM могут: - обновить общий `title` и `link` сразу у всех сессий batch; - выбрать режим уведомлений для игроков: `В группе и в личку` или `Только в группе`; @@ -76,7 +84,7 @@ GM может поднять первого игрока из очереди: ## Отмена и удаление - `Отменить <дата> (ГМ)` в сообщении расписания меняет статус сессии на `Cancelled` и оставляет её в истории пачки. -- `/listsessions` показывает будущие сессии; если команду вызывает GM, бот добавляет кнопки удаления. +- `/listsessions` показывает будущие сессии; если команду вызывает owner или co-GM, бот добавляет кнопки удаления. - Удаление физически удаляет сессию из БД. Если после удаления пачка пустая и была создана forum-тема, бот пытается удалить тему. ## Перенос сессии @@ -85,9 +93,9 @@ GM может поднять первого игрока из очереди: Поток: -1. Бот проверяет, что кнопку нажал GM. +1. Бот проверяет, что кнопку нажал owner или co-GM. 2. Создаётся `reschedule_proposals` со статусом `AwaitingTime`. -3. GM пишет новое время обычным сообщением в чат. +3. Инициатор переноса пишет новое время обычным сообщением в чат. 4. Если активных участников нет, бот переносит сессию сразу. 5. Если активные участники есть, бот создаёт голосование. 6. Любой голос `Против` отклоняет перенос. @@ -108,7 +116,7 @@ GM может поднять первого игрока из очереди: ## Web-панель -Web UI доступен после входа через Telegram Login Widget. GM может: +Web UI доступен после входа через Telegram Login Widget. Owner и co-GM могут: - видеть свои Telegram-группы; - открыть список предстоящих сессий группы; @@ -118,4 +126,6 @@ Web UI доступен после входа через Telegram Login Widget. - выполнять bulk-операции над batch: общий title/link, перенос пачки и клонирование на неделю или месяц. - выбирать режим уведомлений batch: групповые сообщения с личными DM или только групповые сообщения. +Дополнительно owner может управлять списком co-GM на странице группы. + При сохранении отдельной сессии Web-панель обновляет запись в БД, отправляет уведомление в Telegram-группу и пытается перерисовать исходное сообщение расписания пачки. Bulk-операции обновляют исходное batch-сообщение, а clone публикует новое сообщение для новой пачки. diff --git a/Home.md b/Home.md index 956521e..c762de1 100644 --- a/Home.md +++ b/Home.md @@ -1,10 +1,10 @@ # Главная -GM-Relay — Telegram-бот и Blazor-панель для организации TTRPG-сессий. Текущее состояние документации соответствует репозиторию `Toutsu/GmRelayBot` и релизу **v1.5.0**. +GM-Relay — Telegram-бот и Blazor-панель для организации TTRPG-сессий. Текущее состояние документации соответствует репозиторию `Toutsu/GmRelayBot` и релизу **v1.6.0**. ## Текущий стек -- Версия проекта: `1.5.0`. +- Версия проекта: `1.6.0`. - Платформа: `.NET 10`, C# preview, nullable reference types, warnings as errors. - Оркестрация разработки: `.NET Aspire 13` через `src/GmRelay.AppHost`. - Runtime бота: `Worker Service`, Telegram long polling, Native AOT. @@ -20,16 +20,17 @@ GM-Relay — Telegram-бот и Blazor-панель для организаци - Интерактивная запись игроков на конкретные даты и самостоятельный выход через inline-кнопки Telegram. - Лист ожидания: если основной состав заполнен, новые игроки не переполняют сессию, а попадают в очередь. - Автоматическое освобождение места: когда активный игрок снимает запись, первый ожидающий переводится в основной состав. -- Повышение первого игрока из листа ожидания кнопкой GM в Telegram или Web Dashboard. +- Делегирование управления группой: owner может назначать co-GM, а co-GM управляет расписанием в Telegram и Web Dashboard. +- Повышение первого игрока из листа ожидания кнопкой owner/co-GM в Telegram или Web Dashboard. - Автоматическое создание Telegram forum topic для пачки игр, если группа является форумом. -- Отмена отдельной сессии GM из основного сообщения расписания. +- Отмена отдельной сессии owner/co-GM из основного сообщения расписания. - Управление сессиями через `/listsessions` с отображением мест и очереди ожидания. -- Перенос сессии через кнопку GM и голосование активных участников. +- Перенос сессии через кнопку owner/co-GM и голосование активных участников. - RSVP-подтверждение за 24 часа до игры только для основного состава. - Персональные DM-уведомления игрокам о RSVP за 24 часа, напоминание за 1 час, ссылке перед стартом, отмене и переносе. - Отправка ссылки на подключение за 5 минут до подтверждённой игры. - Экспорт будущих запланированных сессий в `.ics` через `/exportcalendar`. -- Web-панель для GM: список групп, список сессий, редактирование названия, времени, ссылки и лимита мест. +- Web-панель для owner/co-GM: список групп, список сессий, редактирование названия, времени, ссылки и лимита мест. - Bulk-операции в Web Dashboard: общий `title/link` для batch, перенос всей пачки на фиксированный шаг и клонирование на следующую неделю или месяц с новым Telegram-сообщением. - Настройка режима уведомлений для batch: `В группе и в личку` или `Только в группе`, при этом групповые сообщения сохраняются всегда. - CSS-fix Web Dashboard: раскрывающиеся списки используют контрастный фон и текст в native select dropdown.