BotPages/TZ.md

Техническое задание

Проект: 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:

  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. Команды

• Команды имеют приоритет над событиями страниц.
• Поддержка шаблонов:

  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?.
• Отправка:

  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

• Интерфейс:

  public interface IUpdateMiddleware
  {
      Task InvokeAsync(UpdateContext ctx, Func<Task> next, CancellationToken ct);
  }
  

• Пример:

  app.AddMiddleware<IUpdateMiddleware, LoggingMiddleware>();
  app.AddMiddleware<ErrorMiddleware>(params);
  

• Порядок регистрации = порядок выполнения.
• Middleware только для входящих обновлений.

---

11. Дефолтная страница

• Конфигурация:

  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.
• Расширенные таймауты и политики отката.