Документация TeleFlow

TeleFlow - это фреймворк для Telegram-ботов на .NET, который оставляет первый handler простым, а выросшее приложение явным и понятным.

Главная идея простая: бот не должен превращаться в чёрный ящик только потому, что framework удобный. TeleFlow оставляет handler code близким к обычному C#, использует обычный dependency injection, даёт прямой доступ к Telegram client и переносит handler metadata generation в build time на рекомендуемом пути.

С чего начать

• Quickstart: минимальный long polling bot.
• Конфигурация и секреты: token и webhook settings через обычную .NET configuration.
• Recommended paths: какой путь выбрать под твой уровень.
• Package guide: что ставить и почему.
• Support desk tutorial: реалистичный бот с DI, state, callbacks и admin actions.
• Roadmap: запланированная работа, которая ещё не является текущим public API.
• English documentation: эта же документация на английском.

Пути изучения

Первый бот

Для трейни и джунов, которым нужно быстро получить рабочий результат без перегруза инфраструктурой:

1. Quickstart
2. Конфигурация и секреты
3. Handlers and routing
4. Callbacks and keyboards
5. State and wizard
6. Support desk tutorial

Production bot

Для разработчиков, которые уже понимают .NET services и хотят правильную структуру:

1. Application model
2. Конфигурация и секреты
3. Структура проекта
4. Dependency injection
5. Telegram client and schema
6. Errors and diagnostics
7. Testing

Enterprise bot

Для команд, которым важны предсказуемый runtime, границы владения, deployment и поддержка через год:

1. Enterprise guide
2. Deployment
3. Performance и scaling
4. Версионирование и релизы
5. Production checklist
6. Architecture notes
7. Generated registration
8. Custom storage

Карта документации

Getting Started

• Quickstart
• Конфигурация и секреты
• Recommended paths
• Packages

Tutorials

• Support desk bot

Fundamentals

• Application model
• Структура проекта
• Handlers and routing
• Filters
• Dependency injection
• Cancellation

Features

• Telegram client and schema
• Callbacks and keyboards
• State and wizard
• Roles and chat members
• Errors and diagnostics

Transports

• Long polling
• Webhooks
• Raw transports

Advanced

• Generated registration
• Custom storage
• Middleware and rate limiting
• Testing

Enterprise

• Enterprise guide
• Deployment
• Performance и scaling
• Версионирование и релизы
• Architecture notes
• Production checklist

Reference

• Attributes
• Options and extension points
• Troubleshooting

Planning

• Roadmap

Философия

TeleFlow создан для момента, когда простой Telegram-бот становится приложением.

Он должен быть простым на старте:

• один console app;
• один command handler;
• один token;
• один long polling transport.

И он должен оставаться честным, когда проект растёт:

• без скрытого reflection fallback на рекомендуемом пути регистрации;
• без требования заворачивать каждый Telegram call в framework-абстракцию;
• без специального service container;
• без fake enterprise story, которая держится только на названиях.

Предпочтение в дизайне простое: явное поведение, предсказуемый runtime, маленькие public contracts и extension points только там, где замена реально нужна.

Текущий scope

В текущем репозитории есть:

• Telegram Bot API client и generated schema models;
• generated client method extension methods;
• handler framework для messages, callbacks и chat member updates;
• атрибуты для command, text, template, regex, media, callback, state, scene, role и custom filters;
• typed callback payloads через [CallbackData] и [Callback<TPayload>];
• inline keyboards, reply keyboards, keyboard removal, force reply и chat actions;
• state, state data, wizard navigation и memory storage;
• long polling и ASP.NET Core webhook adapters;
• raw long polling и raw webhook packages;
• generated handler registration, explicit direct registration и explicit reflection registration;
• replacement points для middleware, update processor, update source, dispatcher, storage, callback serializer и client.