45 lines
3.0 KiB
Markdown
45 lines
3.0 KiB
Markdown
# 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.
|