diff --git a/Home-RU.md b/Home-RU.md index 0da0144..61c3b0a 100644 --- a/Home-RU.md +++ b/Home-RU.md @@ -34,6 +34,59 @@ English version: [[Home]] - [[Recipes-RU]] - [[Testing-Bots-with-Laniakea-RU]] +## Чего еще не хватает в core concepts + +Сейчас wiki уже покрывает почти весь основной surface фреймворка: `Bot`, `BotOpts`, lifecycle, plugins и commands, `MsgContext`, middleware, payloads, `tgapi`, drafts, localization, runners, errors, logging, rate limiting, testing и migration. + +Но если смотреть именно на концептуальные дыры, а не просто на наличие страниц, то все еще выделяются такие темы: + +1. `Update-Routing-Model` +Почему это важно: +Сейчас routing объяснен кусками в `Commands-and-Plugins`, `Bot-Lifecycle` и `Middleware`, но нет одной страницы, которая последовательно показывает, как update проходит через систему. +Что туда войдет: +`prepareUpdateCtx`, bot middleware, command flow, payload flow, update handlers, cloned context для non-command updates и first-match behavior. + +2. `Context-and-State-Model` +Почему это важно: +Страница про `MsgContext` уже есть, но нет отдельной концептуальной страницы про shared state, copied state, поведение `DatabaseContext(T)` и про то, почему pointer types чаще всего являются правильным default choice. +Что туда войдет: +Shared dependencies, copied context values, runtime expectations и места, где легко ошибиться с race assumptions. + +3. `Plugin-Boundaries-and-Composition` +Почему это важно: +Wiki уже объясняет, как plugins использовать на практике, но почти не говорит о том, как о них думать архитектурно. +Что туда войдет: +Как резать бот на plugins, что должно жить в plugin middleware, когда выделять новый plugin и как не прийти к giant-plugin design. + +4. `Handler-Design-Guidelines` +Почему это важно: +Это будет страница не столько про API, сколько про стиль и idiomatic use framework'а. +Что туда войдет: +Когда возвращать `error`, когда отвечать вручную, как держать handlers thin, когда выносить логику в сервисный слой и как не смешивать `tgapi` и high-level helpers без необходимости. + +5. `Update-Types-and-Coverage` +Почему это важно: +Сейчас update handlers уже задокументированы, но нет одной карты того, какие update types идут через commands и payloads, какие через `AddUpdateHandler(...)`, и какие поля `MsgContext` разумно ожидать в каждом flow. +Что туда войдет: +Routing categories, update-specific context guarantees и влияние формы update на handler design. + +6. `Telegram-Limits-and-Validation` +Почему это важно: +Часть этой информации уже разбросана по страницам про rate limiting, payloads и errors, но нет одной общей mental-model страницы. +Что туда войдет: +Лимиты на message text, captions и callback data, validation before send, long replies, Markdown caveats и upload-related ограничения. + +Менее срочные, но тоже полезные темы: +- `Concurrency-Model` +- `Bot-vs-tgapi-Decision-Guide` +- `Public-API-Stability` + +Если приоритизировать, то самый полезный порядок сейчас такой: +1. `Update-Routing-Model` +2. `Context-and-State-Model` +3. `Plugin-Boundaries-and-Composition` +4. `Handler-Design-Guidelines` + ## Миграция и сопровождение - [[Migration-RU]] diff --git a/Home.md b/Home.md index 481e131..316657f 100644 --- a/Home.md +++ b/Home.md @@ -36,6 +36,59 @@ Use this wiki as the structured companion to the README: start with setup, then - [[Localization]] - [[Testing-Bots-with-Laniakea]] +## Missing Core Concepts + +The current wiki already covers most of the main framework surface: `Bot`, `BotOpts`, lifecycle, plugins and commands, `MsgContext`, middleware, payloads, `tgapi`, drafts, localization, runners, errors, logging, rate limiting, testing, and migration. + +If we focus specifically on conceptual gaps rather than simple page presence, these topics still stand out: + +1. `Update-Routing-Model` +Why it matters: +This behavior is currently explained in pieces across `Commands-and-Plugins`, `Bot-Lifecycle`, and `Middleware`, but there is no single page that explains how an update actually flows through the system. +What it would cover: +`prepareUpdateCtx`, bot middleware, command flow, payload flow, update handlers, cloned contexts for non-command updates, and first-match behavior. + +2. `Context-and-State-Model` +Why it matters: +`MsgContext` exists, but there is no dedicated conceptual page about what is shared state, what is copied state, how `DatabaseContext(T)` behaves, and why pointer types are usually the right default. +What it would cover: +Shared dependencies, copied context values, runtime expectations, and where race assumptions can go wrong. + +3. `Plugin-Boundaries-and-Composition` +Why it matters: +The wiki explains how plugins work in practice, but not yet how to think architecturally about plugin boundaries. +What it would cover: +How to split a bot into plugins, what belongs in plugin middleware, when to extract a new plugin, and how to avoid the giant-plugin anti-pattern. + +4. `Handler-Design-Guidelines` +Why it matters: +This would explain framework style rather than raw API surface. +What it would cover: +When to return `error`, when to answer manually, how to keep handlers thin, when to push logic into services, and how to avoid mixing `tgapi` with high-level helpers unnecessarily. + +5. `Update-Types-and-Coverage` +Why it matters: +The wiki has update handlers, but not a single map of which update types go through commands and payloads, which go through `AddUpdateHandler(...)`, and which `MsgContext` fields are safe to expect in each flow. +What it would cover: +Routing categories, update-specific context guarantees, and how update shapes affect handler design. + +6. `Telegram-Limits-and-Validation` +Why it matters: +Some of this exists in rate limiting, payload, and error docs, but not as one mental-model page. +What it would cover: +Message length, caption length, callback data size, validation-before-send behavior, long replies, Markdown caveats, and upload-related limits. + +Less urgent, but still useful later: +- `Concurrency-Model` +- `Bot-vs-tgapi-Decision-Guide` +- `Public-API-Stability` + +If these are prioritized, the most useful order is: +1. `Update-Routing-Model` +2. `Context-and-State-Model` +3. `Plugin-Boundaries-and-Composition` +4. `Handler-Design-Guidelines` + ## Migration and Maintenance - [[Migration]] - [[FAQ]]