feat: add telegram mini app dashboard
This commit is contained in:
@@ -0,0 +1,69 @@
|
||||
# Telegram Mini App Dashboard Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** Add a Telegram Mini App mobile dashboard that reuses the existing Web Dashboard and validates Telegram WebApp `initData` on the server.
|
||||
|
||||
**Architecture:** Extend `TelegramAuthService` for WebApp init data, add a `/miniapp` Blazor entry page plus `/auth/telegram-webapp` endpoint, and add bot entry points through an inline WebApp button and optional menu button setup. Existing application/domain services remain the only write path.
|
||||
|
||||
**Tech Stack:** .NET 10, Blazor Server, Telegram.Bot, xUnit, Dapper/Npgsql-backed existing services.
|
||||
|
||||
---
|
||||
|
||||
### Task 1: Telegram WebApp Authentication
|
||||
|
||||
**Files:**
|
||||
- Modify: `src/GmRelay.Web/Services/TelegramAuthService.cs`
|
||||
- Modify: `src/GmRelay.Web/Program.cs`
|
||||
- Test: `tests/GmRelay.Bot.Tests/Web/TelegramAuthServiceTests.cs`
|
||||
|
||||
- [ ] Write failing tests for valid WebApp `initData`, tampered hash, and expired auth date.
|
||||
- [ ] Run `dotnet test tests/GmRelay.Bot.Tests/GmRelay.Bot.Tests.csproj --filter TelegramAuthServiceTests`.
|
||||
- [ ] Implement WebApp HMAC verification using the Telegram `WebAppData` secret derivation.
|
||||
- [ ] Add `/auth/telegram-webapp` endpoint that signs in using the same claims as `/auth/telegram`.
|
||||
- [ ] Re-run the filtered tests.
|
||||
|
||||
### Task 2: Mini App Entry Page
|
||||
|
||||
**Files:**
|
||||
- Create: `src/GmRelay.Web/Components/Pages/MiniApp.razor`
|
||||
- Modify: `src/GmRelay.Web/Components/App.razor`
|
||||
- Modify: `src/GmRelay.Web/wwwroot/app.css`
|
||||
- Test: `tests/GmRelay.Bot.Tests/Web/MiniAppDashboardTests.cs`
|
||||
|
||||
- [ ] Write failing tests that assert `/miniapp`, `telegram-web-app.js`, `authenticateTelegramMiniApp`, and Mini App CSS hooks exist.
|
||||
- [ ] Run `dotnet test tests/GmRelay.Bot.Tests/GmRelay.Bot.Tests.csproj --filter MiniAppDashboardTests`.
|
||||
- [ ] Implement `/miniapp` to post `Telegram.WebApp.initData` to `/auth/telegram-webapp`, expand/ready the Mini App, and show fallback login when opened outside Telegram.
|
||||
- [ ] Add CSS for a mobile-first Mini App shell and compact dashboard spacing.
|
||||
- [ ] Re-run the filtered tests.
|
||||
|
||||
### Task 3: Bot Entry Points
|
||||
|
||||
**Files:**
|
||||
- Create: `src/GmRelay.Bot/Infrastructure/Telegram/TelegramMiniAppMenuButtonService.cs`
|
||||
- Modify: `src/GmRelay.Bot/Infrastructure/Telegram/UpdateRouter.cs`
|
||||
- Modify: `src/GmRelay.Bot/Program.cs`
|
||||
- Test: `tests/GmRelay.Bot.Tests/Infrastructure/Telegram/TelegramMiniAppEntryPointTests.cs`
|
||||
|
||||
- [ ] Write failing tests that assert `/start` exposes a WebApp button and startup registers the menu button service.
|
||||
- [ ] Run `dotnet test tests/GmRelay.Bot.Tests/GmRelay.Bot.Tests.csproj --filter TelegramMiniAppEntryPointTests`.
|
||||
- [ ] Add a configurable `Telegram:MiniAppUrl` entry point; when missing, keep existing command behavior.
|
||||
- [ ] Add hosted service that calls `SetChatMenuButton` with `MenuButtonWebApp` only when the URL is configured.
|
||||
- [ ] Re-run the filtered tests.
|
||||
|
||||
### Task 4: Docs, Versions, and Release Prep
|
||||
|
||||
**Files:**
|
||||
- Modify: `Directory.Build.props`
|
||||
- Modify: `compose.yaml`
|
||||
- Modify: `.gitea/workflows/deploy.yml`
|
||||
- Modify: `src/GmRelay.Web/wwwroot/app.css`
|
||||
- Modify: `src/GmRelay.Web/Components/Layout/NavMenu.razor`
|
||||
- Modify: `README.md`
|
||||
- Wiki: `Home`, `Быстрый старт`, `Руководство ГМа`, `Развёртывание`, `Архитектура`, `Разработка`
|
||||
|
||||
- [ ] Update project/container/workflow/UI versions to `1.9.0`.
|
||||
- [ ] Document `TELEGRAM_MINI_APP_URL`, BotFather `/setmenubutton`, `/miniapp`, and WebApp auth.
|
||||
- [ ] Run `dotnet test tests/GmRelay.Bot.Tests/GmRelay.Bot.Tests.csproj --collect:"XPlat Code Coverage"`.
|
||||
- [ ] Run `dotnet build GM-Relay.slnx -c Release`.
|
||||
- [ ] Commit, push, close issue #17, update wiki, create tag/release `v1.9.0`.
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user