Добавлена документация

docs/API_REFERENCE.md

@@ -0,0 +1,57 @@
+# API Reference (краткий)
+
+Документ перечисляет публичные API фреймворка и их назначение.
+
+## BotPages.Core
+
+### `BotPagesApp`
+- `AddAdapter(string messengerType, IMessangerAdapterSetup adapter)` — зарегистрировать адаптер для мессенджера.
+- `AddDefaultPage<TPage>() where TPage : SingletonPage` — установить "домашнюю" страницу приложения.
+- `AddMiddleware<TMiddleware>(TMiddleware instance) where TMiddleware : IPageMiddleware` — добавить middleware в конвейер.
+- `MapCommand<TPage>(string commandTemplate) where TPage : Page` — зарегистрировать команду, ведущую на страницу.
+- `MapCommand(string template, CommandHandler handler)` — зарегистрировать кастомный обработчик команды.
+- `MapRoute<TPage>(string template) where TPage : Page` — вручную зарегистрировать маршрут для страницы.
+- `AutoMapRoute()` — автоматически найти и зарегистрировать все Page-типы в загруженных сборках.
+- `HandleUpdateAsync(UpdateContext update, CancellationToken ct)` — главный обработчик апдейтов (вызвается адаптером).
+- `Build(CancellationToken ct)` — запустить все адаптеры и начать обработку апдейтов.
+
+### Страницы
+- `Page` — абстрактный базовый класс.
+- `StatefulPage` — страница с сохранением состояния.
+- `SingletonPage` — одноэкземплярная страница.
+
+### Навигация
+- `NavigationService` — отвечает за определение текущей страницы и переходы.
+  - `GoToAsync<TPage>(PageContext ctx, CancellationToken ct)`
+  - `GoToHomeAsync(PageContext ctx, CancellationToken ct)`
+
+### Команды
+- `CommandsRegistry` — реестр команд (внутренний). Поддерживает шаблоны с именованными аргументами и опциональными параметрами.
+
+### Middleware
+- `IPageMiddleware` — интерфейс middleware.
+  - `InvokeAsync(PageContext ctx, Func<Task> next, CancellationToken ct)`
+
+### Абстракции адаптеров
+- `IMessangerAdapterSetup` — настройка адаптера.
+- `IMessengerAdapter` — экземпляр адаптера, реализующий `StartAdapterAsync(Func<UpdateContext, Task> onUpdate, List<Command> commands, CancellationToken ct)`.
+- `IMessengerAdapterFactory` — фабрика/реестр адаптеров (`MultiAdapterFactory` — реализация).
+
+### Хранилище состояний
+- `IStateStorage` — абстракция для сохранения состояния страниц между сессиями.
+
+## BotPages.Telegram
+- Реализация адаптера для Telegram на базе `Telegram.Bot`.
+- `TelegramUpdateMapper` — маппит апдейты Telegram в `UpdateContext`.
+- `TelegramAlbumBuilder` — собирает медиа-альбомы из последовательных апдейтов.
+- `TelegramAdapter` — реализация адаптера, стартует `StartAdapterAsync`.
+
+
+# Генерация документации
+
+Рекомендуется использовать `docfx` или `Doxygen` для генерации HTML-документации из XML-файлов, которые генерируются при сборке (см. `GenerateDocumentationFile` в `.csproj`).
+
+
+# Примечания
+
+Этот документ — краткое описание API. Для полного списка публичных типов и методов можно сгенерировать reference из XML-вывода компиляции.

docs/CONTRIBUTING.md

@@ -0,0 +1,19 @@
+# Contributing to BotPages
+
+Спасибо за интерес к проекту! Пожалуйста, перед отправкой PR убедитесь, что:
+
+- Ваш код проходит сборку: `dotnet build`.
+- Добавлены/обновлены тесты, если уместно.
+- Следуется стиль кода проекта и включены nullable-аннотации.
+
+Документация генерируется через `docfx`. См. `docfx.json` в корне репозитория и скрипты в `scripts/`.
+
+Пример локальной генерации документации:
+
+```bash
+# Unix
+./scripts/generate-docs.sh
+
+# Windows PowerShell
+./scripts/generate-docs.ps1
+```

docs/GETTING_STARTED.md

@@ -0,0 +1,47 @@
+# Быстрый старт — BotPages
+
+Эта инструкция поможет запустить и протестировать проект локально.
+
+Требования
+- .NET 8 SDK
+- Токен Telegram (если используете Telegram-адаптер)
+
+Сборка
+```bash
+dotnet build
+```
+
+Запуск демонстрации
+1. Откройте проект `Demo`.
+2. Внесите токен Telegram (если используется) в код инициализации адаптера или в переменные окружения проекта Demo.
+3. Запустите:
+```bash
+dotnet run --project Demo
+```
+
+Пример конфигурации приложения
+```csharp
+var app = new BotPagesApp(stateStorage, logger)
+    .AddAdapter("telegram", new TelegramAdapterSetup("<token>"))
+    .AddDefaultPage<WelcomePage>()
+    .MapCommand<WelcomePage>("/start")
+    .AddMiddleware(new LoggingMiddleware(logger));
+
+await app.Build(CancellationToken.None);
+```
+
+Как написать страницу
+- Наследуйте `StatefulPage` для страниц с пер-сессионным состоянием.
+- Наследуйте `SingletonPage` для одноэкземплярных страниц.
+- Переопределите `OnEnter`, `OnUpdate`, `OnText`, `OnButton`, `OnFile`, `OnError` по необходимости.
+- Для автоматического маппинга маршрутов используйте `AutoMapRoute()`.
+
+Тестирование команд
+- Команды регистрируются в `BotPagesApp.MapCommand`.
+- Шаблон команд поддерживает именованные и опциональные аргументы: `/cmd {a} {b?}`.
+
+Подсказки
+- Middleware выполняются в том порядке, в котором их добавляют в `BotPagesApp`.
+- Команды имеют приоритет над обработкой страниц (если текст начинается с `/`).
+
+Если требуется подробный справочник API — смотрите `docs/API_REFERENCE.md`.

docs/PROJECT_DOCUMENTATION.md

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

docs/docfx_project/docfx.css

@@ -0,0 +1,2 @@
+/* Minimal styling overrides for docfx output */
+body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, "Noto Sans", "Liberation Sans", sans-serif; }

docs/docfx_project/docfx.js

@@ -0,0 +1,7 @@
+module.exports = {
+  "templates": {
+    "global": {
+      "favicon": "favicon.ico"
+    }
+  }
+};