docs: update wiki for 1.9.0 mini app dashboard

2026-04-28 14:57:14 +03:00
parent 3ef2184fbb
commit ac41d3ef52
7 changed files with 54 additions and 20 deletions
@@ -6,7 +6,7 @@ GM-Relay состоит из нескольких .NET-проектов и об

 - `src/GmRelay.AppHost` — Aspire AppHost. Поднимает PostgreSQL с PgAdmin и запускает bot/web проекты.
 - `src/GmRelay.Bot` — Worker Service с Telegram long polling, миграциями, планировщиком и вертикальными срезами бота.
- `src/GmRelay.Web` — Blazor Server UI для ГМа.
+- `src/GmRelay.Web` — Blazor Server UI для ГМа, включая Telegram Login Widget и Telegram Mini App вход.
 - `src/GmRelay.Shared` — общие доменные значения и rendering-код Telegram-сообщений.
 - `src/GmRelay.ServiceDefaults` — общие Aspire defaults: OpenTelemetry, service discovery, resilience, health checks.

@@ -57,10 +57,11 @@ GM-Relay состоит из нескольких .NET-проектов и об
 ## Web UI

 Blazor Server-приложение использует cookie auth и Telegram Login Widget.
+Начиная с `1.9.0`, тот же Web UI открывается как Telegram Mini App через `/miniapp`.

 Основные сервисы:

- `TelegramAuthService` валидирует HMAC-SHA256 подпись Telegram Login Widget и `auth_date`.
+- `TelegramAuthService` валидирует HMAC-SHA256 подпись Telegram Login Widget, Telegram WebApp `initData` и `auth_date`.
 - `SessionService` читает и обновляет группы/сессии через Dapper, включая шаблоны кампаний и bulk-операции по `batch_id`.
 - `SessionService` сохраняет режим уведомлений batch и дублирует Web-уведомления в ЛС, если включён `GroupAndDirect`.
 - `SessionService` читает `group_managers`, проверяет роли `Owner`/`CoGm` и сохраняет назначения co-GM.
@@ -70,11 +71,20 @@ Blazor Server-приложение использует cookie auth и Telegram
 Основные страницы:

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

+Поток Mini App:
+
+1. Бот открывает URL `Telegram:MiniAppUrl` через menu button или inline WebApp-кнопку `/start`.
+2. Страница `/miniapp` читает `Telegram.WebApp.initData` из Telegram JS API.
+3. Blazor отправляет initData на `/auth/telegram-webapp`.
+4. Сервер проверяет подпись через ключ `WebAppData` + токен бота, извлекает Telegram ID из `user` и создаёт стандартную auth-cookie.
+5. Дальше пользователь работает с теми же страницами и сервисами, что и в обычном Web Dashboard.
+
 ## Общий домен

 `GmRelay.Shared` содержит:
@@ -1,6 +1,6 @@
 # База данных

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

 ## Миграции

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

+Версия `1.9.0` не добавляет новую миграцию: Telegram Mini App использует существующие таблицы `players`, `group_managers`, `game_groups`, `sessions`, `campaign_templates` и `session_participants`.
+
 ## Основные таблицы

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

-Эта страница описывает минимальный запуск текущей версии GM-Relay **v1.8.2**.
+Эта страница описывает минимальный запуск текущей версии GM-Relay **v1.9.0**.

 ## Требования

@@ -28,6 +28,7 @@ cp .env.example .env
 ```env
 TELEGRAM_BOT_TOKEN=YOUR_BOT_TOKEN_HERE
 TELEGRAM_BOT_USERNAME=YOUR_BOT_USERNAME_HERE
+TELEGRAM_MINI_APP_URL=https://your-domain.example/miniapp
 POSTGRES_PASSWORD=StrongPasswordForDatabase
 GMRELAY_WEB_PORT=8080
 ```
@@ -41,8 +42,8 @@ docker compose up -d
 Compose поднимает:

 - `db`: PostgreSQL 17 Alpine, БД `gmrelay_db`, пользователь `gmrelay`.
- `bot`: образ `git.codeanddice.ru/toutsu/gmrelay-bot:1.8.2`.
- `web`: образ `git.codeanddice.ru/toutsu/gmrelay-web:1.8.2`.
+- `bot`: образ `git.codeanddice.ru/toutsu/gmrelay-bot:1.9.0`.
+- `web`: образ `git.codeanddice.ru/toutsu/gmrelay-web:1.9.0`.

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

@@ -59,6 +60,7 @@ dotnet run --project src/GmRelay.AppHost
 - `ConnectionStrings__gmrelaydb` — строка подключения к PostgreSQL.
 - `Telegram__BotToken` — токен Telegram-бота.
 - `Telegram__BotUsername` — имя бота без `@`, нужно для Telegram Login Widget.
+- `Telegram__MiniAppUrl` — HTTPS URL `/miniapp`, нужен боту для Telegram menu button и кнопки `/start`.

 ## Настройка Telegram

@@ -66,14 +68,16 @@ dotnet run --project src/GmRelay.AppHost
 2. Для forum-групп выдайте право управления темами, иначе бот не сможет создать topic под пачку игр.
 3. Рекомендуемые права: отправка сообщений, закрепление сообщений, управление темами.
 4. Для web-login настройте домен у `@BotFather` через `/setdomain`, если Web-панель используется не локально.
+5. Для Mini App задайте menu button в `@BotFather` на URL из `TELEGRAM_MINI_APP_URL`; бот также сам выставляет default menu button при старте, если URL настроен.

 ## Проверка после запуска

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

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

 ## Сервисы Docker Compose

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

 `bot`:

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

 `web`:

- образ: `git.codeanddice.ru/toutsu/gmrelay-web:1.8.2`;
+- образ: `git.codeanddice.ru/toutsu/gmrelay-web:1.9.0`;
 - запускается после успешного healthcheck сервиса `db`;
- переменные окружения: `ConnectionStrings__gmrelaydb`, `Telegram__BotToken`, `Telegram__BotUsername`;
+- переменные окружения: `ConnectionStrings__gmrelaydb`, `Telegram__BotToken`, `Telegram__BotUsername`, `Telegram__MiniAppUrl`;
 - порт: `${GMRELAY_WEB_PORT:-8080}:8080`;
 - volume: `web_keys` для ключей ASP.NET Data Protection.

@@ -41,6 +41,7 @@ POSTGRES_PASSWORD=...

 ```env
 GMRELAY_WEB_PORT=8080
+TELEGRAM_MINI_APP_URL=https://your-domain.example/miniapp
 POSTGRES_VOLUME_NAME=game_pgdata
 WEB_KEYS_VOLUME_NAME=gmrelay_web_keys
 ```
@@ -88,11 +89,12 @@ docker compose down -v
 - бот должен быть участником группы;
 - в forum-группах боту нужны права управления темами;
 - для удаления исходных командных сообщений или forum topics боту нужны достаточные права администратора;
- для Telegram Login Widget нужно настроить web-домен в `@BotFather`.
+- для Telegram Login Widget нужно настроить web-домен в `@BotFather`;
+- для Telegram Mini App нужно настроить menu button на HTTPS URL `/miniapp`, совпадающий с `TELEGRAM_MINI_APP_URL`.

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

-Бот применяет DbUp-миграции при старте до обработки Telegram updates. Начиная с версии `1.8.0` доступна миграция `V010__add_campaign_templates.sql`: она создаёт таблицу `campaign_templates` для Web-шаблонов кампаний и быстрого создания повторяющихся batch-расписаний. После обновления стоит проверить логи `bot`, чтобы убедиться, что миграции применились без ошибок.
+Бот применяет DbUp-миграции при старте до обработки Telegram updates. Начиная с версии `1.8.0` доступна миграция `V010__add_campaign_templates.sql`: она создаёт таблицу `campaign_templates` для Web-шаблонов кампаний и быстрого создания повторяющихся batch-расписаний. Версия `1.9.0` не добавляет новую миграцию: Telegram Mini App использует существующую модель пользователей, групп и сессий. После обновления стоит проверить логи `bot`, чтобы убедиться, что миграции применились без ошибок.

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

@@ -109,3 +111,4 @@ docker compose down -v
 4. Выполнить `docker compose up -d`.
 5. Проверить `docker compose logs -f bot`: миграции, подключение к БД и старт Telegram polling.
 6. Проверить вход в Web-панель и одну read-only страницу группы или сессии до редактирования данных.
+7. Проверить `/miniapp` из Telegram: пользователь owner/co-GM должен попасть в мобильный dashboard, а пользователь без прав увидеть пустой список своих групп.
@@ -26,7 +26,7 @@ dotnet run --project src/GmRelay.AppHost

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

- `Version`: `1.8.2`.
+- `Version`: `1.9.0`.
 - `TargetFramework`: `net10.0`.
 - `LangVersion`: `preview`.
 - `Nullable`: `enable`.
@@ -77,6 +77,7 @@ V006__add_example_column.sql
 - Telegram polling service behavior;
 - secret redaction;
 - Telegram auth в web;
+- Telegram Mini App `initData` auth и entry points;
 - authorization для web-сессий и шаблонов кампаний.

 Новые тесты стоит класть рядом с feature area, например:
@@ -89,13 +90,15 @@ tests/GmRelay.Bot.Tests/Features/Sessions/CreateSession/NewSessionCommandParserT

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

- `Pages` — страницы `/`, `/login`, `/group/{id}`, `/session/edit/{id}` и служебные страницы.
+- `Pages` — страницы `/`, `/login`, `/miniapp`, `/group/{id}`, `/session/edit/{id}` и служебные страницы.
 - `Layout` — layout, navigation, reconnect modal.

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

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

+Mini App изменения должны переиспользовать те же страницы и сервисы. Серверная проверка `Telegram.WebApp.initData` живёт в `TelegramAuthService`, а входной endpoint `/auth/telegram-webapp` выдаёт ту же cookie-аутентификацию, что и Telegram Login Widget.
+
 ## Практические ограничения

 - Не хранить секреты в appsettings или wiki. Использовать `.env`, environment variables или user secrets.
@@ -1,6 +1,6 @@
 # Руководство ГМа

-Руководство описывает пользовательские сценарии бота и Web-панели для GM-Relay **v1.8.2**.
+Руководство описывает пользовательские сценарии бота, Telegram Mini App и Web-панели для GM-Relay **v1.9.0**.

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

@@ -160,3 +160,14 @@ Web UI доступен после входа через Telegram Login Widget.
 Дополнительно owner может управлять списком co-GM на странице группы.

 При сохранении отдельной сессии Web-панель обновляет запись в БД, отправляет уведомление в Telegram-группу и пытается перерисовать исходное сообщение расписания пачки. Bulk-операции обновляют исходное batch-сообщение, а clone публикует новое сообщение для новой пачки.
+
+## Telegram Mini App Dashboard
+
+Owner и co-GM могут открыть dashboard прямо внутри Telegram:
+
+- через default menu button бота, если настроен `TELEGRAM_MINI_APP_URL`;
+- через кнопку `Открыть dashboard` в ответе на `/start`.
+
+Mini App открывает `/miniapp`, получает `Telegram.WebApp.initData`, отправляет его на серверный endpoint `/auth/telegram-webapp` и проходит HMAC-проверку токеном бота. После проверки пользователь получает обычную cookie-сессию dashboard.
+
+Функционально Mini App использует те же страницы, что и Web Dashboard: список групп, карточки сессий, редактирование, очередь ожидания, применение шаблонов и bulk-операции batch. Доступ к чужим группам не появляется, потому что все операции продолжают проходить через `AuthorizedSessionService` и роль owner/co-GM.
@@ -1,14 +1,14 @@
 # Главная

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

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

- Версия проекта: `1.8.2`.
+- Версия проекта: `1.9.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.
- Web UI: Blazor Server с Telegram Login Widget.
+- Web UI: Blazor Server с Telegram Login Widget и Telegram Mini App входом.
 - База данных: PostgreSQL 17.
 - Доступ к данным: Npgsql, Dapper, Dapper.AOT; миграции через DbUp.
 - Деплой: Docker Compose, образы `gmrelay-bot` и `gmrelay-web`.
@@ -31,6 +31,7 @@ GM-Relay — Telegram-бот и Blazor-панель для организаци
 - Отправка ссылки на подключение за 5 минут до подтверждённой игры.
 - Экспорт будущих запланированных сессий в `.ics` через `/exportcalendar`.
 - Web-панель для owner/co-GM: список групп, список сессий, редактирование названия, времени, ссылки и лимита мест.
+- Telegram Mini App Dashboard: мобильный вход из Telegram через `/miniapp`, серверная проверка WebApp `initData` и те же права owner/co-GM, что в Web Dashboard.
 - Шаблоны кампаний в Web Dashboard: отдельная вкладка для управления сохранёнными параметрами кампаний и применение шаблонов на странице группы по первой дате.
 - Bulk-операции в Web Dashboard: общий `title/link` для batch, перенос всей пачки на фиксированный шаг и клонирование на следующую неделю или месяц с новым Telegram-сообщением.
 - Настройка режима уведомлений для batch: `В группе и в личку` или `Только в группе`, при этом групповые сообщения сохраняются всегда.