docs: update wiki for 1.9.3 mini app fix
@@ -57,7 +57,7 @@ GM-Relay состоит из нескольких .NET-проектов и об
|
||||
## Web UI
|
||||
|
||||
Blazor Server-приложение использует cookie auth и Telegram Login Widget.
|
||||
Начиная с `1.9.0`, тот же Web UI открывается как Telegram Mini App через `/miniapp`; в `1.9.2` вход дополнительно ждёт Telegram `initData` и обновляет fallback-login состояние на `/miniapp` и `/login` без закрытия Mini App.
|
||||
Начиная с `1.9.0`, тот же Web UI открывается как Telegram Mini App через `/miniapp`; в `1.9.3` основной вход по-прежнему проверяет Telegram `initData`, а fallback `/login` использует callback-mode Telegram Login Widget и endpoint `/auth/telegram-login`, чтобы cookie выставлялась внутри активного Mini App WebView без ручного закрытия и повторного открытия.
|
||||
|
||||
Основные сервисы:
|
||||
|
||||
@@ -72,6 +72,7 @@ Blazor Server-приложение использует cookie auth и Telegram
|
||||
|
||||
- `/login` — вход через Telegram.
|
||||
- `/miniapp` — вход из Telegram Mini App через серверную проверку `initData`.
|
||||
- `/auth/telegram-login` — callback-вход Telegram Login Widget: принимает JSON payload, проверяет Telegram HMAC и выдаёт cookie-сессию внутри текущего WebView.
|
||||
- `/auth/status` — лёгкая проверка текущей cookie-сессии для Mini App fallback-flow.
|
||||
- `/` — список групп, где пользователь owner или co-GM.
|
||||
- `/templates` — отдельная вкладка управления шаблонами кампаний по доступным группам.
|
||||
@@ -83,8 +84,10 @@ Blazor Server-приложение использует cookie auth и Telegram
|
||||
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.
|
||||
4. Если `initData` недоступен, fallback `/login` регистрирует `data-onauth`, получает Telegram Login Widget payload в JavaScript и отправляет его на `/auth/telegram-login` без внешнего redirect-flow.
|
||||
5. Shell вызывает `Telegram.WebApp.ready()` / `expand()`, синхронизирует `safeAreaInset` и `contentSafeAreaInset` в CSS-переменные и слушает `safeAreaChanged`, `contentSafeAreaChanged`, `viewportChanged`.
|
||||
6. Сервер проверяет подпись через ключ `WebAppData` + токен бота, извлекает Telegram ID из `user` и создаёт стандартную auth-cookie.
|
||||
7. Дальше пользователь работает с теми же страницами и сервисами, что и в обычном Web Dashboard.
|
||||
|
||||
## Общий домен
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# База данных
|
||||
|
||||
GM-Relay **v1.9.2** использует PostgreSQL. Изменения схемы управляются DbUp-миграциями, встроенными в `GmRelay.Bot` как embedded resources.
|
||||
GM-Relay **v1.9.3** использует PostgreSQL. Изменения схемы управляются DbUp-миграциями, встроенными в `GmRelay.Bot` как embedded resources.
|
||||
|
||||
## Миграции
|
||||
|
||||
@@ -17,7 +17,7 @@ GM-Relay **v1.9.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.2` не добавляет новую миграцию: исправление входа Telegram Mini App использует существующие cookie-auth и таблицы `players`, `group_managers`, `game_groups`, `sessions`, `campaign_templates` и `session_participants`.
|
||||
Версия `1.9.3` не добавляет новую миграцию: исправление входа Telegram Mini App использует существующие cookie-auth и таблицы `players`, `group_managers`, `game_groups`, `sessions`, `campaign_templates` и `session_participants`. Новый endpoint `/auth/telegram-login` проверяет Telegram Login Widget HMAC и создаёт ту же cookie-сессию, не меняя схему БД.
|
||||
|
||||
## Основные таблицы
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Быстрый старт
|
||||
|
||||
Эта страница описывает минимальный запуск текущей версии GM-Relay **v1.9.2**.
|
||||
Эта страница описывает минимальный запуск текущей версии GM-Relay **v1.9.3**.
|
||||
|
||||
## Требования
|
||||
|
||||
@@ -42,8 +42,8 @@ docker compose up -d
|
||||
Compose поднимает:
|
||||
|
||||
- `db`: PostgreSQL 17 Alpine, БД `gmrelay_db`, пользователь `gmrelay`.
|
||||
- `bot`: образ `git.codeanddice.ru/toutsu/gmrelay-bot:1.9.2`.
|
||||
- `web`: образ `git.codeanddice.ru/toutsu/gmrelay-web:1.9.2`.
|
||||
- `bot`: образ `git.codeanddice.ru/toutsu/gmrelay-bot:1.9.3`.
|
||||
- `web`: образ `git.codeanddice.ru/toutsu/gmrelay-web:1.9.3`.
|
||||
|
||||
Web UI будет доступен на `http://localhost:8080`, если `GMRELAY_WEB_PORT` не переопределён.
|
||||
|
||||
@@ -78,6 +78,7 @@ dotnet run --project src/GmRelay.AppHost
|
||||
- Owner/co-GM может нажать `⏰ Перенести`, отправить 2-3 варианта времени и дедлайн; бот создаст голосование и применит победивший вариант по дедлайну.
|
||||
- Web-панель должна перенаправлять неавторизованного пользователя на `/login`.
|
||||
- После входа через Telegram пользователь видит группы, где он назначен owner или co-GM.
|
||||
- `/miniapp` вне Telegram показывает fallback на обычный вход, а внутри Telegram ждёт `initData`, отправляет его на `/auth/telegram-webapp` и открывает тот же dashboard в мобильной раскладке. Если используется внешний Telegram Login на `/login`, текущая Mini App-страница проверяет `/auth/status` и после возврата фокуса делает full reload при необходимости.
|
||||
- `/miniapp` вне Telegram показывает диагностичный fallback на обычный вход, а внутри Telegram ждёт `initData`, отправляет его на `/auth/telegram-webapp` и открывает тот же dashboard в мобильной раскладке. Если нужен fallback `/login`, Telegram Login Widget работает через `data-onauth`: payload отправляется на `/auth/telegram-login`, cookie выставляется в текущем WebView, и страница сразу возвращается на `/`.
|
||||
- Для v1.9.3 не нужно новое действие в BotFather, если домен и menu button уже указывают на HTTPS URL `/miniapp` из `TELEGRAM_MINI_APP_URL`.
|
||||
- В левом меню есть вкладка `Шаблоны` для управления сохранёнными шаблонами кампаний.
|
||||
- На странице группы owner видит блок управления co-GM, а owner/co-GM применяют существующие шаблоны и видят batch-операции: общий title/link, режим уведомлений, перенос всей пачки и клонирование batch.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Развёртывание
|
||||
|
||||
Текущий production-like способ запуска GM-Relay **v1.9.2** — Docker Compose из `compose.yaml`.
|
||||
Текущий production-like способ запуска GM-Relay **v1.9.3** — Docker Compose из `compose.yaml`.
|
||||
|
||||
## Сервисы Docker Compose
|
||||
|
||||
@@ -15,13 +15,13 @@
|
||||
|
||||
`bot`:
|
||||
|
||||
- образ: `git.codeanddice.ru/toutsu/gmrelay-bot:1.9.2`;
|
||||
- образ: `git.codeanddice.ru/toutsu/gmrelay-bot:1.9.3`;
|
||||
- запускается после успешного healthcheck сервиса `db`;
|
||||
- переменные окружения: `ConnectionStrings__gmrelaydb`, `Telegram__BotToken`, `Telegram__MiniAppUrl`.
|
||||
|
||||
`web`:
|
||||
|
||||
- образ: `git.codeanddice.ru/toutsu/gmrelay-web:1.9.2`;
|
||||
- образ: `git.codeanddice.ru/toutsu/gmrelay-web:1.9.3`;
|
||||
- запускается после успешного healthcheck сервиса `db`;
|
||||
- переменные окружения: `ConnectionStrings__gmrelaydb`, `Telegram__BotToken`, `Telegram__BotUsername`, `Telegram__MiniAppUrl`;
|
||||
- порт: `${GMRELAY_WEB_PORT:-8080}:8080`;
|
||||
@@ -94,7 +94,7 @@ docker compose down -v
|
||||
|
||||
## Поведение миграций
|
||||
|
||||
Бот применяет DbUp-миграции при старте до обработки Telegram updates. Начиная с версии `1.8.0` доступна миграция `V010__add_campaign_templates.sql`: она создаёт таблицу `campaign_templates` для Web-шаблонов кампаний и быстрого создания повторяющихся batch-расписаний. Версия `1.9.2` не добавляет новую миграцию: Telegram Mini App использует существующую модель пользователей, групп и сессий, а исправление входа работает на уровне Web-auth flow. После обновления стоит проверить логи `bot`, чтобы убедиться, что миграции применились без ошибок.
|
||||
Бот применяет DbUp-миграции при старте до обработки Telegram updates. Начиная с версии `1.8.0` доступна миграция `V010__add_campaign_templates.sql`: она создаёт таблицу `campaign_templates` для Web-шаблонов кампаний и быстрого создания повторяющихся batch-расписаний. Версия `1.9.3` не добавляет новую миграцию: Telegram Mini App использует существующую модель пользователей, групп и сессий, а исправление входа работает на уровне Web-auth flow через `/auth/telegram-login`. После обновления стоит проверить логи `bot`, чтобы убедиться, что миграции применились без ошибок.
|
||||
|
||||
## Безопасность
|
||||
|
||||
@@ -111,4 +111,5 @@ 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 без повторного открытия Mini App после входа; если сработал fallback `/login`, после возврата из внешнего Telegram Login текущая страница должна обновиться сама.
|
||||
7. Проверить `/miniapp` из Telegram: пользователь owner/co-GM должен попасть в мобильный dashboard без повторного открытия Mini App после входа; если сработал fallback `/login`, callback Telegram Login Widget должен сразу вернуть пользователя на `/` в текущем WebView.
|
||||
8. На телефоне проверить, что верхняя навигация и карточки dashboard начинаются ниже системного статус-бара и панели Telegram; Mini App использует Telegram `safeAreaInset` / `contentSafeAreaInset` и browser `env(safe-area-inset-*)` fallback.
|
||||
|
||||
@@ -26,7 +26,7 @@ dotnet run --project src/GmRelay.AppHost
|
||||
|
||||
`Directory.Build.props` задаёт:
|
||||
|
||||
- `Version`: `1.9.2`.
|
||||
- `Version`: `1.9.3`.
|
||||
- `TargetFramework`: `net10.0`.
|
||||
- `LangVersion`: `preview`.
|
||||
- `Nullable`: `enable`.
|
||||
@@ -97,7 +97,7 @@ Blazor-компоненты находятся в `src/GmRelay.Web/Components`:
|
||||
|
||||
Web-доступ должен проходить через `AuthorizedSessionService`, чтобы пользователь не мог читать или менять чужие группы, сессии и шаблоны кампаний.
|
||||
|
||||
Mini App изменения должны переиспользовать те же страницы и сервисы. Серверная проверка `Telegram.WebApp.initData` живёт в `TelegramAuthService`, входной endpoint `/auth/telegram-webapp` выдаёт ту же cookie-аутентификацию, что и Telegram Login Widget, а `/auth/status` используется Mini App fallback-flow на `/miniapp` и `/login` для обновления текущей страницы после внешнего Telegram Login.
|
||||
Mini App изменения должны переиспользовать те же страницы и сервисы. Серверная проверка `Telegram.WebApp.initData` живёт в `TelegramAuthService`, endpoint `/auth/telegram-webapp` выдаёт ту же cookie-аутентификацию, что и Telegram Login Widget, а fallback `/login` должен использовать callback-flow `data-onauth` и `POST /auth/telegram-login` вместо redirect-flow. `/auth/status` остаётся лёгким smoke endpoint для проверки текущей cookie-сессии. Safe-area изменения должны обновлять shell JS, CSS-переменные и статические regression-тесты, чтобы мобильная шапка не уходила под Telegram UI.
|
||||
|
||||
## Практические ограничения
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Руководство ГМа
|
||||
|
||||
Руководство описывает пользовательские сценарии бота, Telegram Mini App и Web-панели для GM-Relay **v1.9.2**.
|
||||
Руководство описывает пользовательские сценарии бота, Telegram Mini App и Web-панели для GM-Relay **v1.9.3**.
|
||||
|
||||
## Кто управляет группой
|
||||
|
||||
@@ -168,6 +168,6 @@ Owner и co-GM могут открыть dashboard прямо внутри Teleg
|
||||
- через default menu button бота, если настроен `TELEGRAM_MINI_APP_URL`;
|
||||
- через кнопку `Открыть dashboard` в ответе на `/start`.
|
||||
|
||||
Mini App открывает `/miniapp`, ждёт `Telegram.WebApp.initData`, отправляет его на серверный endpoint `/auth/telegram-webapp` и проходит HMAC-проверку токеном бота. После проверки пользователь получает обычную cookie-сессию dashboard. Если Telegram Login открыл внешний браузер с fallback-страницы `/login`, текущая Mini App-страница проверяет `/auth/status` и после возврата фокуса делает full reload, чтобы сервер увидел новую cookie и перевёл пользователя в dashboard.
|
||||
Mini App открывает `/miniapp`, ждёт `Telegram.WebApp.initData`, отправляет его на серверный endpoint `/auth/telegram-webapp` и проходит HMAC-проверку токеном бота. После проверки пользователь получает обычную cookie-сессию dashboard. Если нужен fallback-вход, `/login` использует callback Telegram Login Widget: подтверждение Telegram отправляется на `/auth/telegram-login`, cookie появляется в текущем Mini App WebView, и dashboard открывается без ручного закрытия и повторного запуска Mini App. Интерфейс v1.9.3 также учитывает safe-area телефона и Telegram, поэтому верхняя навигация не должна перекрываться статус-баром.
|
||||
|
||||
Функционально Mini App использует те же страницы, что и Web Dashboard: список групп, карточки сессий, редактирование, очередь ожидания, применение шаблонов и bulk-операции batch. Доступ к чужим группам не появляется, потому что все операции продолжают проходить через `AuthorizedSessionService` и роль owner/co-GM.
|
||||
|
||||
+7
-3
@@ -1,10 +1,10 @@
|
||||
# Главная
|
||||
|
||||
GM-Relay — Telegram-бот, Telegram Mini App и Blazor-панель для организации TTRPG-сессий. Текущее состояние документации соответствует репозиторию `Toutsu/GmRelayBot` и релизу **v1.9.2**.
|
||||
GM-Relay — Telegram-бот, Telegram Mini App и Blazor-панель для организации TTRPG-сессий. Текущее состояние документации соответствует репозиторию `Toutsu/GmRelayBot` и релизу **v1.9.3**.
|
||||
|
||||
## Текущий стек
|
||||
|
||||
- Версия проекта: `1.9.2`.
|
||||
- Версия проекта: `1.9.3`.
|
||||
- Платформа: `.NET 10`, C# preview, nullable reference types, warnings as errors.
|
||||
- Оркестрация разработки: `.NET Aspire 13` через `src/GmRelay.AppHost`.
|
||||
- Runtime бота: `Worker Service`, Telegram long polling, Native AOT.
|
||||
@@ -31,7 +31,7 @@ GM-Relay — Telegram-бот, Telegram Mini App и Blazor-панель для о
|
||||
- Отправка ссылки на подключение за 5 минут до подтверждённой игры.
|
||||
- Экспорт будущих запланированных сессий в `.ics` через `/exportcalendar`.
|
||||
- Web-панель для owner/co-GM: список групп, список сессий, редактирование названия, времени, ссылки и лимита мест.
|
||||
- Telegram Mini App Dashboard: мобильный вход из Telegram через `/miniapp`, ожидание WebApp `initData`, серверная проверка Telegram-подписи и автоматическое обновление текущей Mini App-страницы после внешнего Telegram Login, включая fallback-страницу `/login`.
|
||||
- Telegram Mini App Dashboard: мобильный вход из Telegram через `/miniapp`, проверка WebApp `initData`, callback-based fallback login через `/auth/telegram-login` внутри активного WebView и поддержка Telegram safe-area отступов под статус-бар телефона и верхнюю панель Telegram.
|
||||
- Шаблоны кампаний в Web Dashboard: отдельная вкладка для управления сохранёнными параметрами кампаний и применение шаблонов на странице группы по первой дате.
|
||||
- Bulk-операции в Web Dashboard: общий `title/link` для batch, перенос всей пачки на фиксированный шаг и клонирование на следующую неделю или месяц с новым Telegram-сообщением.
|
||||
- Настройка режима уведомлений для batch: `В группе и в личку` или `Только в группе`, при этом групповые сообщения сохраняются всегда.
|
||||
@@ -46,3 +46,7 @@ GM-Relay — Telegram-бот, Telegram Mini App и Blazor-панель для о
|
||||
- [Разработка](Разработка) — правила разработки, тесты и локальные команды.
|
||||
- [Развёртывание](Развёртывание) — Docker Compose, окружение и эксплуатация.
|
||||
- [База данных](База-данных) — схема БД, миграции и статусная модель.
|
||||
|
||||
## v1.9.3
|
||||
|
||||
Patch-релиз стабилизирует Telegram Mini App: fallback-вход на `/login` больше не уводит cookie в отдельный redirect-flow, а отправляет Telegram Login Widget payload на `/auth/telegram-login` из текущего WebView. Mini App shell также применяет `safeAreaInset` и `contentSafeAreaInset`, поэтому шапка и контент не перекрываются системным статус-баром и верхней панелью Telegram. Новых миграций и действий в BotFather для уже настроенного `/miniapp` URL нет.
|
||||
|
||||
Reference in New Issue
Block a user