docs: update wiki for 1.8.0 campaign templates

2026-04-28 10:01:57 +03:00
parent 5e33e3bbae
commit 360e5251d3
7 changed files with 57 additions and 22 deletions
@@ -61,17 +61,17 @@ Blazor Server-приложение использует cookie auth и Telegram
 Основные сервисы:

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

 Основные страницы:

 - `/login` — вход через Telegram.
 - `/` — список групп, где пользователь owner или co-GM.
- `/group/{GroupId}` — управляющие группы, будущие сессии и batch bulk-операции.
+- `/group/{GroupId}` — управляющие группы, шаблоны кампаний, будущие сессии и batch bulk-операции.
 - `/session/edit/{SessionId}` — редактирование названия, времени и ссылки.

 ## Общий домен
@@ -1,6 +1,6 @@
 # База данных

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

 ## Миграции

@@ -15,6 +15,7 @@ GM-Relay **v1.7.0** использует PostgreSQL. Изменения схем
 - `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-записи.
 - `V009__add_multi_option_reschedule_votes.sql` — дедлайн и выбранный вариант в `reschedule_proposals`, таблицы `reschedule_options` и `reschedule_option_votes` для голосования по нескольким слотам.
+- `V010__add_campaign_templates.sql` — таблица `campaign_templates` для сохранённых шаблонов кампаний и быстрого создания повторяющихся batch-расписаний из Web.

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

@@ -83,6 +84,22 @@ Bulk-операции Web не требуют новых таблиц: общи
 Для активных статусов есть partial index `ix_sessions_pending` по `scheduled_at`.
 Для T-1h напоминаний есть partial index `ix_sessions_one_hour_reminders` по `scheduled_at`.

+### campaign_templates
+
+Сохранённые шаблоны кампаний для Web Dashboard. Шаблон принадлежит группе и описывает параметры будущей пачки игр, но не создаёт `sessions`, пока GM не выберет первую дату.
+
+Важные поля:
+
+- `group_id` — группа, которой доступен шаблон.
+- `name` — человекочитаемое название шаблона; уникально внутри группы.
+- `title` и `join_link` — общие значения для создаваемого batch.
+- `session_count` — количество игр в повторяющемся расписании, от 1 до 52.
+- `interval_days` — фиксированный шаг между играми, от 1 до 365 дней.
+- `max_players` — необязательный лимит мест для каждой создаваемой сессии.
+- `notification_mode` — режим уведомлений, который будет записан в новые `sessions`.
+
+При создании batch из шаблона Web генерирует новый `batch_id`, создаёт строки `sessions` со статусом `Planned`, публикует новое Telegram-сообщение расписания и сохраняет его `batch_message_id`.
+
 ### session_participants

 Участники сессий, их RSVP-состояние и положение в основном составе или очереди.
@@ -1,6 +1,6 @@
 # Быстрый старт

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

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

@@ -70,9 +70,9 @@ dotnet run --project src/GmRelay.AppHost
 ## Проверка после запуска

 - `/start` должен ответить `GM-Relay Bot ready. Use /help for commands.`
- `/help` должен показать формат `/newsession`, включая необязательную строку `Мест:`.
+- `/help` должен показать формат `/newsession`, включая необязательную строку `Мест:` и быстрый повтор через `Игр:`/`Интервал:`.
 - В сообщении расписания у активной сессии должны быть кнопки записи и `Выйти`.
 - Owner/co-GM может нажать `⏰ Перенести`, отправить 2-3 варианта времени и дедлайн; бот создаст голосование и применит победивший вариант по дедлайну.
 - Web-панель должна перенаправлять неавторизованного пользователя на `/login`.
 - После входа через Telegram пользователь видит группы, где он назначен owner или co-GM.
- На странице группы owner видит блок управления co-GM, а owner/co-GM видят batch-операции: общий title/link, режим уведомлений, перенос всей пачки и клонирование batch.
+- На странице группы owner видит блок управления co-GM, а owner/co-GM видят шаблоны кампаний и batch-операции: общий title/link, режим уведомлений, перенос всей пачки и клонирование batch.
@@ -1,6 +1,6 @@
 # Развёртывание

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

 ## Сервисы Docker Compose

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

 `bot`:

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

 `web`:

- образ: `git.codeanddice.ru/toutsu/gmrelay-web:1.7.0`;
+- образ: `git.codeanddice.ru/toutsu/gmrelay-web:1.8.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.7.0` добавлена миграция `V009__add_multi_option_reschedule_votes.sql`: она создаёт таблицы вариантов и голосов для переноса сессии, а также дедлайн и выбранный вариант в `reschedule_proposals`. После обновления стоит проверить логи `bot`, чтобы убедиться, что миграции применились без ошибок.
+Бот применяет DbUp-миграции при старте до обработки Telegram updates. В версии `1.8.0` добавлена миграция `V010__add_campaign_templates.sql`: она создаёт таблицу `campaign_templates` для Web-шаблонов кампаний и быстрого создания повторяющихся batch-расписаний. После обновления стоит проверить логи `bot`, чтобы убедиться, что миграции применились без ошибок.

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

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

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

- `Version`: `1.7.0`.
+- `Version`: `1.8.0`.
 - `TargetFramework`: `net10.0`.
 - `LangVersion`: `preview`.
 - `Nullable`: `enable`.
@@ -70,14 +70,14 @@ V006__add_example_column.sql
 Текущий набор тестов покрывает:

 - domain/status helpers;
- parser `/newsession`;
+- parser `/newsession`, включая быстрые повторы расписания;
 - RSVP flow rules;
 - reschedule voting input, multi-option vote rendering и deadline winner rules;
 - rendering batch-сообщений;
 - Telegram polling service behavior;
 - secret redaction;
 - Telegram auth в web;
- authorization для web-сессий.
+- authorization для web-сессий и шаблонов кампаний.

 Новые тесты стоит класть рядом с feature area, например:

@@ -94,7 +94,7 @@ Blazor-компоненты находятся в `src/GmRelay.Web/Components`:

 Сервисный слой web-панели находится в `src/GmRelay.Web/Services`.

-Web-доступ должен проходить через `AuthorizedSessionService`, чтобы пользователь не мог читать или менять чужие группы и сессии.
+Web-доступ должен проходить через `AuthorizedSessionService`, чтобы пользователь не мог читать или менять чужие группы, сессии и шаблоны кампаний.

 ## Практические ограничения

@@ -1,6 +1,6 @@
 # Руководство ГМа

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

 ## Кто управляет группой

@@ -36,6 +36,20 @@ Owner может назначать помощников с ролью `CoGm` в

 Если `Мест:` не указан, запись остаётся без лимита. Если указан лимит, бот показывает заполненность в формате `Места: 2/4`.

+Для регулярной кампании можно указать одну дату и правило повтора:
+
+```text
+/newsession
+Название: Kingmaker
+Время: 30.04.2026 19:30
+Игр: 6
+Интервал: 7
+Мест: 5
+Ссылка: https://example.com/join
+```
+
+Бот создаст 6 игр с шагом 7 дней. Для количества принимаются строки `Игр:`, `Сессий:` или `Повторов:`, для шага — `Интервал:` или `Шаг:`. Значение количества ограничено 1-52 играми, шаг — 1-365 днями.
+
 ## Запись игроков и лист ожидания

 Игроки записываются через inline-кнопки вида `На <дата>` в сообщении расписания.
@@ -72,12 +86,14 @@ Owner или co-GM может поднять первого игрока из о

 На странице группы Web-панель показывает отдельный блок для каждой видимой пачки игр. Owner и co-GM могут:

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

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

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

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

@@ -1,10 +1,10 @@
 # Главная

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

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

- Версия проекта: `1.7.0`.
+- Версия проекта: `1.8.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.
@@ -15,7 +15,7 @@ GM-Relay — Telegram-бот и Blazor-панель для организаци

 ## Основные возможности

- Создание пачки игровых сессий одной командой `/newsession` с несколькими строками `Время:`.
+- Создание пачки игровых сессий одной командой `/newsession` с несколькими строками `Время:` или одной датой плюс `Игр:`/`Интервал:` для регулярного расписания.
 - Опциональный лимит мест через строку `Мест:` при создании сессии.
 - Интерактивная запись игроков на конкретные даты и самостоятельный выход через inline-кнопки Telegram.
 - Лист ожидания: если основной состав заполнен, новые игроки не переполняют сессию, а попадают в очередь.
@@ -31,6 +31,7 @@ GM-Relay — Telegram-бот и Blazor-панель для организаци
 - Отправка ссылки на подключение за 5 минут до подтверждённой игры.
 - Экспорт будущих запланированных сессий в `.ics` через `/exportcalendar`.
 - Web-панель для owner/co-GM: список групп, список сессий, редактирование названия, времени, ссылки и лимита мест.
+- Шаблоны кампаний в Web Dashboard: сохранённые параметры кампании, лимит мест, режим уведомлений и быстрое создание нового batch по первой дате.
 - Bulk-операции в Web Dashboard: общий `title/link` для batch, перенос всей пачки на фиксированный шаг и клонирование на следующую неделю или месяц с новым Telegram-сообщением.
 - Настройка режима уведомлений для batch: `В группе и в личку` или `Только в группе`, при этом групповые сообщения сохраняются всегда.
 - CSS-fix Web Dashboard: раскрывающиеся списки используют контрастный фон и текст в native select dropdown.