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

2025-12-24 05:55:26 +03:00
parent 41986987b1
commit 833d8c80d9
14 changed files with 405 additions and 89 deletions
--- a/docs/PROJECT_DOCUMENTATION.md
+++ b/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 (список публичных типов и методов) в отдельный документ.