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