From e1b8fa2119af64b0992c587e298ef3cdd714c0a9 Mon Sep 17 00:00:00 2001
From: FrigaT <frostfriman@gmail.com>
Date: Fri, 5 Dec 2025 13:51:57 +0300
Subject: [PATCH] readme

---
 README.md | 152 ++++++++++++++++++++++++++----------------------------
 1 file changed, 72 insertions(+), 80 deletions(-)

diff --git a/README.md b/README.md
index 94b7422..1f67574 100644
--- a/README.md
+++ b/README.md
@@ -1,100 +1,92 @@
-# BotPages.Core
+# BotPages Framework
 
-**BotPages.Core** — это универсальный фреймворк для построения ботов с декларативными страницами, навигацией и единым контекстом.  
-Поддерживает работу сразу с несколькими транспортами (например, Telegram и MAX), сохраняя чистую архитектуру и удобный developer experience.
+BotPages — это архитектурный фреймворк для построения Telegram/MAX‑ботов с чистыми слоями, расширяемыми API и удобным developer experience.
 
----
-
-## ✨ Основные идеи
-
-- **PageResult** — декларативный результат обработки страницы (сообщение, файлы, кнопки, навигация).
-- **PageMessage** — объект сообщения с поддержкой форматов (Plain/Markdown/HTML), флагов (`IsSilent`, `DisableWebPreview`).
-- **PageNavigate** — объект навигации (переход на другую страницу, аргументы, режим Replace).
-- **PageAction** — кнопки (inline/reply, ссылки, запрос контакта/локации, стили).
-- **UpdateContext** — универсальный контекст обновления, независимый от транспорта, с полем `Transport` для разделения Telegram/MAX.
-- **PageRegistry** — реестр страниц, умеет собирать их автоматически из сборки (`CreateFromAssembly`, `CreateFromApplication`).
-- **IStateStore** — хранилище состояния пользователя, ключом является `(Transport, ChatId)`.
-
----
+## ✨ Возможности
+- **Навигация через страницы**: каждая страница — отдельный обработчик логики.
+- **Единый метод GoToAsync**: автоматически поддерживает как `SingletonPage`, так и `StatefulPage`.
+- **StatefulPage**: свойства автоматически сохраняются в `StateStorage`.
+- **SingletonPage**: один экземпляр на всё приложение, без состояния.
+- **Middleware**: подключение промежуточных обработчиков (логирование, обработка ошибок).
+- **Автоматическая регистрация страниц**: через рефлексию.
+- **Роутинг страниц**: возможность устанавливать пути вызова для страниц.
+- **Команды**: возможность установки команд, которые работают приоритетнее обработчиков страниц.
+- **Минимум boilerplate**: декларативные интерфейсы и fluent API.
 
 ## 🚀 Быстрый старт
-
 ```csharp
-// Создаём реестр страниц
-var registry = PageRegistry.CreateFromApplication(defaultPageId: "main");
-
-// Хранилище состояния
-IStateStore store = new InMemoryStateStore();
-
-// Навигация
-INavigationService nav = new NavigationService(registry, store);
-
-// Запуск Telegram
-var telegramBot = new TelegramBotClient("TELEGRAM_TOKEN");
-telegramBot.StartReceiving(async (bot, update, ct) =>
-{
-    var ctx = TelegramUpdateMapper.Map(bot, nav, store, update);
-    await nav.HandleAsync(ctx, ct);
-});
-
-// Запуск MAX
-var maxClient = new MaxClientAdapter("MAX_CONFIG");
-maxClient.OnUpdate(async (update, ct) =>
-{
-    var ctx = MaxUpdateMapper.Map(maxClient, nav, store, update);
-    ctx.Transport = "max";
-    await nav.HandleAsync(ctx, ct);
-});
+var app = new BotPagesApp(factory, state, logger)
+    .UseDefaultPage<WelcomePage>()
+    .MapCommand<WelcomePage>("/start")
+    .AddMiddleware(new LoggingMiddleware(logger))
+    .AddMiddleware(new ErrorHandlingMiddleware(logger));
 ```
 
----
-
-## 📌 Пример страницы
+## 📄 Пример страниц
 
+### StatefulPage
 ```csharp
-public sealed class MainPage : IPage
+public sealed class WelcomePage : StatefulPage
 {
-    public string Id => "main";
+    [Statefull("visitCount")]
+    private int VisitCount;
 
-    public PageResult Handle(UpdateContext ctx)
+    private PageContext? Context { get; set; }
+
+    public override async Task OnEnter(PageContext ctx, CancellationToken ct)
     {
-        return PageResult.Text("🏠 Главная страница", new[]
-        {
-            new PageAction { Label = "Перейти", Value = "inlinePage", Placement = ActionPlacement.Inline }
-        });
+        Context = ctx;
+
+        LoadState();
+        VisitCount++;
+        SaveState();
+
+        await ctx.SendTextAsync($"Добро пожаловать 🚀. Вы заходили сюда {VisitCount} раз(а).", ct: ct);
     }
 }
 ```
 
----
-
-## 🛠️ Возможности
-
-- ✅ Декларативные страницы (`PageResult`)
-- ✅ Навигация (`PageNavigate`)
-- ✅ Сообщения с форматами и флагами (`PageMessage`)
-- ✅ Кнопки с расширенными параметрами (`PageAction`)
-- ✅ Поддержка нескольких транспортов (Telegram)
-- ✅ Автоматическая регистрация страниц (`PageRegistry.CreateFromApplication`)
-- ✅ Хранение состояния по `(ChatClientId, ChatId)`
-
----
-
-## 📂 Структура проекта
-
-```
-BotPages/
- ├── BotPages.Core/   # Основные классы (PageResult, PageMessage, PageNavigate, UpdateContext)
- ├── Demo/            # Пример страниц и запуск
- ├── Adapters/        # Транспортные адаптеры (Telegram)
- └── README.md
+### SingletonPage
+```csharp
+public sealed class HelpPage : SingletonPage
+{
+    public override Task OnEnter(PageContext ctx, CancellationToken ct)
+        => ctx.SendTextAsync("Это справка 📖", ct: ct);
+}
 ```
 
----
+## 🧩 Навигация
+```csharp
+await ctx.Navigation.GoToAsync<WelcomePage>(ctx, ct); // Stateful
+await ctx.Navigation.GoToAsync<WelcomePage>(ctx, agrs, ct);    // Stateful with arguments
+await ctx.Navigation.GoToAsync<HelpPage>(ctx, ct);    // Singleton
+await ctx.Navigation.GoToHome(ctx, ct); // Stateful
+```
 
-## 📖 TODO
+## ⚙️ Middleware
+```csharp
+public sealed class LoggingMiddleware : IPageMiddleware
+{
+    private readonly ILogger _logger;
+    public LoggingMiddleware(ILogger logger) => _logger = logger;
 
-- [ ] Поддержка медиагрупп (альбомов) в Telegram
-- [ ] Расширенные стили кнопок
-- [ ] TTL для сообщений
-- [ ] Плагины для сторонних транспортов
\ No newline at end of file
+    public async Task InvokeAsync(PageContext ctx, Func<Task> next, CancellationToken ct)
+    {
+        _logger.Log(LogLevel.Info, $"Update: {ctx.Update.Kind}");
+        await next();
+    }
+}
+```
+
+## 🏗 Архитектурные принципы
+- **Separation of concerns**: страницы не знают о транспорте, всё через адаптеры.
+- **Расширяемость**: новые страницы и middleware подключаются декларативно.
+- **Прозрачность**: минимум скрытой логики, всё явно через контекст.
+- **Developer Experience**: удобные API, автоматическая регистрация, документация через `///summary`.
+
+## 📌 Итог
+BotPages позволяет писать чистые, расширяемые и удобные для команды боты:
+- минимум boilerplate,
+- декларативные интерфейсы,
+- прозрачная навигация,
+- автоматическое управление состоянием.
\ No newline at end of file