Переработанная версия ядра

2025-12-05 12:57:05 +03:00
parent ee175a35a0
commit d817417a69
81 changed files with 2335 additions and 1453 deletions
--- a/TZ.md
+++ b/TZ.md
@@ -0,0 +1,163 @@
+# Техническое задание  
+## Проект: BotPages
+
+### 1. Общая информация
+- **Название:** BotPages  
+- **Цель:** Создание библиотеки (NuGet‑пакета) для управления страницами в ботах (Telegram, VK, Discord, WhatsApp и др.), позволяющей строить логику без жёсткой привязки к конкретному API.  
+- **Платформа:** .NET 8  
+- **Артефакты:**  
+  - `BotPages.Core` — ядро, независимое от транспорта.  
+  - `BotPages.Telegram` — адаптер для Telegram.  
+  - В будущем: адаптеры для VK, Discord, WhatsApp.  
+- **Демо:** `Demo.exe` — демонстрация работы (создание заявки через несколько страниц, кнопки, файлы).
+
+---
+
+### 2. Основные понятия
+- **Page** — класс, отвечающий за состояние экрана бота.  
+  - `Page` — базовый класс.  
+  - `Page<TArguments>` — страница с аргументами.  
+  - `ModalPage` / `ModalPage<TArguments>` — модальная страница (перехватывает ввод, блокирует переходы).  
+- **Контекст:**  
+  - `UserContext` — данные пользователя (UserId, MessengerType).  
+  - `ChatContext` — данные чата (ChatId, Title, ThreadId?, ленивое обновление).  
+  - `PageContext` — объединяет UserContext, ChatContext, состояние, навигацию, файлы.  
+- **Состояние:**  
+  - `IStateStorage` — универсальный интерфейс хранения.  
+  - Базовая реализация: InMemory.  
+  - Ключ: `CompositeSessionKey(MessengerType:string, ChatId, UserId?)`.  
+  - История состояний: опционально (None, LastN, TimeWindow, Full).  
+
+---
+
+### 3. Жизненный цикл страницы
+- Методы (все async, с `CancellationToken`):  
+  - `OnEnter(ctx)` — вход.  
+  - `OnUpdate(ctx, update)` — общий обработчик.  
+  - `OnText(ctx, text)` — текстовые сообщения.  
+  - `OnFile(ctx, file)` — файлы.  
+  - `OnButton(ctx, action)` — кнопки.  
+  - `OnLeave(ctx)` — выход.  
+  - `OnError(ctx, exception)` — ошибки.  
+  - `OnTimeout(ctx, timeoutInfo)` — таймауты.  
+- Прогресс фоновых операций:  
+  - `StartProgress()`, `UpdateProgress(percent)` + событие обновления.
+
+---
+
+### 4. Навигация
+- Императивный API:  
+  ```csharp
+  ctx.GoTo<CitySelectionPage>();
+  ctx.GoTo<ConfirmationPage>(new ConfirmationArgs { PhotoId = photoId });
+  ctx.GoTo<DetailsPage>(args => { args.Photo = photoId; });
+  ctx.ReplaceWith<MainPage>();
+  ctx.Back();
+  ```
+- Декларативный роутинг:  
+  - Атрибуты `[Route("order/create")]`.  
+  - Реестр `routes.Map<CreateOrderPage>("order/create")`.  
+  - Проверка конфликтов при старте.  
+- Стек навигации: отдельный пакет `BotPages.Navigation.Stack`.  
+
+---
+
+### 5. Команды
+- Команды имеют приоритет над событиями страниц.  
+- Поддержка шаблонов:  
+  ```csharp
+  app.Commands.Map("/start").To<WelcomePage>();
+  app.Commands.Map("/open {page} {id?}")
+      .To(ctx => ctx.GoToByName(page, new { id }));
+  ```
+- Возможность указать страницу, которая открывается при вводе команды.
+
+---
+
+### 6. Файлы
+- **FileDescriptor:**  
+  - `Id`, `Name`, `Extension`, `Size`, `Mime`, `Type(enum)`, `SourceMessenger`, `GetStreamAsync()`, `Checksum?`.  
+- Отправка:  
+  ```csharp
+  await ctx.Chat.SendFileAsync(file, caption: "Документ");
+  await ctx.Chat.Files.BeginAlbum().Add(file1).Add(file2).SendAsync();
+  ```
+- Альбомы, сжатие — на уровне адаптера.  
+- Метаданные файлов — временно в контексте, экспорт в состояние вручную.
+
+---
+
+### 7. Адаптеры
+- Интерфейс `IMessengerAdapter`:  
+  - `SendMessage`, `EditMessage`, `DeleteMessage`, `SendFile`, `SendAlbum`.  
+  - `ReceiveUpdate`.  
+  - `GetChat`, `GetFileStream`.  
+  - `AnswerCallback`, `SetTypingIndicator`.  
+- Telegram: первая реализация.  
+- Поддержка **Webhook** и **Polling** (выбор конфигом).  
+
+---
+
+### 8. Capabilities
+- В `ChatContext.Capabilities`:  
+  - `SupportsInlineButtons`, `SupportsReplyButtons`, `SupportsAlbums`, `SupportsFormattingMarkdown`, `SupportsFormattingHtml`, `MaxMessageLength`.  
+- Разработчик может проверять возможности.  
+- Адаптер всегда деградирует и логирует `Warn`.  
+
+---
+
+### 9. Логирование
+- Уровни: `Info`, `Warn`, `Critical`.  
+- Примеры:  
+  - Info: вход на страницу, прогресс.  
+  - Warn: деградация возможностей.  
+  - Critical: падение хранилища.  
+
+---
+
+### 10. Middleware
+- Интерфейс:
+  ```csharp
+  public interface IUpdateMiddleware
+  {
+      Task InvokeAsync(UpdateContext ctx, Func<Task> next, CancellationToken ct);
+  }
+  ```
+- Пример:
+  ```csharp
+  app.AddMiddleware<IUpdateMiddleware, LoggingMiddleware>();
+  app.AddMiddleware<ErrorMiddleware>(params);
+  ```
+- Порядок регистрации = порядок выполнения.  
+- Middleware только для входящих обновлений.  
+
+---
+
+### 11. Дефолтная страница
+- Конфигурация:
+  ```csharp
+  app.UseDefaultPage<WelcomePage>();
+  ```
+- Одна дефолтная страница для всех мессенджеров.  
+- Условия не нужны.  
+
+---
+
+### 12. Demo.exe
+- Сценарий: создание заявки.  
+- Страницы:  
+  1. **StartPage** — приветствие, кнопка «Создать заявку».  
+  2. **TitlePage** — ввод текста.  
+  3. **DetailsPage** — доп. поля, inline/reply кнопки.  
+  4. **FilesPage** — загрузка файлов, просмотр списка.  
+  5. **ConfirmPage** — подтверждение заявки.  
+  6. **SubmitPage** — отправка, итоговое сообщение.  
+
+---
+
+### 13. TODO (будущие версии)
+- Поддержка модальных страниц со стеком.  
+- Расширенные Capabilities (rate limits, threads).  
+- View‑DSL как надстройка над контекстом.  
+- Cross‑transport identity.  
+- Расширенные таймауты и политики отката.