docs: update wiki for 1.5.0 personal notifications

2026-04-27 10:11:26 +03:00
parent e0f976d40e
commit 449640e3c5
7 changed files with 30 additions and 14 deletions
@@ -45,8 +45,10 @@ GM-Relay состоит из нескольких .NET-проектов и об

 1. Ищет сессии `Planned`, у которых `scheduled_at - 24h <= now()`.
 2. Вызывает `SendConfirmationHandler` и переводит сессию в `ConfirmationSent`.
-3. Ищет сессии `Confirmed`, у которых `scheduled_at - 5min <= now()` и `link_message_id IS NULL`.
-4. Вызывает `SendJoinLinkHandler`.
+3. Ищет сессии `Confirmed` или `ConfirmationSent`, у которых `scheduled_at - 1h <= now()` и `one_hour_reminder_processed_at IS NULL`.
+4. Вызывает `SendOneHourReminderHandler`, который учитывает `sessions.notification_mode`.
+5. Ищет сессии `Confirmed`, у которых `scheduled_at - 5min <= now()` и `link_message_id IS NULL`.
+6. Вызывает `SendJoinLinkHandler`.

 Состояние хранится в PostgreSQL, поэтому после рестарта сервис продолжает работу без in-memory очередей.

@@ -58,6 +60,7 @@ Blazor Server-приложение использует cookie auth и Telegram

 - `TelegramAuthService` валидирует HMAC-SHA256 подпись Telegram Login Widget и `auth_date`.
 - `SessionService` читает и обновляет группы/сессии через Dapper, включая bulk-операции по `batch_id`.
+- `SessionService` сохраняет режим уведомлений batch и дублирует Web-уведомления в ЛС, если включён `GroupAndDirect`.
 - `BatchSchedulePlanner` задаёт детерминированные правила fixed-interval переноса и clone-смещения batch.
 - `AuthorizedSessionService` проверяет, что текущий Telegram ID является ГМом группы.

@@ -74,6 +77,7 @@ Blazor Server-приложение использует cookie auth и Telegram

 - `SessionStatus`: `Planned`, `ConfirmationSent`, `Confirmed`, `Cancelled`.
 - `RsvpStatus`: `Pending`, `Confirmed`, `Declined`.
+- `SessionNotificationMode`: `GroupAndDirect`, `GroupOnly`.
 - `MoscowTime`: парсинг и форматирование МСК (`UTC+3`).
 - `SessionBatchRenderer`: единый renderer для Telegram-сообщения пачки сессий.

@@ -1,6 +1,6 @@
 # База данных

-GM-Relay **v1.4.1** использует PostgreSQL. Изменения схемы управляются DbUp-миграциями, встроенными в `GmRelay.Bot` как embedded resources.
+GM-Relay **v1.5.0** использует PostgreSQL. Изменения схемы управляются DbUp-миграциями, встроенными в `GmRelay.Bot` как embedded resources.

 ## Миграции

@@ -12,6 +12,7 @@ GM-Relay **v1.4.1** использует PostgreSQL. Изменения схем
 - `V004__add_reschedule_proposals.sql` — таблицы предложений переноса и голосов.
 - `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` и индекс для одночасовых напоминаний.

 ## Основные таблицы

@@ -56,10 +57,13 @@ Telegram-группы, где организуются игры.
 - `link_message_id` — ID Telegram-сообщения со ссылкой перед игрой.
 - `thread_id` — ID Telegram forum topic, если тема была создана.
 - `batch_message_id` — ID исходного Telegram-сообщения с расписанием пачки.
+- `notification_mode` — `GroupAndDirect` для групповых сообщений с DM-дублированием или `GroupOnly` только для группы.
+- `one_hour_reminder_processed_at` — когда бот обработал персональное напоминание примерно за 1 час до игры.

 Bulk-операции Web не требуют новых таблиц: общий title/link обновляется по `batch_id`, перенос пересчитывает `scheduled_at` существующих строк, а clone создаёт новый `batch_id` и новые строки `sessions` без копирования `session_participants`.

 Для активных статусов есть partial index `ix_sessions_pending` по `scheduled_at`.
+Для T-1h напоминаний есть partial index `ix_sessions_one_hour_reminders` по `scheduled_at`.

 ### session_participants

@@ -1,6 +1,6 @@
 # Быстрый старт

-Эта страница описывает минимальный запуск текущей версии GM-Relay **v1.4.1**.
+Эта страница описывает минимальный запуск текущей версии GM-Relay **v1.5.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.4.1`.
- `web`: образ `git.codeanddice.ru/toutsu/gmrelay-web:1.4.1`.
+- `bot`: образ `git.codeanddice.ru/toutsu/gmrelay-bot:1.5.0`.
+- `web`: образ `git.codeanddice.ru/toutsu/gmrelay-web:1.5.0`.

 Web UI будет доступен на `http://localhost:8080`, если `GMRELAY_WEB_PORT` не переопределён.

@@ -1,6 +1,6 @@
 # Развёртывание

-Текущий production-like способ запуска GM-Relay **v1.4.1** — Docker Compose из `compose.yaml`.
+Текущий production-like способ запуска GM-Relay **v1.5.0** — Docker Compose из `compose.yaml`.

 ## Сервисы Docker Compose

@@ -15,13 +15,13 @@

 `bot`:

- образ: `git.codeanddice.ru/toutsu/gmrelay-bot:1.4.1`;
+- образ: `git.codeanddice.ru/toutsu/gmrelay-bot:1.5.0`;
 - запускается после успешного healthcheck сервиса `db`;
 - переменные окружения: `ConnectionStrings__gmrelaydb`, `Telegram__BotToken`.

 `web`:

- образ: `git.codeanddice.ru/toutsu/gmrelay-web:1.4.1`;
+- образ: `git.codeanddice.ru/toutsu/gmrelay-web:1.5.0`;
 - запускается после успешного healthcheck сервиса `db`;
 - переменные окружения: `ConnectionStrings__gmrelaydb`, `Telegram__BotToken`, `Telegram__BotUsername`;
 - порт: `${GMRELAY_WEB_PORT:-8080}:8080`;
@@ -92,7 +92,7 @@ docker compose down -v

 ## Поведение миграций

-Бот применяет DbUp-миграции при старте до обработки Telegram updates. В версии `1.4.1` новых миграций нет: релиз содержит CSS-fix читаемости native select dropdown в Web Dashboard и использует существующую схему БД. После обновления стоит проверить логи `bot`, чтобы убедиться, что миграции применились без ошибок.
+Бот применяет DbUp-миграции при старте до обработки Telegram updates. В версии `1.5.0` добавлена миграция `V007__add_session_notification_mode.sql` для режима уведомлений batch и отметки T-1h reminder. После обновления стоит проверить логи `bot`, чтобы убедиться, что миграции применились без ошибок.

 ## Безопасность

@@ -26,7 +26,7 @@ dotnet run --project src/GmRelay.AppHost

 `Directory.Build.props` задаёт:

- `Version`: `1.4.1`.
+- `Version`: `1.5.0`.
 - `TargetFramework`: `net10.0`.
 - `LangVersion`: `preview`.
 - `Nullable`: `enable`.
@@ -1,6 +1,6 @@
 # Руководство ГМа

-Руководство описывает пользовательские сценарии бота и Web-панели для GM-Relay **v1.4.1**.
+Руководство описывает пользовательские сценарии бота и Web-панели для GM-Relay **v1.5.0**.

 ## Кто считается ГМом

@@ -65,11 +65,14 @@ GM может поднять первого игрока из очереди:
 На странице группы Web-панель показывает отдельный блок для каждой видимой пачки игр. GM может:

 - обновить общий `title` и `link` сразу у всех сессий batch;
+- выбрать режим уведомлений для игроков: `В группе и в личку` или `Только в группе`;
 - перенести всю пачку, задав новую первую дату и фиксированный шаг между играми в днях;
 - клонировать batch на следующую неделю или следующий календарный месяц.

 Редактирование title/link и перенос перерисовывают исходное Telegram-сообщение расписания. Клонирование создаёт новую пачку с новым `batch_id`, новым Telegram-сообщением и пустым составом игроков.

+Режим `В группе и в личку` оставляет все групповые сообщения и дополнительно отправляет активным игрокам персональные уведомления в ЛС. Режим `Только в группе` отключает личные сообщения для batch, но не меняет публикацию в групповом чате.
+
 ## Отмена и удаление

 - `Отменить <дата> (ГМ)` в сообщении расписания меняет статус сессии на `Cancelled` и оставляет её в истории пачки.
@@ -101,6 +104,8 @@ GM может поднять первого игрока из очереди:

 За 5 минут до подтверждённой сессии бот отправляет ссылку на подключение и список подтверждённых активных участников.

+Если для batch включены личные уведомления, игроки дополнительно получают DM о RSVP за 24 часа, напоминание примерно за 1 час до старта, ссылку перед игрой, отмену и результат переноса. Если бот не может написать игроку в ЛС, отправка остальным участникам продолжается.
+
 ## Web-панель

 Web UI доступен после входа через Telegram Login Widget. GM может:
@@ -111,5 +116,6 @@ Web UI доступен после входа через Telegram Login Widget.
 - редактировать название, время, ссылку и лимит мест;
 - поднять первого игрока из листа ожидания, если есть свободное место;
 - выполнять bulk-операции над batch: общий title/link, перенос пачки и клонирование на неделю или месяц.
+- выбирать режим уведомлений batch: групповые сообщения с личными DM или только групповые сообщения.

 При сохранении отдельной сессии Web-панель обновляет запись в БД, отправляет уведомление в Telegram-группу и пытается перерисовать исходное сообщение расписания пачки. Bulk-операции обновляют исходное batch-сообщение, а clone публикует новое сообщение для новой пачки.
@@ -1,10 +1,10 @@
 # Главная

-GM-Relay — Telegram-бот и Blazor-панель для организации TTRPG-сессий. Текущее состояние документации соответствует репозиторию `Toutsu/GmRelayBot` и релизу **v1.4.1**.
+GM-Relay — Telegram-бот и Blazor-панель для организации TTRPG-сессий. Текущее состояние документации соответствует репозиторию `Toutsu/GmRelayBot` и релизу **v1.5.0**.

 ## Текущий стек

- Версия проекта: `1.4.1`.
+- Версия проекта: `1.5.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.
@@ -26,10 +26,12 @@ GM-Relay — Telegram-бот и Blazor-панель для организаци
 - Управление сессиями через `/listsessions` с отображением мест и очереди ожидания.
 - Перенос сессии через кнопку GM и голосование активных участников.
 - RSVP-подтверждение за 24 часа до игры только для основного состава.
+- Персональные DM-уведомления игрокам о RSVP за 24 часа, напоминание за 1 час, ссылке перед стартом, отмене и переносе.
 - Отправка ссылки на подключение за 5 минут до подтверждённой игры.
 - Экспорт будущих запланированных сессий в `.ics` через `/exportcalendar`.
 - Web-панель для GM: список групп, список сессий, редактирование названия, времени, ссылки и лимита мест.
 - Bulk-операции в Web Dashboard: общий `title/link` для batch, перенос всей пачки на фиксированный шаг и клонирование на следующую неделю или месяц с новым Telegram-сообщением.
+- Настройка режима уведомлений для batch: `В группе и в личку` или `Только в группе`, при этом групповые сообщения сохраняются всегда.
 - CSS-fix Web Dashboard: раскрывающиеся списки используют контрастный фон и текст в native select dropdown.

 ## Разделы