Документация проекта 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

Сборка проекта:

dotnet build

Запуск демонстрации:

dotnet run --project Demo

Для Telegram-адаптера настройте токен и параметры в Demo (или в коде инициализации адаптера).

Документы API и комментарии

XML-документация генерируется флагом GenerateDocumentationFile в .csproj для проектов. Для автогенерации документации используйте стандартные инструменты (например, docfx, doxygen или MkDocs с генерацией из XML).

Примеры

Пример регистрации кусочка конфигурации:

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);

Пример простой страницы:

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 (список публичных типов и методов) в отдельный документ.

4.5 KiB Raw Blame History Unescape Escape