114 lines
4.5 KiB
Markdown
114 lines
4.5 KiB
Markdown
# Документация проекта BotPages
|
||
|
||
Краткая документация по всему проекту. Описывает архитектуру, основные компоненты, сценарии использования и сборки.
|
||
|
||
## Структура репозитория
|
||
|
||
- `BotPages.Core` — ядро фреймворка.
|
||
- Навигация: `NavigationService`, страницы: `Page`, `StatefulPage`, `SingletonPage`.
|
||
- Маршрутизация: `RoutesRegistry` (авторегистрация через `AutoMapRoute`).
|
||
- Команды: `CommandsRegistry` (парсер шаблонов команд, `TryDispatch`).
|
||
- Middleware: интерфейс `IPageMiddleware` и реализация `LoggingMiddleware`.
|
||
- Абстракции адаптеров/адаптер-фабрика: `IMessangerAdapterSetup`, `IMessengerAdapterFactory` (например `MultiAdapterFactory`).
|
||
- Хранилище состояния: `IStateStorage`.
|
||
|
||
- `BotPages.Telegram` — реализация адаптера для Telegram (использует `Telegram.Bot`).
|
||
|
||
- `Demo` — демонстрационное приложение с примерами страниц и конфигурации.
|
||
|
||
- `BotPages` — мета-проект/пакет для упаковки.
|
||
|
||
## Главные сущности и сценарии использования
|
||
|
||
- `BotPagesApp` — точка конфигурации и запуска приложения.
|
||
- Регистрация адаптеров: `AddAdapter(string messengerType, IMessangerAdapterSetup adapter)`.
|
||
- Регистрация middleware: `AddMiddleware<T>(T instance)`.
|
||
- Регистрация команд: `MapCommand<TPage>(string template)` или `MapCommand(string template, CommandHandler handler)`.
|
||
- Маршруты: `MapRoute<TPage>(string template)` и `AutoMapRoute()` для автоматического поиска страниц по рефлексии.
|
||
- Запуск: `Build(CancellationToken)` — старт адаптеров и приём апдейтов.
|
||
|
||
- Страницы:
|
||
- `Page` — базовый класс (абстрактный) с жизненным циклом (`OnEnter`, `OnUpdate`, `OnText`, `OnButton`, `OnFile`, `OnError`).
|
||
- `StatefulPage` — хранит состояние в `IStateStorage` (сериализация полей, атрибуты для stateful-полей).
|
||
- `SingletonPage` — один экземпляр на приложение, без per-session состояния.
|
||
|
||
- Навигация: `NavigationService` управляет текущей страницей пользователя (определяется по `PageContext.SessionKey`) и предоставляет методы `GoToAsync<TPage>`, `GoToHomeAsync`.
|
||
|
||
- Команды: шаблоны вида `/cmd {arg} {opt?}`. Парсер в `CommandsRegistry.ToRegex` поддерживает именованные группы и опциональные аргументы. При совпадении вызывается `CommandHandler(PageContext, IDictionary<string,string>, CancellationToken)`.
|
||
|
||
- Middleware: реализуют `IPageMiddleware.InvokeAsync(PageContext, Func<Task> next, CancellationToken ct)`; вызываются в порядке регистрации (конвейер).
|
||
|
||
## Формат и схема апдейта
|
||
|
||
- `UpdateContext` содержит данные апдейта: `MessengerType`, `Chat`, `User`, `Kind` (флаги `Text`, `Button`, `File`), `Text`, `Files`.
|
||
- При поступлении апдейта `BotPagesApp.HandleUpdateAsync` создаёт `PageContext` и:
|
||
1. Проверяет команды (если текст и начинается с `/`) — команды имеют приоритет.
|
||
2. Запускает pipeline middleware.
|
||
3. Передаёт управление текущей странице через `DispatchToPageAsync`.
|
||
|
||
## Расширение и адаптеры
|
||
|
||
- Чтобы добавить новый мессенджер, реализуйте `IMessangerAdapterSetup`/`IMessengerAdapter` и зарегистрируйте через `BotPagesApp.AddAdapter`.
|
||
- `MultiAdapterFactory` служит для хранения и разрешения адаптеров по ключу `messengerType`.
|
||
|
||
## Сборка и запуск
|
||
|
||
Требования:
|
||
- .NET 8 SDK
|
||
|
||
Сборка проекта:
|
||
|
||
```bash
|
||
dotnet build
|
||
```
|
||
|
||
Запуск демонстрации:
|
||
|
||
```bash
|
||
dotnet run --project Demo
|
||
```
|
||
|
||
Для Telegram-адаптера настройте токен и параметры в `Demo` (или в коде инициализации адаптера).
|
||
|
||
## Документы API и комментарии
|
||
|
||
XML-документация генерируется флагом `GenerateDocumentationFile` в `.csproj` для проектов. Для автогенерации документации используйте стандартные инструменты (например, `docfx`, `doxygen` или `MkDocs` с генерацией из XML).
|
||
|
||
## Примеры
|
||
|
||
- Пример регистрации кусочка конфигурации:
|
||
|
||
```csharp
|
||
var app = new BotPagesApp(stateStorage, logger)
|
||
.AddAdapter("telegram", new TelegramAdapterSetup(token))
|
||
.AddMiddleware(new LoggingMiddleware(logger))
|
||
.MapCommand<WelcomePage>("/start")
|
||
.AddDefaultPage<WelcomePage>();
|
||
|
||
await app.Build(CancellationToken.None);
|
||
```
|
||
|
||
- Пример простой страницы:
|
||
|
||
```csharp
|
||
public sealed class WelcomePage : StatefulPage
|
||
{
|
||
public override async Task OnEnter(PageContext ctx, CancellationToken ct)
|
||
{
|
||
await ctx.SendTextAsync("Добро пожаловать", ct: ct);
|
||
}
|
||
}
|
||
```
|
||
|
||
## Вклад и тестирование
|
||
|
||
- Направляйте PR в репозиторий. Описывайте изменения в заголовке и теле PR.
|
||
- Поддерживайте единый стиль кода и null-safe практики (`Nullable` включён).
|
||
|
||
## Лицензия
|
||
|
||
Проект распространяется под лицензией MIT (см. `.csproj` и `LICENSE`).
|
||
|
||
---
|
||
|
||
Это краткий обзор. При необходимости можно сгенерировать подробный Reference по API (список публичных типов и методов) в отдельный документ. |