Добавлена документация
This commit is contained in:
FrigaT
164
README.md
164
README.md
@@ -1,92 +1,96 @@
|
||||
# BotPages Framework
|
||||
# BotPages
|
||||
|
||||
BotPages — это архитектурный фреймворк для построения Telegram/MAX‑ботов с чистыми слоями, расширяемыми API и удобным developer experience.
|
||||
BotPages — кроссплатформенный фреймворк для создания диалоговых ботов с системой страниц (page‑based conversational framework).
|
||||
|
||||
## ✨ Возможности
|
||||
- **Навигация через страницы**: каждая страница — отдельный обработчик логики.
|
||||
- **Единый метод GoToAsync**: автоматически поддерживает как `SingletonPage`, так и `StatefulPage`.
|
||||
- **StatefulPage**: свойства автоматически сохраняются в `StateStorage`.
|
||||
- **SingletonPage**: один экземпляр на всё приложение, без состояния.
|
||||
- **Middleware**: подключение промежуточных обработчиков (логирование, обработка ошибок).
|
||||
- **Автоматическая регистрация страниц**: через рефлексию.
|
||||
- **Роутинг страниц**: возможность устанавливать пути вызова для страниц.
|
||||
- **Команды**: возможность установки команд, которые работают приоритетнее обработчиков страниц.
|
||||
- **Минимум boilerplate**: декларативные интерфейсы и fluent API.
|
||||
Цели проекта:
|
||||
- Простая модель страниц и навигации.
|
||||
- Портируемость между мессенджерами через адаптеры.
|
||||
- Поддержка middleware и декларативной системы команд.
|
||||
- Минимум boilerplate и удобный developer experience.
|
||||
|
||||
Структура репозитория
|
||||
|
||||
- `BotPages.Core` — ядро фреймворка: навигация, страницы, маршрутизация, реестр команд, middleware, абстракции адаптеров и хранилища состояния.
|
||||
- `BotPages.Telegram` — адаптер для Telegram Bot API (реализация `IMessangerAdapterSetup`/`IMessengerAdapter`).
|
||||
- `Demo` — пример приложения с несколькими страницами и конфигурацией адаптера.
|
||||
- `BotPages` — мета‑проект для упаковки библиотек.
|
||||
- `docs/` — внутренняя документация проекта (Quickstart, API reference и т.д.).
|
||||
|
||||
Требования
|
||||
|
||||
- .NET 8 SDK
|
||||
- C# 12
|
||||
|
||||
Быстрый старт (локально)
|
||||
|
||||
1. Клонируйте репозиторий:
|
||||
|
||||
```bash
|
||||
git clone https://git.frigat.duckdns.org/FrigaT/BotPages.git
|
||||
cd BotPages
|
||||
```
|
||||
|
||||
2. Соберите решения:
|
||||
|
||||
```bash
|
||||
dotnet build
|
||||
```
|
||||
|
||||
3. Запуск демо (Telegram):
|
||||
|
||||
- Установите переменную окружения `TELEGRAM_TOKEN` с токеном бота.
|
||||
|
||||
```bash
|
||||
setx TELEGRAM_TOKEN "<token>" # Windows
|
||||
export TELEGRAM_TOKEN="<token>" # Linux/macOS
|
||||
```
|
||||
|
||||
- Запустите demo:
|
||||
|
||||
```bash
|
||||
dotnet run --project Demo
|
||||
```
|
||||
|
||||
Основные концепции
|
||||
|
||||
- `BotPagesApp` — точка конфигурации приложения: регистрация адаптеров, middleware, маршрутов и команд, запуск.
|
||||
- `Page`, `StatefulPage`, `SingletonPage` — модели страниц с жизненным циклом (`OnEnter`, `OnUpdate`, `OnText`, `OnButton`, `OnFile`, `OnError`).
|
||||
- `NavigationService` — управление переходами между страницами и определение текущей страницы по сессии.
|
||||
- `CommandsRegistry` — шаблоны команд вида `/cmd {arg} {opt?}` с поддержкой именованных и опциональных аргументов.
|
||||
- `IPageMiddleware` — middleware-конвейер, выполняющийся для каждого апдейта.
|
||||
- `IMessangerAdapterSetup` / `IMessengerAdapter` — интерфейсы, позволяющие подключать новые мессенджеры.
|
||||
|
||||
Документация
|
||||
|
||||
Полная внутренняя документация находится в `docs/`:
|
||||
- `docs/GETTING_STARTED.md` — быстрый старт и примеры конфигурации.
|
||||
- `docs/API_REFERENCE.md` — краткий reference публичных API.
|
||||
- `docs/PROJECT_DOCUMENTATION.md` — обзор архитектуры и компонентов.
|
||||
|
||||
XML‑документация генерируется при сборке (опция `GenerateDocumentationFile` в `.csproj`), её можно использовать для генерации HTML‑референса (docfx, MkDocs и т.п.).
|
||||
|
||||
Примеры использования
|
||||
|
||||
## 🚀 Быстрый старт
|
||||
```csharp
|
||||
var app = new BotPagesApp(factory, state, logger)
|
||||
.UseDefaultPage<WelcomePage>()
|
||||
var app = new BotPagesApp(stateStorage, logger)
|
||||
.AddAdapter("telegram", new TelegramAdapterSetup(token))
|
||||
.AddDefaultPage<WelcomePage>()
|
||||
.MapCommand<WelcomePage>("/start")
|
||||
.AddMiddleware(new LoggingMiddleware(logger))
|
||||
.AddMiddleware(new ErrorHandlingMiddleware(logger));
|
||||
.AddMiddleware(new LoggingMiddleware(logger));
|
||||
|
||||
await app.Build(CancellationToken.None);
|
||||
```
|
||||
|
||||
## 📄 Пример страниц
|
||||
Вклад и тестирование
|
||||
|
||||
### StatefulPage
|
||||
```csharp
|
||||
public sealed class WelcomePage : StatefulPage
|
||||
{
|
||||
[Statefull("visitCount")]
|
||||
private int VisitCount;
|
||||
- Принимам пулл‑реквесты. Описание PR должно содержать цель и краткое описание изменения.
|
||||
- Следуйте единому стилю кода и включённым nullable-аннотациям.
|
||||
|
||||
private PageContext? Context { get; set; }
|
||||
Лицензия
|
||||
|
||||
public override async Task OnEnter(PageContext ctx, CancellationToken ct)
|
||||
{
|
||||
Context = ctx;
|
||||
Проект распространяется под лицензией MIT. Смотрите файл `LICENSE`.
|
||||
|
||||
LoadState();
|
||||
VisitCount++;
|
||||
SaveState();
|
||||
Контакты
|
||||
|
||||
await ctx.SendTextAsync($"Добро пожаловать 🚀. Вы заходили сюда {VisitCount} раз(а).", ct: ct);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### SingletonPage
|
||||
```csharp
|
||||
public sealed class HelpPage : SingletonPage
|
||||
{
|
||||
public override Task OnEnter(PageContext ctx, CancellationToken ct)
|
||||
=> ctx.SendTextAsync("Это справка 📖", ct: ct);
|
||||
}
|
||||
```
|
||||
|
||||
## 🧩 Навигация
|
||||
```csharp
|
||||
await ctx.Navigation.GoToAsync<WelcomePage>(ctx, ct); // Stateful
|
||||
await ctx.Navigation.GoToAsync<WelcomePage>(ctx, agrs, ct); // Stateful with arguments
|
||||
await ctx.Navigation.GoToAsync<HelpPage>(ctx, ct); // Singleton
|
||||
await ctx.Navigation.GoToHome(ctx, ct); // Stateful
|
||||
```
|
||||
|
||||
## ⚙️ Middleware
|
||||
```csharp
|
||||
public sealed class LoggingMiddleware : IPageMiddleware
|
||||
{
|
||||
private readonly ILogger _logger;
|
||||
public LoggingMiddleware(ILogger logger) => _logger = logger;
|
||||
|
||||
public async Task InvokeAsync(PageContext ctx, Func<Task> next, CancellationToken ct)
|
||||
{
|
||||
_logger.Log(LogLevel.Info, $"Update: {ctx.Update.Kind}");
|
||||
await next();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 🏗 Архитектурные принципы
|
||||
- **Separation of concerns**: страницы не знают о транспорте, всё через адаптеры.
|
||||
- **Расширяемость**: новые страницы и middleware подключаются декларативно.
|
||||
- **Прозрачность**: минимум скрытой логики, всё явно через контекст.
|
||||
- **Developer Experience**: удобные API, автоматическая регистрация, документация через `///summary`.
|
||||
|
||||
## 📌 Итог
|
||||
BotPages позволяет писать чистые, расширяемые и удобные для команды боты:
|
||||
- минимум boilerplate,
|
||||
- декларативные интерфейсы,
|
||||
- прозрачная навигация,
|
||||
- автоматическое управление состоянием.
|
||||
Автор: FrigaT
|
||||
Репозиторий: https://git.frigat.duckdns.org/FrigaT/BotPages
|
||||
Reference in New Issue
Block a user