From 425dbfd015e9a637a387d6c213ba362dc3ee2814 Mon Sep 17 00:00:00 2001 From: Toutsu Date: Fri, 17 Apr 2026 11:10:28 +0300 Subject: [PATCH] docs: Update README with Web Dashboard info --- README.md | 85 +++++++++++++++++++++++++++++++------------------------ 1 file changed, 48 insertions(+), 37 deletions(-) diff --git a/README.md b/README.md index f39ac5e..4bd059e 100644 --- a/README.md +++ b/README.md @@ -1,34 +1,47 @@ -# 🎲 GM-Relay: TTRPG Session Scheduling Bot +# 🎲 GM-Relay: TTRPG Session Scheduling Bot & Web Dashboard -**GM-Relay** — это высокопроизводительный Telegram-бот для Мастеров Подземелий (ГМов), предназначенный для автоматизации записи игроков на сессии и управления игровым расписанием. +**GM-Relay** — это комплексное решение для Мастеров Подземелий (ГМов), состоящее из высокопроизводительного Telegram-бота и удобного веб-интерфейса. Предназначено для автоматизации записи игроков на сессии, управления расписанием и проведения игр. -Бот разработан с упором на скорость, минимальное потребление ресурсов и удобство использования в реальных игровых группах. +Проект разработан с упором на производительность, архитектуру Vertical Slice, Native AOT (для бота) и удобство развертывания с использованием .NET Aspire. --- ## ✨ Ключевые возможности +### 🤖 Telegram Бот - **📅 Создание расписаний (Batch Sessions)**: Создавайте сразу несколько игр одним сообщением (на неделю или месяц вперед). - **✋ Интерактивная запись**: Игроки записываются на конкретные даты нажатием одной кнопки. - **📁 Поддержка Форумов (Telegram Topics)**: Бот автоматически создает тему во вложенных чатах Telegram под каждую новую пачку игр. - **❌ Управление сессиями**: Мастер может отменять отдельные игры прямо в общем сообщении расписания. - **🗓 Экспорт в Календарь**: Генерация файла `.ics` для добавления всех игр в Google, Apple или Яндекс Календарь одной командой. -- **🚀 Native AOT**: Скомпилирован в нативный бинарный файл. Мгновенный запуск и потребление памяти в десятки раз меньше обычных .NET приложений. Идеально для **Raspberry Pi**. +- **🚀 Native AOT**: Скомпилирован в нативный бинарный файл. Мгновенный запуск и минимальное потребление памяти. Идеально для **Raspberry Pi**. + +### 🌐 Web Dashboard (Blazor Server) +- **🔐 Авторизация через Telegram**: Безопасный вход с использованием Telegram Login Widget (HMAC-SHA256 валидация). +- **📝 Удобное редактирование**: Веб-интерфейс для детального редактирования сессий, изменения дат, названий и статусов. +- **🔄 Автоматическая синхронизация**: Любые изменения в веб-интерфейсе мгновенно обновляют сообщения с расписанием в Telegram-чатах игроков. +- **🕒 Управление временем**: UI адаптирован под московское время (UTC+3), в то время как база данных работает в UTC. --- ## 🛠 Технологический стек -- **Язык**: C# 13 (.NET 10) +- **Язык**: C# 14 (.NET 10) +- **Архитектура**: Vertical Slice Architecture, общая библиотека (`GmRelay.Shared`) для доменной логики. +- **Бот**: Telegram.Bot, Native AOT. +- **Веб-интерфейс**: Blazor Server. +- **Оркестрация**: .NET Aspire (`GmRelay.AppHost`). - **База данных**: PostgreSQL -- **ORM**: Dapper (AOT-совместный через Dapper.AOT) -- **Миграции**: DbUp (автоматически при старте) -- **Контейнеризация**: Docker + Multi-arch build (AMD64/ARM64) +- **ORM**: Dapper (с использованием Dapper.AOT для source generators). +- **Миграции**: DbUp. +- **Развертывание**: Docker Compose + Multi-arch (AMD64/ARM64). --- ## 🚀 Быстрый старт (Docker Compose) +Проект использует Docker Compose для одновременного запуска базы данных, бота и веб-интерфейса. + ### 1. Подготовка Убедитесь, что у вас установлены **Docker** и **Docker Compose**. @@ -42,35 +55,39 @@ cp .env.example .env Отредактируйте `.env`: ```env -# Токен вашего бота от @BotFather +# Токен вашего бота от @BotFather (используется и для бота, и как секретный ключ для веб-авторизации) TELEGRAM_BOT_TOKEN=ваш_токен_здесь # Пароль для базы данных PostgreSQL POSTGRES_PASSWORD=ваш_надежный_пароль ``` +*(Опционально)* Настройте домен Telegram бота в @BotFather командой `/setdomain` для работы виджета авторизации на вашем сайте. + ### 3. Запуск Выполните команду: ```bash -docker compose up -d +docker compose up -d -build ``` -Бот сам создаст базу данных, применит миграции и начнет слушать сообщения. +Инфраструктура автоматически: +- Поднимет PostgreSQL. +- Запустит бота (применив миграции БД). +- Запустит веб-интерфейс (доступен по умолчанию на порту **8080** внутри контейнера). --- -## ⚙️ Настройка в Telegram +## ⚙️ Настройка бота в Telegram -Чтобы бот работал корректно в вашей игровой группе: - -1. **Добавьте бота в группу** (или Супергруппу/Форум). -2. **Назначьте бота Администратором**. -3. **Необходимые права**: - * `Выбор тем` (Managed Topics) — **обязательно**, если вы используете Форум (Темы), иначе бот не сможет создавать ветки для игр. - * `Отправка сообщений` — само собой. - * `Закрепление сообщений` — рекомендуется для удобства игроков. +Чтобы бот работал корректно: +1. **Добавьте бота в группу** (или Супергруппу/Форум). +2. **Назначьте бота Администратором**. +3. **Необходимые права**: + * `Выбор тем` (Managed Topics) — **обязательно** для Форумов. + * `Отправка сообщений`. + * `Закрепление сообщений` — рекомендуется. > [!TIP] -> Колонку "Мастер" (GM) бот определяет по первому человеку, который создал сессию в этой группе. Только этот пользователь сможет отменять игры через кнопки. +> Колонку "Мастер" (GM) бот определяет по первому человеку, который создал сессию в этой группе. Только этот пользователь сможет отменять игры через кнопки бота и редактировать их в веб-интерфейсе. --- @@ -87,32 +104,26 @@ docker compose up -d Ссылка: https://discord.gg/invite-link ``` -* **Название**: Заголовок игры (будет отображаться в списке). -* **Время**: Неограниченное количество строк "Время:" для каждой сессии. -* **Ссылка**: Ссылка на Discord/Roll20/Foundry (будет доступна игрокам). - ### Другие команды - `/listsessions` — Показать список всех актуальных игр в этой группе. -- `/reschedulesession` — Перенести сессию на другое время. Запускает голосование среди всех записавшихся игроков — время обновится только после единогласного одобрения. -- `/deletesession` — Удалить сессию. Автоматически закрывает связанную тему в Форуме. -- `/exportcalendar` — Получить файл `.ics` со всеми вашими будущими играми. +- `/reschedulesession` — Перенести сессию на другое время с голосованием игроков. +- `/deletesession` — Удалить сессию. +- `/exportcalendar` — Получить `.ics` файл с играми. - `/help` — Справка по формату. --- -## 🏗 Разработка и сборка +## 🏗 Разработка и запуск локально (.NET Aspire) -Если вы хотите собрать проект вручную без Docker: +Для локальной разработки проще всего использовать .NET Aspire: -1. Установите [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0). -2. Настройте строку подключения в `appsettings.json` или через переменные окружения. -3. Для сборки Native AOT: - ```bash - dotnet publish src/GmRelay.Bot/GmRelay.Bot.csproj -c Release - ``` +1. Установите [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0) и workload Aspire. +2. Откройте решение `GM-Relay.slnx`. +3. Установите переменные окружения (или user secrets) для `GmRelay.AppHost`. +4. Запустите проект `GmRelay.AppHost`. Aspire Dashboard запустится автоматически, предоставляя удобный мониторинг БД, бота и веб-интерфейса. > [!NOTE] -> При использовании **Dapper** в режиме Native AOT, все SQL-запросы должны использовать строго типизированные DTO. Динамические типы (`dynamic`) не поддерживаются. +> При использовании **Dapper** в режиме Native AOT, все SQL-запросы используют строго типизированные DTO. Динамические типы (`dynamic`) не поддерживаются. ---