# BotPages Framework

BotPages — это архитектурный фреймворк для построения Telegram/MAX‑ботов с чистыми слоями, расширяемыми API и удобным developer experience.

## ✨ Возможности
- **Навигация через страницы**: каждая страница — отдельный обработчик логики.
- **Единый метод GoToAsync**: автоматически поддерживает как `SingletonPage`, так и `StatefulPage`.
- **StatefulPage**: свойства автоматически сохраняются в `StateStorage`.
- **SingletonPage**: один экземпляр на всё приложение, без состояния.
- **Middleware**: подключение промежуточных обработчиков (логирование, обработка ошибок).
- **Автоматическая регистрация страниц**: через рефлексию.
- **Роутинг страниц**: возможность устанавливать пути вызова для страниц.
- **Команды**: возможность установки команд, которые работают приоритетнее обработчиков страниц.
- **Минимум boilerplate**: декларативные интерфейсы и fluent API.

## 🚀 Быстрый старт
```csharp
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 WelcomePage : StatefulPage
{
    [Statefull("visitCount")]
    private int VisitCount;

    private PageContext? Context { get; set; }

    public override async Task OnEnter(PageContext ctx, CancellationToken ct)
    {
        Context = ctx;

        LoadState();
        VisitCount++;
        SaveState();

        await ctx.SendTextAsync($"Добро пожаловать 🚀. Вы заходили сюда {VisitCount} раз(а).", ct: ct);
    }
}
```

### 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
```

## ⚙️ Middleware
```csharp
public sealed class LoggingMiddleware : IPageMiddleware
{
    private readonly ILogger _logger;
    public LoggingMiddleware(ILogger logger) => _logger = logger;

    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,
- декларативные интерфейсы,
- прозрачная навигация,
- автоматическое управление состоянием.