164 lines
6.8 KiB
Markdown
164 lines
6.8 KiB
Markdown
# Техническое задание
|
||
## Проект: 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.
|
||
- Расширенные таймауты и политики отката.
|