From ac41d3ef524dd00395915252fd2caf02408ee8f7 Mon Sep 17 00:00:00 2001 From: Toutsu Date: Tue, 28 Apr 2026 14:57:14 +0300 Subject: [PATCH] docs: update wiki for 1.9.0 mini app dashboard --- ...D1%82%D0%B5%D0%BA%D1%82%D1%83%D1%80%D0%B0.md | 14 ++++++++++++-- ...0%B0-%D0%B4%D0%B0%D0%BD%D0%BD%D1%8B%D1%85.md | 4 +++- ...1%8B%D0%B9-%D1%81%D1%82%D0%B0%D1%80%D1%82.md | 12 ++++++++---- ...D1%82%D1%8B%D0%B2%D0%B0%D0%BD%D0%B8%D0%B5.md | 17 ++++++++++------- ...D1%80%D0%B0%D0%B1%D0%BE%D1%82%D0%BA%D0%B0.md | 7 +++++-- ...1%81%D1%82%D0%B2%D0%BE-%D0%93%D0%9C%D0%B0.md | 13 ++++++++++++- Home.md | 7 ++++--- 7 files changed, 54 insertions(+), 20 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 0b68302..87ff49d 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 @@ -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` содержит: 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 760b83e..848c053 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.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 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 7f1b9ba..9974938 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.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. 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 65e6701..7dd6db5 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.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, а пользователь без прав увидеть пустой список своих групп. 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 015a975..6db525d 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.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. 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 6552d79..ba58995 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,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. diff --git a/Home.md b/Home.md index 959e5e1..c759eaf 100644 --- a/Home.md +++ b/Home.md @@ -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: `В группе и в личку` или `Только в группе`, при этом групповые сообщения сохраняются всегда.