feat: add telegram mini app dashboard

2026-04-28 14:56:55 +03:00
parent 5082dd4fcf
commit 41f2ea6e90
21 changed files with 698 additions and 26 deletions
@@ -0,0 +1,44 @@
+# Telegram Mini App Dashboard Design
+
+## Goal
+
+Issue #17 adds a Telegram Mini App dashboard as the mobile entry point for the existing Web Dashboard. Owner and co-GM users must be able to open the dashboard from Telegram, pass server-side Telegram WebApp `initData` validation, and manage only their own groups.
+
+## Scope
+
+- Add Mini App authentication using Telegram WebApp `initData`.
+- Add a `/miniapp` entry page that signs the user into the existing cookie auth flow, then opens the regular dashboard UI in mobile-first mode.
+- Reuse `AuthorizedSessionService`, `SessionService`, and existing Blazor pages for groups, sessions, templates, waitlist promotion, edit forms, and bulk batch operations.
+- Add bot entry points: a Mini App button in `/start` and a configurable default menu button when `Telegram:MiniAppUrl` is set.
+- Update README, wiki, deployment config, and visible version strings to `1.9.0`.
+
+## Architecture
+
+The Mini App is not a second dashboard implementation. It is a Telegram-authenticated entrance into the existing Blazor dashboard. This keeps authorization, domain operations, Telegram message synchronization, and Web Dashboard behavior in one place.
+
+`TelegramAuthService` gains a second verification method for WebApp `initData`. The server accepts the raw URL-encoded init payload at `/auth/telegram-webapp`, verifies the Telegram HMAC with the bot token, extracts the user id/name from the embedded `user` JSON, and issues the same auth cookie as the login widget endpoint.
+
+`/miniapp` loads `telegram-web-app.js`, posts `window.Telegram.WebApp.initData` to the server endpoint, expands the WebApp viewport, and redirects to `/`. If a user opens `/miniapp` outside Telegram, the page shows the regular login fallback.
+
+## Data Flow
+
+1. User opens the Mini App from the bot menu button or `/start` inline button.
+2. Telegram injects `initData` into the WebApp JavaScript API.
+3. `/miniapp` posts `{ initData }` to `/auth/telegram-webapp`.
+4. The server verifies the WebApp signature and expiry.
+5. The server creates the same claims used by Telegram Login Widget.
+6. Existing Blazor pages load groups through `AuthorizedSessionService`.
+7. Any edit, waitlist, template, or batch action still goes through existing services and keeps Telegram messages synchronized.
+
+## Error Handling
+
+- Missing or invalid init data returns `401` and leaves the user on the Mini App page.
+- Expired auth data is rejected with the same 24-hour window used by the Login Widget.
+- A verified Telegram user with no owner/co-GM groups sees the existing empty dashboard state.
+- Direct navigation to a foreign group/session still redirects to `/access-denied` through existing authorization checks.
+
+## Testing
+
+- Unit tests cover valid and invalid WebApp `initData`.
+- File-level regression tests ensure `/miniapp`, `/auth/telegram-webapp`, Telegram WebApp script loading, bot Mini App button, menu button setup, and mobile Mini App CSS hooks remain present.
+- Existing `AuthorizedSessionServiceTests` continue covering owner/co-GM access behavior.