# Техническое задание  
## Проект: 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>` — страница с аргументами.  
- **Контекст:**  
  - `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<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.  
- Расширенные таймауты и политики отката.